跳至主要內容

common-conf

大约 5 分钟约 1519 字

common-conf - 通用项目配置插件

简介

common-conf插件是一个专为Gradle项目设计的通用配置插件，旨在简化Java和Kotlin项目的标准化配置过程。该插件通过自动设置源码与目标JVM版本、统一文件编码为UTF-8、自动生成源码JAR包等功能，为开发者提供开箱即用的项目配置解决方案。

插件的核心设计理念是"零配置可用，高级配置可选"，既可以让开发者快速开始项目开发而无需复杂的配置，又为需要特殊定制的场景提供了灵活的扩展能力。

项目结构

common-conf插件采用模块化的设计架构，主要包含以下核心模块：

核心组件

CommonConfPlugin - 主要插件类

CommonConfPlugin是插件的核心实现类，负责应用所有标准化配置。插件通过Gradle的Plugin接口实现，提供自动化的配置设置功能。

CommonConfExtension - 配置扩展点

CommonConfExtension提供了两个关键的配置选项：withSourcesJar控制是否生成源码JAR包，jdkVersion指定JVM版本，为用户提供灵活的定制能力。

plugin-common - 基础支撑模块

plugin-common模块提供了插件开发的基础设施，包括模板同步机制、项目属性管理和通用工具函数，确保插件的稳定性和可维护性。

架构概览

common-conf插件采用了分层架构设计，通过Gradle插件机制实现配置的自动化应用：

详细组件分析

插件核心实现

CommonConfPlugin通过afterEvaluate回调确保在项目评估完成后应用配置，这种设计保证了所有任务都已注册，可以正确地对它们进行配置。

配置应用机制

插件通过类型安全的任务过滤器对不同类型的编译任务应用相应的配置：

  • JavaCompile任务：设置UTF-8编码，确保跨平台兼容性
  • Javadoc任务：同样设置UTF-8编码，保证文档生成质量
  • Test任务：默认启用JUnit Platform，支持现代测试框架

配置选项详解

withSourcesJar选项

withSourcesJar是一个布尔型配置选项，控制是否自动生成源码JAR包。默认值为true，这意味着插件会自动为项目创建包含源代码的JAR文件，便于其他开发者或工具使用源码进行调试或分析。

jdkVersion选项

jdkVersion指定项目使用的JVM版本，默认值为"21"。插件通过Kotlin DSL的工具链配置机制，自动设置Java语言版本，确保编译输出与目标JVM兼容。

配置优先级

插件支持通过gradle.properties文件全局配置JDK版本，同时允许在单个项目中覆盖默认值，实现了灵活的配置管理策略。

使用示例

基础使用

最简单的使用方式是在build.gradle.kts中添加插件声明：

plugins {
    id("team.aikero.gradle.plugin.common-conf") version "3.0.2"
}

应用插件后，项目会自动获得以下配置：

  • 所有编译任务使用UTF-8编码
  • JVM工具链设置为指定版本
  • JUnit 5测试框架自动配置
  • 默认生成源码JAR包

高级配置示例

对于需要特殊配置的项目，可以通过DSL块进行定制：

commonConf {
    withSourcesJar = true      // 控制是否生成源码JAR
    jdkVersion = "21"          // 指定JVM版本
}

不同模块的配置差异

不同的子模块可能需要不同的配置策略：

  • api-version-generator：专注于版本信息生成，配置较为简单
  • publish-conf：侧重发布配置，集成Maven发布流程
  • plugin-common：作为基础模块，提供模板同步功能

验证配置

构建命令验证

验证common-conf插件配置是否生效的推荐命令：

./gradlew build

构建完成后，可以通过以下方式验证配置效果：

  • 检查build/libs/目录下是否存在*-sources.jar文件
  • 查看编译输出是否使用UTF-8编码
  • 验证测试任务是否正确使用JUnit 5

配置确认检查表

故障排除指南

常见问题及解决方案

编码问题

如果遇到字符编码相关的编译错误，确保插件正确设置了UTF-8编码。可以通过检查编译任务的options.encoding属性来验证。

JVM版本不匹配

当出现JVM版本不兼容的错误时，检查jdkVersion配置是否与实际环境匹配。可以通过java --version命令确认系统JDK版本。

测试框架问题

如果测试任务失败，确认JUnit 5框架已正确启用。插件默认配置useJUnitPlatform()，但可能需要额外的依赖。

调试技巧

  1. 启用详细日志：使用--info或--debug参数运行Gradle命令
  2. 检查任务配置：使用./gradlew tasks --all查看所有任务及其配置
  3. 验证扩展属性：通过./gradlew properties检查commonConf扩展的属性值
Copyright © 2025 aikero