Moya

مويا 15.0.0

يمكن العثور على نسخة صينية من هذا المستند هنا.

أنت مطور ذكي. ربما تستخدم Alamofire لتجريد الوصول إلى URLSession وكل تلك التفاصيل السيئة التي لا تهتم بها حقًا. ولكن بعد ذلك ، مثل الكثير من المطورين الأذكياء ، يمكنك كتابة طبقات تجريد الشبكة المخصصة. ربما يطلق عليهم "Apimanager" أو "NetworkModel" ، وينتهي دائمًا بالبكاء.

تعتبر طبقات الشبكة المخصصة شائعة في تطبيقات iOS. إنهم سيئون لعدة أسباب:

• يجعل من الصعب كتابة تطبيقات جديدة ("من أين أبدأ؟")
• يجعل من الصعب الحفاظ على التطبيقات الموجودة ("يا إلهي ، هذه الفوضى ...")
• يجعل من الصعب كتابة اختبارات الوحدة ("كيف أفعل هذا مرة أخرى؟")

لذا فإن الفكرة الأساسية لـ Moya هي أننا نريد بعض طبقة تجريد الشبكة التي تغلف بشكل كافٍ استدعاء Alamofire بشكل كافٍ. يجب أن يكون الأمر بسيطًا بما يكفي لأن الأشياء الشائعة سهلة ، ولكنها شاملة بما يكفي أن تكون الأشياء المعقدة سهلة أيضًا.

إذا كنت تستخدم alamofire لتجريد URLSession بعيدا ، فلماذا لا تستخدم شيء لتجريد بعيدا عن شجاع عناوين URL ، والمعلمات ، وما إلى ذلك؟

بعض الميزات الرائعة لمويا:

• تجميع وقت التحقق من الوصول إلى نقطة نهاية API الصحيح.
• يتيح لك تحديد استخدام واضح لنقاط النهاية المختلفة مع قيم التعداد المرتبطة.
• يعامل كوب الاختبار كمواطنين من الدرجة الأولى ، لذا فإن اختبار الوحدة هو سهولة للغاية.

يمكنك التحقق من المزيد حول اتجاه المشروع في وثيقة الرؤية.

مشاريع عينة

لقد قدمنا ​​مشروعين عينة في المستودع. لاستخدامها ، قم بتنزيل repo ، قم بتشغيل carthage update لتنزيل المكتبات المطلوبة وفتح moya.xcodeproj. سترى مخططان: Basic Multi-Target - حدد واحدًا ثم بناء وتشغيل! ملفات المصدر لها موجودة في دليل Examples في مشروع Navigator. استمتع!

حالة المشروع

هذا المشروع قيد التطوير بنشاط ، ويتم استخدامه في تطبيق مزاد Artsy. نحن نعتبرها جاهزة للاستخدام الإنتاج.

تثبيت

إصدار Moya مقابل إصدار Swift.

فيما يلي جدول يوضح إصدار Moya الذي يجب استخدامه لإصدارك السريع.

سريع	مويا	Rxmoya	ReactiveMoya	rxswift	رد الفعل	ألاموفير
> = 5.2	> = 15.0.0	> = 15.0.0	> = 15.0.0	6.x	6.x	5.x
5.x	> = 14.0.0	> = 14.0.0	> = 14.0.0	5.x	6.x	5.x
5.x	> = 13.0.0	> = 13.0.0	> = 13.0.0	4.x	5.x	> = 4.1
4.x	9.0.0 - 12.0.1	10.0.0 - 12.0.1	9.0.0 - 12.0.1	4.x (> = 10.0.0)	4.x (> = 12.0.0)	4.1 (> = 11.0.0)
3.x	8.0.0 - 8.0.5	8.0.0 - 8.0.5	8.0.0 - 8.0.5	-	-	-
2.3	7.0.2 - 7.0.4	7.0.2 - 7.0.4	7.0.2 - 7.0.4	-	-	-
2.2	<= 7.0.1	<= 7.0.1	<= 7.0.1	-	-	-

ملاحظة: إذا كنت تستخدم Swift 4.2 في مشروعك ، لكنك تستخدم Xcode 10.2 ، فيجب أن تعمل Moya 13 بشكل صحيح على الرغم من أننا نستخدم Swift 5.0.

الترقية إلى نسخة رئيسية جديدة من Moya؟ تحقق من أدلة الهجرة لدينا.

مدير الحزمة السريع

ملاحظة: التعليمات أدناه هي لاستخدام SwiftPM بدون واجهة المستخدم Xcode. من الأسهل الذهاب إلى إعدادات المشروع -> حزم سريعة وإضافة Moya من هناك.

