Apollo iOS 中自定义 JSON 标量类型的实现方案

背景介绍

在 Apollo iOS 1.0 版本迁移过程中，许多开发者遇到了自定义标量类型的兼容性问题。特别是对于常用的 JSON 类型（即 [String: Any] 字典结构），在从 0.x 版本升级到 1.0 版本时，原有的简单类型别名方式不再适用。

问题核心

Apollo iOS 1.0 对自定义标量类型提出了更严格的要求：

1. 必须实现 CustomScalarType 协议
2. 需要符合 Hashable 协议
3. 在某些情况下还需要实现 SelectionSetEntityValue 协议

解决方案演变

初始方案：包装器结构体

最初开发者尝试使用结构体包装 [String: Any] 类型：

public struct JSON: CustomScalarType, SelectionSetEntityValue {
    private let value: JSONValue
    
    // 需要实现大量委托方法
    public subscript<T>(_ key: String) -> T? {
        guard let dict = value as? [String: Any] else { fatalError() }
        return dict[key] as? T
    }
    
    // 其他字典方法的委托实现...
}

这种方案虽然能让代码编译通过，但存在明显缺点：

1. 需要为字典的每个方法都实现委托
2. 嵌套 JSON 结构类型不一致（顶层是包装类型，嵌套层是原生字典类型）

改进方案：使用 AnyHashable

Apollo 团队成员建议使用 [String: AnyHashable] 替代 [String: Any]：

struct JSON: CustomScalarType, Hashable {
    private let wrapped: [String: AnyHashable]
    
    init(_jsonValue value: JSONValue) throws {
        guard let value = value as? [String: AnyHashable] else { 
            throw JSONDecodingError.wrongType 
        }
        self.wrapped = value
    }
    
    var _jsonValue: JSONValue { wrapped }
}

这个方案解决了部分问题，但仍然需要开发者手动访问 wrapped 属性来操作字典内容。

技术难点分析

1. 类型系统限制：Swift 的 Dictionary 类型无法直接满足 CustomScalarType 的协议要求，特别是 Any 和 AnyHashable 之间的类型转换问题。

2. 嵌套结构处理：当 JSON 包含嵌套结构时，类型一致性难以保证，开发者需要处理包装类型和原生字典类型之间的转换。

3. 向后兼容性：从 0.x 升级到 1.0 版本时，原有代码中大量的字典操作需要重构。

最佳实践建议

1. 明确类型边界：在项目早期就定义好 JSON 标量的使用边界，尽量避免深层嵌套结构。

2. 统一访问方式：为包装类型实现完整的字典接口，或者统一使用特定方法访问内容。

3. 错误处理：使用更健壮的错误处理替代 fatalError()，提供更有意义的错误信息。

4. 类型转换辅助：为常用类型转换创建扩展方法，简化开发者的日常使用。

总结

Apollo iOS 1.0 对类型系统进行了重大改进，这虽然带来了短期的迁移成本，但也提供了更好的类型安全和运行时稳定性。对于 JSON 标量类型的处理，开发者需要在类型安全和开发便利性之间找到平衡点。包装器模式虽然增加了少量样板代码，但能够提供更好的类型控制和错误处理能力，是当前推荐的实现方式。