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<MyService>()
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<MyService> in
    return Endpoint<MyService>(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<MyService> in
let sampleResponseClosure = { () -> (EndpointSampleResponse) in
if shouldTimeout {
return .networkError(NSError())
} else {
return .networkResponse(200, target.sampleData)
}
}
return Endpoint<MyService>(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<MyService>!

// 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的具体网址。

Basic Usage（基本用法）--Moya文档

Basic Usage（基本用法）--Moya文档

Moya-Basic.md

Basic Usage（基本用法）

总结这小节的核心:

推荐阅读更多精彩内容

Basic Usage（基本用法）--Moya文档

Moya-Basic.md

Basic Usage（基本用法）

总结 这小节的核心:

推荐阅读更多精彩内容

总结这小节的核心: