将 JSON 转换为 Swift Codable struct!

输入 JSON,即可生成包含嵌套对象的 Swift Codable struct 代码!支持 Codable, CodingKeys, JSONDecoder, iOS。
JSON
结果
 

将 JSON 转换为 Swift Codable struct!

把 JSON 转换成遵循 Codable 的 Swift struct。属性用 let 声明并重命名为 camelCase,只有当某个 struct 中存在名称与 JSON key 不同的属性时,才会为它生成 CodingKeys enum。

当 iOS 或 macOS 应用需要一个模型来用 JSONDecoder 解码 URLSession 响应,或者你想要与 SwiftUI 预览背后的 mock JSON 对应的类型时,就可以用它。

使用方法

  1. 粘贴 API 的响应体,比如用 Proxyman 或 Charles 抓到的内容。
  2. 把 类型名 设为顶层 struct 的名称(例如 EpisodePage)。
  3. 把结果粘贴到 Swift 文件中;已包含 import Foundation。
  4. 用 try JSONDecoder().decode(EpisodePage.self, from: data) 解码。

示例

输入 (JSON)
{
  "podcast": "Swift Talk",
  "episodes": [
    { "id": 301, "title": "Async Sequences", "duration": 1840, "explicit": false },
    { "id": 302, "title": "Macros", "duration": 2215.5, "explicit": false, "guest_name": "Chris" }
  ],
  "total_count": 2
}
输出 (Swift · Codable)
import Foundation

struct EpisodePage: Codable {
    let podcast: String
    let episodes: [Episode]
    let totalCount: Int

    enum CodingKeys: String, CodingKey {
        case podcast
        case episodes
        case totalCount = "total_count"
    }
}

struct Episode: Codable {
    let id: Int
    let title: String
    let duration: Double
    let explicit: Bool
    let guestName: String?

    enum CodingKeys: String, CodingKey {
        case id
        case title
        case duration
        case explicit
        case guestName = "guest_name"
    }
}

episodes 数组的元素变成了 Episode struct。duration 混有整数(1840)和小数(2215.5),因此是 Double;只在第二集中出现的 guest_name 是 guestName: String?。凡是有字段被重命名的 struct,都会得到一个列出其全部 key 的 CodingKeys enum。

支持的功能

  • 每个 struct 都遵循 Codable;属性是不可变的 let。
  • snake_case 和 kebab-case 的 key 变成 camelCase 属性,只有在这种情况下才会添加带原始 key 的 enum CodingKeys: String, CodingKey。
  • 类型:String、Int、Double、Bool,数组为 [T]。
  • 在部分元素中缺失或包含 null 的字段是 Optional(String?),缺少 key 时也能解码。
  • 类型混杂的值使用生成的、可解码的 JSONValue enum。
  • default、class、self 等 Swift 关键字会用反引号括起来。
  • 顶层为数组时生成 typealias Root = [RootItem]。

使用场景

配合 async/await 使用 URLSession

只需一份示例响应,就能得到一个模型,在 let (data, _) = try await URLSession.shared.data(from: url) 的下一行直接解码。

SwiftUI 列表页面

给生成的 struct 加上 Identifiable(当它有 id 字段时),就能直接传给 List(page.episodes) { ... }。

打包在应用里的 mock 数据

把设计阶段的示例 JSON 放进应用 bundle,用同一个模型解码,这样在真实 API 就绪之前就能开发页面。

注意事项与限制

  • 日期字符串会输出为 String。要得到 Date,请修改属性类型并设置 decoder.dateDecodingStrategy = .iso8601 之类的策略。
  • 如果响应中缺少非 Optional 属性对应的 key,解码会抛出 DecodingError.keyNotFound。对于 API 可能省略的字段,即使示例中一直存在,也请加上 ?。
  • 所有属性都是 let;作为视图状态需要修改的模型,请改成 var。
  • 不会遵循 Identifiable、Hashable 等额外协议。
  • JSONValue enum 是为混合类型准备的辅助代码;如果项目里已有等价的类型,删掉它改用你自己的即可。

常见问题

使用 keyDecodingStrategy = .convertFromSnakeCase 后,可以删掉 CodingKeys 吗?

可以,解码器会替你完成 guest_name ↔ guestName 的转换。但不要两者同时使用:解码器会先把 key 转成 camelCase,再与 CodingKeys 中的原始值 "guest_name" 比较,结果匹配失败。

为什么用 struct 而不是 class?

把响应模型当作值类型是 Swift 的惯例,而且 struct 自带逐一成员初始化器,构造测试数据很方便。如果需要引用语义,请改成 final class 并添加初始化器。

我以为是整数的字段输出成了 Double。

当一个 key 同时包含整数和小数时,用 Double 可以避免丢失精度。反过来,如果所有示例值都形如 4.0,浏览器的 JSON 解析器会把它读成整数,你可能得到 Int,所以请检查 API 的真实值。

编码回 JSON 时会保留原始 key 吗?

编码时同样会使用 CodingKeys,所以 JSONEncoder 会重新写出 guest_name。值为 nil 的 Optional 属性会从输出中省略。