Swift Academy · 课时

CustomDebugStringConvertible

Q: 「CustomDebugStringConvertible」这节课中我会学到什么？

提供更丰富的调试输出。 你通过在浏览器中直接运行的动手代码来练习 Swift Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

提供更丰富的调试输出。

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

独立的调试视图

CustomDebugStringConvertible 提供 debugDescription，这是 debugPrint、LLDB 的 po 命令和调试器使用的表示形式。它可以比 description 包含更多细节。

添加 debugDescription

遵循该协议并提供此属性：

struct Point: CustomDebugStringConvertible {
    let x: Int
    let y: Int
    var debugDescription: String { "Point(x: \(x), y: \(y))" }
}
debugPrint(Point(x: 1, y: 2))  // Point(x: 1, y: 2)

debugPrint 与 print

print 使用 description；debugPrint 使用 debugDescription：

struct Money: CustomStringConvertible, CustomDebugStringConvertible {
    let cents: Int
    var description: String { "$\(Double(cents)/100)" }
    var debugDescription: String { "Money(cents: \(cents))" }
}
let m = Money(cents: 250)
print(m)       // $2.5
debugPrint(m)  // Money(cents: 250)

何时同时提供两者

使用 description 生成简洁的用户输出，使用 debugDescription 提供诊断细节（原始值、内部状态）。同时提供两者，可以分别满足这两种场景的需求。

在调试信息中提供更多细节

显示不应让用户看到的内部信息：

struct Session: CustomStringConvertible, CustomDebugStringConvertible {
    let user: String
    let token: String
    var description: String { "Session(\(user))" }
    var debugDescription: String { "Session(user: \(user), token: \(token))" }
}
let s = Session(user: "ann", token: "xyz")
print(s)       // Session(ann)
debugPrint(s)  // Session(user: ann, token: xyz)

集合中的调试输出

对集合使用 debugPrint 时，会使用每个元素的 debugDescription：

struct Tag: CustomDebugStringConvertible {
    let name: String
    var debugDescription: String { "Tag(\(name))" }
}
debugPrint([Tag(name: "a"), Tag(name: "b")])  // [Tag(a), Tag(b)]

String(reflecting:)

正如 String(describing:) 使用 description 一样，String(reflecting:) 使用 debugDescription：

struct Code: CustomDebugStringConvertible {
    let n: Int
    var debugDescription: String { "Code<\(n)>" }
}
print(String(reflecting: Code(n: 7)))  // Code<7>

回退行为

如果类型只提供 description，debugPrint 会回退到使用它。如果类型只提供 debugDescription，普通的 print 仍会使用默认的镜像形式：

struct Only: CustomStringConvertible {
    let v: Int
    var description: String { "Only(\(v))" }
}
debugPrint(Only(v: 3))  // Only(3)  -- falls back to description

调试输出中的引号

请注意，对字符串使用 debugPrint 时会添加引号，这体现了它的调试属性：

print("hi")        // hi
debugPrint("hi")   // "hi"

不泄露信息的诊断

不要将机密信息放入 description；只有在日志安全的情况下，才可以将其放入 debugDescription。请谨慎决定每个属性要透露什么。

struct Key: CustomStringConvertible {
    let secret: String
    var description: String { "Key(***)" }
}
print(Key(secret: "abc"))  // Key(***)

枚举的调试细节

使用 debugDescription 暴露原始枚举分支和载荷，可以让枚举受益：

enum Load: CustomDebugStringConvertible {
    case idle
    case progress(Int)
    var debugDescription: String {
        switch self {
        case .idle: return "Load.idle"
        case .progress(let p): return "Load.progress(\(p))"
        }
    }
}
debugPrint(Load.progress(40))  // Load.progress(40)

快速检查

哪个函数使用 debugDescription 而不是 description？

总结

您学习了自定义调试字符串表示：

提供 var debugDescription: String 来生成诊断输出
由 debugPrint、String(reflecting:) 和调试器使用
print 使用 description；debugPrint 使用 debugDescription
将额外的内部细节放入调试表示，将简洁文本放入 description

接下来：使用 Mirror 进行反射。

常见问题解答

「CustomDebugStringConvertible」课时是免费的吗？

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

「CustomDebugStringConvertible」这节课中我会学到什么？

提供更丰富的调试输出。你通过在浏览器中直接运行的动手代码来练习 Swift Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Swift Academy 需要有经验吗？

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

「CustomDebugStringConvertible」课时需要多长时间？

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

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

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

此课程中的所有课时

← 返回 Swift Academy