3. AudioRecord工程化采集

3.1 核心原理：依赖声明的三层结构

单模块 Gradle 项目的依赖管理围绕三个层次展开：坐标定位、作用域限定、版本控制。坐标定位（group:name:version）唯一确定一个制品；作用域限定通过依赖分组（configuration）控制依赖在编译、运行时、测试等阶段的可见性；版本控制则管理依赖的精确版本或版本范围，防止冲突与意外升级。

三者共同构成一条完整的依赖声明链：

• 坐标（group:name:version） — 声明“依赖谁”
• 分组（configuration） — 声明“在哪个阶段使用”
• 版本管理方式 — 声明“版本如何确定与锁定”

3.2 完整单模块 build.gradle 写法

以下是一个生产级单模块项目的完整 build.gradle，覆盖了核心依赖声明、版本管理、仓库配置与常用插件：

plugins {
    id 'java-library'          // 提供 api / implementation 分组
    id 'maven-publish'         // 发布制品
}

group = 'com.example'
version = '2.1.0'

repositories {
    mavenCentral()
    // 内部仓库（可选）
    // maven { url 'https://repo.example.com/releases' }
}

// ──────────────────────────────────
// 统一版本号管理（ext 方式）
// ──────────────────────────────────
ext {
    versions = [
        junit    : '5.10.2',
        jackson  : '2.16.1',
        lombok   : '1.18.30',
        slf4j    : '2.0.12'
    ]
}

dependencies {
    // ——— 编译期必须的生产依赖 ———
    implementation "com.fasterxml.jackson.core:jackson-databind:${versions.jackson}"
    implementation "org.slf4j:slf4j-api:${versions.slf4j}"

    // ——— 对外暴露 API 的依赖 ———
    api "com.fasterxml.jackson.core:jackson-annotations:${versions.jackson}"

    // ——— 编译期仅声明，运行时由容器提供 ———
    compileOnly "org.projectlombok:lombok:${versions.lombok}"
    annotationProcessor "org.projectlombok:lombok:${versions.lombok}"

    // ——— 测试专用 ———
    testImplementation "org.junit.jupiter:junit-jupiter:${versions.junit}"
    testRuntimeOnly "org.junit.platform:junit-platform-launcher"

    // ——— 运行时才需要，编译期不需要 ———
    runtimeOnly "ch.qos.logback:logback-classic:1.5.3"
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

tasks.named('test') {
    useJUnitPlatform()
}

3.3 依赖分组（Configuration）分类详解

Gradle 为 Java 生态提供了 7 种核心依赖分组，按用途划分为三大类：

3.4 依赖版本号管理策略

版本管理有三种主流实现方式，各有适用场景：

1. ext 映射（本示例使用） — 适合单模块项目，所有版本集中在 ext.versions 中，直观且无需额外插件。
2. gradle.properties 集中声明 — 键值对写在 gradle.properties 文件中，适合多模块共享版本。
3. version catalog（libs.versions.toml） — Gradle 7.0+ 官方推荐，支持类型安全与 IDE 补全，适合大型项目。

// 方式一：ext 映射
ext.versions = [ guava: '32.1.3-jre' ]
implementation "com.google.guava:guava:${versions.guava}"

// 方式二：gradle.properties
// 文件内容：guavaVersion=32.1.3-jre
implementation "com.google.guava:guava:${guavaVersion}"

// 方式三：version catalog（libs.versions.toml）
// [versions] guava = "32.1.3-jre"
// [libraries] guava = { module = "com.google.guava:guava", version.ref = "guava" }
implementation libs.guava

3.5 依赖调试：诊断 classpath 冲突与缺失

当依赖出现冲突或类找不到时，使用以下命令快速定位：

# 查看完整依赖树（按分组着色）
gradle dependencies --configuration compileClasspath

# 查看某特定依赖的解析路径
gradle dependencyInsight --dependency jackson-databind --configuration runtimeClasspath

# 输出为 HTML 报告，便于在浏览器中交互分析
gradle build --scan

典型输出示例（依赖树片段）：

compileClasspath
+--- com.fasterxml.jackson.core:jackson-databind:2.16.1
|    +--- com.fasterxml.jackson.core:jackson-annotations:2.16.1 -> 2.16.1
|    \--- com.fasterxml.jackson.core:jackson-core:2.16.1
\--- org.slf4j:slf4j-api:2.0.12

箭头 -> 表示版本冲突时 Gradle 选择的最终版本。若发现错误版本，可使用 force 或 strictly 约束：

implementation("com.fasterxml.jackson.core:jackson-databind:2.16.1") {
    version {
        strictly '2.16.1'
        prefer '2.16.1'
    }
}

3.6 常见错误与解决方案

3.7 依赖分组与版本管理架构图

下图以单模块项目为核心，展示了依赖分组的作用域、版本管理入口与 classpath 的流向关系：

3.8 稳定性与优化建议

• 锁定版本避免浮标： 所有依赖使用固定版本号，禁用 + 和 latest.release。需要批量升级时，使用 gradle refreshVersions 插件或 renovate 自动化工具。
• 最小化传递依赖： 对已知不必要的传递依赖使用 exclude 排除，减少 classpath 膨胀。
• 分组选择遵循最小特权原则： 能不暴露就不使用 api，能用 compileOnly 就不使用 implementation，减少消费者侧的冲突风险。
• 构建缓存友好： 保持依赖声明幂等，避免在 dependencies 块中执行动态计算或 IO 操作。
• 定期清理未使用的依赖： 使用 gradle buildHealth 或 com.autonomousapps.dependency-analysis 插件检测死依赖。