Apollo Kotlin 简介

Apollo Kotlin 是一个强类型的 GraphQL 客户端，它为您的 GraphQL 操作生成 Kotlin 模型。

Apollo Kotlin 执行操作针对的 GraphQL 服务器 并以操作特定的 Kotlin 类型返回结果。这意味着您不需要处理解析 JSON，也不需要手动将客户端的值强制转换为正确的类型。Map 和将值强制转换为正确类型的客户端。您也不需要自己编写模型类型，因为这些类型是从您的应用程序使用的 GraphQL 定义生成的。

因为生成的类型是 操作特定的，您只能访问作为操作一部分实际指定的数据。如果您在一个操作中不请求特定的 字段，则无法访问返回数据结构上相应的属性。

此库主要针对 Android 设计，但您可以在任何 Kotlin 应用程序中使用它，包括 KMP（Kotlin 多平台）。

功能

• Kotlin 多平台代码生成
• 查询、 变异 和 订阅。
• 无反射解析
• 规范化缓存
• HTTP 缓存
• 自定义 标量 类型
• 自动 持久化查询
• 查询批处理
• 文件上传
• 用于测试的模拟模型
• AppSync 和 GraphQL-ws WebSocket
• GraphQL AST 解析器
• Android Studio 和 IntelliJ 插件

入门

如果您对 GraphQL 感兴趣，请查看 教程，该教程将指导您使用 Apollo 构建 Android 应用。

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

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

1
plugins {
2
  id("com.apollographql.apollo") version "4.0.0"
3
}

添加运行时依赖

1
dependencies {
2
  implementation("com.apollographql.apollo:apollo-runtime:4.0.0")
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（或者KMP的src/commonMain/graphql）目录中有一个模式。您可以使用内省来下载模式，使用命令./gradlew downloadApolloSchema。有时内省被禁用，您需要要求后端团队提供模式。将此模式复制到您的模块：

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

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

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

构建您的项目。这将生成一个HeroQuery类，您可以使用ApolloClient实例使用它：

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的其他信息

• 执行您的第一个突变。
• 处理自定义标量类型。
• 使用 片段 来提取公共模式。

多平台

Apollo Kotlin 是一个 Kotlin Multiplatform 项目。

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

¹: Apple currently includes

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

需求

某些平台有特定的运行时要求

• JVM 8+
• Android API level 21+ (apollo-http-cache 需要启用 核心库反编译 在 Android API levels < 26)
• iOS 13+

在构建时，它需要

• Gradle 8.0+
• JVM 项目需要 Kotlin 1.9+
• 原生、JS 和 Wasm 项目需要 Kotlin 2.0+

Proguard / R8 配置

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

Android Studio / IntelliJ 插件

Android Studio 和 IntelliJ 的一个 插件 可用于帮助您使用 Apollo Kotlin，提供自动代码生成、与 GraphQL IntelliJ Plugin 集成、导航到 GraphQL 定义、迁移助手等。

有关安装说明和更多信息，请参阅 此处。

版本发布

最新版本是 4.0.0。

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

发布版本托管在 Maven Central 上。该插件还托管在 Gradle Plugin Portal

1
plugins {
2
  id("com.apollographql.apollo") version "4.0.0"
3
}
4

5
repositories {
6
  mavenCentral()
7
}
8

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

12
  // Optional: if you want to use the normalized cache
13
  implementation("com.apollographql.apollo:apollo-normalized-cache-sqlite:4.0.0")
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.apollo:apollo-api:4.0.0")
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
}

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

这些快照在下一次对 main 的推送时更新。

Android Studio / IntelliJ插件的每周快照 也可用。

演变策略

您可以在 专门的页面 上了解我们的演变策略。

贡献

如果您想贡献，请参阅 CONTRIBUTING.md。

社区集成

• 如果您使用的是 Maven构建工具， apollo-client-maven-plugin 是一个Maven插件，用于调用Apollo Kotlin编译器来生成您的Java/Kotlin源代码。
• 如果您正在使用 Absinthe Phoenix 订阅，kotlin-phoenix 提供了可以与 ApolloClient 一起使用的 PhoenixNetworkTransport)

其他资源

• Confetti：一个使用 Apollo Kotlin、SwiftUI 和 Jetpack Compose 的 Kotlin 多平台会议应用程序。
• MortyComposeKMM：一个使用 Apollo Kotlin、SwiftUI 和 Jetpack Compose 的 Kotlin 多平台 GitHub 演示模板。
• Kotlin 多平台之旅：该项目如何迁移到 Kotlin 多平台，在 2020 年 6 月 Kotliners 活动上发表的演讲。
• #125，Fragmented Podcast：关于 Apollo Kotlin 以及整个旅程的为什么和如何。
• GraphQL.org：有关 GraphQL 本身的介绍和参考。
• apollographql.com了解 Apollo 开源和商业工具。
• Apollo 博客阅读关于 GraphQL、Apollo 产品发布和社区文章的长篇内容。
• Apollo Twitter 账户获取最新资讯。