Restler

Restler 框架旨在利用 Swift 最新版本的功能。它的灵感来自用于构建 Swift 服务器端的 Vapor 库。我们喜欢函数式编程，因此您可以通过调用一些链式函数来构建所需请求。框架的主要目标是提供一个最简单、最快进行 API 请求的接口。

内容列表

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

文档

我们认为 README 不是一个完整文档的好地方，因此我们决定将其生成到框架存储库内的文件夹中。完整的文档可以在Documentation/Reference文件夹中找到。如果您正在查找特定协议或类的描述，我们在这里列出了最重要的符号。

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)

报头

设置header的值非常简单。只需将其作为字典设置即可

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 被反初始化，网络任务将自动取消。

贡献

如果您想为这个框架做出贡献，只需在这里提交您的pull请求。

如果您发现了任何错误，请在问题区域提交。

如果您想让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