Swift Academy · 课时

使用 CodingKeys 重命名

Q: 「使用 CodingKeys 重命名」这节课中我会学到什么？

映射不同的 JSON 名称和属性名称。 你通过在浏览器中直接运行的动手代码来练习 Swift Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

映射不同的 JSON 名称和属性名称。

使用 CodingKeys 重命名 是 CoddyKit 上的免费 Swift Academy 课时。这是第 1 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Swift Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Swift Academy 课程共包含 4 节课。

为什么要重命名键？

JSON API 经常使用与 Swift 属性名不同的名称，例如 first_name 与 firstName。CodingKeys 枚举可以在不改变模型 API 的情况下连接这两种命名。

import Foundation

struct User: Codable {
    var firstName: String
    enum CodingKeys: String, CodingKey {
        case firstName = "first_name"
    }
}

print("CodingKeys maps firstName to first_name")

CodingKeys 的结构

CodingKeys 是一个符合 String, CodingKey 的嵌套枚举。每个枚举成员对应一个属性名；它的原始值就是要使用的 JSON 键。

import Foundation

struct Product: Codable {
    var productName: String
    var unitPrice: Double
    enum CodingKeys: String, CodingKey {
        case productName = "product_name"
        case unitPrice = "unit_price"
    }
}

print(Product.CodingKeys.productName.rawValue)

使用重命名的键进行解码

解码时，解码器会使用 CodingKeys 中的原始值查找每个属性，因此采用 snake_case 的 JSON 可以填充 camelCase 属性。

import Foundation

struct User: Codable {
    var firstName: String
    enum CodingKeys: String, CodingKey {
        case firstName = "first_name"
    }
}

let json = "{\"first_name\":\"Ada\"}"
let u = try JSONDecoder().decode(User.self, from: json.data(using: .utf8)!)
print(u.firstName)

使用重命名的键进行编码

编码时会反向使用同一映射：输出的 JSON 包含原始值键，而不是 Swift 属性名。

import Foundation

struct User: Codable {
    var firstName: String
    enum CodingKeys: String, CodingKey {
        case firstName = "first_name"
    }
}

let data = try JSONEncoder().encode(User(firstName: "Ada"))
print(String(data: data, encoding: .utf8)!)

列出所有属性

添加 CodingKeys 枚举后，必须为每个要编码或解码的属性包含一个枚举成员。保留但不指定原始值的枚举成员会直接使用属性名。

import Foundation

struct Item: Codable {
    var id: Int
    var displayName: String
    enum CodingKeys: String, CodingKey {
        case id
        case displayName = "display_name"
    }
}

let data = try JSONEncoder().encode(Item(id: 1, displayName: "Pen"))
print(String(data: data, encoding: .utf8)!)

省略属性

将属性从 CodingKeys 中省略，会使它不参与编码和解码。此类属性必须有默认值，这样自动合成的初始化方法才能继续构建该类型。

import Foundation

struct User: Codable {
    var name: String
    var cachedToken: String = "none"
    enum CodingKeys: String, CodingKey {
        case name
    }
}

let u = try JSONDecoder().decode(User.self, from: "{\"name\":\"Ada\"}".data(using: .utf8)!)
print(u.name, u.cachedToken)

重命名多个键

您可以映射任意数量的键。每个枚举成员都会将一个 Swift 属性与服务器所需的确切 JSON 键对应起来。

import Foundation

struct Account: Codable {
    var userId: Int
    var isVerified: Bool
    enum CodingKeys: String, CodingKey {
        case userId = "user_id"
        case isVerified = "is_verified"
    }
}

let json = "{\"user_id\":7,\"is_verified\":true}"
let a = try JSONDecoder().decode(Account.self, from: json.data(using: .utf8)!)
print(a.userId, a.isVerified)

映射为更友好的名称

CodingKeys 不仅适用于 snake_case。您还可以用它将含义晦涩的 API 键重命名为清晰的 Swift 属性名。

import Foundation

struct Reading: Codable {
    var temperature: Double
    enum CodingKeys: String, CodingKey {
        case temperature = "t"
    }
}

let json = "{\"t\":19.5}"
let r = try JSONDecoder().decode(Reading.self, from: json.data(using: .utf8)!)
print(r.temperature)

嵌套类型中的 CodingKeys

每个 Codable 类型都有自己的 CodingKeys。嵌套结构体可以独立重命名自己的键，而不受父类型影响。

import Foundation

struct Meta: Codable {
    var createdAt: String
    enum CodingKeys: String, CodingKey { case createdAt = "created_at" }
}
struct Doc: Codable { var title: String; var meta: Meta }

let json = "{\"title\":\"A\",\"meta\":{\"created_at\":\"today\"}}"
let d = try JSONDecoder().decode(Doc.self, from: json.data(using: .utf8)!)
print(d.meta.createdAt)

使用重命名键进行往返转换

编码和解码两个方向都由同一个 CodingKeys 驱动，因此值会编码为 snake_case，并解码回相同的 Swift 值。

import Foundation

struct User: Codable {
    var firstName: String
    var lastName: String
    enum CodingKeys: String, CodingKey {
        case firstName = "first_name"
        case lastName = "last_name"
    }
}

let u = User(firstName: "Ada", lastName: "Lovelace")
let data = try JSONEncoder().encode(u)
let back = try JSONDecoder().decode(User.self, from: data)
print(back.firstName, back.lastName)

何时使用 CodingKeys

当需要精确控制单个键、只有部分键名称不同时，或者必须省略某个属性时，请使用显式的 CodingKeys 枚举。对于统一采用 snake_case 的 API，解码策略可能更简单。

import Foundation

struct Event: Codable {
    var eventName: String
    var startTime: String
    enum CodingKeys: String, CodingKey {
        case eventName = "name"
        case startTime = "start_time"
    }
}

let json = "{\"name\":\"Launch\",\"start_time\":\"10:00\"}"
let e = try JSONDecoder().decode(Event.self, from: json.data(using: .utf8)!)
print(e.eventName, e.startTime)

快速检查：CodingKeys

测试您对键重命名的理解。

回顾：使用 CodingKeys 重命名

您已经学习了如何精确控制键：

在类型内部声明嵌套的 enum CodingKeys: String, CodingKey。
每个枚举成员的原始值都是 JSON 键；这些枚举成员同时控制编码和解码。
列出所有需要编码的属性；省略某个属性就会排除它（该属性需要默认值）。
嵌套类型拥有各自独立的 CodingKeys。

常见问题解答

「使用 CodingKeys 重命名」课时是免费的吗？

是的 — 「使用 CodingKeys 重命名」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Swift Academy 课程的其余内容，请升级到 CoddyKit PRO。 Swift Academy 课程共包含 4 节课。

「使用 CodingKeys 重命名」这节课中我会学到什么？

映射不同的 JSON 名称和属性名称。你通过在浏览器中直接运行的动手代码来练习 Swift Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Swift Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Swift Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 1 节课，共 4 节。

「使用 CodingKeys 重命名」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Swift Academy 课中编写并运行代码吗？

能。每节 Swift Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 Swift Academy