你是个聪明的开发者。你可能使用 Alamofire 来抽象对 URLSession
的访问,以及所有那些你并不关心的糟糕细节。但是接下来,就像许多聪明开发者一样,你编写专有的网络抽象层,它们可能被称作 "APIManager" 或 "NetworkModel",它们的下场总是很惨。
在 iOS app 中,专有网络层非常常见,但它们有以下缺点:
所以 Moya 的基本思想是,提供一些网络抽象层,它们经过充分地封装,并直接调用 Alamofire。它们应该足够简单,可以很轻松地应对常见任务,也应该足够全面,应对复杂任务也同样容易。
如果你使用 Alamofire 来抽象
URLSession
, 那为什么不使用某些方式来进一步抽象 URLs 和 parameters 等等的本质呢?
Moya 的一些特色功能:
你可以在 愿景文档 中查看更多关于项目方向的信息。
我们在仓库中提供了两个示例项目。要使用它,请下载仓库,运行 carthage update
下载所需的库,然后打开 [Moya.xcodeproj](https://github.com/Moya/Moya/tree/master/Moya.xcodeproj)。你会看到两个 scheme:Basic
和 Multi-Target
——选择一个然后构建并运行!这些源文件位于项目导航的 Examples
目录中。玩得开心!
这个项目正在积极地开发中,并且它正被用于 Artsy 的新拍卖应用。我们认为它已经可以用于生产了。
下边的表格展示了 Moya 版本与其对应的 Swift 版本。
Swift | Moya | RxMoya | ReactiveMoya |
---|---|---|---|
5.X | >= 13.0.0 | >= 13.0.0 | >= 13.0.0 |
4.X | 9.0.0 - 12.0.1 | 10.0.0 - 12.0.1 | 9.0.0 - 12.0.1 |
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 |
升级到 Moya 的最新主版本?查看我们的 迁移向导。
要使用苹果的 Swift Package Manager 集成,将以下内容作为依赖添加到你的 Package.swift
:
.package(url: "https://github.com/Moya/Moya.git", .upToNextMajor(from: "14.0.0"))
然后指定 "Moya"
为你想要使用 Moya 的 Target 的依赖。如果你想要使用响应式扩展,将 "ReactiveMoya"
和 "RxMoya"
也也作为依赖加入进来。这里是一个 PackageDescription
实例:
// swift-tools-version:5.0
import PackageDescription
let package = Package(
name: "MyPackage",
products: [
.library(
name: "MyPackage",
targets: ["MyPackage"]),
],
dependencies: [
.package(url: "https://github.com/Moya/Moya.git", .upToNextMajor(from: "14.0.0"))
],
targets: [
.target(
name: "MyPackage",
dependencies: ["ReactiveMoya"])
]
)
注意从 Moya 10 开始,SPM 仅适用于 Swift 4 与更高版本的工具链。
在你的 Podfile 文件中添加 Moya:
pod 'Moya', '~> 14.0'
# or
pod 'Moya/RxSwift', '~> 14.0'
# or
pod 'Moya/ReactiveSwift', '~> 14.0'
然后运行 pod install
。
在任何你想使用 Moya 的文件中,使用 import Moya
导入框架。
Carthage 用户可以指向这个仓库并使用他们喜欢的生成框架,Moya
,RxMoya
或者 ReactiveMoya
。
在你的 Cartfile 中添加下面的代码:
github "Moya/Moya" ~> 14.0
然后运行 carthage update
。
如果这是你首次在项目中使用 Carthage,你将需要进行一些额外的步骤,它们在 Carthage 中有解释。
注意:目前,Carthage 没有提供仅构建特定仓库子模块的方法。使用上述命令将构建所有子模块及其依赖项。但是,你不必将不使用的框架复制到项目中。例如,如果您没有使用 ReactiveSwift,请在
carthage update
完成后随意从 Carthage 的构建目录中删除框架 ReactiveMoya。或者如果你使用的是 ReactiveSwift 而不是 RxSwift,则可以安全地删除 RxMoya,RxTest,RxCocoa 等。
cd
到你项目的顶层目录,如果你的项目没有初始化为 git 仓库,运行下面的命令:$ git init
$ git submodule add https://github.com/Alamofire/Alamofire.git
$ git submodule add https://github.com/antitypical/Result.git
$ git submodule add https://github.com/Moya/Moya.git
Alamofire
文件夹,把 Alamofire.xcodeproj
拖拽到你 XCode 的项目导航中。对 Result 文件夹下的 Result.xcodeproj
和 Moya 文件夹下的 Moya.xcodeproj
做同样的操作。它们应该嵌套在应用程序的蓝色项目图标下面,在其它 Xcode group 的上面或者下面都没关系。
xcodeproj
的部署 target 与你项目导航中的应用程序 target 一致。+
按钮。Alamofire.xcodeproj
文件夹。每个文件夹都有两个不同版本的 Alamofire.framework
嵌套在 Products
文件夹里。选择哪个
Products
文件夹并不重要,重要的是你选择的是上边的还是下边的Alamofire.framework
。
Alamofire.framework
,下边的用于 macOS。你可以通过检查项目的构建日志来验证你选择的是哪一个。
Alamofire
的 build target 将被列为Alamofire iOS
,Alamofire macOS
,Alamofire tvOS
或Alamofire watchOS
。
点击 "Embedded Binaries" 下面的 +
按钮,为 Result
添加你需要的 build target。
再次点击 +
按钮为 Moya
添加正确的 build target。
这就完事了!
这三个框架会作为 target dependency,linked framework 和 embedded framework 被自动添加到一个 copy files build phase,这就是在模拟器和设备进行构建所需要的全部内容了。
经过 一些设置 后,使用 Moya 相当简单。你可以用下边的方式访问一个 API:
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 将参数编码到 enum 中来访问端点,如下所示:
provider = MoyaProvider<GitHub>()
provider.request(.userProfile("ashfurrow")) { result in
// do something with the result
}
URLs 不再有书写错误。不再会缺失参数值。也不再有混乱的参数编码。
更多示例可以查看 documentation。
更酷的是响应式扩展。Moya 为 ReactiveSwift 和 RxSwift 提供了响应式扩展。
ReactiveSwift
extension 提供了 reactive.request(:callbackQueue:)
和 reactive.requestWithProgress(:callbackQueue:)
两种立即返回 SignalProducer
对象的方法,你可以 start,bind,map 或做任何你想做的。
对于错误处理,举例来说,我们可以像下面这样处理:
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
extension 也提供了 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 还有一系列信号操作符,它们可以把从网络响应接收到的数据分别通过 mapImage()
,mapJSON()
以及 mapString()
映射成一个图片、一些 json 或者一个字符串。如果映射不成功,你会从信号中得到一个错误。你还可以使用一些方便的方法来过滤某些状态码。这意味着你可以将处理 API 错误(比如 400)的代码与处理无效响应的代码写在相同的位置。
Moya 有一个很棒的社区,有些人已经创建了一些非常有用的扩展。
嗨!你喜欢 Moya 吗?非常棒!我们的确需要你的帮助!
开源不仅仅是写代码。Moya 可以在以下几个方面需要你的帮助:
如果你对其中任何一个感兴趣,请发送一个请求!经过几轮贡献,我们会把你作为管理员添加到 repo 中,这样你就可以合并 pull 请求并且帮助驾驶这艘船 🚢。你可以在我们的 贡献指南 中阅读更多详情。
Moya 社区拥有巨大的正能量,同时维护人员致力于让事情变得更棒。像 CocoaPods 一样,总是提取积极的意图;即使某个评论听起来非常刻薄,它仍会让人从怀疑中受益。
请注意,这个项目与 Contributor Code of Conduct 一起发布。为了参与到这个项目中来,你需要遵守它的 条款。
如果你从 Moya 添加或者移除一个源文件,仓库的根目录的 Moya.xcodeproj 也需要作出相应的改变。这个项目要用于 Carthage。但是别担心,如果你提交请求时忘了,会收到一个自动的警告。
无论你是核心成员还是用户,你可以通过改进文档对 Moya 做出重大的贡献。如何帮助我们:
Moya 是在 MIT license 下发布的。更多信息可以查看 License.md。
此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。