Apollo Kotlin 简介

Apollo Kotlin（原名 Apollo Android）是一个 GraphQL客户端，可以从GraphQL查询中生成Kotlin和Java模型。

Apollo Kotlin执行查询和 更改操作，针对GraphQL服务器运行，并以特定于查询的Kotlin类型返回结果。这意味着你无需处理解析JSON或传递Map（映射）和将值手动转换为正确的类型的操作。你也不必自己编写模型类型，因为这些类型是从UI使用的GraphQL定义生成的。

由于生成的类型是特定于查询的，因此您只能访问查询中实际指定的数据。如果您在查询中没有请求特定的字段，您无法访问返回数据结构上的对应属性。

这个库主要针对Android设计，但您可以在任何Java/Kotlin应用程序中使用它，包括多平台。

特性

• Java和Kotlin多平台代码生成
• 查询、更改和订阅。
• 无反射解析
• 规范化缓存
• 自定义标量类型
• HTTP缓存
• 自动持久查询
• 查询批处理
• 文件上传
• Espresso IdlingResource
• 测试的模拟模型
• AppSync和graphql-websocket
• GraphQL AST解析器

多平台

Apollo Kotlin是一个Kotlin Multiplatform项目。

以下是每个平台支持的功能矩阵

¹: 苹果目前包含

• macosX64
• macosArm64
• iosArm64
• iosX64
• iosSimulatorArm64
• watchosArm32
• watchosArm64
• watchosSimulatorArm64
• tvosArm64
• tvosX64
• tvosSimulatorArm64

开始使用

如果您是 GraphQL 的新手，请查看教程，该教程将指导您使用 Apollo、Kotlin 和协同程序构建 Android 应用。

如果您想将 Apollo Kotlin 添加到现有项目中，请按照以下步骤操作：

将插件添加到您的build.gradle.kts：

1
plugins {
2
  id("com.apollographql.apollo3").version("3.8.3")
3
}

添加运行时依赖项

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

设置用于生成的模型所使用的包名

1
apollo {
2
  service("service") {
3
    packageName.set("com.example")
4
  }
5
}

Apollo Kotlin 支持三种类型的文件：

• .graphqls 模式文件：使用 GraphQL 语法描述您后端中的类型。
• .json 模式文件：使用 Json 语法描述您后端中的类型。
• .graphql 可执行文件：使用 GraphQL 语法描述您的查询和操作。

默认情况下，Apollo Kotlin 要求在模块的src/main/graphql 目录中有一个模式。您可以使用 introspection 任务./gradlew downloadApolloSchema下载模式。有时候 introspection 是禁用的，您将需要请求您的后端团队提供模式。将该模式复制到您的模块：

1
cp ${schema} ${module}/src/main/graphql/

在文件${module}/src/main/graphql/GetRepository.graphql中编写一个查询：

1
query HeroQuery($id: String!) {
2
  hero(id: $id) {
3
    id
4
    name
5
    appearsIn
6
  }
7
}

构建您的项目。这将生成一个用于与 ApolloClient 实例一起使用的 HeroQuery 类：

1
// Create a client
2
  val apolloClient = ApolloClient.Builder()
3
      .serverUrl("https://example.com/graphql")
4
      .build()
5

6
  // Execute your query. This will suspend until the response is received.
7
  val response = apolloClient.query(HeroQuery(id = "1")).execute()
8

9
  println("Hero.name=${response.data?.hero?.name}")

要了解更多关于其他 Apollo Kotlin API 的信息

• 执行您的第一个 变异操作
• 处理 自定义标量类型
• 使用 碎片 因素常见的模式

要求

有些平台有特定要求

• Android API 级别 21+（apollo-http-cache 和 apollo-adapters 需要 启用核心库降级 Android API 级别 < 26）
• JDK 8+
• iOS 13+

构建时需要

• Gradle 5.6
• JVM 项目需要 Kotlin 1.8+
• 本地项目需要 Kotlin 1.9+

Proguard / R8 配置

由于 Apollo Kotlin 生成的代码没有使用任何反射，它可以安全地由 Proguard 或 R8 进行优化/混淆，因此不需要配置特定排除。

IntelliJ 插件

The JS Graphql IntelliJ Plugin 提供了自动完成、错误高亮以及跳转到定义功能，用于您的 .graphql 文件。您可以创建一个 .graphqlconfig 文件，以便使用 GraphQL 擦拭文件处理方案外代码（如编写临时查询以测试 解析器）。请确保在插件设置中选中 “指令” 类似于 @nonnull 和 typePolicy 被识别。

发布

最新版本是

查看 变更日志 以了解发布历史。

发布托管在 Maven Central。此外，插件还托管在 Gradle 插件门户

1
plugins {
2
  id("com.apollographql.apollo3").version("3.8.3")
3
}
4

5
repositories {
6
  mavenCentral()
7
}
8

9
dependencies {
10
  implementation("com.apollographql.apollo3:apollo-runtime:3.8.5")
11

12
  // optional: if you want to use the normalized cache
13
  implementation("com.apollographql.apollo3:apollo-normalized-cache-sqlite:3.8.5")
14
  // optional: if you just want the generated models and parsers and write your own HTTP code/cache code, you can remove apollo-runtime
15
  // and use apollo-api instead
16
  implementation("com.apollographql.apollo3:apollo-api:3.8.5")
17
}

快照

最新的开发更改可在 Sonatype 的快照仓库中获得

1
// build.gradle.kts
2
repositories {
3
  maven {
4
    url = uri("https://s01.oss.sonatype.org/content/repositories/snapshots/")
5
  }
6
  mavenCentral()
7
  // other repositories...
8
}
9

10
// settings.gradle.kts
11
pluginManagement {
12
  repositories {
13
    maven {
14
      url = uri("https://s01.oss.sonatype.org/content/repositories/snapshots/")
15
    }
16
    gradlePluginPortal()
17
    mavenCentral()
18
    // other repositories...
19
  }
20
}

然后使用插件的 3.8.6-SNAPSHOT 版本和库。

贡献

如果您想贡献，请查看 Contributing.md。

社区集成

• 如果您正在使用Maven构建工具，https://github.com/aoudiamoncef/apollo-client-maven-plugin是一个Maven插件，它调用Apollo Android编译器来生成您的Java/Kotlin源代码。
• 如果您使用Absinthe Phoenix订阅，kotlin-phoenix有一个PhoenixNetworkTransport，您可以与ApolloClient结合使用（文档）

补充资源

• Kotlin多平台之旅：该项目如何在2020年6月迁移到Kotlin多平台，由Kotliners在2020年6月举办的讲座。
• #125，Fragmented Podcast：关于Apollo Kotlin及其整个历程的为什么和如何。
• GraphQL.org 了解GraphQL及相关参考资料。
• apollographql.com 了解Apollo开源及商业工具。
• Apollo博客 阅读关于GraphQL的长篇文章、Apollo功能发布及社区文章。
• Apollo推特账户 获取实时新闻。