للتكامل باستخدام Manager Swift Package من Apple ، دون تكامل Xcode ، أضف ما يلي كاعتماد على Package.swift الخاصة بك.

 . package ( url : " https://github.com/Moya/Moya.git " , . upToNextMajor ( from : " 15.0.0 " ) )

ثم حدد "Moya" كاعتماد على الهدف الذي ترغب في استخدامه Moya. إذا كنت ترغب في استخدام الامتدادات التفاعلية ، فأضف أيضًا "ReactiveMoya" أو "RxMoya" أو "CombineMoya" كاعتماد على الهدف على التوالي. فيما يلي مثال PackageDescription :

// swift-tools-version:5.3
import PackageDescription

let package = Package (
    name : " MyPackage " ,
    products : [
        . library (
            name : " MyPackage " ,
            targets : [ " MyPackage " ] ) ,
    ] ,
    dependencies : [
        . package ( url : " https://github.com/Moya/Moya.git " , . upToNextMajor ( from : " 15.0.0 " ) )
    ] ,
    targets : [
        . target (
            name : " MyPackage " ,
            dependencies : [ " ReactiveMoya " ] )
    ]
)

الجمع بين ملاحظة: إذا كنت تستخدم Combinemoya ، فتأكد من استخدام Xcode 11.5.0 أو أحدث. مع الإصدارات السابقة من XCode ، سيتعين عليك إضافة الجمع يدويًا كإطار مرتبط بشكل ضعيف بهدف التطبيق الخاص بك.

أكسيو

ACCIO هو مدير التبعية يعتمد على SWIFTPM والذي يمكنه إنشاء أطر عمل لنظام التشغيل iOS/MACOS/TVOS/WatchOS. لذلك فإن خطوات تكامل MOYA هي نفسها كما هو موضح أعلاه. بمجرد تكوين ملف Package.swift الخاص بك ، قم بتشغيل accio update بدلاً من swift package update .

كوكوبودس

بالنسبة إلى Moya ، استخدم الإدخال التالي في Podfile:

 pod 'Moya' , '~> 15.0'

# or 

pod 'Moya/RxSwift' , '~> 15.0'

# or

pod 'Moya/ReactiveSwift' , '~> 15.0'

# or

pod 'Moya/Combine' , '~> 15.0'

ثم قم بتشغيل pod install .

في أي ملف ترغب في استخدام Moya In ، لا تنس استيراد الإطار باستخدام import Moya .

قرطاج

يمكن لمستخدمي Carthage الإشارة إلى هذا المستودع واستخدام أي إطار تم إنشاؤه لديهم ، Moya أو RxMoya أو ReactiveMoya أو CombineMoya .

قم بإجراء الإدخال التالي في Cartfile:

 github "Moya/Moya" ~> 15.0

ثم قم بتشغيل carthage update --use-xcframeworks .

إذا كانت هذه هي المرة الأولى التي تستخدم فيها قرطاج في المشروع ، فستحتاج إلى المرور ببعض الخطوات الإضافية كما هو موضح في قرطاج.

ملاحظة: في هذا الوقت ، لا يوفر قرطاج وسيلة لبناء عروض فرعية مستودع محددة فقط. سيتم بناء جميع العوامل الفرعية وتبعياتها مع الأمر أعلاه. ومع ذلك ، لا تحتاج إلى نسخ الأطر التي لا تستخدمها في مشروعك. على سبيل المثال ، إذا كنت لا تستخدم ReactiveSwift ، فلا تتردد في حذف هذا الإطار مع ReactiveMoya من دليل بناء قرطاج بعد اكتمال carthage update . أو إذا كنت تستخدم ReactiveSwift ولكن ليس RxSwift أو Combine ، فإن RxMoya ، RxTest ، RxCocoa ، CombineMoya وما إلى ذلك يمكن حذفها بأمان.

يدويًا

• افتح Up Terminal ، cd في دليل المشروع على مستوى أعلى ، وقم بتشغيل الأمر التالي إذا لم يتم تهيئة مشروعك كمستودع GIT:

$ git init

• أضف Alamofire & Moya كوحدة فرعية GIT عن طريق تشغيل الأوامر التالية:

$ git submodule add https://github.com/Alamofire/Alamofire.git
$ git submodule add https://github.com/Moya/Moya.git

• افتح مجلد Alamofire الجديد ، واسحب Alamofire.xcodeproj في مشروع Navigator لمشروع Xcode الخاص بالتطبيق. افعل نفس الشيء مع Moya.xcodeproj في مجلد Moya .

يجب أن تظهر متداخلة تحت أيقونة المشروع الأزرق في طلبك. سواء كانت أعلى أو أقل من جميع مجموعات Xcode الأخرى لا تهم.

