docs: 新增Gradle构建工具入门指南

4 months ago · dec620ccf3
parent 5f69857de5
commit dec620ccf3
1 changed files with 431 additions and 0 deletions
--- a/docs/00-Gradle构建工具入门指南.md
+++ b/docs/00-Gradle构建工具入门指南.md
@ -0,0 +1,431 @@
+# Gradle 构建工具入门指南
+
+本文档帮助初学者快速掌握 Gradle，涵盖本项目中使用的所有语法和命令。
+
+---
+
+## 1. Gradle 是什么？
+
+Gradle 是 Java 项目的自动化构建工具，类似于 Maven，但更灵活。它能帮你：
+- 编译代码
+- 运行测试
+- 打包 JAR/WAR
+- 管理依赖
+
+---
+
+## 2. 快速开始
+
+### 2.1 使用项目自带的 Gradle（推荐）
+
+项目根目录有 `gradlew.bat`（Windows）和 `gradlew`（Linux/Mac），无需安装 Gradle：
+
+```bash
+# Windows
+gradlew.bat build
+
+# Linux/Mac
+./gradlew build
+```
+
+### 2.2 常用命令速查
+
+| 命令 | 作用 |
+|------|------|
+| `gradlew build` | 编译并打包所有模块 |
+| `gradlew clean` | 清理构建产物 |
+| `gradlew test` | 运行所有测试 |
+| `gradlew :core:build` | 只构建 core 模块 |
+| `gradlew :cli:run` | 运行 CLI 应用 |
+| `gradlew :gui:run` | 运行 GUI 应用 |
+| `gradlew :backend:bootRun` | 运行 Web 应用 |
+| `gradlew tasks` | 查看所有可用任务 |
+
+---
+
+## 3. build.gradle 文件详解
+
+每个模块都有一个 `build.gradle` 文件，定义如何构建该模块。
+
+### 3.1 插件（plugins）
+
+插件为 Gradle 添加功能：
+
+```groovy
+plugins {
+    id 'java'                    // Java 编译支持
+    id 'application'             // 可运行应用支持
+    id 'war'                     // WAR 打包支持
+    id 'jacoco'                  // 代码覆盖率
+    id 'org.springframework.boot' version '3.2.0'  // Spring Boot
+    id 'org.openjfx.javafxplugin' version '0.0.14' // JavaFX
+}
+```
+
+### 3.2 项目信息
+
+```groovy
+group = 'com.smartlibrary'  // 组织名
+version = '1.0.0'           // 版本号
+```
+
+### 3.3 Java 版本
+
+```groovy
+java {
+    sourceCompatibility = JavaVersion.VERSION_21  // 源码版本
+    targetCompatibility = JavaVersion.VERSION_21  // 编译目标版本
+}
+```
+
+### 3.4 仓库（repositories）
+
+告诉 Gradle 从哪里下载依赖：
+
+```groovy
+repositories {
+    mavenCentral()  // Maven 中央仓库（最常用）
+}
+```
+
+### 3.5 依赖（dependencies）
+
+声明项目需要的库：
+
+```groovy
+dependencies {
+    // 编译和运行时都需要
+    implementation 'com.google.code.gson:gson:2.11.0'
+    
+    // 依赖本项目的其他模块
+    implementation project(':core')
+    
+    // 只在测试时需要
+    testImplementation 'org.junit.jupiter:junit-jupiter:5.10.1'
+    
+    // 传递给依赖此模块的其他模块
+    api 'com.google.zxing:core:3.5.2'
+}
+```
+
+**依赖格式**: `'组织:名称:版本'`
+
+---
+
+## 4. 多模块项目
+
+本项目是多模块结构：
+
+```
+mcslms/
+├── build.gradle          # 根项目配置
+├── settings.gradle       # 模块声明
+├── core/build.gradle     # 核心模块
+├── cli/build.gradle      # CLI 模块
+├── gui/build.gradle      # GUI 模块
+├── backend/build.gradle  # Web 模块
+└── android/build.gradle  # Android 模块
+```
+
+### 4.1 settings.gradle
+
+声明包含哪些子模块：
+
+```groovy
+rootProject.name = 'mcslms'
+include 'core', 'cli', 'gui', 'backend', 'android', 'launcher'
+```
+
+### 4.2 模块间依赖
+
+在子模块中引用其他模块：
+
+```groovy
+dependencies {
+    implementation project(':core')  // 依赖 core 模块
+}
+```
+
+### 4.3 指定模块执行任务
+
+```bash
+# 格式: gradlew :模块名:任务名
+gradlew :core:build      # 构建 core
+gradlew :cli:run         # 运行 cli
+gradlew :backend:test    # 测试 backend
+```
+
+---
+
+## 5. 常用任务配置
+
+### 5.1 application 插件 - 运行应用
+
+```groovy
+plugins {
+    id 'application'
+}
+
+application {
+    mainClass = 'com.smartlibrary.cli.CLIApplication'
+}
+
+// 允许命令行输入
+run {
+    standardInput = System.in
+}
+```
+
+运行：`gradlew :cli:run`
+
+### 5.2 jar 任务 - 打包 JAR
+
+```groovy
+jar {
+    archiveBaseName = 'mcslms-cli'
+    archiveVersion = 'v1.0.0'
+    manifest {
+        attributes(
+            'Main-Class': 'com.smartlibrary.cli.CLIApplication',
+            'Implementation-Title': 'Smart Library CLI'
+        )
+    }
+}
+```
+
+### 5.3 fatJar 任务 - 打包可执行 JAR（含所有依赖）
+
+```groovy
+tasks.register('fatJar', Jar) {
+    archiveClassifier = 'all'
+    duplicatesStrategy = DuplicatesStrategy.EXCLUDE
+    manifest {
+        attributes 'Main-Class': 'com.smartlibrary.cli.CLIApplication'
+    }
+    from {
+        configurations.runtimeClasspath.collect { 
+            it.isDirectory() ? it : zipTree(it) 
+        }
+    }
+    with jar
+    // 排除签名文件
+    exclude 'META-INF/*.SF', 'META-INF/*.DSA', 'META-INF/*.RSA'
+}
+```
+
+运行：`gradlew :cli:fatJar`
+
+### 5.4 test 任务 - 运行测试
+
+```groovy
+tasks.named('test') {
+    useJUnitPlatform()  // 使用 JUnit 5
+    testLogging {
+        events "passed", "skipped", "failed"
+    }
+}
+```
+
+运行：`gradlew test`
+
+### 5.5 jacoco 插件 - 代码覆盖率
+
+```groovy
+plugins {
+    id 'jacoco'
+}
+
+tasks.named('test') {
+    finalizedBy jacocoTestReport  // 测试后自动生成报告
+}
+
+jacocoTestReport {
+    dependsOn test
+    reports {
+        xml.required = true   // SonarQube 需要
+        html.required = true  // 本地查看
+    }
+}
+```
+
+运行：`gradlew test jacocoTestReport`
+
+---
+
+## 6. Spring Boot 配置
+
+### 6.1 基本配置
+
+```groovy
+plugins {
+    id 'org.springframework.boot' version '3.2.0'
+    id 'io.spring.dependency-management' version '1.1.4'
+}
+
+springBoot {
+    mainClass = 'com.smartlibrary.web.WebApplication'
+}
+```
+
+### 6.2 常用任务
+
+```bash
+gradlew :backend:bootRun   # 运行 Spring Boot 应用
+gradlew :backend:bootJar   # 打包可执行 JAR
+gradlew :backend:bootWar   # 打包 WAR（部署到 Tomcat）
+```
+
+---
+
+## 7. JavaFX 配置
+
+```groovy
+plugins {
+    id 'org.openjfx.javafxplugin' version '0.0.14'
+}
+
+javafx {
+    version = "21"
+    modules = ['javafx.controls', 'javafx.fxml']
+}
+```
+
+---
+
+## 8. 排除依赖冲突
+
+```groovy
+configurations {
+    all {
+        exclude group: 'org.slf4j', module: 'slf4j-simple'
+    }
+}
+```
+
+---
+
+## 9. 动态版本号
+
+从命令行传入构建号：
+
+```groovy
+def buildNumber = project.findProperty('buildNumber') ?: '0'
+def fullVersion = "v${version}.${buildNumber}"
+```
+
+使用：
+```bash
+gradlew :cli:fatJar -PbuildNumber=123
+# 生成: mcslms-cli-v1.11.0.123-all.jar
+```
+
+---
+
+## 10. SonarQube 配置
+
+根项目 `build.gradle`：
+
+```groovy
+plugins {
+    id 'org.sonarqube' version '4.4.1.3373'
+}
+
+sonar {
+    properties {
+        property 'sonar.projectKey', 'mcslms'
+        property 'sonar.projectName', 'MCSLMS'
+        property 'sonar.sourceEncoding', 'UTF-8'
+        property 'sonar.java.source', '21'
+        property 'sonar.coverage.jacoco.xmlReportPaths', 
+            'core/build/reports/jacoco/test/jacocoTestReport.xml'
+    }
+}
+```
+
+运行：
+```bash
+gradlew sonar -Dsonar.host.url=http://localhost:9000
+```
+
+---
+
+## 11. 实用技巧
+
+### 11.1 跳过测试
+
+```bash
+gradlew build -x test
+```
+
+### 11.2 强制刷新依赖
+
+```bash
+gradlew build --refresh-dependencies
+```
+
+### 11.3 查看依赖树
+
+```bash
+gradlew :core:dependencies
+```
+
+### 11.4 并行构建
+
+```bash
+gradlew build --parallel
+```
+
+### 11.5 禁用 Daemon（CI 环境）
+
+```bash
+gradlew build --no-daemon
+```
+
+---
+
+## 12. 本项目完整构建流程
+
+```bash
+# 1. 清理旧构建
+gradlew clean
+
+# 2. 编译所有模块
+gradlew build -x test
+
+# 3. 运行测试
+gradlew test
+
+# 4. 生成覆盖率报告
+gradlew jacocoTestReport
+
+# 5. 打包各端
+gradlew :cli:fatJar :gui:fatJar :backend:bootJar :backend:bootWar
+
+# 6. 运行 SonarQube 扫描
+gradlew sonar -Dsonar.host.url=http://localhost:9000
+
+# 7. 构建 Android
+gradlew :android:assembleDebug
+```
+
+---
+
+## 13. 常见问题
+
+| 问题 | 解决方案 |
+|------|---------|
+| `Could not find method` | 检查 Gradle 版本，本项目需要 8.5+ |
+| `Unsupported class file version` | 确保 JDK 21 |
+| 依赖下载慢 | 配置国内镜像或使用代理 |
+| `Task not found` | 检查模块名是否正确 |
+
+---
+
+## 总结
+
+掌握这些内容，你就能：
+- 理解项目的 `build.gradle` 配置
+- 使用命令行构建、测试、打包
+- 解决常见的构建问题
+
+更多详情参考 [Gradle 官方文档](https://docs.gradle.org/)