Moya
15.0.3
Une version chinoise de ce document peut être trouvée ici.
Vous êtes un développeur intelligent. Vous utilisez probablement Alamofire pour résumer l'accès à URLSession et tous ces détails désagréables qui ne vous soucient pas vraiment. Mais ensuite, comme beaucoup de développeurs intelligents, vous écrivez des couches d'abstraction de réseau ad hoc. Ils sont probablement appelés "apimanager" ou "NetworkModel", et ils se terminent toujours en larmes.
Les couches de réseau ad hoc sont courantes dans les applications iOS. Ils sont mauvais pour plusieurs raisons:
L'idée de base de Moya est donc que nous voulons une couche d'abstraction de réseau qui résume suffisamment en appelant réellement l'allamofire directement. Il devrait être assez simple que les choses courantes soient faciles, mais suffisamment complets pour que les choses compliquées soient également faciles.
Si vous utilisez l'allamofire pour résumer
URLSession, pourquoi ne pas utiliser quelque chose pour abstraire la moitié des URL, des paramètres, etc.?
Quelques fonctionnalités impressionnantes de Moya:
Vous pouvez en savoir plus sur la direction du projet dans le document Vision.
Nous avons fourni deux exemples de projets dans le référentiel. Pour l'utiliser, téléchargez le dépôt, exécutez carthage update pour télécharger les bibliothèques requises et ouvrir moya.xcodeproj. Vous verrez deux schémas: Basic et Multi-Target - sélectionnez-en un, puis construisez et exécutez! Les fichiers source pour ceux-ci sont dans le répertoire Examples dans Project Navigator. Amusez-vous!
Ce projet est activement en cours de développement et est utilisé dans l'application d'enchères d'Artsy. Nous le considérons comme prêt pour une utilisation en production.
Vous trouverez ci-dessous un tableau qui montre la version de Moya que vous devez utiliser pour votre version rapide.
| Rapide | Moya | Rxmoya | Reactivemoya | Rxswift | Reactifswift | Alamofire |
|---|---|---|---|---|---|---|
| > = 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 | - | - | - |
Remarque: Si vous utilisez Swift 4.2 dans votre projet, mais que vous utilisez Xcode 10.2, Moya 13 devrait fonctionner correctement même si nous utilisons SWIFT 5.0.
Mise à niveau vers une nouvelle version majeure de Moya? Découvrez nos guides de migration.
Remarque: les instructions ci-dessous sont pour l'utilisation de SWIFTPM sans l'interface utilisateur Xcode. Il est le plus facile d'aller dans les paramètres de votre projet -> Packages Swift et d'ajouter Moya à partir de là.
Pour intégrer à l'aide de Swift Package Manager d'Apple, sans intégration Xcode, ajoutez ce qui suit en tant que dépendance à votre Package.swift :
. package ( url : " https://github.com/Moya/Moya.git " , . upToNextMajor ( from : " 15.0.0 " ) ) puis spécifiez "Moya" comme dépendance de la cible dans laquelle vous souhaitez utiliser Moya. Si vous souhaitez utiliser des extensions réactives, ajoutez également "ReactiveMoya" , "RxMoya" ou "CombineMoya" comme dépendance cible respectivement. Voici un exemple 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 " ] )
]
)Combinez Remarque: si vous utilisez Combinemoya , assurez-vous d'utiliser Xcode 11.5.0 ou version ultérieure. Avec les versions antérieures de Xcode, vous devrez ajouter manuellement Combine en tant que cadre faiblement lié à votre objectif d'application.
ACCIO est un gestionnaire de dépendances basé sur SWIFTPM qui peut créer des frameworks pour iOS / MacOS / TVOS / WatchOS. Par conséquent, les étapes d'intégration de Moya sont exactement les mêmes que celles décrites ci-dessus. Une fois votre fichier Package.swift configuré, exécutez accio update au lieu de swift package update .
Pour Moya, utilisez l'entrée suivante dans votre podfile:
pod 'Moya' , '~> 15.0'
# or
pod 'Moya/RxSwift' , '~> 15.0'
# or
pod 'Moya/ReactiveSwift' , '~> 15.0'
# or
pod 'Moya/Combine' , '~> 15.0' Puis exécutez pod install .
Dans n'importe quel fichier dans lequel vous souhaitez utiliser Moya, n'oubliez pas d'importer le framework avec import Moya .
Les utilisateurs de Carthage peuvent pointer vers ce référentiel et utiliser le cadre généré qu'ils souhaitent, Moya , RxMoya , ReactiveMoya ou CombineMoya .
Faites l'entrée suivante dans votre carton:
github "Moya/Moya" ~> 15.0
Ensuite, exécutez carthage update --use-xcframeworks .
Si c'est la première fois que vous utilisez Carthage dans le projet, vous devrez passer par quelques étapes supplémentaires comme expliqué à Carthage.
Remarque: Pour le moment, Carthage ne fournit pas de moyen de créer uniquement des sous-modules de référentiel spécifiques. Tous les sous-modules et leurs dépendances seront construits avec la commande ci-dessus. Cependant, vous n'avez pas besoin de copier des cadres que vous n'utilisez pas dans votre projet. Par exemple, si vous n'utilisez pas
ReactiveSwift, n'hésitez pas à supprimer ce cadre avecReactiveMoyadu répertoire de construction de Carthage une foiscarthage updateterminée. Ou si vous utilisezReactiveSwiftmais pasRxSwiftouCombine, alorsRxMoya,RxTest,RxCocoa,CombineMoyaetc. peuvent être supprimés en toute sécurité.
cd dans votre répertoire de projet de niveau supérieur et exécutez la commande suivante si votre projet n'est pas initialisé en tant que référentiel GIT: $ git init$ git submodule add https://github.com/Alamofire/Alamofire.git
$ git submodule add https://github.com/Moya/Moya.gitAlamofire et faites glisser le Alamofire.xcodeproj dans le navigateur de projet du projet Xcode de votre application. Faites de même avec le Moya.xcodeproj dans le dossier Moya .Ils devraient apparaître imbriqués sous l'icône du projet bleu de votre application. Que ce soit au-dessus ou en dessous de tous les autres groupes Xcode n'a pas d'importance.
xcodeproj correspondent à celle de votre objectif d'application dans le Navigator du projet.+ sous la section "Binaires intégrés".Alamofire.xcodeproj différents avec deux versions différentes de l' Alamofire.framework imbriqué dans un dossier Products .Peu importe le dossier
Productsque vous choisissez, mais il est important que vous choisissiez le haut ou le basAlamofire.framework.
Alamofire.framework pour iOS et le bas pour macOS.Vous pouvez vérifier celui que vous avez sélectionné en inspectant le journal de construction pour votre projet. L'objectif de construction pour
Alamofiresera répertorié commeAlamofire iOS,Alamofire macOS,Alamofire tvOSouAlamofire watchOS.
Cliquez sur le bouton + sous "Binaires intégrés" et ajoutez à nouveau la cible de construction correcte pour Moya .
Et c'est tout!
Les trois frameworks sont ajoutés automatiquement en tant que dépendance cible, cadre lié et cadre intégré dans une phase de construction de fichiers de copie qui est tout ce dont vous avez besoin pour construire sur le simulateur et un appareil.
Après une configuration, l'utilisation de Moya est vraiment simple. Vous pouvez accéder à une API comme ceci:
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.
}
}C'est un exemple de base. De nombreuses demandes d'API nécessitent des paramètres. Moya les code dans l'énumération que vous utilisez pour accéder au point de terminaison, comme ceci:
provider = MoyaProvider < GitHub > ( )
provider . request ( . userProfile ( " ashfurrow " ) ) { result in
// do something with the result
}Plus de fautes de frappe dans les URL. Plus de valeurs de paramètres manquantes. Plus de gâchis avec le codage des paramètres.
Pour plus d'exemples, consultez la documentation.
Les extensions réactives sont encore plus froides. Moya fournit des extensions réactives pour ReactivesWift, RxSwift et Combine.
ReactiveSwift Extension fournit à la fois reactive.request(:callbackQueue:) et reactive.requestWithProgress(:callbackQueue:) méthodes qui renvoient immédiatement SignalProducer S que vous pouvez démarrer, lier, mapper ou tout ce que vous voulez faire. Pour gérer les erreurs, par exemple, nous pourrions faire ce qui suit:
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
}
} L'extension RxSwift fournit également à la fois rx.request(:callbackQueue:) et rx.requestWithProgress(:callbackQueue:) méthodes, mais le type de retour est différent pour les deux. Dans le cas d'un rx.request(:callbackQueue) , le type de retour est Single<Response> qui émet un élément unique ou une erreur. Dans le cas d'un rx.requestWithProgress(:callbackQueue:) , le type de retour est Observable<ProgressResponse> , car nous pouvons obtenir plusieurs événements de Progress et un dernier événement qui est une réponse.
Pour gérer les erreurs, par exemple, nous pourrions faire ce qui suit:
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 )
}
} En plus de l'option d'utiliser des signaux au lieu de blocs de rappel, il existe également une série d'opérateurs de signal pour RXSWift et ReactivesWift qui tentera de mapper les données reçues de la réponse du réseau dans une image, un JSON ou une chaîne, avec mapImage() , mapJSON() et mapString() , respectivement. Si le mappage est infructueux, vous obtiendrez une erreur sur le signal. Vous obtenez également des méthodes pratiques pour filtrer certains codes d'état. Cela signifie que vous pouvez placer votre code pour gérer les erreurs d'API comme 400 aux mêmes endroits que le code pour gérer les réponses non valides.
Combine Extension Fournit requestPublisher(:callbackQueue:) et requestWithProgressPublisher(:callbackQueue) renvoyant AnyPublisher<Response, MoyaError> et AnyPublisher<ProgressResponse, MoyaError> respectivement.
Voici un exemple d'utilisation 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 a une grande communauté autour de lui et certaines personnes ont créé des extensions très utiles.
Hé! Aimez-vous Moya? Génial! Nous pourrions vraiment utiliser votre aide!
Open Source n'écrit pas seulement du code. Moya pourrait utiliser votre aide avec l'une des éléments suivants:
Si tout cela vous semble cool, envoyez une demande de traction! Après votre première contribution, nous vous ajouterons en tant que membre au dépôt afin que vous puissiez fusionner les demandes de traction et aider à diriger le navire? Vous pouvez lire plus de détails à ce sujet dans nos directives de contributeurs.
La communauté de Moya a une énorme énergie positive, et les mainteneurs se sont engagés à garder les choses géniales. Comme dans la communauté Cocoapods, assumez toujours une intention positive. Même si un commentaire semble mesquin, donnez à la personne le bénéfice du doute.
Veuillez noter que ce projet est publié avec un code de conduite de contributeur. En participant à ce projet, vous acceptez de respecter ses conditions.
Si vous ajoutez ou supprimez un fichier source de Moya, un changement correspondant doit être apporté au projet Moya.xcodeproj à la racine de ce référentiel. Ce projet est utilisé pour Carthage. Ne vous inquiétez pas, vous obtiendrez un avertissement automatisé lors de la soumission d'une demande de traction si vous oubliez.
Que vous soyez un membre de base ou un utilisateur qui l'essaie pour la première fois, vous pouvez apporter une contribution précieuse à Moya en améliorant la documentation. Aidez-nous par:
Moya est libéré sous une licence du MIT. Voir Licence.md pour plus d'informations.
