Apollo Kotlin 中的自定义标量类型

除了其内置标量类型（Int, String 等.), GraphQL 支持自定义标量。例如，您的模式可能定义了一个用于 Long, Date, BigDecimal 或 GeoPoint 的自定义标量。

定义类映射

在与您的 Apollo Kotlin 应用中的自定义标量进行交互时，您需要在您的 build.gradle[.kts] 文件中定义一个映射。这将告诉 Apollo Kotlin 使用哪个类来表示您 schema 中的每个自定义标量。

build.gradle[.kts]

1
apollo {
2
  service("service") {
3
    mapScalar("GeoPoint", "com.example.GeoPoint")
4

5
    // Shortcuts exist for standard types - equivalent to mapScalar("Long", "kotlin.Long")
6
    mapScalarToKotlinLong("Long")
7
  }
8
}

如果需要的话，您也可以用内置标量（如 ID）来覆盖其默认类型。

定义类适配器

您用来表示自定义标量的每个类也需要一个 适配器，用于将其转换为从网络发送的 JSON 格式。

每个适配器都需要一个 fromJson 函数。如果您的应用将自定义标量作为 GraphQL 参数传递，则需要一个 toJson 函数。

这是一个用于 GeoPoint 自定义标量的适配器：

1
class GeoPoint(val latitude: Double, val longitude: Double)
2

3
val geoPointAdapter = object : Adapter<GeoPoint> {
4
  override fun fromJson(reader: JsonReader, customScalarAdapters: CustomScalarAdapters): GeoPoint {
5
    var latitude: Double? = null
6
    var longitude: Double? = null
7
    reader.beginObject()
8
    while(reader.hasNext()) {
9
      when (reader.nextName()) {
10
        "latitude" -> latitude = reader.nextDouble()
11
        "longitude" -> longitude = reader.nextDouble()
12
      }
13
    }
14
    reader.endObject()
15

16
    // fromJson can throw on unexpected data and the exception will be wrapped in a
17
    // ApolloParseException
18
    return GeoPoint(latitude!!, longitude!!)
19
  }
20

21
  // If you do not expect your scalar to be used as input, you can leave this method as TODO()
22
  override fun toJson(writer: JsonWriter, customScalarAdapters: CustomScalarAdapters, value: GeoPoint) {
23
    writer.beginObject()
24
    writer.name("latitude").value(value.latitude)
25
    writer.name("longitude").value(value.longitude)
26
    writer.endObject()
27
  }
28
}

如果您更喜欢使用 Map， Apollo Kotlin 提供了 AnyAdapter，它支持将 String、Int、Double、Boolean、List 和 Map 进行适配。您可以在中间步骤中使用它：

1
val geoPointAdapter = object : Adapter<GeoPoint> {
2
  override fun fromJson(reader: JsonReader, customScalarAdapters: CustomScalarAdapters): GeoPoint {
3
    val map = AnyAdapter.fromJson(reader) as Map<String, Double>
4
    return GeoPoint(map["latitude"] as Double, map["longitude"] as Double)
5
  }
6

7
  override fun toJson(writer: JsonWriter, customScalarAdapters: CustomScalarAdapters, value: GeoPoint) {
8
    val map = mapOf(
9
        "latitude" to value.latitude,
10
        "longitude" to value.longitude
11
    )
12
    AnyAdapter.toJson(writer, map)
13
  }
14
}

此解决方案更简洁，但性能略低。

注册适配器

定义完适配器后，您需要注册它们。这可以在 build.gradle[.kts] 文件中完成，或者在运行时完成。

`build.gradle[.kts]`

可以为 mapScalar 传递第三个参数来指定要使用的适配器：

build.gradle[.kts]

1
apollo {
2
  service("service") {
3
    mapScalar("GeoPoint", "com.example.GeoPoint", "com.example.Adapters.geoPointAdapter")
4
  }
5
}

生成的代码中直接复制给定的表达式。因此，可以传递以下任何一种

实例化表达式，如 "com.example.GeoPointAdapter()"
单例引用，如 "com.example.GeoPointAdapter"
函数调用，如 "com.example.Adapters.getGeoPointAdapter()"

确保传递包括包在内的完整类名，因为不会自动生成导入。

在运行时

您还可以通过调用 ApolloClient.Builder.addCustomScalarAdapter 为每个适配器在您的 ApolloClient 实例上注册适配器：

1
val apolloClient = ApolloClient.Builder().serverUrl("https://")
2
    .addCustomScalarAdapter(GeoPoint.type, geoPointAdapter)
3
    .build()

此方法接收从 Types 生成的类型安全的类及其对应的适配器。

如果您找不到 Types，请在构建项目中触发代码生成。

由 Apollo 提供的适配器

以下内置适配器可以与常见的自定义标量类型一起使用：

适配器	描述
`com.apollographql.apollo3.api.FloatAdapter`	转换 `kotlin.Float`/`java.lang.Float`
`com.apollographql.apollo3.api.LongAdapter`	转换 `kotlin.Long`/`java.lang.Long`

除此之外，com.apollographql.apollo3:apollo-adapters 软件包还提供了以下适配器：

适配器	描述
`com.apollographql.apollo3.adapter.KotlinxInstantAdapter`	用于 `kotlinx.datetime.Instant` ISO8601 日期
`com.apollographql.apollo3.adapter.JavaInstantAdapter`	用于 `java.time.Instant` ISO8601 日期
`com.apollographql.apollo3.adapter.KotlinxLocalDateAdapter`	用于 `kotlinx.datetime.LocalDate` ISO8601 日期
`com.apollographql.apollo3.adapter.JavaLocalDateAdapter`	用于 `java.time.LocalDate` ISO8601 日期
`com.apollographql.apollo3.adapter.KotlinxLocalDateTimeAdapter`	用于 `kotlinx.datetime.LocalDateTime` ISO8601 日期
`com.apollographql.apollo3.adapter.JavaLocalDateTimeAdapter`	用于 `java.time.LocalDateTime` ISO8601 日期
`com.apollographql.apollo3.adapter.KotlinxLocalTimeAdapter`	用于 `kotlinx.datetime.LocalTime` ISO8601 日期
`com.apollographql.apollo3.adapter.JavaLocalTimeAdapter`	用于 `java.time.LocalTime` ISO8601 日期
`com.apollographql.apollo3.adapter.JavaOffsetDateTimeAdapter`	用于 `java.time.OffsetDateTime` ISO8601 日期
`com.apollographql.apollo3.adapter.DateAdapter`	用于 `java.util.Date` ISO8601 日期
`com.apollographql.apollo3.adapter.BigDecimalAdapter`	用于包含大数值的 Multiplatform `com.apollographql.apollo3.adapter.BigDecimal` 类

注意：由于一些适配器使用了 kotlinx.datetime（它本身又使用了 java.time），您需要在 Android API 级别 < 26 上启用核心库降级。

例如，要使用 DateAdapter，请按照以下方式配置您的 Gradle 脚本：

build.gradle[.kts]

1
dependencies {
2
  implementation("com.apollographql.apollo3:apollo-adapters:3.8.5")
3
}
4

5
apollo {
6
  service("service") {
7
    mapScalar("Date", "java.util.Date", "com.apollographql.apollo3.adapter.DateAdapter")
8
  }
9
}

错误处理

片段