RestEssentials 是一个极其轻量级的 REST 和 JSON Swift 库，可用于 iOS、iPadOS、macOS、tvOS 和 watchOS。

• 轻松执行发送 JSON 的异步 REST 网络调用（GET、POST、PUT、PATCH 或 DELETE）
• 易于使用的 API，采用 Swift 的 async/await 语法
• 原生集成了 Swift 的 Decodable 和 Encodable 类型
• 支持 JSON、Void、UIImage/NSImage 和 Data 响应类型，并完全支持自定义扩展
• 完整的 JSON 解析功能
• HTTP 响应验证
• 发送自定义 HTTP 标头
• 接受自签名 SSL 证书
• 更改超时选项
• 完全原生的 Swift API

RestEssentials 6.0 及更高版本适用于以下列出的任何受支持的操作系统，以及相应版本的 Xcode。

• iOS 15.0+
• tvOS 15.0+
• watchOS 8.0+
• iPadOS 15.0+
• macOS 12.0+

如果您需要支持旧版本的操作系统，可以使用 5.2.0 版本，该版本支持追溯到 iOS 11.0。

RestEssentials 仅与 Swift 5 及更高版本兼容。请参阅下文，查看针对您 Swift 版本的推荐版本列表

• Swift 5.5+ -> RestEssentials 6.0.1
• Swift 5 -> RestEssentials 5.2.0（或 4.0.3+ -- macOS 和 SPM 支持在 5.0.1 中添加）
• Swift 4 -> RestEssentials 4.0.2
• Swift 3 -> RestEssentials 3.1.0
• Swift 2.3 -> 不支持
• Swift 2.0-2.2 -> RestEssentials 2.0.0
• Swift 1 -> RestEssentials 1.0.2

• 如果您需要帮助，请使用 Stack Overflow。（标签 'restessentials'）
• 如果您想提出一般性问题，请使用 Stack Overflow。
• 如果您发现错误，请提交 issue。
• 如果您有功能请求，请提交 issue。
• 如果您想要贡献代码，请提交 pull request。

RestEssentials 与 macOS、iOS、iPadOS、tvOS 和 watchOS 的 SPM 兼容（目前在 Linux 上不可用）。当使用 Xcode 11 时，Swift 包管理器是推荐的安装方法。

要在 Xcode 11+ 中使用，请打开您的项目并转到 File->Swift Packages->Add Package Dependency...，然后按照对话框操作。就是这样！

如果您更喜欢使用 SPM 手动添加，只需将 RestEssentials 依赖项添加到您的 Package.swift 文件中的目标即可。

dependencies: [
.package(url: "https://github.com/sean7512/RestEssentials.git", from: "6.0.1")
]

CocoaPods 是 Cocoa 项目的依赖项管理器。

使用以下命令安装最新版本的 CocoaPods

$ sudo gem install cocoapods

要使用 CocoaPods 将 RestEssentials 集成到您的 Xcode 项目中，请在您的 Podfile 中指定它

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '15.0'
use_frameworks!

target 'MyApp' do
pod 'RestEssentials', '~> 6.0.1'
end

然后，运行以下命令

$ pod install

如果您不想使用 CocoaPods，您可以手动将 RestEssentials 集成到您的项目中。

• 通过打开终端，cd 进入您的顶层项目目录，并输入以下命令，将 RestEssentials 添加为 子模块

$ git submodule add https://github.com/sean7512/RestEssentials.git

• 打开新的 RestEssentials 文件夹，并将 RestEssentials.xcodeproj 拖到您的应用程序 Xcode 项目的 Project Navigator 中。

  它应该嵌套在您的应用程序的蓝色项目图标下方。它是在所有其他 Xcode 组之上还是之下都无关紧要。

• 在 Project Navigator 中选择 RestEssentials.xcodeproj，并验证部署目标与您的应用程序目标是否匹配。

• 就这样！

RestEssentials.framework 会自动作为目标依赖项、链接框架和嵌入式框架添加到复制文件构建阶段，这就是您在模拟器和设备上构建所需的一切。

