api-version-generator

大约 3 分钟约 896 字

api-version-generator - API版本信息生成

简介

api-version-generator插件是一个Gradle插件，旨在为Kotlin项目自动生成包含项目名称、版本号和构建时间的API版本信息类。该插件通过KotlinPoet库在构建过程中动态生成代码，无需任何额外配置即可实现运行时版本追踪与调试功能。

核心功能

api-version-generator插件的核心功能是自动生成一个Kotlin对象类（如MyProjectApiVersionInfo），该类包含以下信息：

项目名称：从项目路径派生的名称
版本号：来自gradle.properties文件的版本信息
构建时间：代码生成时的精确时间戳

生成的类被放置在build/generated-sources/kotlin/main目录下，并自动添加到Kotlin编译源集中，使得应用代码可以直接访问这些版本信息。

实现机制

插件使用KotlinPoet库在构建时生成带有@VersionMarked注解的Kotlin对象类。其主要实现步骤如下：

插件注册：在build.gradle.kts中通过gradlePlugin块注册插件，指定实现类为team.aikero.gradle.plugin.api.version.ApiVersionInfoGeneratorPlugin。
任务创建：ApiVersionInfoGeneratorPlugin类实现Plugin<Project>接口，在apply方法中创建名为generateApiVersionInfo的Gradle任务。
代码生成：使用GenerateApiVersionInfoTask任务类，通过KotlinPoet构建Kotlin文件结构：
- 创建继承自VersionInfo接口的对象
- 添加@VersionMarked注解
- 生成包含name、version和buildTime属性的代码
输出配置：将生成的代码输出到build/generated-sources/kotlin/main目录。
编译集成：配置Kotlin编译任务依赖于generateApiVersionInfo任务，并将生成的源码目录添加到Kotlin源集。

任务触发时机

generateApiVersionInfo任务的触发时机有两种方式：

自动触发：当插件被应用后，generateApiVersionInfo任务会自动成为compileKotlin任务的依赖。这意味着在执行任何Kotlin编译任务（如build）时，版本信息类会自动先生成。
手动触发：可以通过命令行或IDE直接执行该任务：
```
./gradlew generateApiVersionInfo
```

这种设计确保了版本信息总是在编译前最新生成，保证了构建时间的准确性。

在应用代码中使用版本信息

生成的版本信息类可以在应用代码中直接访问，示例如下：

fun getVersionInfo(): String {
    return "${MyProjectApiVersionInfo.name} v${MyProjectApiVersionInfo.version} (${MyProjectApiVersionInfo.buildTime})"
}

其中：

name：项目名称，基于项目路径生成
version：项目版本号，来自gradle.properties
buildTime：构建时间戳，精确到纳秒级别

生成的类示例：

@VersionMarked
public object MyProjectApiVersionInfo : VersionInfo {
  override val name: String = "my-project"
  override val buildTime: String = "2025-02-08T11:17:23.133925"
  override val version: String = "3.0.2"
}

开箱即用特性

api-version-generator插件具有以下开箱即用的特性：

无需配置：应用插件后即可使用，无需任何额外配置
自动集成：自动生成的代码自动集成到构建流程中
运行时可用：生成的版本信息类在运行时可直接访问
调试友好：提供精确的构建时间戳，便于问题追踪和版本管理
类型安全：通过KotlinPoet生成类型安全的Kotlin代码

这些特性使得开发者可以轻松实现API版本追踪和调试功能，而无需关心底层实现细节。