Restler

Restler 框架被构建来使用 Swift 最新版本的功能。其灵感来源于用于用 Swift 构建服务器端应用程序的 Vapor 库。我们所爱的是函数式编程，因此您可以通过调用一些链式函数来构建期望的请求。该框架的主要目标是提供一个简单、快速的接口来执行 API 调用。

内容列表

1. 文档
2. 安装
3. 用法
   • 错误解析器
   • 头部
   • Restler 调用
   • Combine
   • RxSwift
4. 贡献

文档

我们认为 README 不是完整文档的好地方，所以我们决定将其生成至框架仓库内部的文件夹。完整的文档可以在 Documentation 文件夹中找到。如果您正在寻找特定协议或类的描述，我们在此列出了最重要的符号。

Restler

RestlerType - 作为在模拟或使用 Restler 类的实例时应该使用的主要协议。

请求构建器

• RestlerBasicRequestBuilderType - 可用于所有 HTTP 方法。
• RestlerQueryRequestBuilderType - 可用于所有 HTTP 方法。
• RestlerBodyRequestBuilderType - 可用于所有 HTTP 方法。
• RestlerDownloadRequestBuilderType - 仅适用于 GET。
• RestlerMultipartRequestBuilderType - 仅适用于 POST。
• RestlerDecodableResponseRequestBuilderType - 可用于 GET、POST、PUT、PATCH 和 DELETE（所有都不包括 HEAD）。

所有这些协议都定义在一个文件中： RestlerRequestBuilderType

请求

Restler.Request - 由 Restler 提供的所有请求类型的泛型类。

错误

• Restler.Error - Restler 返回的错误。
• Restler.ErrorType - Restler 能够自行解码的类型。每种不同的类型都会是一个 unknownError。

错误解析器

• RestlerErrorParserType - ErrorParser 类的公开协议。
• RestlerErrorDecodable - 如果一个对象应该由 ErrorParser 解码，则应实现此协议。

安装

这里非常容易，如果您使用Swift Package Manager，只需将其添加到依赖项中。

否则，您可以使用CocoaPods。如果您使用它，只需将其添加到您的 Podfile 中。

...
pod 'Restler/Core'
...

请注意，使用 /Core 是非常重要的！（从 v1.0 开始变更）并在您的控制台中调用它

pod install

将框架导入到项目中

import RestlerCore

并调用它！

使用示例

错误解析器

如果您不希望解析每个请求失败时出现的相同错误，只需将其直接添加到 Restler 对象的错误解析器中。

restler.errorParser.decode(ErrorToDecodeOnFailure.self)

如果您不再需要对其进行解码，只需停止解码即可

restler.errorParser.stopDecoding(ErrorToDecodeOnFailure.self)

头文件

设置头文件值非常简单。只需将其作为字典设置即可

restler.header = [
  .contentType: "application/json",
  .cacheControl: "none",
  "customKey": "value"
]
restler.header[.cacheControl] = nil

如果您使用基本身份验证并以“Authorization”键提供用户名和密码，只需将其提供到头文件中即可

restler.header.setBasicAuthentication(username: "me", password: "password")

Restler 调用

GET

Restler(baseURL: myBaseURL)
  .get(Endpoint.myProfile) // 1
  .query(anEncodableQueryObject) // 2
  .failureDecode(ErrorToDecodeOnFailure.self) // 3
  .setInHeader("myNewTemporaryToken", forKey: "token") // 4
  .receive(on: .main) // 5
  .decode(Profile.self) // 6
  // 7

  .subscribe(
    onSuccess: { profile in // 8
      updateProfile(with: profile)
    },
    onCompletion: { _ in // 9
      hideLoadingIndicator()
  })

1. 向给定的端点发送 GET 请求。
2. 将对象编码并放入 GET 请求的查询中。
3. 如果将发生错误，错误解析器将尝试解码给定类型。
4. 仅为此请求设置指定键的指定值在标题中。
5. 将完成处理器调用的派发队列设置为主队列。
6. 在响应成功时解码 Profile 对象。如果不为可选，则可以调用失败处理程序。
7. 从现在起，我们处于请求状态，而不是请求构建器状态。
8. 如果 Restler 成功结束请求，则调用该处理程序。
9. 无论结果如何，请求完成后都会调用该处理程序。

POST

