Swift-Protobuf 项目中 TextFormat 解析对保留字段的处理问题分析

在 Protocol Buffers 的文本格式（TextFormat）解析过程中，对于消息定义中标记为保留（reserved）的字段名称和字段编号的处理存在一个长期未发现的问题。根据 Protocol Buffers 官方文本格式规范，解析器应当忽略任何出现在保留字段列表中的字段，无论其以何种形式出现（标量、列表或消息）。

这个问题直到最近才被上游 Protocol Buffers 项目通过添加一致性测试发现。在 Swift-Protobuf 实现中，当前版本尚未正确处理这一规范要求，需要针对保留字段名称和编号进行特殊处理。

问题背景

Protocol Buffers 允许开发者通过 reserved 关键字将某些字段名称或编号标记为保留状态，这通常用于防止其他开发者意外重用已被删除的字段标识符。根据规范，TextFormat 解析器遇到这些保留字段时应当：

1. 对于未在消息定义中指定但出现在保留字段列表中的字段，应当允许存在但忽略其值
2. 对于明确标记为保留的字段，无论其以何种形式出现都应被忽略

技术实现方案分析

在 Swift-Protobuf 中实现这一功能需要考虑以下几个方面：

方案一：扩展 _ProtoNameProviding 协议

这个方案建议在现有的 _ProtoNameProviding 协议中增加两个静态变量来提供保留字段信息：

• 添加只读的静态变量来获取保留字段名称列表和保留编号范围
• 提供默认实现返回空值
• 为有保留字段的消息生成特定实现
• 在 TextFormatScanner 中进行额外检查

优点：

• 逻辑集中，只有 TextFormat 解析需要处理这些特殊情况
• 对现有代码影响小，属于非破坏性变更

缺点：

• 需要修改多处代码来支持新的协议要求

方案二：修改 _NameMap 结构

这个方案建议通过扩展 _NameMap 结构来携带保留字段信息：

• 添加新的初始化方法支持传入保留字段数据
• 利用特殊值编码保留信息（如使用≤0的字段编号）
• 更新所有扫描器逻辑处理这些特殊值

优点：

• 信息集中存储，便于访问
• 与现有名称查找机制结合紧密

缺点：

• 可能增加 _NameMap 的内存占用
• 需要更复杂的编码方案处理保留编号范围

最终实现方向

经过讨论，团队倾向于采用结合 KeyValuePairs 和 _NameMap 扩展的混合方案：

1. 为 _NameMap 添加新初始化方法，支持同时传入常规字段映射和保留字段信息
2. 在 _NameMap 中添加专门API检查字段是否属于保留范围
3. 使 TextFormatScanner 在遇到未知字段时进行保留字段检查

这种方案平衡了代码清晰度和性能考虑，同时保持了良好的扩展性。虽然会轻微增加 _NameMap 结构的大小，但由于所有调用都是内部（internal）的，未来仍有优化空间。

对其他类型的影响

值得注意的是，Protocol Buffers 的枚举类型也支持类似的保留字段机制。虽然当前实现尚未使用这些信息，但设计的解决方案应当考虑未来可能的扩展需求，确保能够同样适用于枚举类型的保留字段处理。

这个改进将帮助 Swift-Protobuf 更好地遵循 Protocol Buffers 规范，提高与其他语言实现的兼容性，同时也为开发者提供了更符合预期的行为。