plugin-common - 核心基础库

简介

plugin-common 是 Aikero Gradle 插件套件中的核心基础库，为所有其他插件提供共享的公共常量、工具类和通用接口。该模块作为插件开发的基础依赖，通过提供标准化的配置和工具，实现了插件间的代码复用和一致性。它支持构建时模板注入、类型安全访问器（TYPESAFE_PROJECT_ACCESSORS），并通过在配置阶段固化值来支持 Gradle 配置缓存。

提示

注意: 它并非是一个 gradle插件

项目结构

plugin-common 模块是整个 Gradle 插件项目的一部分，位于 gradle-plugin 仓库的根目录下。该项目采用多模块结构，plugin-common 被其他所有插件模块（如 common-conf、publish-conf、api-version-generator 和 version-catalog）作为内部依赖引用。

核心组件

plugin-common 模块的核心功能包括提供公共常量、共享工具函数以及通过构建脚本实现的模板注入机制。它定义了 Nexus 仓库的属性常量和项目扩展函数，并通过 syncKotlinTemplates 任务在构建时生成包含版本信息的 Kotlin 源码文件。这些组件共同构成了插件开发的基础，确保了配置的一致性和构建的可缓存性。

架构概述

plugin-common 模块采用分层架构设计，上层为其他插件提供依赖，下层通过 Gradle 的构建生命周期实现自动化功能。其核心是构建脚本中定义的 syncKotlinTemplates 任务，该任务负责将模板文件中的占位符替换为实际值并生成源码。生成的源码被添加到 Kotlin 编译路径中，确保在编译前完成模板注入。

详细组件分析

公共常量与工具类分析

plugin-common 提供了两个核心的 Kotlin 对象：NexusProp 和 ProjectExt，分别用于定义 Nexus 仓库的属性常量和扩展项目功能。

公共常量定义

工具函数实现

构建脚本与模板注入机制分析

plugin-common 的构建脚本实现了关键的模板注入功能，通过 syncKotlinTemplates 任务在构建时生成包含版本信息的 Kotlin 类。

构建脚本执行流程

KotlinPoet 依赖与类型安全访问器分析

虽然 plugin-common 本身不直接依赖 KotlinPoet，但它是其他插件（如 api-version-generator）使用 KotlinPoet 的基础。同时，plugin-common 所在的项目通过 settings.gradle.kts 启用了 TYPESAFE_PROJECT_ACCESSORS 功能。

依赖关系与功能支持

依赖分析

plugin-common 模块作为核心基础库，被项目中的所有其他插件模块所依赖。它本身仅依赖于 Gradle 的 Kotlin DSL 插件和 common-conf 插件，保持了轻量级和高内聚的特性。这种依赖结构确保了 plugin-common 可以独立演进，同时为上层插件提供稳定的基础。

故障排除指南

当使用 plugin-common 模块时，可能遇到的常见问题包括：

• Nexus 属性未设置：确保在 gradle.properties 文件中正确配置了 companyNexusUsername、companyNexusPassword 等属性，或通过环境变量提供。
• 模板生成失败：检查 src/main/kotlinTemplates 目录是否存在，以及 syncKotlinTemplates 任务的路径配置是否正确。
• 类型安全访问器不可用：确认 settings.gradle.kts 中已启用 enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS")。
• 构建缓存失效：避免在构建脚本中直接访问 project 属性，应使用 providers API 来获取值。