本文介绍如何在 Gradle 构建的 Java 项目中，通过下载依赖的源码包并正确配置 jdb 调试器，实现对第三方依赖（如 OkHttp）源码的单步调试和 list 命令查看。
本文介绍如何在 gradle 构建的 java 项目中，通过下载依赖的源码包并正确配置 `jdb` 调试器，实现对第三方依赖（如 okhttp）源码的单步调试和 `list` 命令查看。
Gradle 默认仅下载依赖的二进制 JAR（*.jar），不包含源码（*-sources.jar）。而 jdb 要支持 step 进入依赖方法或用 list 显示其源码，必须显式提供对应源码路径。Spring 的 io.spring.dependency-management 插件不负责下载源码——它仅用于统一管理依赖版本（类似 BOM），与源码获取无关。因此需额外配置源码下载逻辑。
✅ 正确下载依赖源码
在 build.gradle 中添加以下任务，显式下载所有 implementation 依赖的源码：
// 下载所有 runtime 依赖的 sources JAR
task downloadSources(type: Copy) {
from configurations.runtimeClasspath.resolve()
.collect { it.name.replace('.jar', '-sources.jar') }
.collect { zipTree(configurations.compileClasspath.files.find { it.name == it } ?: fileTree(dir: 'dummy')) }
.flatten()
.findAll { it.name.endsWith('-sources.jar') }
.collect { zipTree(it) }
into "$buildDir/sources"
// 更健壮的方式：使用 resolutionStrategy + dependencies task（推荐）
}
// ✅ 推荐方式：使用内置的 dependencySources 任务（Gradle 6.0+）
tasks.register("downloadDependenciesSources", Download) {
description = "Download all dependency sources"
group = "build"
src = configurations.runtimeClasspath.incoming.artifactView {
viewConfiguration {
attributes {
attribute(Usage.USAGE_ATTRIBUTE, objects.named(Usage, Usage.JAVA_RUNTIME))
attribute(LibraryElements.LIBRARY_ELEMENTS_ATTRIBUTE, objects.named(LibraryElements, LibraryElements.SOURCES))
}
}
}.files
dest = file("$buildDir/dependency-sources")
rename { it.replace('-sources.jar', '.jar') } // 可选：解压后扁平化命名
}
更简洁且兼容性更好的做法是直接运行 Gradle 内置任务（无需修改脚本）：
./gradlew downloadDependencySources --include-build # 或（旧版 Gradle）： ./gradlew dependencies --configuration runtimeClasspath
但最通用可靠的方式是执行：
./gradlew build -Porg.gradle.downloadSources=true
⚠️ 注意：Gradle 并无原生 downloadSources 任务，需手动定义或借助插件。实际推荐使用 gradle-download-task 插件，或直接调用 IDE（如 IntelliJ）的 “Download Sources” 功能（右键依赖 → “Download Sources”）——该操作会自动将源码 JAR 关联至对应依赖。
✅ 配置 jdb 加载源码路径
假设你已将源码解压到 build/dependency-sources/ 目录（或保留为 JAR），启动 jdb 时需通过 -sourcepath 指定源码位置：
# 方式1：指定解压后的源码目录（推荐，便于 list 查看） jdb -sourcepath "src/main/java:build/dependency-sources" -classpath build/classes/java/main:build/libs/*.jar App # 方式2：直接指向 sources JAR 文件（jdb 支持 JAR 中的源码） jdb -sourcepath "src/main/java:build/libs/okhttp-4.9.0-sources.jar" -classpath build/classes/java/main:build/libs/okhttp-4.9.0.jar App
✅ 成功标志：
- 在 jdb 中执行 run 后，遇到 OkHttpClient.newCall(...) 等调用时，输入 step 可进入 OkHttp 源码；
- 输入 list 即可显示当前类的源码行（前提是类已被加载且源码路径匹配）。
? 验证源码是否可用
可在调试前快速验证：
- 检查 ~/.gradle/caches/modules-2/files-2.1/com.squareup.okhttp3/okhttp/4.9.0/ 目录下是否存在 xxx-sources.jar；
- 若不存在，手动执行 ./gradlew --refresh-dependencies 并确保仓库支持源码发布（Maven Central 通常提供）；
- 使用 jar -tf okhttp-4.9.0-sources.jar | head -n 5 确认 JAR 内含 .java 文件。
? 最佳实践建议
- 优先使用 IDE 调试：IntelliJ IDEA / Eclipse 可自动关联源码、设置断点、可视化调试，比命令行 jdb 更高效；
- 避免硬编码路径：在 build.gradle 中定义 sourceSets.main.java.srcDirs += file("$buildDir/dependency-sources")，使 Gradle 编译期也识别源码（非必需，但利于一致性）；
- 注意 JDK 版本兼容性：jdb 对 Java 17+ 的模块化支持有限，建议搭配 jshell 或 jdb --version 确认兼容性。
通过以上步骤，你即可完整打通从源码下载、路径配置到 jdb 实时调试的全链路，真正实现“所见即所调”。
