Swift OpenAPI Generator 中处理动态 JSON 字段的最佳实践

在 Swift 开发中处理 REST API 时，我们经常会遇到需要处理动态 JSON 结构的场景。本文将以 Jira API 为例，深入探讨如何利用 Swift OpenAPI Generator 处理这类动态字段。

动态 JSON 字段的挑战

许多现代 API（如 Jira）允许客户端发送包含任意字段的 JSON 对象。在 OpenAPI 规范中，这种结构通常通过 additionalProperties 关键字定义。当使用 Swift OpenAPI Generator 处理这种结构时，会遇到几个关键挑战：

1. 类型安全与动态结构的平衡
2. 复杂嵌套结构的处理
3. 与 Swift 强类型系统的兼容性

OpenAPI 规范的不同定义方式

OpenAPI 规范提供了两种定义动态对象的方式，它们生成的 Swift 代码有所不同：

1. additionalProperties: {} 方式：

fields:
  additionalProperties: {}
  type: object

这会生成 [String: OpenAPIValueContainer] 类型的 Swift 代码。

2. additionalProperties: true 方式：

fields:
  additionalProperties: true
  type: object

这会生成 OpenAPIObjectContainer 类型的 Swift 代码，使用起来更为简便。

处理 [String: OpenAPIValueContainer]

当遇到第一种定义方式时，我们需要手动构建包含 OpenAPIValueContainer 的字典。以下是几种处理方法：

基础类型转换

对于简单的基础类型，可以直接使用字面量初始化：

let container: [String: OpenAPIValueContainer] = [
    "stringField": .init(stringLiteral: "value"),
    "intField": .init(integerLiteral: 42),
    "boolField": .init(booleanLiteral: true),
    "doubleField": .init(floatLiteral: 3.14)
]

复杂结构处理

对于嵌套的字典或数组结构，需要递归处理：

func convertToContainer(_ value: Any) -> OpenAPIValueContainer {
    switch value {
    case let str as String: return .init(stringLiteral: str)
    case let num as Int: return .init(integerLiteral: num)
    case let dict as [String: Any]:
        let converted = dict.mapValues { convertToContainer($0) }
        return try! .init(unvalidatedValue: converted)
    case let array as [Any]:
        let converted = array.map { convertToContainer($0) }
        return try! .init(unvalidatedValue: converted)
    default:
        return .init(nilLiteral: ())
    }
}

简化方案

实际上，我们可以利用 Sendable 协议简化转换过程：

func createContainer(values: [String: Any]) throws -> [String: OpenAPIValueContainer] {
    try values.mapValues { try OpenAPIValueContainer(unvalidatedValue: $0 as! Sendable) }
}

实际应用建议

1. 优先修改 OpenAPI 规范：如果可能，将 additionalProperties: {} 改为 additionalProperties: true，这样生成的代码更易用。

2. 处理第三方 API 文档：当遇到不完整或过时的 OpenAPI 文档时，可以适当修改本地副本，但要记录修改内容。

3. 错误处理：在实际应用中，应该添加更完善的错误处理，而不是使用强制解包。

4. 性能考虑：对于大型复杂结构，递归转换可能影响性能，应考虑优化或缓存策略。

总结

处理动态 JSON 结构是 API 集成中的常见需求。通过理解 OpenAPI 规范的不同定义方式及其对应的 Swift 代码生成结果，我们可以选择最适合项目需求的解决方案。无论是手动构建 OpenAPIValueContainer 还是修改规范使用 OpenAPIObjectContainer，关键在于平衡类型安全与开发效率。