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

Moya-Basic.md

Basic Usage（基本用法）

如何來使用這個庫呢？額，相當(dāng)簡單滴！只要跟隨這個模板就好了。首先，使用一個枚舉來設(shè)置你所有的API目標(biāo)。注意，你可以把包含的信息作為枚舉的一部分。下面，我們來看一個常用的例子。第一步，我們創(chuàng)建一個名為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（在編譯時）提供具體的實現(xiàn)細(xì)節(jié)。您可以看到請求所需的參數(shù)可以被定義為每個枚舉case情況下的參數(shù)。這個枚舉必須遵循“TargetType”協(xié)議。我們在同一個文件中通過一個擴展來實現(xiàn)。

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協(xié)議保證了每個枚舉的值都轉(zhuǎn)化為了一個完整的請求。每個完整的請求被分割成了baseURL、path(指定請求的子路徑)、method(定義了HTTP的method)和可選的parameters。（ps：還有個task）

注意目前為止你已經(jīng)為一個基本的API網(wǎng)絡(luò)層添加了足夠的信息。默認(rèn)。Moya將會結(jié)合所有給定的參數(shù)為一個完整的請求：

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的基礎(chǔ)URL，同時也為每個枚舉值指定了樣例數(shù)據(jù)。這個數(shù)據(jù)是Data類型的實例對象，它可以代表JSON，images,text,任何你期望從后端返回的數(shù)據(jù)。

你也可以設(shè)置自定義的endpoint來替代默認(rèn)的行為，從而來滿足你的需求。比如：

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)
}

每次當(dāng)一個API調(diào)用被發(fā)起的時候,你提供的閉包將會被調(diào)用.它的責(zé)任是返回一個設(shè)置好的Endpoint實例給到Moya使用.傳遞到閉包的參數(shù)可以讓你配置Endpoint--這些個參數(shù)不會自動的傳遞到網(wǎng)絡(luò)請求上,所以如果需要的話可以把它們添加到Endpoint.它們可能是一些app內(nèi)在的數(shù)據(jù)，用來幫助配置Endpoint.在這個事例中,盡管它們僅僅傳遞了一下

大多數(shù)情況下,這個閉包是直接把target，method，parameter組裝成一個Endpoint實例.而且,由于它是一個閉包并且可以在每次API調(diào)用的時候被執(zhí)行,所以你可以做任何你想要的. 比如,你想在測試網(wǎng)絡(luò)錯誤,如超時等.

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數(shù)據(jù)是必須.這是Moya的一個亮點,它可以很容易的用來測試app或者使用stub來響應(yīng)API的請求.

非常好,目前我們已經(jīng)設(shè)置完所有的了,下面需要創(chuàng)建我們的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)

如何發(fā)送請求呢?

provider.request(.zen) { result in
// do something with `result`
}

請求方法接收了包含創(chuàng)建Endpoint的所需要的Myservice的value(.zen)--或者在測試的時候返回一個stub的響應(yīng).

Endpoint實例用來創(chuàng)建URLRequest(已經(jīng)被Alamofire做了),request將會被發(fā)送(同樣是被Alamofire做了).一旦Alamofire得到了一個response(或者失敗了),Moya將會把成功或者失敗用枚舉Result包裹起來,結(jié)果要么是.success(Moya.Response) 要么是failure(MoyaError).
你將需要從Moya.Response中解包數(shù)據(jù)和狀態(tài)碼

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,它意味著服務(wù)器要么沒收到請求(比如,請求時網(wǎng)絡(luò)連接有問題),或者服務(wù)器沒有發(fā)送response(比如,請求超時).如果你得到一個.failure事件,你可能想在一段時間后或者當(dāng)網(wǎng)絡(luò)連接可用時再來發(fā)送請求.

一旦你有一個.success(response)你可能想過了狀態(tài)碼或者把響應(yīng)數(shù)據(jù)轉(zhuǎn)化為JSON.
Moya.Response可以幫忙!

更多查看

do {
try moyaResponse.filterSuccessfulStatusCodes()
let data = try moyaResponse.mapJSON()
}
catch {
// show an error to your user
}

總結(jié) 這小節(jié)的核心:

  1. 創(chuàng)建符合TargetType協(xié)議的enum對象,(TargetType里面有URLRequest所需的各種數(shù)據(jù)片段)

  2. 創(chuàng)建MoyaProvider默認(rèn)對象provider

  3. 使用provider發(fā)起request請求

  4. 使用自定義的Endpoint來創(chuàng)建MoyaProvider( MoyaProvider(endpointClosure: endpointClosure))

  5. 對request后的返回結(jié)果的處理(.success(Moya.Response) or .failure(MoyaError).).可以對成功返回的結(jié)果過濾狀態(tài)碼(moyaResponse.filterSuccessfulStatusCodes())

ps: 路徑又稱"終點"（endpoint），表示API的具體網(wǎng)址。

最后編輯于 ：
?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成，瀏覽時請結(jié)合常識與多方信息審慎甄別。
平臺聲明：文章內(nèi)容（如有圖片或視頻亦包括在內(nèi)）由作者上傳并發(fā)布，文章內(nèi)容僅代表作者本人觀點，簡書系信息發(fā)布平臺，僅提供信息存儲服務(wù)。

相關(guān)閱讀更多精彩內(nèi)容

友情鏈接更多精彩內(nèi)容