Apollo Kotlin 中处理输入类型默认值的优化方案

背景介绍

在 GraphQL 开发中，我们经常需要在 schema 中定义输入类型(Input Type)并为其字段设置默认值。Apollo Kotlin(原 Apollo Android)作为一款强大的 GraphQL 客户端库，会自动根据 schema 生成对应的数据类。然而，默认值的处理方式在某些场景下可能不是最优解。

默认值处理的现状

当前，当 schema 中定义了一个带有默认值的输入字段时，例如：

input AddOnPlanId {
  addOnPlanId: ID!
  termsConsented: Boolean! = false
}

Apollo Kotlin 会生成如下 Kotlin 数据类：

data class AddOnPlanId(
  val addOnPlanId: String,
  val termsConsented: Boolean = false
) : InputType

这种实现方式直接将默认值硬编码到生成的客户端代码中，虽然简单直接，但也带来了一些限制。

现有方案的问题

1. 网络传输效率：即使客户端使用默认值，字段仍会被包含在请求负载中，增加了不必要的网络传输数据量。

2. 服务端灵活性：当服务端需要修改默认值时，必须等待所有客户端更新并重新下载 schema，这在移动端(特别是 Android 和 iOS)尤其成问题，因为用户可能不会立即更新应用。

3. 版本兼容性：服务端无法在不破坏兼容性的情况下修改默认值行为。

改进方案

社区提出了一种优化方案：将带有默认值的字段生成为可选(Optional)类型，默认值为 Optional.Absent，而不是直接应用 schema 中的默认值。这样生成的代码会变为：

data class AddOnPlanId(
  val addOnPlanId: String,
  val termsConsented: Optional<Boolean?> = Optional.Absent
) : InputType

方案优势

1. 减少网络负载：当客户端不显式设置值时，字段不会被包含在请求中，减少了传输数据量。

2. 服务端控制权：默认值的逻辑完全由服务端控制，可以随时调整而无需客户端更新。

3. 更好的兼容性：服务端可以更灵活地演进 API，不会因为默认值的变化而破坏现有客户端。

技术实现细节

在 Apollo Kotlin 3.x 版本中，这一改进已经得到实现。例如对于以下 schema 定义：

input AmendReservationInput {
  isRemediationFlow: Boolean! = false
}

生成的 Kotlin 代码会将字段标记为 Optional：

public data class AmendReservationInput(
  public val isRemediationFlow: Optional<Boolean> = Optional.Absent
)

最佳实践建议

1. 服务端设计：在设计 GraphQL schema 时，考虑将可能变化的业务逻辑默认值放在服务端处理。

2. 客户端使用：在客户端代码中，可以显式省略使用默认值的字段，让服务端处理默认逻辑。

3. 版本规划：对于关键业务字段，即使有默认值也建议显式传递，避免因服务端默认值变更而影响业务逻辑。

总结

Apollo Kotlin 对输入类型默认值处理的优化，体现了 GraphQL 客户端库在灵活性和效率方面的持续改进。这种设计模式不仅减少了不必要的网络传输，还赋予了服务端更大的控制权，使得 API 的演进更加平滑。对于需要长期维护的移动应用尤其有价值，可以有效降低因默认值变更带来的客户端更新压力。