• تحقق من أن أهداف النشر الخاصة بـ xcodeproj S تطابق مع هدف التطبيق الخاص بك في Navigator Project.
• بعد ذلك ، حدد مشروع التطبيق الخاص بك في Project Navigator (أيقونة المشروع الأزرق) للانتقال إلى نافذة التكوين الهدف وحدد هدف التطبيق تحت عنوان "الأهداف" في الشريط الجانبي.
• في شريط علامة التبويب في الجزء العلوي من تلك النافذة ، افتح لوحة "عامة".
• انقر على الزر + أسفل قسم "الثنائيات المدمجة".
• سترى مجلدين مختلفين Alamofire.xcodeproj لكل منهما نسختين مختلفتين من Alamofire.framework المتداخل داخل مجلد Products .

لا يهم مجلد Products الذي تختاره من بينه ، ولكن لا يهم ما إذا كنت تختار العليا أو السفلي Alamofire.framework .

• حدد الجزء العلوي من Alamofire.framework لنظام التشغيل iOS والأسفل لـ MacOS.

يمكنك التحقق من الشخص الذي حددته من خلال فحص سجل الإنشاء لمشروعك. سيتم إدراج هدف الإنشاء لـ Alamofire إما على أنه Alamofire iOS أو Alamofire macOS أو Alamofire tvOS أو Alamofire watchOS .

• انقر على الزر + ضمن "الثنائيات المدمجة" مرة أخرى وأضف هدف البناء الصحيح لـ Moya .

• وهذا كل شيء!

تتم إضافة الأطر الثلاثة بشكل تلقائي كاعتماد مستهدف ، إطار عمل مرتبط وإطار مضمن في مرحلة إنشاء ملفات النسخ وهو كل ما تحتاجه للبناء على المحاكاة والجهاز.

الاستخدام

بعد بعض الإعداد ، يكون استخدام Moya بسيطًا حقًا. يمكنك الوصول إلى واجهة برمجة تطبيقات مثل هذا:

provider = MoyaProvider < GitHub > ( )
provider . request ( . zen ) { result in
    switch result {
    case let . success ( moyaResponse ) :
        let data = moyaResponse . data
        let statusCode = moyaResponse . statusCode
        // do something with the response data or statusCode
    case let . failure ( error ) :
        // this means there was a network failure - either the request
        // wasn't sent (connectivity), or no response was received (server
        // timed out).  If the server responds with a 4xx or 5xx error, that
        // will be sent as a ".success"-ful response.
    }
}

هذا مثال أساسي. تحتاج العديد من طلبات API إلى معلمات. يقوم Moya بتشفير هذه الأشياء في التعداد الذي تستخدمه للوصول إلى نقطة النهاية ، مثل هذا:

provider = MoyaProvider < GitHub > ( )
provider . request ( . userProfile ( " ashfurrow " ) ) { result in
    // do something with the result
}

لا مزيد من الأخطاء المطبعية في عناوين URL. لا مزيد من قيم المعلمة مفقودة. لا مزيد من العبث مع ترميز المعلمة.

لمزيد من الأمثلة ، راجع الوثائق.

الامتدادات التفاعلية

حتى البرودة هي الامتدادات التفاعلية. يوفر Moya امتدادات تفاعلية لـ Reactiveswift و Rxswift و Combine.

رد الفعل

يوفر ReactiveSwift Extension كل من reactive.request(:callbackQueue:) و reactive.requestWithProgress(:callbackQueue:) الطرق التي تُرجع على الفور SignalProducer التي يمكنك البدء بها أو ربطها أو خريطةها أو ما تريد القيام به. للتعامل مع الأخطاء ، على سبيل المثال ، يمكننا القيام بما يلي:

provider = MoyaProvider < GitHub > ( )
provider . reactive . request ( . userProfile ( " ashfurrow " ) ) . start { event in
    switch event {
    case let . value ( response ) :
        image = UIImage ( data : response . data )
    case let . failed ( error ) :
        print ( error )
    default :
        break
    }
}

rxswift

يوفر امتداد RxSwift أيضًا كل من rx.request(:callbackQueue:) و rx.requestWithProgress(:callbackQueue:) الأساليب ، ولكن نوع الإرجاع مختلف لكليهما. في حالة وجود rx.request(:callbackQueue) ، يكون نوع الإرجاع Single<Response> الذي ينبعث منه إما عنصر واحد أو خطأ. في حالة rx.requestWithProgress(:callbackQueue:) ، يمكن Observable<ProgressResponse> ، حيث قد نحصل على أحداث متعددة من التقدم وحدث أخير وهو رد.

