Apollo Kotlin 中枚举类型的向前兼容性处理优化

在 GraphQL 与 Kotlin 的类型系统交互中，枚举类型的处理一直是一个需要特别注意的领域。Apollo Kotlin 作为 GraphQL 的 Kotlin 客户端实现，近期对其枚举类型的生成逻辑进行了重要优化，特别是在处理未知枚举值时的行为。

问题背景

在 GraphQL 规范中，枚举类型是严格定义的，客户端只能使用服务端已声明的枚举值。然而，在实际开发中，服务端可能会随着时间的推移添加新的枚举值。为了保持向前兼容性，Apollo Kotlin 客户端通常会为每个枚举类型生成一个特殊的 UNKNOWN__ 值，用于处理客户端尚未识别的枚举值。

但这种实现方式存在一个潜在问题：开发者可能会错误地将 UNKNOWN__ 值作为输入参数传递给 GraphQL 变更操作。由于服务端并未定义这个值，这样的请求必定会在服务端验证阶段失败。

原始实现分析

在优化前的版本中，Apollo Kotlin 会为每个 GraphQL 枚举生成如下的 Kotlin 代码：

public enum class SomeEnum {
  FOO,
  BAR,
  UNKNOWN__;
  
  public companion object {
    public fun safeValueOf(rawValue: String): SomeEnum =
        values().find { it.name == rawValue } ?: UNKNOWN__
  }
}

这种实现允许开发者直接使用 UNKNOWN__ 作为输入值，虽然这在逻辑上是不正确的。

解决方案演进

开发团队考虑了多种解决方案：

1. 使用密封类替代枚举：通过 sealedClassesForEnumsMatching 配置，可以将枚举转换为密封类，这提供了更好的类型安全性。团队曾考虑将其设为 v4 版本的默认行为。

2. 添加 @OptIn 注解：最初尝试在 UNKNOWN__ 构造函数上添加 Kotlin 的 @OptIn 注解，使开发者需要显式声明才能使用这个值。

3. 移除 UNKNOWN__ 构造函数：最终采用的方案是完全移除 UNKNOWN__ 构造函数，强制开发者使用 safeValueOf 方法来处理未知值。这种方法既保持了向前兼容性，又防止了错误使用。

最终实现

优化后的代码生成如下：

public enum class SomeEnum {
  FOO,
  BAR;
  
  public companion object {
    public fun safeValueOf(rawValue: String): SomeEnum =
        values().find { it.name == rawValue } 
            ?: throw IllegalArgumentException("Unknown enum value: $rawValue")
  }
}

这种实现方式具有以下优点：

1. 编译时安全性：开发者无法直接构造无效的枚举值，错误会在编译阶段被发现。

2. 明确的错误处理：当遇到未知值时，safeValueOf 方法会抛出异常，强制开发者处理这种情况。

3. 保持兼容性：仍然能够处理服务端新增的枚举值，只是现在需要显式处理。

开发者影响

对于现有项目，这一变化意味着：

1. 所有直接使用 UNKNOWN__ 的代码都需要重构，改为使用 safeValueOf 方法。

2. 错误处理逻辑需要更加明确，不能依赖默认的未知值处理。

3. 新项目从一开始就能避免潜在的错误使用模式。

最佳实践建议

基于这一变更，推荐以下开发实践：

1. 始终使用生成的 safeValueOf 方法来解析枚举值，而不是直接引用枚举常量。

2. 在处理来自网络或存储的枚举值时，添加适当的错误处理逻辑。

3. 考虑在项目中使用 sealedClassesForEnumsMatching 配置，以获得更强的类型安全性。

这一优化体现了 Apollo Kotlin 团队对类型安全性和开发者体验的持续关注，使得 GraphQL 客户端开发更加健壮和可靠。