项目结构

标准 Java 项目结构

Gradle 遵循 Maven 约定的目录布局，这让熟悉 Maven 的开发者可以快速上手。

project-root/
├── build.gradle.kts              ← 根项目构建脚本
├── settings.gradle.kts           ← 项目设置（必须）
├── gradle.properties             ← 配置属性（可选）
├── gradlew                       ← Wrapper 脚本（Linux/macOS）
├── gradlew.bat                   ← Wrapper 脚本（Windows）
├── gradle/
│   └── wrapper/
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
└── src/
    ├── main/
    │   ├── java/                 ← Java 源码
    │   │   └── com/example/
    │   │       └── App.java
    │   ├── kotlin/               ← Kotlin 源码（如使用 Kotlin）
    │   └── resources/            ← 资源文件（配置、模板等）
    │       ├── application.yml
    │       └── logback.xml
    └── test/
        ├── java/                 ← 测试源码
        │   └── com/example/
        │       └── AppTest.java
        └── resources/            ← 测试资源

多项目结构

company-app/
├── settings.gradle.kts           ← 声明所有子项目
├── build.gradle.kts              ← 根项目（共享配置）
├── gradle.properties
├── gradlew / gradlew.bat
├── gradle/wrapper/...
│
├── core/                         ← 核心库模块
│   ├── build.gradle.kts
│   └── src/main/java/...
│
├── service/
│   ├── auth/                     ← 认证服务模块
│   │   ├── build.gradle.kts
│   │   └── src/...
│   └── order/                    ← 订单服务模块
│       ├── build.gradle.kts
│       └── src/...
│
└── web/                          ← Web 应用模块
    ├── build.gradle.kts
    └── src/...

settings.gradle.kts（多项目）：

rootProject.name = "company-app"

include(
    "core",
    "service:auth",
    "service:order",
    "web"
)

构建输出目录

所有构建产物默认输出到 build/ 目录：

build/
├── classes/
│   └── java/
│       ├── main/     ← 编译后的主源码 .class
│       └── test/     ← 编译后的测试 .class
├── generated-sources/    ← 自动生成的源码（注解处理器）
├── libs/
│   └── my-app-1.0.0.jar ← 打包产物
├── reports/
│   ├── tests/
│   │   └── test/
│   │       └── index.html  ← 测试报告
│   └── checkstyle/
│       └── main.html       ← 代码检查报告
├── resources/
│   └── main/              ← 处理后的资源文件
├── test-results/
│   └── test/
│       └── *.xml          ← JUnit XML 格式测试结果
└── tmp/                   ← 临时文件

关键配置文件说明

settings.gradle.kts

// 插件管理（可选）
pluginManagement {
    repositories {
        gradlePluginPortal()
        mavenCentral()
    }
}

// 依赖解析管理（可选）
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        mavenCentral()
    }
}

// 根项目名称
rootProject.name = "my-app"

// 子项目（多项目时）
include("core", "web")

build.gradle.kts

// 插件声明
plugins {
    java
    id("org.springframework.boot") version "3.2.0"
}

// 项目信息
group = "com.example"
version = "1.0.0"

// 仓库
repositories {
    mavenCentral()
}

// 依赖
dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")
    testImplementation("org.springframework.boot:spring-boot-starter-test")
}

// 任务配置
tasks.withType<Test> {
    useJUnitPlatform()
}

gradle.properties

# JVM 启动参数（增加内存、启用守护进程等）
org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8

# 启用并行构建
org.gradle.parallel=true

# 启用构建缓存
org.gradle.caching=true

# 启用配置缓存（Gradle 8+）
org.gradle.configuration-cache=true

# 项目自定义属性
app.version=1.0.0
db.url=jdbc:mysql://localhost:3306/mydb

版本目录文件（推荐）

Gradle 7.4+ 支持在 gradle/libs.versions.toml 中统一声明依赖版本：

gradle/
└── libs.versions.toml    ← 版本目录

[versions]
spring-boot = "3.2.0"
junit = "5.10.1"

[libraries]
spring-boot-web = { module = "org.springframework.boot:spring-boot-starter-web", version.ref = "spring-boot" }
spring-boot-test = { module = "org.springframework.boot:spring-boot-starter-test", version.ref = "spring-boot" }
junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit" }

[plugins]
spring-boot = { id = "org.springframework.boot", version.ref = "spring-boot" }

使用方式：

// build.gradle.kts
dependencies {
    implementation(libs.spring.boot.web)
    testImplementation(libs.spring.boot.test)
}

.gitignore 配置

推荐的 .gitignore：

# Gradle 构建输出
build/
.gradle/

# IDEA
.idea/
*.iml
*.ipr
*.iws

# Eclipse
.project
.classpath
.settings/

# Gradle Wrapper（保留 jar，忽略缓存）
!gradle/wrapper/gradle-wrapper.jar
!gradlew
!gradlew.bat

下一步

• 常用命令 - 日常开发必备的 Gradle 命令
• 构建生命周期 - 理解构建的三个阶段