如果您喜欢老式方法，可以通过将 Source 目录（Source/*.swift）内的所有 Swift 文件直接添加到您的项目中来集成 RestEssentials。请注意，由于您实际上没有加载框架，因此您不再需要 import RestEssentials。

RestEssentials 最好与 Swift 4 的原生 JSON 支持（使用 Codable/Encodabe/Decodable 协议）一起使用。如果您的代码不使用新的 Codable 协议，RestEssentials 也可以与内置的 JSON 解析和支持一起使用。

RestEssentials 中内置 JSON 对象和 Swift 4 的 Codable 的使用是可互换的（您可以发布 JSON 并期望返回 Codable 对象，或者您可以发布 Codable 对象并获得任何响应类型）。

import RestEssentials

struct HttpBinResponse: Codable {
    let url: String
}

guard let rest = RestController.make(urlString: "http://httpbin.org/get") else {
    print("Bad URL")
    return
}

let response = try await rest.get(HttpBinResponse.self)
print(response.url) // "http://httpbin.org/get"

import RestEssentials

// httpbin returns json with the url and the posted data under a key called "json"
struct HttpBinResponse: Codable {
    let url: String
    let json: Car
}

struct Car: Codable {
    let make: String
    let model: String
    let year: Int
}

guard let rest = RestController.make(urlString: "http://httpbin.org") else {
    print("Bad URL")
    return
}

let myCar = Car(make: "Jeep", model: "Grand Cherokee", year: 2017)
let response = try await rest.post(myCar, at: "post", responseType: HttpBinResponse.self)
let car = response.json // car is of type Car

import RestEssentials

guard let rest = RestController.make(urlString: "http://httpbin.org/get") else {
    print("Bad URL")
    return
}

let json = try await rest.get(withDeserializer: JSONDeserializer())
print(json["url"].string) // "http://httpbin.org/get"

import RestEssentials

guard let rest = RestController.make(urlString: "http://httpbin.org") else {
    print("Bad URL")
    return
}

let postData: JSON = ["key1": "value1", "key2": 2, "key3": 4.5, "key4": true, "key5": [1, 2, 3, 4]]
let json = try await rest.post(postData, at: "post")
print(json["url"].string) // "http://httpbin.org/post"
print(json["json"]["key1"].string) // "value1"
print(json["json"]["key2"].int) // 2
print(json["json"]["key3"].double) // 4.5
print(json["json"]["key4"].bool) // true
print(json["json"]["key5"][2].numerical) // 3
print(json["json"]["key6"].string) // nil

import RestEssentials

guard let rest = RestController.make(urlString: "http://httpbin.org/put") else {
    print("Bad URL")
    return
}

let putData: JSON = ["key1": "value1", "key2": 2, "key3": 4.5, "key4": true]
let json = try await rest.put(putData)
print(json["url"].string) // "http://httpbin.org/put"

import RestEssentials

guard let rest = RestController.make(urlString: "https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png") else {
    print("Bad URL")
    return
}

let img = try await rest.get(withDeserializer: ImageDeserializer())
let isImage = img is UIImage // true

所有网络调用都可能在运行时抛出错误。错误可能是内置的 NetworkingError 类型之一，也可能来自 Foundation。为了您的方便，内置的错误定义如下。

/// Errors related to the networking for the `RestController`
public enum NetworkingError: Error {
    /// Indicates the server responded with an unexpected status code.
    /// - parameter Int: The status code the server respodned with.
    /// - parameter HTTPURLResponse: The HTTPURLResponse from the server
    /// - parameter Data: The raw returned data from the server
    case unexpectedStatusCode(Int, HTTPURLResponse, Data)

    /// Indicates that the server responded using an unknown protocol.
    /// - parameter URLResponse: The response returned form the server.
    /// - parameter Data: The raw returned data from the server.
    case badResponse(URLResponse, Data)

    /// Indicates the server's response could not be deserialized using the given Deserializer.
    /// - parameter HTTPURLResponse: The HTTPURLResponse from the server
    /// - parameter Data: The raw returned data from the server
    /// - parameter Error: The original system error (like a DecodingError, etc) that caused the malformedResponse to trigger
    case malformedResponse(HTTPURLResponse, Data, Error)
}

如果您调用的 Web 服务不返回任何 JSON（或者您不需要捕获它），请使用 VoidDeserializer。如果您想返回除 Decodable、JSON、Data 或 UIImage/NSImage 之外的其他数据类型，请创建 Deserializer 的新实现并使用它。

有一个替代的静态函数可以实例化 RestController 对象：make:URL。此变体不会像 String 版本那样返回 Optional。这对于轻松构建带有查询参数的 URL（通常用于 GET 请求）非常有用。

RestController 有一个 headerGenerator 字段，它是一个闭包回调，每次调用都会执行以生成标头。这简化了在每个请求上发送相同标头的过程，因为不需要为每个请求创建 RestOptions 对象。

所有操作都可以接受可选的 RestOptions 对象，您可以使用它来配置预期的 HTTP 状态代码、要包含在请求中的可选 HTTP 标头以及请求的超时时间（以秒为单位）。

所有操作也可以接受要使用的相对路径。如果您的 RestController 对象是 http://foo.com，您可以传入 some/relative/path，然后请求将发送到 http://foo.com/some/relative/path。这使您可以使用单个 RestController 对象来处理对同一主机的​​所有 REST 调用。这 是 首选行为，而不是为每个调用创建新的 RestController。

您可以选择允许框架使用 RestController 实例上的 acceptSelfSignedCertificate 属性接受来自主机的自签名 SSL 证书。您必须正确配置 App Transport Security。

如果您正在 Swift 中启动一个新项目，并希望充分利用其约定和语言功能，那么 RestEssentials 是一个不错的选择。虽然功能不如 Alamofire、AFNetworking 或 RestKit 那么全面，但它应该可以满足您的基本 REST 需求。如果您只需要执行标准网络选项（GET、PUT、POST、DELETE）、接受自签名 SSL 证书、发送 HTTP 标头，并且您只处理 JSON 作为输入（以及任何数据类型作为输出），那么 RestEssentials 是完美的选择！

重要的是要注意，这两个库不是互斥的：RestEssentials 可以与任何其他网络库共存于同一个项目中。

Alamofire 是一个功能更全面的网络库，也是用 Swift 编写的。它增加了对多部分文件上传的支持以及配置您自己的 URLSessionConfiguration 的能力（大多数人可能不需要这样做）。

AFNetworking 仍然是适用于 OS X 和 iOS 的首要网络库，并且可以像任何其他 Objective-C 代码一样轻松地在 Swift 中使用。AFNetworking 稳定可靠，并且不会消失。

在以下任何情况下使用 AFNetworking

• UIKit 扩展，例如将图像异步加载到 UIImageView
• 网络可达性监控，使用 AFNetworkReachabilityManager

RestKit 是一个非常高级的库，它构建在 AFNetworking 之上，并提供非常高级的功能，例如自动将 JSON 映射到类。RestKit 也是一个 Objective-C 库，但它可以在您的 Swift 项目中轻松使用。

RestEssentials 由 Sean K 拥有和维护。

RestEssentials 在 MIT 许可证下发布。有关详细信息，请参阅 LICENSE。