RetrofireSwift

这是什么？

RetrofireSwift 是一个受 Retrofit 启发的库。由于 Retrofit 使用注解和代理，这些在 Swift 中不可用，因此这个库使用 Sourcery 的稍作定制的版本（称为 SourceryForRetrofire）来根据您在协议中编写的注释/注解来生成 Alamofire 的 SessionManager 扩展。只需查看 用法 部分以更好地理解它 :)。

示例

为了运行示例项目，首先克隆仓库，从 Example 目录运行 pod install

要求

您只需在项目中包含 cocoapods 即可。

安装

目前，安装此库的唯一官方方式是使用 CocoaPods；当然，您也可以从 GitHub (始终保持一致) 自己构建二进制文件，但在此期间遇到任何问题，我将无法提供帮助。

• 请将以下行添加到您的 Podfile 中

pod 'RetrofireSwift', '0.3.1' # Since this pod is not stable you need to specify its version

• 运行 pod install
• 在您的目标中 Build Phase 标签下添加一个 New Run Script Phase
• 将您新创建的脚本在 [CP] Check Pods Manifest.lock 和 Compile Sources (N items) 之间移动
• 在 Shell 框框下方添加以下脚本：$PODS_ROOT/RetrofireSwift/retrofire.sh
• 创建您的协议及其注释（更多详细信息请参阅 Usage 部分）
• 构建您的项目 (cmd-b)
• 在您的项目根目录下，您会看到一个新文件，Generated/RetrofireSourcery.generated.swift
• 将 Generated 文件夹拖放到 Xcode 中（如下 GIF 所示）
• 取消选中 Copy items if needed（如果已选中），选择 Create groups 并按 Finish
• 现在您可以开始使用自动生成的代码啦 :)

提示：您只需执行这些步骤一次，然后只需构建项目，所有内容都会自动更新

使用方法

以获取 GitHub 用户的仓库列表为例。我们需要请求的 URL 是 https://api.github.com/users/dcoletto/repos，其中 dcoletto 是用户名。响应是一个 JSON 文件，因此我们需要创建一个结构/类来存储我们的数据。注意：使用 Codable 协议，从而使 Retrofire 能够自动解析您的 JSON 并实例化您的 swift 对象

struct GithubRepo: Codable {
    var name: String
    var owner: GithubUser
}

struct GithubUser: Codable {
    var login: String
}

如您在上面示例中看到的，可以嵌套采用 Codable 协议的类/结构体。

现在我们需要设置协议（https）、基本 URL（api.github.com）和端口号（https 使用端口 443）

func setupRetrofire(){
    RetrofireConfig.networkProtocol = "https"
    RetrofireConfig.baseUrl = "api.github.com"
    RetrofireConfig.port = 443
}

最后一步，创建一个采用 Retrofire 协议的协议

protocol Api: Retrofire {
    // @GET = /users/{user}/repos
    func getRepo(
        /* @Path */ user: String
    ) -> [GithubRepo]
}

如您所见，您只需要定义一个函数，并在函数上方添加注释以定义一个注释来定义一个简单的 HTTP 调用。目前支持的 HTTP 方法是：@GET, @POST, @PATCH, @PUT, @DELETE 然后附加您的端点和编译时将出现魔法！如果要了解如何使用路径、查询或身体参数，请参阅下面的部分

如果您检查您的 Generated/RetrofireSourcery.generated.swift 文件夹，您会看到有一个对 SessionManager 的扩展方法。这样，你可以决定是使用默认的 Alamofire 的 SessionManager 还是创建自己的实现；以下是一个使用默认 SessionManager 的基本示例

SessionManager.default.getRepo(user: "dcoletto") { (repoList, error) in
    repoList?.forEach { repo in
        print("Repo \(repo.name) from \(repo.owner.login)")
    }
}

这样，仅用 11 行代码就生成了一个网络调用（即使算上闭合括号 :P)

添加 @Path 参数

为了向您的请求添加路径参数，您只需在 Swift 函数中添加具有相同名称的参数，并在同一行注释中包含 @Path 关键字。您可以在参数前后放置注释：在前面：/* @Path */ user: String

在后面：user: String /* @Path */

行内：user: String // @Path

请记住，使用花括号将端点中的变量括起来：// @GET = /users/{user}/repos

RetrofireSwift 将替换花括号中单词的所有出现，使用与此完全相同的变量名！如果您需要在变量和实际的路径参数之间设置不同的名称，您可以在等号后简单指定名称：/* @Path = different_name */ user: String。这样，您就可以拥有一个端点如 /users/{different_name}/repos，而无需更改函数签名。

最终结果

// @GET = /users/{user}/repos
func getRepo(
    /* @Path */ user: String
) -> [GithubRepo]

SessionManager.default.getRepo("dcoletto") {...}

上面的函数将调用 /users/dcoletto/repos

添加 @Query 参数

为了向您的请求添加查询参数，您只需在 Swift 函数中添加具有相同名称的参数，并在同一行注释中包含 @Query 关键字。您可以在参数前后放置注释：在前面：/* @Query */ q: String

在后面：q: String /* @Query */

行内：q: String // @Query

端点无需任何修改，查询参数将自动添加到端点后面

RetrofireSwift 将添加所有与参数完全相同的参数名！如果您需要在变量和实际的路径参数之间设置不同的名称，您可以在等号后简单指定名称：/* @Query = q */ query: String。这样，您可以在保持函数参数有意义名称的同时调用类似 /search/repositories?q=test 的端点。

最终结果

// @GET = /search/repositories
func searchRepo(
    /* @Query */ q: String
) -> RepoList

SessionManager.default.searchRepo("retrofire swift") {...}

上面的函数将调用 /search/repositories?q=retrofire%20swift

添加 @Body 参数

为了向您的请求添加正文，您只需在 Swift 函数中添加一个参数，并在同一行注释中包含 @Body 关键字。您可以在参数前后放置注释：在前面：/* @Body */ body: CodableObject

之后： body: CodableObject /* @Query */

内联： body: CodableObject // @Query

端点无需任何修改，查询参数将自动添加到端点后面

RetrofireSwift会从你的对象中生成一个JSON字符串，所以它需要遵守'Codable'协议

    var title: String
    var body: String
    var userId: Int
}

最终结果

// @POST = /posts
func postSample(
    /* @Body */ body: PostReq
) -> PostRes

let req = PostReq(title: "Sample", body: "Full body", userId: 1)
SessionManager.default.postSample(body: req) {...}

上面的函数将会调用/posts，并将此JSON体传递给它：{"title": "Sample", "body": "Full body", "userId": 1}

添加@Header参数

为了向你的请求添加一个header参数，你只需在你的swift函数中添加一个参数，并在同一行上用一个包含@Header关键词、等号和头部名称注释标记这个参数。你可以在参数之前或之后放置注释：之前：/* @Header = Authorization */ token: String

之后： token: String /* @Header = Authorization */

内联： token: String // @Header = Authorization

使用@Headers添加更多headers

目前（2019年9月4日）无法使用@Headers来添加更多headers。无论如何，如果你需要更多参数，你可以在同一个函数上使用多个@Header注解。

作者

Coletto Dario, [email protected]

许可证

Retrofire遵循MIT许可证。有关更多信息，请参阅LICENSE文件。