IQAPIClient 4.0.1

IQAPIClient 4.0.1

×

由Mohd Iftekhar Qurashi维护。

IQAPIClient 4.0.1

  • 作者
  • Iftekhar Qurashi

IQAPIClient

基于模型的API客户端

Build Status

IQAPIClient允许我们使用定义的模型对象来发送API请求并获取响应。

要求

Platform iOS

库 语言 最低iOS目标版本 最低Xcode版本
IQAPIClient Swift iOS 10.0 Xcode 11

支持的Swift版本

5.0及以上

安装

CocoaPods 安装

CocoaPods

IQAPIClient 通过 CocoaPods 提供。要安装它，只需要在 Podfile 中添加以下行

pod 'IQAPIClient'

或者您可以根据 Swift 支持表格从 要求 中选择您需要的版本

pod 'IQAPIClient', '1.0.0'

源代码安装

Github tag

拖拽 IQAPIClient 目录从演示项目到您的项目

使用 Swift Package Manager 安装

Swift Package Manager(SPM) 是苹果的依赖管理工具。现在它在 Xcode 11 中得到支持。因此，它可以在所有 appleOS 类型的项目中使用。它也可以与其他工具（如 CocoaPods 和 Carthage）一起使用。

要将 IQAPIClient 包安装到您的包中，请在 Package.swift 文件的依赖关系部分添加对 IQAPIClient 和目标发布版本的引用

import PackageDescription

let package = Package(
    name: "YOUR_PROJECT_NAME",
    products: [],
    dependencies: [
        .package(url: "https://github.com/hackiftekhar/IQAPIClient.git", from: "1.0.0")
    ]
)

要通过 Xcode 安装 IQAPIClient 包

基本配置

好了，在使用 IQAPIClient 前我们需要先进行初始化配置，比如设置 API 基础 URL 和默认头部等。你可以在 AppDelegate 中完成这些操作。

        IQAPIClient.baseURL = URL(string: "https://www.example.com/api/v1")
        IQAPIClient.httpHeaders["Content-Type"] = "application/json"
        IQAPIClient.httpHeaders["Accept"] = "application/json"

配置我们的模型

假设你有一个 API 返回用户列表，并且你有一个 User 模型针对那个 API。

struct User {

    let id: Int

    let name: String

    let email: String?
}

首先，我们需要修改我们的模型以使其与 IQAPIClient 兼容。为此，我们只需确认我们的 User Model 符合 Decodable 协议即可。

// Now it's ready to be used with IQAPIClient
struct User: Decodable {

    let id: Int

    let name: String

    let email: String?
}

IQAPIClient 基础方法签名

Swift.Result 版本

static func sendRequest<Success>(
            path: String,
            method: HTTPMethod = .get,
            parameters: Parameters? = nil,
            completionHandler: @escaping
            (_ result: Swift.Result<Success, Error>) -> Void)

其中原生的 Swift.Result 如此所示

enum Result<Success, Failure> where Failure: Error {
    case success(Success)	/// A success, storing a `Success` value.
    case failure(Failure)	/// A failure, storing a `Failure` value.
}

IQAPIClient.Result 版本

static func sendRequest<Success, Failure>(
            path: String,
            method: HTTPMethod = .get,
            parameters: Parameters? = nil,
            completionHandler: @escaping 
            (_ result: IQAPIClient.Result<Success, Failure>) -> Void)

其中 IQAPIClient.Result 如此所示

enum Result<Success, Failure> {
    case success(Success)	/// A success, storing a `Success` value.
    case failure(Failure)	/// A failure, storing a `Failure` value.
    case error(Error)		/// An error, storing an `Error` value.
}

使用 IQAPIClient 进行 API 调用

要获取用户列表，您可以使用 IQAPIClient 的几种方法。

方法 1：直接使用 sendRequest 方法（Swift.Result 版本）

class ViewController: UIViewController {

    private func getUsersList() {
        //Result<[User], NSError> detects that the app is asking for array of User object
        IQAPIClient.sendRequest(path: "/users") { [weak self] (result: Swift.Result<[User], NSError>) in
            switch result {
            case .success(let users):
                self?.users = users
                self?.refreshUI()
            case .failure(let error):
                //Show error alert
                print(error.localizedDescription)
            }
        }
    }
}

方法 2：相同的请求但使用 IQAPIClient.Result 版本

假设 APIMessage 的外观如下，当出错时我们获得如下响应：

struct APIMessage: Decodable {
    let status: Bool
    let code: Int
    let message: String
}
class ViewController: UIViewController {

    private func getUsersList() {
        //Result<[User], NSError> detects that the app is asking for array of User object
        IQAPIClient.sendRequest(path: "/users") { [weak self] (result: Swift.Result<[User], APIMessage>) in
            switch result {
            case .success(let users):   //[User] object
                self?.users = users
                self?.refreshUI()
            case .failure(let message): //APIMessage object
                //Show failure alert
                print(message.code)
                print(message.message)
            case .error(let error):     //Error object
                //Show error alert
                print(error.localizedDescription)
            }
        }
    }
}

方法 2：将此调用移动到 IQAPIClient 扩展中的函数

extension IQAPIClient {

    @discardableResult
    static func getUsersList(completionHandler: @escaping (_ result: Swift.Result<User, NSError>) -> Void) -> DataRequest {
        return sendRequest(path: "/users", completionHandler: completionHandler)
    }
}

方法3：如果您还没有模型，您也可以以如下字典数组形式接收到响应

extension IQAPIClient {

    @discardableResult
    static func getUsersList(completionHandler: @escaping (_ result: Swift.Result<[[String:Any]], NSError>) -> Void) -> DataRequest {
        return sendRequest(path: "/users", completionHandler: completionHandler)
    }
}

class ViewController: UIViewController {

    private func getUsersList() {
        
        //Now use the getUsersList function
        IQAPIClient.getUsersList { [weak self] result in
            switch result {
            case .success(let users):
                self?.users = users
                self?.refreshUI()
            case .failure(let error):
                //Show error alert
                print(error.localizedDescription)
            }
        }
    }
}

高级配置

sendRequest方法的高级参数

- successSound: Bool = false  //A success sound/vibration will be played on success response, you could use it when you create some records like saving something in the server.
- failedSound: Bool = false   //An error sound/vibration will be played on error 
- executeErroHandlerOnError: Bool = true  //This will also execute common error handler block on error to handle all error from a single place.

//待补充示例

授权协议

根据MIT授权协议分发。

贡献

任何贡献都欢迎！您可以通过GitHub上的拉取请求和问题来进行贡献。

作者

如果您想联系我，请给我发邮件： [email protected]