Restler(baseURL: myBaseURL)
  .post(Endpoint.myProfile) // 1
  .body(anEncodableQueryObject) // 2
  .failureDecode(ErrorToDecodeOnFailure.self)
  .decode(Profile.self)

  .subscribe(
    onFailure: { error in // 3
      print("\(error)")
    },
    onCompletion: { _ in
      hideLoadingIndicator()
  })

1. 向给定的端点发送 POST 请求。
2. 将对象编码并将其放入请求的正文中。如果选定的请求方法不支持它，则忽略。
3. 请求失败时将调用该处理程序。

其他

任何其他方法调用都与这两个非常相似，但如果有问题，请创建一个问题。

Restler + Combine

• Restler 方法

Restler(baseURL: myBaseURL)
  .get("/profile") // 1
  .decode(Profile.self) // 2
  .publisher // 3
  .catch { _ in Empty() } // 4
  .assign(to: \.profile, on: self) // 5
  .store(in: &subscriptions) // 6

1. 向给定的端点发送 GET 请求。
2. 解码 Profile 对象。
3. 将请求对象转换为发布者，以便在您的代码中轻松使用 Combine。
4. 处理抛出的错误
5. 将发布者中的每个元素分配到对象属性上。
6. 将此类型擦除的可取消取消的实例存储在指定的集合中。

• 更多的 Combine 方法

Restler(baseURL: myBaseURL)
  .get(Endpoint.myProfile) // 1
  .query(anEncodableQueryObject) // 2
  .publisher()? // 3
  .receive(on: DispatchQueue.main) // 4
  .map(\.data) // 5
  .decode(type: Profile.self, decoder: JSONDecoder()) // 6
  .catch { _ in Empty() } // 7
  .assign(to: \.profile, on: self) // 8
  .store(in: &subscriptions) // 9

1. 向给定的端点发送 GET 请求。
2. 将对象编码并放入 GET 请求的查询中。
3. 构建请求并返回 Combine 支持的发布者。
4. 指定接收发布者元素的调度器。在这种情况下是主队列。
5. 从 DataTaskPublisher 获得数据对象。
6. 解码 Profile 对象。
7. 处理错误
8. 将发布者的每个元素分配给对象上的一个属性。
9. 将此类型擦除的可取消取消的实例存储在指定的集合中。

Restler + RxSwift

首先，您需要将 RxRestler 添加到您的目标中，您可以在 SPM 中简单地进行此操作。在 CocoaPods 中，您应该在 Podfile 中添加

pod `Restler/Rx`

然后，将 import RxRestler 添加到需要它的每个文件中。

Restler(baseURL: myBaseURL)
  .get(Endpoint.myProfile)
  .query(anEncodableQueryObject)
  .receive(on: .main) // 1
  .decode(Profile.self) // 2
  .rx // 3
  .subscribe( // 4
    onSuccess: { print("This is my profile:", $0) },
    onError: { print("This is an error:", $0) })
  .disposed(by: bag) // 5

1. 订阅处理程序将在提供的队列上被调用，即使它是使用 RxSwift 完成的（设置具有此属性设置的调度器可能会导致在接收响应和处理它之间产生一些轻微的延迟，但处理程序将在提供的调度器上调用）。
2. 在成功响应中解码某些类型 - Void、Data 或某些自定义对象。
3. 将请求移动到 Rx 使用。在这种情况下，它返回 Single<Profile>。
4. 这里我们调用了已提供的 RxSwift 函数。
5. 请记住将 Disposable 添加到 DisposeBag 中。如果 bag 被销毁，则将自动取消网络任务的执行。

贡献

如果您想为这个框架做出贡献，只需将您的拉取请求提交到这里。

如果您发现了任何错误，请将其在问题中提交。

如果您想让 Restler 做其他事情，请创建一个带有功能请求的问题。

配置

1. 克隆项目并在终端中打开项目文件夹。
2. 运行配置脚本来执行 ./Scripts/configure.sh
3. 在文件夹 Restler-Example/Restler-Example/Configuration 中，按需填写配置文件命名为 Debug.xcconfig 的文件中的信息。
4. 在文件夹 Restler-Example 中打开项目。您可以从终端完成此操作：open Restler-Example/Restler-Example.xcodeproj
5. 运行测试以确保一切正常工作。

代码风格检查

在将更改推送到仓库之前，运行命令 ./Scripts/pod_lib_lint.rb Restler.podspec 来检查 podspec。

发布

1. 打开项目根目录。
2. cd Scripts/releaseTool
3. swift run ReleaseTool release ../..

依赖项

宝石

• cocoapods 1.10.0
• fastlane 2.171.0
• slather 2.6.0