Moya-Basic.md
Basic Usage（基本用法）
如何来使用这个库呢？额，相当简单滴！只要跟随这个模板就好了。首先，使用一个枚举来设置你所有的API目标。注意，你可以把包含的信息作为枚举的一部分。下面，我们来看一个常用的例子。第一步，我们创建一个名为MyService.swift的文件：
enum MyService{
case zen
case showUser(id : Int)
case createUser(firstName:String,lastName:String)
case updateUser(id:Int,firstName:String,lastName:String)
case showAccounts
}
这个枚举被用来确保你为每个target（在编译时）提供具体的实现细节。您可以看到请求所需的参数可以被定义为每个枚举case情况下的参数。这个枚举必须遵循“TargetType”协议。我们在同一个文件中通过一个扩展来实现。
extension MyService: TargetType{
var baseURL:URL {return URL(String:"https://api.myservice.com")}
var path:String{
switch self{
case .zen:
return "/zen"
case .showUser(let id), .updateUser(let id, _, _):
return "/users/\(id)"
case .createUser(_, _):
return "/users"
case .showAccounts:
return "/accounts"
}
}
}
var method:Moya.Method{
switch self {
case .zen, .showUser, .showAccounts:
return .get
case .createUser, .updateUser:
return .post
}
}
var parameters:[String:Any]?{
switch self {
case .zen, .showUser, .showAccounts:
return nil
case .createUser(let firstName, let lastName), .updateUser(_, let firstName, let lastName):
return ["first_name": firstName, "last_name": lastName]
}
}
var parameterEncoding: ParameterEncoding {
switch self {
case .zen, .showUser, .showAccounts:
return URLEncoding.default
case .updateUser:
return URLEncoding.queryString
case .createUser:
return JSONEncoding.default
}
}
var sampleData: Data {
switch self {
case .zen:
return "Half measures are as bad as nothing at all.".utf8Encoded
case .showUser(let id):
return "{\"id\": \(id), \"first_name\": \"Harry\", \"last_name\": \"Potter\"}".utf8Encoded
case .createUser(let firstName, let lastName):
return "{\"id\": 100, \"first_name\": \"\(firstName)\", \"last_name\": \"\(lastName)\"}".utf8Encoded
case .updateUser(let id, let firstName, let lastName):
return "{\"id\": \(id), \"first_name\": \"\(firstName)\", \"last_name\": \"\(lastName)\"}".utf8Encoded
case .showAccounts:
// Provided you have a file named accounts.json in your bundle.
guard let url = Bundle.main.url(forResource: "accounts", withExtension: "json"),
let data = try? Data(contentsOf: url) else {
return Data()
}
return data
}
}
var task: Task {
switch self {
case .zen, .showUser, .createUser, .updateUser, .showAccounts:
return .request
}
}
}
// MARK: - Helpers
private extension String {
var urlEscaped: String {
return self.addingPercentEncoding(withAllowedCharacters: .urlHostAllowed)!
}
var utf8Encoded: Data {
return self.data(using: .utf8)!
}
}
(String的扩展仅为了方便使用，你必须非得去使用它)
你可以看到TargetType协议保证了每个枚举的值都转化为了一个完整的请求。每个完整的请求被分割成了baseURL、path(指定请求的子路径)、method(定义了HTTP的method)和可选的parameters。（ps：还有个task）
注意目前为止你已经为一个基本的API网络层添加了足够的信息。默认。Moya将会结合所有给定的参数为一个完整的请求：
let provider = MoyaProvider()
provider.request(.createUser(firstName:"James",lastName:"Potter")){result in
// do something with the result (read on for more details)
}
// The full request will result to the following:
// POST https://api.myservice.com/users
// Request body:
// {
// "first_name": "James",
// "last_name": "Potter"
// }
provider.request(.updateUser(id: 123, firstName: "Harry", lastName: "Potter")) { result in
// do something with the result (read on for more details)
}
// The full request will result to the following:
// POST https://api.myservice.com/users/123?first_name=Harry&last_name=Potter
TargetType指定了API的基础URL，同时也为每个枚举值指定了样例数据。这个数据是Data类型的实例对象，它可以代表JSON，images,text,任何你期望从后端返回的数据。
你也可以设置自定义的endpoint来替代默认的行为，从而来满足你的需求。比如：
public func url(route: TargetType) -> String {
return route.baseURL.appendingPathComponent(route.path).absoluteString
}
let endpointClosure = { (target: MyService) -> Endpoint in
return Endpoint(url: url(target), sampleResponseClosure: {.networkResponse(200, target.sampleData)}, method: target.method, parameters: target.parameters)
}
每次当一个API调用被发起的时候,你提供的闭包将会被调用.它的责任是返回一个设置好的Endpoint实例给到Moya使用.传递到闭包的参数可以让你配置Endpoint--这些个参数不会自动的传递到网络请求上,所以如果需要的话可以把它们添加到Endpoint.它们可能是一些app内在的数据，用来帮助配置Endpoint.在这个事例中,尽管它们仅仅传递了一下
大多数情况下,这个闭包是直接把target，method，parameter组装成一个Endpoint实例.而且,由于它是一个闭包并且可以在每次API调用的时候被执行,所以你可以做任何你想要的. 比如,你想在测试网络错误,如超时等.
let failureEndpointClosure = { (target: MyService) -> Endpoint in
let sampleResponseClosure = { () -> (EndpointSampleResponse) in
if shouldTimeout {
return .networkError(NSError())
} else {
return .networkResponse(200, target.sampleData)
}
}
return Endpoint(url: url(target), sampleResponseClosure: sampleResponseClosure, method: target.method, parameters: target.parameters)
}
注意,里面的返回的sample数据是必须.这是Moya的一个亮点,它可以很容易的用来测试app或者使用stub来响应API的请求.
非常好,目前我们已经设置完所有的了,下面需要创建我们的provider
// Tuck this away somewhere where it'll be visible to anyone who wants to use it
var provider: MoyaProvider!
// Create this instance at app launch
let provider = MoyaProvider(endpointClosure: endpointClosure)
如何发送请求呢?
provider.request(.zen) { result in
// do something with `result`
}
请求方法接收了包含创建Endpoint的所需要的Myservice的value(.zen)--或者在测试的时候返回一个stub的响应.
Endpoint实例用来创建URLRequest(已经被Alamofire做了),request将会被发送(同样是被Alamofire做了).一旦Alamofire得到了一个response(或者失败了),Moya将会把成功或者失败用枚举Result包裹起来,结果要么是.success(Moya.Response) 要么是failure(MoyaError).
你将需要从Moya.Response中解包数据和状态码
provider.request(.zen) { result in
switch result {
case let .success(moyaResponse):
let data = moyaResponse.data // Data, your JSON response is probably in here!
let statusCode = moyaResponse.statusCode // Int - 200, 401, 500, etc
// do something in your app
case let .failure(error):
// TODO: handle the error == best. comment. ever.
}
}
特别注意 .failure,它意味着服务器要么没收到请求(比如,请求时网络连接有问题),或者服务器没有发送response(比如,请求超时).如果你得到一个.failure事件,你可能想在一段时间后或者当网络连接可用时再来发送请求.
一旦你有一个.success(response)你可能想过了状态码或者把响应数据转化为JSON.
Moya.Response可以帮忙!
更多查看
do {
try moyaResponse.filterSuccessfulStatusCodes()
let data = try moyaResponse.mapJSON()
}
catch {
// show an error to your user
}
总结 这小节的核心:
创建符合TargetType协议的enum对象,(TargetType里面有URLRequest所需的各种数据片段)
创建MoyaProvider默认对象provider
使用provider发起request请求
使用自定义的Endpoint来创建MoyaProvider( MoyaProvider(endpointClosure: endpointClosure))
对request后的返回结果的处理(.success(Moya.Response) or .failure(MoyaError).).可以对成功返回的结果过滤状态码(moyaResponse.filterSuccessfulStatusCodes())
ps: 路径又称"终点"（endpoint），表示API的具体网址。