Apollo iOS 中关于废弃类型标记问题的技术解析

在 Apollo iOS 1.15.3 版本中，开发者发现了一个关于 GraphQL 废弃标记在代码生成中的行为差异问题。这个问题涉及到 GraphQL 模式中废弃字段和废弃类型在生成的 Swift 代码中的不同处理方式。

问题背景

在 GraphQL 模式定义中，开发者可以使用 @deprecated 指令来标记不再推荐使用的字段或枚举值。当这些被标记的元素在客户端代码中被使用时，理想情况下应该能够通过编译警告来提醒开发者迁移到新的替代方案。

在 Apollo iOS 的代码生成过程中，对于字段级别的废弃标记（如对象类型的字段）能够正确地在生成的 Swift 代码中添加 @available(*, deprecated) 标记。然而，当整个操作（如查询、变更或订阅）被废弃时，生成的 Swift 操作类型本身却没有被标记为废弃。

技术细节分析

这个问题本质上反映了 GraphQL 规范与客户端实现之间的理解差异。在 GraphQL 规范中，@deprecated 指令只能应用于字段定义、参数定义、输入字段定义和枚举值，而不能直接应用于类型定义或操作定义。

在 Apollo iOS 的实现中，代码生成器会为每个 GraphQL 操作生成一个对应的 Swift 类型。当这些操作引用了被废弃的字段时，生成器会正确地在字段访问器上添加废弃标记，但不会将整个操作类型标记为废弃。

解决方案探讨

经过项目维护团队的深入讨论，认为当前的行为是符合设计意图的。主要基于以下几点考虑：

1. 一个操作可能包含多个字段，其中只有部分字段被废弃。将整个操作类型标记为废弃会影响那些只使用非废弃字段的合法用例。

2. 在 GraphQL 模式中，废弃标记应用于字段而非操作本身。客户端代码生成应该准确反映这一语义。

3. 对于需要强制迁移废弃操作的使用场景，可以通过其他工具（如 SwiftLint）来实现自定义规则检查，而无需修改核心代码生成逻辑。

实践建议

对于希望确保代码库中不使用任何废弃 GraphQL 操作的开发者，可以采用以下解决方案：

1. 使用 SwiftLint 或其他代码检查工具，设置自定义规则来检测生成的 Swift 文件中包含 @available(*, deprecated) 标记的情况。

2. 在持续集成流程中添加检查步骤，确保不会提交包含废弃操作引用的代码。

3. 对于需要逐步迁移的场景，可以利用现有的字段级废弃标记，逐个替换对废弃字段的引用。

这种设计决策体现了 Apollo iOS 团队在保持核心功能简洁性和支持特殊用例之间的平衡考虑，同时也为开发者提供了通过生态系统工具扩展功能的灵活性。