GRDB.swift 中实现通用记录包装器的编码方案

在 Swift 数据库框架 GRDB.swift 的使用过程中，开发者经常会遇到需要包装数据库记录的场景。本文将深入探讨如何正确实现一个通用记录包装器的编码方案，特别是解决在使用 singleValueContainer 时遇到的问题。

问题背景

在实际开发中，我们经常需要隐藏数据库表中的某些字段，仅保留部分字段对外暴露。常见的做法是创建一个通用包装器结构体，内部包含原始模型和额外字段。例如：

struct Wrapper<Model: Codable>: Codable {
    var model: Model
    var otherValue: String
}

当我们需要对这种包装器进行编码时，按照 Swift 标准库的惯例，通常会使用 singleValueContainer 来处理内部模型的编码：

func encode(to encoder: any Encoder) throws {
    var modelContainer = encoder.singleValueContainer()
    try modelContainer.encode(model)
    
    var container = encoder.container(keyedBy: CodingKeys.self)
    try container.encode(otherValue, forKey: .otherValue)
}

遇到的问题

在 GRDB.swift 6.27.0 版本中，上述实现会抛出 single value encoding is not supported 错误。这是因为 GRDB 的编码器尚未完全实现对单值容器的支持。

解决方案

经过 GRDB 维护者的快速响应，这个问题在 6.28.0 版本中得到了解决。现在开发者可以安全地使用 singleValueContainer 来编码包装的内部模型。

正确的实现方式应该考虑以下几点：

1. 优先使用 EncodableRecord：如果包装的内部类型同时符合 EncodableRecord 协议，GRDB 会优先使用该协议提供的编码能力。

2. 单值容器与键控容器的结合使用：可以同时使用单值容器编码主模型，使用键控容器编码额外字段。

3. 向后兼容：新版本的实现保持了与旧版本的兼容性，不会破坏现有代码。

最佳实践

以下是推荐的完整实现示例：

struct Wrapper<Model: Codable>: Codable {
    var model: Model
    var metadata: String
    
    enum CodingKeys: String, CodingKey {
        case metadata
    }
    
    init(model: Model, metadata: String) {
        self.model = model
        self.metadata = metadata
    }
    
    init(from decoder: any Decoder) throws {
        model = try Model(from: decoder)
        let container = try decoder.container(keyedBy: CodingKeys.self)
        metadata = try container.decode(String.self, forKey: .metadata)
    }
    
    func encode(to encoder: any Encoder) throws {
        // 使用单值容器编码主模型
        var modelContainer = encoder.singleValueContainer()
        try modelContainer.encode(model)
        
        // 使用键控容器编码额外字段
        var container = encoder.container(keyedBy: CodingKeys.self)
        try container.encode(metadata, forKey: .metadata)
    }
}

技术原理

GRDB.swift 的编码器在处理单值容器时，实际上是将整个类型作为一个整体交给编码器处理。这与直接将值编码到编码器有所不同：

• 直接编码：将类型的内容写入编码器
• 单值容器编码：给编码器机会拦截整个类型

这种设计使得编码器能够更灵活地处理不同类型的数据结构，特别是在处理数据库记录时，可以保持更好的类型安全和数据一致性。

总结

GRDB.swift 6.28.0 版本对单值容器编码的支持，使得开发者能够更灵活地实现通用记录包装器。通过合理使用单值容器和键控容器的组合，我们可以构建出既能保持内部模型完整结构，又能添加额外元数据的包装类型。这种模式特别适用于需要隐藏部分数据库字段，同时保留内部使用完整数据的场景。