URLQueryEncoder

一个可定制的 Swift Encoder，可将数据类型的实例编码为 URL 查询项。支持所有 OpenAPI 序列化选项。

示例

编码基本数据类型

let encoder = URLQueryEncoder()
encoder.encode(id, forKey: "id")

print(encoder.queryItems)
// [URLQueryItem(name: "id", value: "5")]

默认情况下，可选值不会被编码。

var id: Int?
let encoder = URLQueryEncoder()
encoder.encode(id, forKey: "id")

print(encoder.queryItems)
// []

编码数组

let ids = [3, 4, 5]
let encoder = URLQueryEncoder()
encoder.encode(ids, forKey: "id")

// Query: "id=3&id=4&id=5"

当 explode 选项禁用时

let ids = [3, 4, 5]
let encoder = URLQueryEncoder()
encoder.encode(ids, forKey: "id", explode: false)

// Query: "id=3,4,5"

当 explode 选项禁用且使用自定义分隔符时

let ids = [3, 4, 5]
let encoder = URLQueryEncoder()
encoder.encode(ids, forKey: "id", explode: false, delimeter: "|")

// Query: "id=3|4|5"

编码对象

let user = User(role: "admin", name: "kean")

let encoder = URLQueryEncoder()
encoder.encode(user, forKey: "id")

// Query: "role=admin&name=kean"

当 explode 选项禁用时

let user = User(role: "admin", name: "kean")

let encoder = URLQueryEncoder()
encoder.encode(user, forKey: "id", explode: false)

// Query: "id=role,admin,name,kean"

作为“深层”对象

let user = User(role: "admin", name: "kean")

let encoder = URLQueryEncoder()
encoder.encode(user, forKey: "id", isDeepObject: true)

// Query: "id[role]=admin&id[name]=kean")"

如果您正在使用 URL 表单编码对请求体进行编码，则可以使用便捷的 URLQueryEncoder.encode(_:) 方法。

编码选项

有两种方法可以更改编码选项。您可以直接在 URLQueryEncoder 实例上设置它们。

let encoder = URLQueryEncoder()
encoder.explode = false
encoder.isDeepObject = true
encoder.delimiter = "|"
encoder.dateEncodingStrategy = .millisecondsSince1970

或者在每次单独的 encode 调用中传递选项。

let user = User(role: "admin", name: "kean")
let ids = [3, 4, 5]

let encoder = URLQueryEncoder()
encoder.encode(ids, forKey: "ids", explode: false)
encoder.encode(ids, forKey: "ids2", explode: true)
encoder.encode(user, forKey: "user", isDeepObject: true)
encoder.encode(2, forKey: "id")

// Query: "ids=3,4,5&ids2=3&ids2=4&ids2=5&user[role]=admin&user[name]=kean&id=2"

这样设计的原因是在 OpenAPI 中，每个参数都可以带有不同的序列化选项。

访问结果

您可以随时访问编码结果，并且它们以不同的形式出现

public final class URLQueryEncoder {
    // Encoded query items.
    public var queryItems: [URLQueryItem]
    // Encoded query items as name-value pairs.
    public var items: [(String, String?)]
    // The encoded query items as a URL query subcomponent.
    public var query: String?
    // The encoded query items as a URL query subcomponent with percent-encoded values.
    public var percentEncodedQuery: String?
}

许可证

URLQueryEncoder 在 MIT 许可证下可用。有关更多信息，请参阅 LICENSE 文件。