Apollo Kotlin 项目开发指南

Apollo Kotlin 项目开发指南

apollo-kotlin :robot:  A strongly-typed, caching GraphQL client for the JVM, Android, and Kotlin multiplatform. 项目地址: https://gitcode.com/gh_mirrors/ap/apollo-kotlin

本文将为开发者详细介绍如何参与 Apollo Kotlin 项目的开发工作。Apollo Kotlin 是一个强大的 GraphQL 客户端库，专为 Kotlin 和 Android 平台设计，支持多平台开发。

开发环境准备

要开始 Apollo Kotlin 的开发工作，需要准备以下环境：

1. JDK 17+：项目要求 Java 17 或更高版本的 JDK
2. IDE：推荐使用 IntelliJ IDEA Community 版，虽然 Android Studio 也能工作，但 IntelliJ 对多平台代码的支持更好
3. iOS 开发环境：如果要开发 iOS/MacOS 相关功能，需要：
   • MacOS 系统
   • Xcode 开发者工具
   • iOS/watchOS 模拟器用于测试

项目结构解析

Apollo Kotlin 采用多模块 Gradle 构建系统，主要包含以下几个部分：

1. 主构建(root build)：包含核心库代码
2. 构建逻辑(build-logic)：共享的 Gradle 构建逻辑
3. 测试模块(tests)：集成测试代码
4. 基准测试(benchmarks)：Android 微基准和宏基准测试

对于日常开发，建议在 IntelliJ 中打开 tests 文件夹。这是一个复合构建，包含了主构建和集成测试，便于添加 GraphQL 并进行端到端的代码生成测试。

本地开发与测试

要在本地项目中测试 Apollo Kotlin 的修改，可以按照以下步骤操作：

1. 发布本地版本到 Maven 本地仓库：

./gradlew publishToMavenLocal

2. 在其他项目的构建脚本中添加本地 Maven 仓库：

// build.gradle.kts
repositories {
  mavenLocal()
  mavenCentral()
}

// settings.gradle.kts
pluginManagement {
  repositories {
    mavenLocal()
    gradlePluginPortal()
    mavenCentral()
  }
}

这种方法需要在每次修改 Apollo Kotlin 后重新运行 publishToMavenLocal。对于更紧密的集成，也可以使用 Gradle 的复合构建功能。

代码规范指南

基础规范

1. 命名约定：

   • 类名使用 PascalCase
   • 方法和变量使用 camelCase
   • 缩进使用 2 个空格

2. 构建器模式：

   • 当参数不超过一个可选参数时，优先使用带有 @JvmOverloads 的主构造函数
   • 对于类，将构建器直接嵌套在类下
   • 对于接口，使用 Default${Interface} 命名模式

3. Java 互操作：

   • 尽量避免扩展函数，因为它们在 Java 中使用不便
   • 使用 @JvmOverloads 优化带可选参数的函数
   • 优先使用顶层 val 而非单例 object

日志与错误处理

1. 日志规范：

   • 禁止使用 System.out 或 System.err 输出日志
   • 错误信息通过 Exception.message 传递给用户
   • 为调试提供专门的 API 获取诊断信息

2. 错误消息格式：

   • 当消息来源不明显时，应包含 "Apollo: " 前缀

Gradle API 使用

1. 命名约定：
   • 惰性属性使用名词形式，如 packageName.set("com.example")
   • 带参数的方法使用动词形式，如 mapScalar("ID", "kotlin.Long")
   • 单一 Action<T> 类型参数的方法例外

其他规范

1. 时间参数：

   • 毫秒参数应带有 "Millis" 后缀
   • 其他情况使用 kotlin.time.Duration

2. 实验性 API：

   • 尽量避免使用 Kotlin 的实验性 API
   • 项目自定义的 @ApolloExperimental 注解可用于标记实验性功能

API 演进策略

Apollo Kotlin 遵循语义化版本控制原则：

1. 二进制兼容性：使用 Binary compatibility validator 插件跟踪公共 API 变更

2. API 变更处理：

   • 运行 ./gradlew apiDump 检查不兼容变更
   • 提交变更前检查生成的 API 文件

3. 废弃 API 流程：

   stateDiagram-v2
       direction LR
       NotDeprecated: 未废弃
       NotDeprecated --> Deprecated(WARNING): 次要版本
       Deprecated(WARNING) --> Removed: 主要版本
   

测试策略

项目包含多种测试类型：

1. 单元测试：运行 ./gradlew build
2. 集成测试：运行 ./gradlew -p tests build
3. Gradle 测试：用于特定场景测试：
   • 测试特定 Gradle/插件版本
   • 需要调整 Gradle 环境的测试
   • 测试增量构建、构建缓存等特性

发布流程

Apollo Kotlin 的发布流程如下：

1. 准备阶段：

   • 确保主分支代码最新
   • 运行发布脚本指定版本号

2. 发布过程：

   • 准备变更日志
   • 等待 CI 完成编译
   • 在 Sonatype 上手动发布构件

3. 发布后：

   • 等待构件出现在 Maven Central
   • 合并待处理的文档更新
   • 在版本发布页面发布变更日志

调试技巧

由于 Gradle 插件使用 R8 进行依赖重定位，堆栈跟踪默认与源代码不匹配。可以使用以下步骤重新追踪：

1. 获取 R8 工具和映射文件
2. 使用 R8 的 Retrace 工具处理堆栈跟踪

CI 工作流概述

项目使用自动化构建系统，包含三个主要工作流：

1. PR 工作流：

   • 运行各种测试任务
   • 检查 API 变更
   • 构建 IntelliJ 插件

2. 主分支推送工作流：

   • 运行全部测试
   • 发布快照版本
   • 发布文档

3. 标签发布工作流：

   • 发布库到 Maven Central
   • 发布 IntelliJ 插件

通过本文，开发者可以全面了解 Apollo Kotlin 项目的开发规范和工作流程，为参与项目开发做好准备。

apollo-kotlin :robot:  A strongly-typed, caching GraphQL client for the JVM, Android, and Kotlin multiplatform. 项目地址: https://gitcode.com/gh_mirrors/ap/apollo-kotlin