للتعامل مع الأخطاء ، على سبيل المثال ، يمكننا القيام بما يلي:

provider = MoyaProvider < GitHub > ( )
provider . rx . request ( . userProfile ( " ashfurrow " ) ) . subscribe { event in
    switch event {
    case let . success ( response ) :
        image = UIImage ( data : response . data )
    case let . error ( error ) :
        print ( error )
    }
}

بالإضافة إلى خيار استخدام الإشارات بدلاً من كتل رد الاتصال ، هناك أيضًا سلسلة من مشغلي الإشارات لـ RXSWIFT و Reactiveswift التي ستحاول تعيين البيانات المستلمة من استجابة الشبكة إلى صورة أو بعض JSON أو سلسلة ، مع mapImage() ، و mapJSON() ، و mapString() ، على التوالي. إذا كان التعيين غير ناجح ، فستحصل على خطأ في الإشارة. يمكنك أيضًا الحصول على طرق مفيدة لتصفية رموز الحالة معينة. هذا يعني أنه يمكنك وضع الكود الخاص بك للتعامل مع أخطاء API مثل 400 في نفس الأماكن مثل التعليمات البرمجية للتعامل مع الاستجابات غير الصالحة.

يجمع

يوفر Combine extension requestPublisher(:callbackQueue:) و requestWithProgressPublisher(:callbackQueue) العودة AnyPublisher<Response, MoyaError> و AnyPublisher<ProgressResponse, MoyaError> على التوالي.

فيما يلي مثال على استخدام requestPublisher :

provider = MoyaProvider < GitHub > ( )
let cancellable = provider . requestPublisher ( . userProfile ( " ashfurrow " ) )
    . sink ( receiveCompletion : { completion in
        guard case let . failure ( error ) = completion else { return }

        print ( error )
    } , receiveValue : { response in
        image = UIImage ( data : response . data )
    } ) 

مشاريع المجتمع

لدى Moya مجتمعًا رائعًا حوله ، وقد خلق بعض الناس بعض الامتدادات المفيدة للغاية.

المساهمة

يا! هل تحب مويا؟ مذهل! يمكننا في الواقع استخدام مساعدتك!

المصدر المفتوح ليس مجرد كتابة رمز. يمكن لمويا استخدام مساعدتك في أي مما يلي:

• العثور على (والإبلاغ!) الأخطاء.
• اقتراحات ميزة جديدة.
• الإجابة على الأسئلة حول القضايا.
• تحسينات الوثائق.
• مراجعة طلبات السحب.
• المساعدة في إدارة أولويات القضية.
• إصلاح الأخطاء/الميزات الجديدة.

إذا كان أي من هذا يبدو رائعًا بالنسبة لك ، فأرسل طلب سحب! بعد مساهمتك الأولى ، سنضيفك كعضو إلى الريبو حتى تتمكن من دمج طلبات السحب والمساعدة في توجيه السفينة؟ يمكنك قراءة المزيد من التفاصيل حول ذلك في إرشادات المساهمين لدينا.

يمتلك مجتمع Moya طاقة إيجابية هائلة ، ويلتزم المشروعون بالحفاظ على الأمور رائعة. كما هو الحال في مجتمع Cocoapods ، افترض دائمًا نية إيجابية. حتى لو كان التعليق يبدو أن الروح المتوسطة ، فامنح الشخص فائدة الشك.

يرجى ملاحظة أن هذا المشروع يتم إصداره باستخدام مدونة سلوك المساهم. من خلال المشاركة في هذا المشروع ، فإنك توافق على الالتزام بشروطه.

إضافة ملفات مصدر جديدة

إذا قمت بإضافة أو إزالة ملف مصدر من Moya ، فيجب إجراء تغيير مماثل لمشروع Moya.xcodeproj في جذر هذا المستودع. يستخدم هذا المشروع في قرطاج. لا تقلق ، ستحصل على تحذير تلقائي عند تقديم طلب سحب إذا نسيت.

ساعدنا في تحسين وثائق Moya

سواء كنت عضوًا أساسيًا أو مستخدمًا يحاول ذلك لأول مرة ، يمكنك تقديم مساهمة قيمة في Moya من خلال تحسين الوثائق. ساعدنا من خلال:

• إرسال ملاحظات لنا حول شيء تعتقد أنه مربك أو مجرد مفقود.
• اقتراح صياغة أفضل أو طرق لشرح مواضيع معينة.
• إرسال طلب سحب لنا عبر جيثب.
• تحسين الوثائق الصينية.

رخصة

يتم إصدار Moya بموجب ترخيص MIT. انظر الترخيص. md لمزيد من المعلومات.