RestEssentials 6.0.1

RestEssentials 6.0.1

×

测试已测试✓
Lang语言 SwiftSwift
许可证 MIT
发布最新发布2022年7月
SPM支持 SPM✗

由 RestEssentials 维护。

RestEssentials 6.0.1

  • By
  • sean7512

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

功能

  • 轻松执行异步 REST 网络调用（GET、POST、PUT、PATCH 或 DELETE），并发送 JSON
  • 使用 Swift 的异步/等待语法的简单 API
  • 与 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。

Swift 版本兼容性

RestEssentials 仅与 Swift 5 及以上版本兼容。以下列出了 Swift 各个版本推荐的 RestEssentials 版本

  • 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。
  • 如果您发现了一个 bug，请提交问题。
  • 如果您有功能请求，请提交问题。
  • 如果您想做出贡献，请提交 pull request。

安装

Swift 包管理器

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

要在 XCode 11+ 中使用它，请打开您的项目，转到 文件 -> Swift 包 -> 添加包依赖... 并按照对话框操作。就这样了！

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

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

CocoaPods

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

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

$ sudo gem install cocoapods

要使用 CocoaPods 在 Xcode 项目中集成 RestEssentials，请在您的 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。

用法

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

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

发送GET请求并获取Swift 4 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"

使用Swift 4 Codable对象发送POST请求并返回Swift 4 Codable对象

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

发送GET请求并解析原始JSON响应（不使用Swift 4的 Codable）

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"

发送POST请求并解析响应（不使用Swift 4的 Codable）

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

发送PUT请求并解析响应（不使用Swift 4的 Codable）

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"

制作 GET 请求以获取图像

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)
}

其他注意事项

如果你调用的网络服务不返回任何 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。

常见问题解答

我应该在什么时候使用RestEssentials？

如果您正在用Swift开始一个新项目，并且想充分利用它的约定和语言特性，RestEssentials是一个很好的选择。尽管它不像Alamofire、AFNetworking或RestKit那样功能齐全，但它应该能够满足您的基本REST需求。如果您只需要执行标准网络选项（GET、PUT、POST、DELETE）、接受自签名SSL证书、发送HTTP头部，并且您的输入始终是JSON（输出可以是任何数据类型），那么RestEssentials是完美的选择！

值得注意的是，这两个库并不互相排斥：RestEssentials可以与其他任何网络库在同一项目中使用。

我应该在什么时候使用Alamofire？

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

我应该在什么时候使用AFNetworking？

AFNetworking仍然是可用的、对于OS X和iOS的顶级网络库，并且可以像其他Objective-C代码一样在Swift中轻松使用。AFNetworking稳定可靠，没有消失的迹象。

以下情况可以使用AFNetworking:

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

我应该何时使用RestKit？

RestKit是一个基于AFNetworking构建的非常先进的库，提供了诸如自动JSON映射到类的高级功能。RestKit还是一个Objective-C库，但它在Swift项目中很容易使用。

致谢

RestEssentials 由 Sean K 拥有和维护。

许可

RestEssentials 在MIT许可下发布。有关详情，请参阅LICENSE文件。