根本原因是Maven未真正下载依赖或未将其加入类路径，常见于scope错误、父POM版本覆盖、IDE未刷新；多模块需确保父POM packaging为pom、modules用相对路径、relativePath配置正确；dependencyManagement仅声明版本，dependencies才实际引入。

为什么 pom.xml 里加了依赖却报 ClassNotFoundException

根本原因不是没写对，而是 Maven 没真正拉下来或没参与编译/运行类路径。常见于：依赖 scope 写错、父 POM 覆盖了版本、IDE 没刷新 Maven 项目。

• scope 用 test 却在 main 代码里调用——立刻报错，改成 compile（默认可省略）
• 用了 provided（如 servlet-api），但本地运行没容器——手动加 runtime classpath 或换 compile
• IDE 显示依赖存在，但 mvn compile 报错——先删掉 target/，再执行 mvn clean compile -U（-U 强制更新快照）

多模块项目中 parent 和 modules 怎么配才不翻车

父子模块结构一旦错位，Maven 就找不到子模块，或者继承关系失效，导致插件配置、属性替换全挂。

• 父 pom.xml 的 <packaging></packaging> 必须是 pom，否则子模块无法被识别为 module
• <modules></modules> 里写的是相对路径（如 <module>user-service</module>），不是 groupId 或 artifactId
• 子模块的 <parent></parent> 中 <relativepath></relativepath> 默认是 ../pom.xml；如果父 POM 不在上一级，必须显式写对，比如 <relativepath>../../parent/pom.xml</relativepath>

dependencyManagement 和 dependencies 到底谁管版本谁管引入

前者只“声明”版本和默认 scope，后者才真正把依赖拉进 classpath。混用时容易以为加了就生效，结果编译通过、运行失败。

java-api-doc-generator

分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。

下载

• 在 parent 中用 <dependencymanagement></dependencymanagement> 统一指定 spring-boot-starter-web 版本 → 子模块只需写 <dependency></dependency>（不用写 <version></version>）就能复用该版本
• 如果子模块自己写了 <version></version>，会覆盖 dependencyManagement 的声明
• dependencyManagement 里的依赖不会自动引入！必须在子模块的 <dependencies></dependencies> 里显式声明才能生效

构建失败提示 Failed to read artifact descriptor 怎么快速定位

本质是某个依赖的 pom 文件下载不完整或校验失败，常发生在公司私仓配置错误、网络中断、镜像源不可用时。

立即学习“Java免费学习笔记（深入）”；

• 看错误行末尾的坐标，比如 com.example:utils:1.2.0，去本地仓库对应路径（如 ~/.m2/repository/com/example/utils/1.2.0/）检查是否存在 utils-1.2.0.pom 文件，以及是否为空或只有 .lastUpdated 后缀
• 删掉整个版本目录，再跑 mvn clean compile -U
• 检查 settings.xml 中 <mirror></mirror> 是否指向了已下线的镜像，或认证配置（<server></server>）缺失用户名密码

真正麻烦的不是配置项多，而是某些字段（比如 relativePath、scope、version 在 management vs dependencies 中的行为差异）只差一步就全链路失效，而且错误信息从不直接告诉你缺哪一环。