ECC Java 构建错误解析 Agent 实战指南面向 Spring Boot 与 Quarkus 的最小化修复方法论【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC在 ECCEverything Claude Code中java-build-resolver是专为 Java/Maven/Gradle 项目设计的构建错误解析子代理Sub-agent。当 Java 构建失败时它负责自动识别 Spring Boot 或 Quarkus 框架、定位编译错误、Maven/Gradle 配置问题与依赖解析失败并以「最小外科手术式改动」修复问题——不做重构、不改签名、只解决构建本身。读完本文你将掌握一套可复用的框架识别 → 诊断 → 精准修复 → 回归验证的完整工作流以及面向 Spring Boot[SPRING]与 Quarkus[QUARKUS]两套框架的差异化错误对照表与排障命令集。一、Agent 定位修构建错误而非重构代码该 Agent 的角色定义明确写在其 Frontmatter 描述中Java/Maven/Gradle build, compilation, and dependency error resolution specialist。在 ECC 的全局编排体系见 AGENTS.md中java-build-resolver与java-reviewer负责代码评审分工互补前者对应Java build failures聚焦构建、编译与依赖错误。它在 README.md 中被归入 67 个专用子代理之一并与其他语言解析器cpp-build-resolver、go-build-resolver、kotlin-build-resolver、pytorch-build-resolver等共同构成覆盖多语言的构建救援矩阵。其核心行为约束是三条铁律只修复构建错误fix the build error only明确声明You DO NOT refactor or rewrite code所有改动必须minimal、surgical绝不扩大变更范围每次修复后必须重新运行构建验证修复 root cause 而不是压制症状。二、框架检测先行SPRING / QUARKUS / BOTH / UNKNOWN在实际动手前Agent 首先通过构建文件嗅探技术栈cat pom.xml 2/dev/null || cat build.gradle 2/dev/null || cat build.gradle.kts 2/dev/null判定规则如下检测结果处理策略构建文件包含quarkus应用[QUARKUS]规则集构建文件包含spring-boot应用[SPRING]规则集两者同时出现少见标记为 finding同时应用两套规则两者都未检测到仅使用通用 Java 规则并记录技术栈模糊这一事实这一步决定了后续所有修复动作的语义例如No qualifying bean of type X在 Spring 中指向Component/组件扫描而在 Quarkus 中对应UnsatisfiedResolutionException的 CDI 注入问题——两者生态语义完全不同。从仓库结构看这种按技术栈分流到专用模式库的设计在 ECC 中是一贯模式Java 侧同时维护了 springboot-patterns、quarkus-patterns 等模式技能文档末尾即建议在[SPRING]场景下查阅skill: springboot-patterns、在[QUARKUS]场景下查阅skill: quarkus-patterns。与此同时rules/java 目录下的coding-style.md、testing.md、security.md等提供 Java 通用规则底座供 Agent 在遵循项目规则时回查。三、核心职责与诊断命令序列3.1 五大核心职责诊断 Java 编译错误compilation errors修复 Maven 与 Gradle 构建配置问题解决依赖冲突与版本不匹配处理注解处理器错误Lombok、MapStruct、Spring、Quarkus修复 Checkstyle 与 SpotBugs 违规。3.2 诊断命令按序执行./mvnw compile -q 21 || mvn compile -q 21 ./mvnw test -q 21 || mvn test -q 21 ./gradlew build 21 ./mvnw dependency:tree 21 | head -100 ./gradlew dependencies --configuration runtimeClasspath 21 | head -100 ./mvnw checkstyle:check 21 || echo checkstyle not configured ./mvnw spotbugs:check 21 || echo spotbugs not configured设计要点解读./mvnw ... || mvn ...的写法同时兼容 Maven Wrapper 与系统 Maven-qquiet只输出错误避免诊断信息被日志淹没先 compile/test 再 dependency:tree先暴露编译错误再暴露依赖图遵循由表及里的排查顺序checkstyle/spotbugs命令末尾追加|| echo not configured避免因未配置插件而中断整个诊断流程——这种软失败处理很符合 Agent 自主排障场景。四、标准解析工作流文档给出了一条六步闭环流程是 Agent 修复动作的主干1. Detect framework (Spring Boot / Quarkus) 2. ./mvnw compile OR ./gradlew build - Parse error message 3. Read affected file - Understand context 4. Apply minimal fix - Only whats needed 5. ./mvnw compile OR ./gradlew build - Verify fix 6. ./mvnw test OR ./gradlew test - Ensure nothing broke可见该流程把「读受影响源码理解上下文」放在修复之前——避免盲改把「重新 compile」与「跑 test」分开验证——先证明编译通过再证明没有破坏既有行为。这与文档末尾 Key Principles 中Always run the build after each fix to verify互为呼应。五、常见错误速查表可直接复制使用5.1 通用 Java 错误错误原因修复cannot find symbol缺少 import、拼写错误、缺少依赖添加 import 或依赖incompatible types: X cannot be converted to Y类型错误、缺少强转添加显式强转或修正类型method X in class Y cannot be applied to given types实参类型或个数错误修正实参或检查重载variable X might not have been initialized局部变量未初始化使用前先初始化non-static method X cannot be referenced from a static context以静态方式调用实例方法创建实例或改为静态方法reached end of file while parsing缺少右花括号补上缺失的}package X does not exist缺少依赖或 import 路径错误在pom.xml/build.gradle添加依赖error: cannot access X, class file not found缺少传递依赖添加显式依赖Annotation processor threw uncaught exceptionLombok/MapStruct 配置错误检查注解处理器配置Could not resolve: group:artifact:version缺少仓库或版本错误添加仓库或在 POM 中修正版本The following artifacts could not be resolved私有仓库或网络问题检查仓库凭证或settings.xmlCOMPILATION ERROR: Source option X is no longer supportedJava 版本不匹配更新maven.compiler.source/targetCompatibility5.2 [SPRING] Spring Boot 专属错误错误原因修复No qualifying bean of type X缺少Component/Service或组件扫描范围不对添加注解或修正扫描包路径Circular dependency involving X构造器注入成环重构打破循环或在一侧使用LazyBeanCreationException: Error creating bean缺配置、属性错误或依赖缺失检查application.yml、依赖树HttpMessageNotReadableExceptionJSON 格式错误或缺少 Jackson 依赖确认spring-boot-starter-web已包含 JacksonCould not autowire. No beans of type found缺少 Bean 或 Profile 不对检查Profile、ConditionalOn*、组件扫描Failed to configure a DataSource缺少数据库驱动或数据源属性添加驱动依赖或spring.datasource.*配置spring-boot-starter-* not foundBOM 版本不匹配检查父 POM 中spring-boot-dependenciesBOM 版本5.3 [QUARKUS] Quarkus 专属错误错误原因修复UnsatisfiedResolutionException: no bean found缺少ApplicationScoped/Inject或扩展添加 CDI 注解或quarkus-*扩展AmbiguousResolutionException多个 Bean 匹配同一注入点添加Priority、Alternative或 qualifierBuild step X threw an exception: RuntimeException构建期增强augmentation失败读完整堆栈——多为缺扩展、配置错误或反射问题Error injecting X: its a non-proxyable bean typeSingleton与拦截器或final类冲突改用ApplicationScoped或去掉finalClassNotFoundException at native image build缺少RegisterForReflection或反射配置添加RegisterForReflection或reflect-config.json条目BlockingNotAllowedOnIOThread在 Vert.x 事件循环上执行阻塞调用为端点添加Blocking或改用响应式客户端ConfigurationException: SRCFG*缺少或格式错误的配置属性检查application.properties中必需的quarkus.*/mp.*键quarkus-extension-* not foundBOM 版本错误或扩展不在 BOM 中检查quarkus-bom版本使用quarkus ext add nameDEV mode hot reload failuredev 模式期间的不兼容变更用 clean 方式重启./mvnw clean quarkus:devPanache entity not enhanced构建期未检测到实体确保实体在被扫描的包内检查是否缺少quarkus-hibernate-orm-panache或quarkus-mongodb-panache扩展RESTEASY* deployment failureJAX-RS 路径重复或缺少 provider检查Path唯一性确认quarkus-resteasy-reactive与quarkus-resteasy未混用说明这三张表的共同工程哲学是——每条错误都同时给出原因判定与最小修复动作让 Agent 不必在错误信息与修复方案之间做二次推断直接按表格执行即可这正是外科手术式修复的落地载体。六、Maven 专项排障# 查看依赖树定位冲突 ./mvnw dependency:tree -Dverbose # 强制更新快照并重新下载 ./mvnw clean install -U # 分析依赖冲突 ./mvnw dependency:analyze # 查看有效 POM继承解析结果 ./mvnw help:effective-pom # 调试注解处理器 ./mvnw compile -X 21 | grep -i processor\|lombok\|mapstruct # 跳过测试以隔离编译错误 ./mvnw compile -DskipTests # 查看当前使用的 Java 版本 ./mvnw --version java -version几个命令在真实场景中的价值dependency:tree -Dverbose是版本仲裁dependency mediation问题的核心武器能直接显示每个依赖被哪个路径引入、以及冲突中被丢弃的版本-U强制刷新SNAPSHOT常用于本地缓存了过期快照导致改了代码不生效的诡异场景help:effective-pom能看到父子 POM 继承合并后的最终形态排查spring-boot-dependenciesBOM 或quarkus-bom是否真正生效compile -X输出调试级日志并过滤 processor 关键字是定位 Lombok/MapStruct 注解处理器崩溃的标准手段。七、Gradle 专项排障# 查看依赖树定位冲突 ./gradlew dependencies --configuration runtimeClasspath # 强制刷新依赖 ./gradlew build --refresh-dependencies # 清理 Gradle 构建缓存 ./gradlew clean rm -rf .gradle/build-cache/ # 带调试输出运行 ./gradlew build --debug 21 | tail -50 # 查看某个依赖的解析路径 ./gradlew dependencyInsight --dependency name --configuration runtimeClasspath # 查看 Java 工具链 ./gradlew -q javaToolchains对比 Maven 版可以发现两者一一对应dependencies之于dependency:tree、--refresh-dependencies之于-U、dependencyInsight之于-Dverbose下的定位能力。Gradle 侧额外值得注意javaToolchains——它直接呼应了 Java 8 之后多 JDK 并存时代最常见的本地能编、CI 报 Java 版本错误问题。文档开篇即强调在执行任何命令前先确认pom.xml/build.gradle/build.gradle.kts中的实际构建工具避免把 Gradle 命令错发给 Maven 项目。八、[SPRING] Spring Boot 专属验证命令# 验证应用上下文能加载用 test profile 启动 ./mvnw spring-boot:run -Dspring-boot.run.arguments--spring.profiles.activetest # 检查缺失 Bean 或循环依赖 ./mvnw test -Dtest*ContextLoads* -q # 验证 Lombok 被配置为注解处理器而非仅仅作为依赖 grep -A5 annotationProcessorPaths\|annotationProcessor pom.xml build.gradle # 检查 Spring Boot 版本对齐 ./mvnw dependency:tree | grep org.springframework.boot三条命令分别命中三类高发问题启动期上下文失败用*ContextLoads*测试类快速验证、注解处理器配置缺失Lombok 必须同时出现在annotationProcessorPaths/annotationProcessor配置中而不仅是 compile 依赖、依赖版本漂移通过dependency:tree过滤出所有org.springframework.boot版本判断是否被 BOM 拉齐。九、[QUARKUS] Quarkus 专属验证命令9.1 Maven 侧# 验证 Quarkus 构建期增强 ./mvnw quarkus:build -q # dev 模式运行以暴露运行时错误 ./mvnw quarkus:dev # 列出已安装扩展 ./mvnw quarkus:list-extensions -q 21 | grep ✓\|installed # 添加缺失扩展 ./mvnw quarkus:add-extension -Dextensionsextension-name # 检查 Quarkus BOM 版本对齐 ./mvnw dependency:tree | grep io.quarkus # 验证 native 构建前置条件GraalVM ./mvnw package -Pnative -DskipTests 21 | head -50 # 调试构建期增强失败 ./mvnw compile -X 21 | grep -i augment\|build step\|extension9.2 Gradle 侧# 验证 Quarkus 构建期增强 ./gradlew quarkusBuild # dev 模式运行 ./gradlew quarkusDev # 列出已安装扩展 ./gradlew listExtensions # 添加缺失扩展 ./gradlew addExtension --extensionsextension-name # 检查 Quarkus 依赖对齐 ./gradlew dependencies --configuration runtimeClasspath | grep io.quarkus # 验证 native 构建前置条件GraalVM ./gradlew build -Dquarkus.native.enabledtrue -x test 21 | head -509.3 通用两套构建工具共用# 检查反射注册native image 场景 grep -rn RegisterForReflection src/main/java --include*.java # 验证 CDI Bean 发现先跑 dev mode再看输出 # Maven: ./mvnw quarkus:dev | Gradle: ./gradlew quarkusDev # 然后 grep 日志关键字bean|unsatisfied|ambiguous与 Spring Boot 不同Quarkus 的最大特征是构建期增强build-time augmentation与 native 编译大量错误Panache 实体未增强、反射缺失、non-proxyable bean type只在构建期或原生镜像阶段才会暴露。因此 Quarkus 的验证命令大量围绕quarkus:build、native profile 与RegisterForReflection反射登记展开。文档特别强调添加扩展优先使用quarkus ext addMaven/addExtensionGradle而不是手工编辑pom.xml因为扩展的 BOM 版本对齐由工具自动完成能显著降低quarkus-extension-* not found类错误的概率。十、关键原则与停止条件10.1 修复纪律Key PrinciplesSurgical fixes only——不重构只修错误未经明确批准绝不使用SuppressWarnings压制警告除非必要绝不改方法签名每次修复后必须重新构建验证修复根因而非压制症状优先补 import 而非改逻辑[QUARKUS]扩展优先走quarkus ext add加反射配置前先确认是否需要RegisterForReflection动手前先核对pom.xml/build.gradle/build.gradle.kts确认构建工具再跑对应命令。10.2 停止并上报Stop Conditions以下情况 Agent 必须停下汇报而非继续盲目尝试同一错误在 3 次修复尝试后仍然存在修复引入的错误多于其解决的错误错误需要超出范围的架构级改动缺少需要用户决策的外部依赖私有仓库、许可证[QUARKUS]native 镜像构建因本机未安装 GraalVM 失败——直接上报前置条件缺失。这组停止条件本质上是防失控护栏它防止 Agent 在错误方向上深挖不止把需要人类判断的边界问题许可证、私有仓库、架构决策及时交还给用户。十一、结构化输出格式Agent 每次排障结束需按统一模板输出结果保证日志可解析、可追溯Framework: [SPRING|QUARKUS|BOTH|UNKNOWN] [FIXED] src/main/java/com/example/service/PaymentService.java:87 Error: cannot find symbol — symbol: class IdempotencyKey Fix: Added import com.example.domain.IdempotencyKey Remaining errors: 1最终一行给出总结态Framework: X | Build Status: SUCCESS/FAILED | Errors Fixed: N | Files Modified: list。该输出契约的价值在于每次修改都以文件:行号 原始错误 修复动作三元组落盘配合Framework与Remaining errors状态字段天然支持在 ECC 的 java-reviewer代码评审等下游流程中做二次复核或复盘。十二、与仓库生态的协同java-build-resolver并非孤立存在它在 ECC 中被设计为 Java 工作流的一环评审对偶java-reviewer 面向代码质量评审构建解析器面向构建失败二者在 AGENTS.md 的 Agent 编排表中互为补充见 AGENTS.md模式知识库深度修复需要框架范式时[SPRING] 场景查阅 skills/springboot-patterns/SKILL.md涵盖RestController分层、Spring Data JPA 仓库模式、事务服务层、校验与异常处理等[QUARKUS] 场景查阅 skills/quarkus-patterns/SKILL.md涵盖 Quarkus 3.x 的 CDI 服务层、Panache 数据访问、Camel 消息与 native 编译模式多语言家族仓库内还维护了面向 Java 的 rules/java/coding-style.md 编码风格、rules/java/patterns.md 模式等规则文件供 Agent 在遵循项目既有规则时引用多语言化该 Agent 定义随仓库多语言文档体系同步翻译例如 docs/zh-CN/agents/java-build-resolver.md、docs/ja-JP/agents/java-build-resolver.md 等便于不同语言环境团队采用同一套排障规范。结语把构建排障工程化综观全文档java-build-resolver提供的不是某个灵丹妙药而是一套可复制、可审计、有护栏的工程化排障流程框架先行判定 → 标准化诊断命令 → 错误-原因-修复对照表 → 最小改动修复 → 构建/测试双重验证 → 统一结构化输出。它对 Spring Boot 与 Quarkus 两套生态分别维护专属错误表和命令集对 Maven 与 Gradle 双工具链一视同仁并以3 次尝试上限等停止条件防止过度操作。这套方法论对任何 Java 团队的 CI 故障响应、AI 辅助排障乃至人工排障 SOP 设计都具有直接的参考价值——无论你的项目是传统 Spring Boot 单体、还是追求原生镜像的 Quarkus 云原生服务。【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ECC Java 构建错误解析 Agent 实战指南：面向 Spring Boot 与 Quarkus 的最小化修复方法论
ECC Java 构建错误解析 Agent 实战指南面向 Spring Boot 与 Quarkus 的最小化修复方法论【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC在 ECCEverything Claude Code中java-build-resolver是专为 Java/Maven/Gradle 项目设计的构建错误解析子代理Sub-agent。当 Java 构建失败时它负责自动识别 Spring Boot 或 Quarkus 框架、定位编译错误、Maven/Gradle 配置问题与依赖解析失败并以「最小外科手术式改动」修复问题——不做重构、不改签名、只解决构建本身。读完本文你将掌握一套可复用的框架识别 → 诊断 → 精准修复 → 回归验证的完整工作流以及面向 Spring Boot[SPRING]与 Quarkus[QUARKUS]两套框架的差异化错误对照表与排障命令集。一、Agent 定位修构建错误而非重构代码该 Agent 的角色定义明确写在其 Frontmatter 描述中Java/Maven/Gradle build, compilation, and dependency error resolution specialist。在 ECC 的全局编排体系见 AGENTS.md中java-build-resolver与java-reviewer负责代码评审分工互补前者对应Java build failures聚焦构建、编译与依赖错误。它在 README.md 中被归入 67 个专用子代理之一并与其他语言解析器cpp-build-resolver、go-build-resolver、kotlin-build-resolver、pytorch-build-resolver等共同构成覆盖多语言的构建救援矩阵。其核心行为约束是三条铁律只修复构建错误fix the build error only明确声明You DO NOT refactor or rewrite code所有改动必须minimal、surgical绝不扩大变更范围每次修复后必须重新运行构建验证修复 root cause 而不是压制症状。二、框架检测先行SPRING / QUARKUS / BOTH / UNKNOWN在实际动手前Agent 首先通过构建文件嗅探技术栈cat pom.xml 2/dev/null || cat build.gradle 2/dev/null || cat build.gradle.kts 2/dev/null判定规则如下检测结果处理策略构建文件包含quarkus应用[QUARKUS]规则集构建文件包含spring-boot应用[SPRING]规则集两者同时出现少见标记为 finding同时应用两套规则两者都未检测到仅使用通用 Java 规则并记录技术栈模糊这一事实这一步决定了后续所有修复动作的语义例如No qualifying bean of type X在 Spring 中指向Component/组件扫描而在 Quarkus 中对应UnsatisfiedResolutionException的 CDI 注入问题——两者生态语义完全不同。从仓库结构看这种按技术栈分流到专用模式库的设计在 ECC 中是一贯模式Java 侧同时维护了 springboot-patterns、quarkus-patterns 等模式技能文档末尾即建议在[SPRING]场景下查阅skill: springboot-patterns、在[QUARKUS]场景下查阅skill: quarkus-patterns。与此同时rules/java 目录下的coding-style.md、testing.md、security.md等提供 Java 通用规则底座供 Agent 在遵循项目规则时回查。三、核心职责与诊断命令序列3.1 五大核心职责诊断 Java 编译错误compilation errors修复 Maven 与 Gradle 构建配置问题解决依赖冲突与版本不匹配处理注解处理器错误Lombok、MapStruct、Spring、Quarkus修复 Checkstyle 与 SpotBugs 违规。3.2 诊断命令按序执行./mvnw compile -q 21 || mvn compile -q 21 ./mvnw test -q 21 || mvn test -q 21 ./gradlew build 21 ./mvnw dependency:tree 21 | head -100 ./gradlew dependencies --configuration runtimeClasspath 21 | head -100 ./mvnw checkstyle:check 21 || echo checkstyle not configured ./mvnw spotbugs:check 21 || echo spotbugs not configured设计要点解读./mvnw ... || mvn ...的写法同时兼容 Maven Wrapper 与系统 Maven-qquiet只输出错误避免诊断信息被日志淹没先 compile/test 再 dependency:tree先暴露编译错误再暴露依赖图遵循由表及里的排查顺序checkstyle/spotbugs命令末尾追加|| echo not configured避免因未配置插件而中断整个诊断流程——这种软失败处理很符合 Agent 自主排障场景。四、标准解析工作流文档给出了一条六步闭环流程是 Agent 修复动作的主干1. Detect framework (Spring Boot / Quarkus) 2. ./mvnw compile OR ./gradlew build - Parse error message 3. Read affected file - Understand context 4. Apply minimal fix - Only whats needed 5. ./mvnw compile OR ./gradlew build - Verify fix 6. ./mvnw test OR ./gradlew test - Ensure nothing broke可见该流程把「读受影响源码理解上下文」放在修复之前——避免盲改把「重新 compile」与「跑 test」分开验证——先证明编译通过再证明没有破坏既有行为。这与文档末尾 Key Principles 中Always run the build after each fix to verify互为呼应。五、常见错误速查表可直接复制使用5.1 通用 Java 错误错误原因修复cannot find symbol缺少 import、拼写错误、缺少依赖添加 import 或依赖incompatible types: X cannot be converted to Y类型错误、缺少强转添加显式强转或修正类型method X in class Y cannot be applied to given types实参类型或个数错误修正实参或检查重载variable X might not have been initialized局部变量未初始化使用前先初始化non-static method X cannot be referenced from a static context以静态方式调用实例方法创建实例或改为静态方法reached end of file while parsing缺少右花括号补上缺失的}package X does not exist缺少依赖或 import 路径错误在pom.xml/build.gradle添加依赖error: cannot access X, class file not found缺少传递依赖添加显式依赖Annotation processor threw uncaught exceptionLombok/MapStruct 配置错误检查注解处理器配置Could not resolve: group:artifact:version缺少仓库或版本错误添加仓库或在 POM 中修正版本The following artifacts could not be resolved私有仓库或网络问题检查仓库凭证或settings.xmlCOMPILATION ERROR: Source option X is no longer supportedJava 版本不匹配更新maven.compiler.source/targetCompatibility5.2 [SPRING] Spring Boot 专属错误错误原因修复No qualifying bean of type X缺少Component/Service或组件扫描范围不对添加注解或修正扫描包路径Circular dependency involving X构造器注入成环重构打破循环或在一侧使用LazyBeanCreationException: Error creating bean缺配置、属性错误或依赖缺失检查application.yml、依赖树HttpMessageNotReadableExceptionJSON 格式错误或缺少 Jackson 依赖确认spring-boot-starter-web已包含 JacksonCould not autowire. No beans of type found缺少 Bean 或 Profile 不对检查Profile、ConditionalOn*、组件扫描Failed to configure a DataSource缺少数据库驱动或数据源属性添加驱动依赖或spring.datasource.*配置spring-boot-starter-* not foundBOM 版本不匹配检查父 POM 中spring-boot-dependenciesBOM 版本5.3 [QUARKUS] Quarkus 专属错误错误原因修复UnsatisfiedResolutionException: no bean found缺少ApplicationScoped/Inject或扩展添加 CDI 注解或quarkus-*扩展AmbiguousResolutionException多个 Bean 匹配同一注入点添加Priority、Alternative或 qualifierBuild step X threw an exception: RuntimeException构建期增强augmentation失败读完整堆栈——多为缺扩展、配置错误或反射问题Error injecting X: its a non-proxyable bean typeSingleton与拦截器或final类冲突改用ApplicationScoped或去掉finalClassNotFoundException at native image build缺少RegisterForReflection或反射配置添加RegisterForReflection或reflect-config.json条目BlockingNotAllowedOnIOThread在 Vert.x 事件循环上执行阻塞调用为端点添加Blocking或改用响应式客户端ConfigurationException: SRCFG*缺少或格式错误的配置属性检查application.properties中必需的quarkus.*/mp.*键quarkus-extension-* not foundBOM 版本错误或扩展不在 BOM 中检查quarkus-bom版本使用quarkus ext add nameDEV mode hot reload failuredev 模式期间的不兼容变更用 clean 方式重启./mvnw clean quarkus:devPanache entity not enhanced构建期未检测到实体确保实体在被扫描的包内检查是否缺少quarkus-hibernate-orm-panache或quarkus-mongodb-panache扩展RESTEASY* deployment failureJAX-RS 路径重复或缺少 provider检查Path唯一性确认quarkus-resteasy-reactive与quarkus-resteasy未混用说明这三张表的共同工程哲学是——每条错误都同时给出原因判定与最小修复动作让 Agent 不必在错误信息与修复方案之间做二次推断直接按表格执行即可这正是外科手术式修复的落地载体。六、Maven 专项排障# 查看依赖树定位冲突 ./mvnw dependency:tree -Dverbose # 强制更新快照并重新下载 ./mvnw clean install -U # 分析依赖冲突 ./mvnw dependency:analyze # 查看有效 POM继承解析结果 ./mvnw help:effective-pom # 调试注解处理器 ./mvnw compile -X 21 | grep -i processor\|lombok\|mapstruct # 跳过测试以隔离编译错误 ./mvnw compile -DskipTests # 查看当前使用的 Java 版本 ./mvnw --version java -version几个命令在真实场景中的价值dependency:tree -Dverbose是版本仲裁dependency mediation问题的核心武器能直接显示每个依赖被哪个路径引入、以及冲突中被丢弃的版本-U强制刷新SNAPSHOT常用于本地缓存了过期快照导致改了代码不生效的诡异场景help:effective-pom能看到父子 POM 继承合并后的最终形态排查spring-boot-dependenciesBOM 或quarkus-bom是否真正生效compile -X输出调试级日志并过滤 processor 关键字是定位 Lombok/MapStruct 注解处理器崩溃的标准手段。七、Gradle 专项排障# 查看依赖树定位冲突 ./gradlew dependencies --configuration runtimeClasspath # 强制刷新依赖 ./gradlew build --refresh-dependencies # 清理 Gradle 构建缓存 ./gradlew clean rm -rf .gradle/build-cache/ # 带调试输出运行 ./gradlew build --debug 21 | tail -50 # 查看某个依赖的解析路径 ./gradlew dependencyInsight --dependency name --configuration runtimeClasspath # 查看 Java 工具链 ./gradlew -q javaToolchains对比 Maven 版可以发现两者一一对应dependencies之于dependency:tree、--refresh-dependencies之于-U、dependencyInsight之于-Dverbose下的定位能力。Gradle 侧额外值得注意javaToolchains——它直接呼应了 Java 8 之后多 JDK 并存时代最常见的本地能编、CI 报 Java 版本错误问题。文档开篇即强调在执行任何命令前先确认pom.xml/build.gradle/build.gradle.kts中的实际构建工具避免把 Gradle 命令错发给 Maven 项目。八、[SPRING] Spring Boot 专属验证命令# 验证应用上下文能加载用 test profile 启动 ./mvnw spring-boot:run -Dspring-boot.run.arguments--spring.profiles.activetest # 检查缺失 Bean 或循环依赖 ./mvnw test -Dtest*ContextLoads* -q # 验证 Lombok 被配置为注解处理器而非仅仅作为依赖 grep -A5 annotationProcessorPaths\|annotationProcessor pom.xml build.gradle # 检查 Spring Boot 版本对齐 ./mvnw dependency:tree | grep org.springframework.boot三条命令分别命中三类高发问题启动期上下文失败用*ContextLoads*测试类快速验证、注解处理器配置缺失Lombok 必须同时出现在annotationProcessorPaths/annotationProcessor配置中而不仅是 compile 依赖、依赖版本漂移通过dependency:tree过滤出所有org.springframework.boot版本判断是否被 BOM 拉齐。九、[QUARKUS] Quarkus 专属验证命令9.1 Maven 侧# 验证 Quarkus 构建期增强 ./mvnw quarkus:build -q # dev 模式运行以暴露运行时错误 ./mvnw quarkus:dev # 列出已安装扩展 ./mvnw quarkus:list-extensions -q 21 | grep ✓\|installed # 添加缺失扩展 ./mvnw quarkus:add-extension -Dextensionsextension-name # 检查 Quarkus BOM 版本对齐 ./mvnw dependency:tree | grep io.quarkus # 验证 native 构建前置条件GraalVM ./mvnw package -Pnative -DskipTests 21 | head -50 # 调试构建期增强失败 ./mvnw compile -X 21 | grep -i augment\|build step\|extension9.2 Gradle 侧# 验证 Quarkus 构建期增强 ./gradlew quarkusBuild # dev 模式运行 ./gradlew quarkusDev # 列出已安装扩展 ./gradlew listExtensions # 添加缺失扩展 ./gradlew addExtension --extensionsextension-name # 检查 Quarkus 依赖对齐 ./gradlew dependencies --configuration runtimeClasspath | grep io.quarkus # 验证 native 构建前置条件GraalVM ./gradlew build -Dquarkus.native.enabledtrue -x test 21 | head -509.3 通用两套构建工具共用# 检查反射注册native image 场景 grep -rn RegisterForReflection src/main/java --include*.java # 验证 CDI Bean 发现先跑 dev mode再看输出 # Maven: ./mvnw quarkus:dev | Gradle: ./gradlew quarkusDev # 然后 grep 日志关键字bean|unsatisfied|ambiguous与 Spring Boot 不同Quarkus 的最大特征是构建期增强build-time augmentation与 native 编译大量错误Panache 实体未增强、反射缺失、non-proxyable bean type只在构建期或原生镜像阶段才会暴露。因此 Quarkus 的验证命令大量围绕quarkus:build、native profile 与RegisterForReflection反射登记展开。文档特别强调添加扩展优先使用quarkus ext addMaven/addExtensionGradle而不是手工编辑pom.xml因为扩展的 BOM 版本对齐由工具自动完成能显著降低quarkus-extension-* not found类错误的概率。十、关键原则与停止条件10.1 修复纪律Key PrinciplesSurgical fixes only——不重构只修错误未经明确批准绝不使用SuppressWarnings压制警告除非必要绝不改方法签名每次修复后必须重新构建验证修复根因而非压制症状优先补 import 而非改逻辑[QUARKUS]扩展优先走quarkus ext add加反射配置前先确认是否需要RegisterForReflection动手前先核对pom.xml/build.gradle/build.gradle.kts确认构建工具再跑对应命令。10.2 停止并上报Stop Conditions以下情况 Agent 必须停下汇报而非继续盲目尝试同一错误在 3 次修复尝试后仍然存在修复引入的错误多于其解决的错误错误需要超出范围的架构级改动缺少需要用户决策的外部依赖私有仓库、许可证[QUARKUS]native 镜像构建因本机未安装 GraalVM 失败——直接上报前置条件缺失。这组停止条件本质上是防失控护栏它防止 Agent 在错误方向上深挖不止把需要人类判断的边界问题许可证、私有仓库、架构决策及时交还给用户。十一、结构化输出格式Agent 每次排障结束需按统一模板输出结果保证日志可解析、可追溯Framework: [SPRING|QUARKUS|BOTH|UNKNOWN] [FIXED] src/main/java/com/example/service/PaymentService.java:87 Error: cannot find symbol — symbol: class IdempotencyKey Fix: Added import com.example.domain.IdempotencyKey Remaining errors: 1最终一行给出总结态Framework: X | Build Status: SUCCESS/FAILED | Errors Fixed: N | Files Modified: list。该输出契约的价值在于每次修改都以文件:行号 原始错误 修复动作三元组落盘配合Framework与Remaining errors状态字段天然支持在 ECC 的 java-reviewer代码评审等下游流程中做二次复核或复盘。十二、与仓库生态的协同java-build-resolver并非孤立存在它在 ECC 中被设计为 Java 工作流的一环评审对偶java-reviewer 面向代码质量评审构建解析器面向构建失败二者在 AGENTS.md 的 Agent 编排表中互为补充见 AGENTS.md模式知识库深度修复需要框架范式时[SPRING] 场景查阅 skills/springboot-patterns/SKILL.md涵盖RestController分层、Spring Data JPA 仓库模式、事务服务层、校验与异常处理等[QUARKUS] 场景查阅 skills/quarkus-patterns/SKILL.md涵盖 Quarkus 3.x 的 CDI 服务层、Panache 数据访问、Camel 消息与 native 编译模式多语言家族仓库内还维护了面向 Java 的 rules/java/coding-style.md 编码风格、rules/java/patterns.md 模式等规则文件供 Agent 在遵循项目既有规则时引用多语言化该 Agent 定义随仓库多语言文档体系同步翻译例如 docs/zh-CN/agents/java-build-resolver.md、docs/ja-JP/agents/java-build-resolver.md 等便于不同语言环境团队采用同一套排障规范。结语把构建排障工程化综观全文档java-build-resolver提供的不是某个灵丹妙药而是一套可复制、可审计、有护栏的工程化排障流程框架先行判定 → 标准化诊断命令 → 错误-原因-修复对照表 → 最小改动修复 → 构建/测试双重验证 → 统一结构化输出。它对 Spring Boot 与 Quarkus 两套生态分别维护专属错误表和命令集对 Maven 与 Gradle 双工具链一视同仁并以3 次尝试上限等停止条件防止过度操作。这套方法论对任何 Java 团队的 CI 故障响应、AI 辅助排障乃至人工排障 SOP 设计都具有直接的参考价值——无论你的项目是传统 Spring Boot 单体、还是追求原生镜像的 Quarkus 云原生服务。【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考