Maven 与构建工具

• GitHub Actions 的抽象层级：workflow（工作流）→ job（任务）→ step（步骤）→ runner（运行器）
• 本地 ~/.m2 或 ~/.gradle 缓存目录的持久化与命中
• actions/cache 的 key 与 restore-keys 设计

GitHub Actions 中一个 workflow 是仓库 .github/workflows/ 下的 YAML 文件，内含多个 job；job 并行执行，通过 needs 建立依赖；每个 job 运行在独立的 runner 上，由多个 step 顺序组成，step 是执行命令或 action 的最小单元。Maven 构建非常依赖缓存，因为每次编译都要解析依赖并下载到本地仓库。actions/cache 能把 ~/.m2/repository（Maven）或 ~/.gradle/caches（Gradle）缓存到 GitHub 存储，后续 job 通过 restore-keys 复用，避免重复下载第三方依赖。key 的粒度过细（如每次 commit）会导致命中率低，过粗则可能复用陈旧依赖，因此常用 cache: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }} 使 POM 变化时才重建缓存。

缓存的本质是本地仓库的持久化，Maven 的 -o（离线）、-U（强制更新）与 updatePolicy 共同决定缓存何时失效。仅缓存依赖还不够，还应考虑 Maven 的 -T 并行构建以缩短编译时间。

• AOT（Ahead-of-Time）编译与 JIT 的差异
• Spring Boot 的 AOT 处理：配置分析、Bean 定义生成、反射/资源/代理元数据收集
• 阶段划分：AOT 分析 → 生成代码 → 编译 → 原生镜像打包

-Daot.enabled=true 让 Maven 构建进入 Spring Boot 4.0 的 AOT 处理模式。其核心流程分为几个阶段：首先是配置分析阶段，Spring 容器在"编译期"运行上下文刷新，收集所有 Bean 定义、条件装配（@Conditional）、拦截器与代理信息；随后是代码生成阶段，将分析结果生成为 AOT 后的 Java 源码（如 *ApplicationContextInitializer、*BeanDefinitions 等），把运行时反射解析变成静态字节码；之后是编译阶段，把生成的代码连同应用一起编译；最后是可选的镜像打包阶段，通常配合 GraalVM Native Image 生成自包含可执行文件。AOT 的核心价值是提前完成类路径扫描与反射分析，减少运行时启动开销，并让 Spring 能被原生镜像工具静态分析。

AOT 被设计为对已有代码无侵入的增强，它通过 Maven 的 spring-boot-maven-plugin 的 process-aot goal 触发。启用 AOT 后，依赖动态特性（如反射、懒加载 bean）的代码需要额外声明 hint。

• -DskipTests：跳过测试执行但保留编译测试类
• -Dmaven.test.skip：连测试代码编译也跳过
• 与 Surefire 的默认行为及 Spring Boot 测试的集成

-DskipTests 是 Surefire 的标准参数，它跳过测试的执行但会先编译测试类，因此测试代码中的编译错误仍会被发现，适合只想快速验证装配但保留测试可运行的场景。-Dmaven.test.skip 则彻底跳过测试代码的编译与执行，构建更快，但测试类的语法错误也会被忽略，通常用于 CI 中确实需要跳过测试的分发构建。前者对应 Surefire/Failsafe 的 skipTests 属性，后者对应编译插件与测试插件共用的 maven.test.skip 属性；在 Spring Boot 项目中，测试类（如 @SpringBootTest）若不执行，其上下文加载与断言自然不会触发，但 -DskipTests 仍会占用测试编译时间。

两者本质区别在于是否编译测试代码。生产发布时若需保证测试质量，应使用 -DskipTests 或运行集成测试，而不是用 -Dmaven.test.skip 掩盖问题。

• Maven 4.0 对 Gradle 风格 CLI 的兼容
• 构建 POM 与消费者 POM（pom 结构与元数据）的分离
• 与传统 <project> 根元素 POM 的差异

Maven 4.0 引入了与 Gradle 更接近的 CLI 体验，并提供 init/build 等更简洁的命令，同时其核心变化是"构建 POM"与"消费者 POM"分离：构建 POM 是开发者看到的完整构建模型，消费者 POM 是发布到仓库供下游依赖的简化模型。这种分离让构建私有配置（如插件配置、profile）不污染下游，也提升了依赖解析的并发与增量性能。与传统 pom 相比，Maven 4.0 默认使用新的 pom.xml 结构并支持 TOML 配置，但保持向后兼容旧 POM。

该设计让 Maven 在大型多模块场景下更接近 Gradle 的灵活性，同时保留内核的确定性。迁移时需验证插件对构建 POM/消费者 POM 分离的兼容性。

• --update-snapshots 强制刷新 SNAPSHOT 依赖
• --fail-on-warning 将警告升级为失败
• 对镜像构建可复现性与质量门禁的影响

--update-snapshots 等价于经典的 -U，强制从远程仓库重新获取 SNAPSHOT 依赖的最新时间戳版本，避免 CI 因本地缓存陈旧而构建出旧版本；--fail-on-warning 则把构建过程中的警告（如 JDK 版本提示、废弃 API 警告）升级为失败，从而在 CI 中强制团队处理警告。二者结合时，镜像构建会先拉取最新依赖再严格校验警告，保证产物质量，但也会让构建更慢、更易失败，需要权衡是否适合每条流水线。

SNAPSHOT 依赖默认按 updatePolicy（默认 daily）刷新，--update-snapshots 覆盖该策略。--fail-on-warning 是质量门禁的一种，适合发布流水线而非日常开发。

• 独立版本元数据（version metadata）的引入
• 与 Maven Central 索引/校验和的同步
• 离线构建（offline build）与缓存预取

Maven 4.0 改进了依赖解析的元数据结构，将版本列表、时间戳等元数据与制品文件分离管理，并与 Maven Central 的索引同步，使解析器能更快定位最新版本。离线构建策略依赖本地仓库的完整缓存：通过预先把 Central 索引与所需制品下载到本地镜像仓库，配合 -o（离线）模式，可以在无外网环境（如内网 CI）中完成构建。校验和（checksum）与签名验证确保了离线缓存内容可信，防止被篡改。

独立版本元数据让远程仓库查询更快更一致，是离线/内网构建的基础。离线构建的可复现性依赖锁定版本与完整缓存，需要配合 dependency:go-offline 预取。

• .mvn/maven.config 的机制与 Maven 4.0 中的处理
• 对 CI 流水线参数传递的影响
• 迁移到 MAVEN_ARGS 环境变量或显式命令行参数

.mvn/maven.config 文件中的默认参数（如 -T、-DskipTests）在 Maven 4.0 中仍会被自动加载，并未被移除（Maven 4 还改进了配置文件的编码处理）。但为让 CI 流水线行为更显式、可预测，建议将关键参数显式写入 CI 的 MAVEN_ARGS 环境变量或命令行参数，并审查所有依赖 .mvn/maven.config 的流水线，避免 CI 与本地行为不一致。

maven.config 在 Maven 4 中仍是受支持的机制，但构建行为显式化是工程最佳实践。迁移时应先确认哪些参数是必需的，再统一到显式配置，避免 CI 与本地行为不一致。

• Archetype 的结构（archetype-metadata.xml、原型文件、velocity 模板）
• requiredProperties 的字段校验（defaultValue、boolean/选项）
• 版本约束模板（像 ${springBootVersion} 这类占位符）

Maven Archetype 通过 archetype-metadata.xml 定义生成参数（requiredProperties），可在其中声明字段的默认值、required 属性与是否允许为 true/false，Maven 在生成时对这些字段做校验。原型文件里的 velocity 模板用 ${groupId}、${artifactId}、${springBootVersion} 等占位符填充，把版本号、包名等约束写入 pom.xml 模板。生成 Spring Boot Starter 脚手架时，常见做法是把 Spring Boot 版本、groupId、artifactId 作为 requiredProperties，并在 pom 模板中通过 property 占位引用，避免版本硬编码。

Archetype 的价值在于统一工程初始化，字段校验保证了生成物合法，版本约束模板保证各模块依赖版本一致。mvn archetype:generate 会读取模板并替换占位符。

• -parameters 保留方法参数名元数据
• Spring MVC 中 @RequestParam、@PathVariable 在未指定名称时的参数名解析
• 与 -g 调试信息、局部变量名表的区别

-parameters 让 javac 在字节码中保留真实的参数名（MethodParameters 属性），Spring 在参数绑定时可据此按名称解析参数。Spring Boot 的 spring-boot-starter-parent 默认开启该参数，使 @RequestParam("name") 在省略名称时也能通过参数名推断。未开启时，Spring 只能退化为 @RequestParam 的默认值或依赖 -g 的局部变量名表（LocalVariableTable），后者在部分优化下不可靠。因此 -parameters 是 Spring MVC 参数名绑定、以及 Spring 反射参数名发现的基础。

该参数直接关系到 Spring 能否由参数名推断绑定名称，是 Spring Boot 默认配置的一部分。自定义 Maven 配置时若覆盖 compiler 参数需留意保留。

• Surefire 执行单元测试、Failsafe 执行集成测试
• JUnit 5 的并行执行（junit.jupiter.execution.parallel.enabled）
• 并行度与 Spring 上下文缓存、线程安全

Surefire 默认绑定 test 阶段执行 *Test 类，Failsafe 绑定 integration-test 与 verify 阶段执行 *IT 类。JUnit 5 的并行执行需先在 junit-platform.properties 或 junit.jupiter.execution.parallel.enabled 中开启，并配置 parallel.mode.default（如 concurrent）与 parallelism。Spring Boot 测试依赖 ApplicationContext 缓存，并行执行时不同测试类若共享同一上下文，需保证上下文线程安全，或通过 @DirtiesContext 控制；同时注意数据库、文件等共享资源的并发冲突。

并行执行能显著缩短集成测试时间，但要求测试隔离。Failsafe 的 verify 阶段在集成测试后汇总结果，失败时保证 post-integration-test 清理仍执行。

• maven-toolchains-plugin 与 toolchains.xml
• 构建 JVM 与编译/测试 JDK 的分离
• CI 节点上的工具链校验（jdks 存在性、版本匹配）

Maven Toolchains 通过 toolchains.xml 声明本地可用的 JDK 列表，maven-toolchains-plugin 在构建时按 jdkToolchain 指定版本选择编译与测试所用的 JDK，而 Maven 自身进程仍运行在配置的 JVM 上，从而实现"构建进程 JVM"与"编译/测试 JDK"解耦。这对多 JDK 矩阵很重要：可以在同一构建进程下用 JDK 17 编译、用 JDK 21 测试。CI 节点应校验 toolchains.xml 中声明的 JDK 路径存在且版本匹配，通常通过专门的 job 或脚本提前验证，避免构建中途失败。

Toolchains 让同一份 pom 在不同 JDK 下复用，是 CI 多版本矩阵的基础。校验应覆盖路径存在性、版本号与 JAVA_HOME 一致性。

• Maven Wrapper（mvnw）如何定位 JAVA_HOME
• 多 JDK 构建矩阵（matrix）的 CI 配置
• Spring Boot 4.0 对 JDK 版本的要求

Maven Wrapper 通过查找 JAVA_HOME 环境变量（或 PATH 中的 java）来启动 Maven，因此 CI 矩阵中每个 job 可设置不同的 JAVA_HOME 指向不同 JDK，从而覆盖多版本构建。Spring Boot 4.0 要求较新的 JDK（如 17+），构建矩阵需在支持的 JDK 上分别跑 mvnw verify，并可在 .mvn/wrapper/maven-wrapper.properties 中固定 Maven 版本。为保证一致性，矩阵 job 应显式设置 JAVA_HOME 并校验 java -version。

Wrapper 保证 Maven 版本一致，JAVA_HOME 隔离 JDK 版本，二者结合实现稳定可复现的多 JDK 矩阵。CI 中常用 setup-java 等 action 设置 JAVA_HOME。

• Spring Boot 4.x 对 Maven 3.6.3+ 的要求
• Maven 版本过低导致的功能缺失
• 升级 Maven 的兼容性考量

Spring Boot 4.x 的构建需要 Maven 3.6.3 及以上版本，因为其父 POM 与插件（如 spring-boot-maven-plugin）使用了较新的 Maven 特性与 API。若使用过低版本，插件可能无法正确解析或执行，导致构建失败。升级 Maven 时主要考虑本地仓库元数据兼容性、第三方插件对 Maven 版本的依赖，以及 CI 节点上 Maven 版本的一致性。

版本兼容性是工程化的基础，Spring Boot 官方文档明确给出最低 Maven 版本，团队应在 CI 中固定并校验 Maven 版本。

• 多模块聚合与依赖管理（父子 POM）
• 模块化降低耦合、复用公共代码
• 与微服务拆分（模块化单体）的呼应

Maven 多模块通过父 POM 聚合子模块，用 <modules> 与 <parent> 实现统一版本管理与依赖管理，在 Spring Boot 3.5+ 微服务拆分中，可将公共领域模型、通用工具、基础设施抽象为独立模块，业务模块按领域拆分，实现"模块化单体"或微服务前的代码组织。这降低了模块间耦合、避免重复代码、统一依赖版本，并让构建一次完成所有模块。

多模块是微服务拆分的前置工程手段，配合 Spring Modulith 等工具可验证模块边界。价值在于可维护性、可复用性与构建统一性。

• spring-boot-maven-plugin 的 build-image goal
• 生成符合 Cloud Native Buildpacks 的镜像
• 无需编写 Dockerfile 的便捷性

Spring Boot 3.5+ 通过 spring-boot-maven-plugin 的 build-image goal，利用 Cloud Native Buildpacks 直接生成可运行的容器镜像，无需手写 Dockerfile。它自动探测运行环境、选择基础镜像、合理分层（依赖层与应用层分离），使镜像更小、更安全、构建更可复现。工程价值在于：统一镜像构建流程、避免 Dockerfile 运维成本、提升可移植性与供应链安全。

镜像构建是容器化部署的前提，Buildpacks 将"如何构建镜像"抽象掉，让开发者专注于应用本身。分层缓存还能加速 CI 构建。

• maven-enforcer-plugin 的 rules（bannedDependencies、requireMavenVersion）
• License 检查（bannedLicenses 或外部插件）
• 减少失效依赖与合规风险

maven-enforcer-plugin 通过 enforce goal 在构建早期执行规则。bannedDependencies 可禁止过时/有漏洞的依赖版本（如声明 excludes 指定 groupId:artifactId），requireMavenVersion 校验 Maven 版本，bannedLicenses 检查依赖的 License 是否允许，从而把合规与安全硬约束注入构建。工程实践上，把这些规则放在父 POM 的 <build><plugins><pluginManagement> 中，全项目统一生效，并让 fail 级规则阻止错误版本进入发布。

Enforcer 是把架构/安全约束"代码化"的工具，属于质量门禁的一部分。规则应在 CI 中强制执行而非仅本地。

• Maven 本地仓库的依赖复用
• Gradle 的构建缓存（build cache）与依赖缓存
• 增量构建与增量

Maven 的 ~/.m2/repository 保存已下载的依赖，重复构建时直接复用，避免网络下载；Gradle 除了依赖缓存，还有构建缓存（build cache），可缓存编译产物与任务输出，支持本地与远程，跨机器复用。加速的核心是"缓存命中"：Maven 主要靠本地仓库 + 增量编译，Gradle 靠任务级输入输出哈希判定是否重跑。CI 中常通过 actions/cache 持久化这些目录。

Maven 的缓存粒度是依赖，Gradle 的缓存粒度是任务输出，后者在增量上与并行上更优。缓存需配合更新策略（如 SNAPSHOT 的 updatePolicy）避免陈旧。

• Maven 版本中的 build metadata（如 -r<commit>、时间戳）
• 基于 Git 的版本号生成（git-commit-id-plugin）
• 可复现构建与可追溯性

通过 git-commit-id-plugin 或 CI 脚本把 Git commit、构建时间注入 Maven 版本号或 MANIFEST 中，使每个制品能追溯到对应源码与构建环境。常见做法是版本号 1.0.0-<commit短哈希>，并在构件中写入 build number、commit、时间戳等 metadata。这保证可追溯性（出问题能定位代码版本）与可复现性（记录构建环境与输入）。可复现构建还要求固定依赖版本、避免时间戳随机化。

制品可追溯是运维与安全审计的基础。build metadata 应随构建生成并写入 MANIFEST 或 properties 文件，供运行时读取。

• 增量构建与任务级缓存
• Groovy/Kotlin DSL 的灵活性与可编程性
• 并行构建与守护进程

Gradle 相比 Maven 的优势主要在于：构建性能上，任务级增量构建、构建缓存（本地/远程）、并行执行与守护进程（daemon）使大型项目构建更快；DSL 灵活性上，Groovy/Kotlin DSL 允许脚本编程、自定义任务、条件逻辑，比 Maven 的 XML 声明式更灵活。Android 官方即采用 Gradle。但灵活性也带来学习成本与构建脚本不可控的风险。

选择工具需权衡：Maven 规范、可视化稳定，适合标准化团队；Gradle 灵活、性能好，适合大型、构建复杂项目。构建性能差异在大规模多模块下尤为明显。

• settings.gradle：项目级配置、模块包含（include）、仓库
• build.gradle：模块的依赖、插件、任务配置
• 多项目构建的协调

settings.gradle（或 settings.gradle.kts）是项目级配置，声明要包含哪些子项目（include ':module'）、仓库（repositories）、插件管理，是整个多项目构建的入口；build.gradle 是每个模块的构建脚本，配置该模块的依赖（dependencies）、插件（plugins）、任务（tasks）与扩展。Gradle 先读 settings 确定项目结构，再对每个项目执行对应 build.gradle。

二者分工清晰：settings 负责"有哪些项目、用什么仓库"，build 负责"每个项目怎么构建"。这是多模块 Gradle 的基础。

• maven-resolver（Aether）的解析优化
• 增量构建与缓存
• 并行构建（-T）与依赖解析

Maven 3.9+ 基于 maven-resolver 改进了依赖解析的性能与可靠性：增强了解析缓存、自动处理校验和与元数据、改善对 SNAPSHOT 与远程仓库的并发请求。配合 -T 1C（按 CPU 核数并行）构建，多模块可并行编译，显著缩短时间。增量构建方面，maven-compiler-plugin 通过检查输入输出变化避免重复编译。并行构建时需注意插件 threadSafe 声明与共享输出目录。

性能优化集中在解析层与执行层。并行度提升明显，但需保证模块间无隐藏依赖冲突与共享资源竞态。

• 构建 POM 与消费者 POM 的分离动机
• 下游污染与构建私有配置泄漏
• 插件兼容性验证

Maven 4 中构建 POM 是开发者编辑的完整构建模型，消费者 POM 是发布给下游的简化模型，二者分离解决的核心问题是：构建私有配置（插件、profile、properties）污染下游依赖解析，导致消费者解析出错误或冗余的依赖。迁移前应验证：所用插件是否支持 consumer POM 模型、依赖解析结果是否改变、插件是否读取/写入构建私有属性，以及仓库中原有制品与新模型是否兼容。

分离让元数据更干净、解析更快，但可能改变下游可见的依赖树，因此迁移前需对比依赖树与消费者 POM 内容。

• 多模块构建的并行与增量
• Gradle 任务级缓存 vs Maven 模块级构建
• 构建速度与生态的权衡

在 Spring Cloud Alibaba 这类多模块场景下，Gradle 8.x 通常构建更快，因为其任务级增量构建、构建缓存与更强的并行执行能力，能避免重复编译未变更模块；Maven 4.0 虽改进了解析与并行，但整体构建模型仍是模块级，增量粒度较粗。不过 Maven 的生态成熟、与 Spring Boot 官方插件集成紧密、配置规范，团队若看重生态与可维护性，Maven 也是稳妥选择。实际对比需结合模块数量、变更频率与 CI 缓存。

构建速度并非唯一指标，需权衡生态、学习成本与团队习惯。Gradle 在大型多模块、频繁迭代场景下提速更明显。

• maven-wrapper.properties 的 distributionUrl
• 校验和（checksum）验证
• 供应链安全（防止下载到被篡改的 Maven）

Maven Wrapper 的 maven-wrapper.properties 中 distributionUrl 指向 Maven 发行包下载地址，应审查其使用 HTTPS 官方/可信源；distributionSha256Sum 可声明期望的校验和，Wrapper 下载后校验，防止下载到被替换的发行包。工程实践上应固定 distributionUrl 的版本、配置校验和，并审查 CI 中是否允许覆盖这些属性（防止攻击者通过环境变量注入恶意 URL）。

Wrapper 目标是保障 Maven 版本一致，但下载源本身也需可信。校验和是供应链安全的关键防线。

• mvnw/mvnw.cmd 脚本
• .mvn/wrapper/maven-wrapper.properties 固定版本
• 团队统一 Maven 版本

Maven Wrapper 提供 mvnw（Unix）与 mvnw.cmd（Windows）脚本，首次使用时按 .mvn/wrapper/maven-wrapper.properties 中的 distributionUrl 下载并缓存指定版本的 Maven，之后所有成员与 CI 都用同一版本构建，实现版本对齐。它的价值是消除"我本地 Maven 版本不同导致构建不一致"的问题，保证可复现构建。

Wrapper 固定 Maven 版本，与固定 JDK 版本并重，是构建可复现性的基础。仓库应提交 wrapper 文件。

• dependency:tree 查看依赖树与冲突
• dependency:analyze 检测未使用/声明缺失依赖
• 依赖冲突定位与修复

dependency:tree 打印完整依赖树，可直观看到传递依赖、被调解掉（omitted）的版本与产生冲突的路径，是定位依赖冲突（如版本不一致、类加载冲突）的首选工具；dependency:analyze 分析已使用而未声明、以及声明但未使用的依赖，帮助清理过多依赖并避免隐式依赖。二者结合：先用 tree 看冲突来源，再用 analyze 判断哪些依赖真正需要声明或可移除。

依赖冲突常表现为 NoSuchMethodError、ClassNotFoundException。tree 定位路径，analyze 精简依赖，是依赖治理的常用手段。

• Maven 的 XML 声明式配置
• Gradle 的 Groovy/Kotlin DSL 可编程性
• 学习曲线与灵活性

Maven 使用 XML 声明式配置，结构固定、约定优于配置，插件通过 <goal> 绑定生命周期，可读性好但灵活度低；Gradle 使用 Groovy/Kotlin DSL，构建脚本本质是代码，可自定义任务、条件逻辑、函数，灵活度高，但学习成本更高、脚本更易失控。Maven 适合标准化、规范团队，Gradle 适合需要定制构建的大型或复杂项目。

差异本质是"声明式 vs 可编程式"。Maven 的可预测性来自约定，Gradle 的灵活性来自代码表达力。

• 最近路径优先（nearest definition）
• 先声明者优先（first declaration wins）
• 与 dependencyManagement 的关系

Maven 依赖调解核心规则是"最近路径优先"：当同一构件出现多个版本时，选择依赖树中路径最短的版本；若路径深度相同，则按"先声明者优先"原则，依赖树中先出现的版本获胜。dependencyManagement 可显式锁定版本，覆盖调解规则，是解决冲突的推荐手段。了解调解规则有助于理解为什么最终用了某个版本以及如何用 dependencyManagement 干预。

调解规则是 Maven 默认行为，理解它才能预判冲突结果。显式 dependencyManagement 比依赖隐式调解更可控。

• 聚合（）的目标
• 多模块（继承 ）的目标
• 二者常见结合使用

聚合通过父 POM 的 <modules> 列出子模块，目的是一次构建所有模块、统一管理构建顺序；多模块（继承）通过子 POM 的 <parent> 指向父 POM，目的是继承父 POM 的依赖管理、插件配置与属性。聚合管"构建"，继承管"继承配置"，二者常结合使用：父 POM 既声明 modules 又作为依赖父，实现"一次构建、统一配置"。

聚合与继承是正交概念，聚合决定构建范围，继承决定配置继承。理解二者便于设计多模块结构。

• maven-compiler-plugin：编译与 Java 版本
• maven-surefire-plugin：单元测试执行
• maven-shade-plugin：打 Fat Jar / 重定位

maven-compiler-plugin 负责编译源代码，配置 source/target/release 与 -parameters 等编译参数；maven-surefire-plugin 在 test 阶段执行单元测试（JUnit/TestNG）并生成报告，失败则构建失败；maven-shade-plugin 把项目及其依赖打成一个可执行 Fat Jar，并支持重定位（relocate）包名避免冲突。三者分别覆盖编译、测试、打包三个环节。

这些是 Maven 生命周期中形成标准构建链路的核心插件。release 参数优于 source/target，能同时约束平台 API。

• BOM 是一组依赖版本管理
• <scope>import</scope> 引入外部 BOM
• 统一版本、避免版本冲突

BOM（Bill of Materials）是一个特殊的 POM，只通过 dependencyManagement 声明一组依赖的推荐版本，不引入具体依赖。消费方在 dependencyManagement 中用 <scope>import</scope> 引入 BOM，即可继承其中所有版本，从而在引入多个依赖时保持一致版本、避免冲突。Spring Boot 的 spring-boot-dependencies 就是典型 BOM，让 Spring Boot 生态依赖版本统一。

BOM 是"版本管理"的复用，import 将外部 BOM 的 dependencyManagement 合并进来。注意 import 只在 dependencyManagement 顶层生效。

• profile 的条件激活（JDK/系统属性/文件存在）
• 按环境配置参数与资源过滤
• 多环境（dev/prod）的构建

Maven Profile 允许在特定条件下覆盖或新增配置，激活条件包括 JDK 版本、系统属性、文件存在等，也可通过 -P 显式指定。多环境构建中，常用 profile 为 dev/prod 等环境设置不同的 properties、资源文件（配合 resource filtering）、插件参数，使同一 POM 在不同环境产出不同配置。工程实践要注意 profile 的默认值与环境隔离，避免生产配置泄漏。

Profile 是 Maven 多环境的手段，配合 maven-resources-plugin 的 filtering 实现配置模板化。但需谨慎，过多 profile 会降低可维护性。

• SNAPSHOT 是可变版本、允许重复发布
• RELEASE 是稳定、不可变版本
• 版本发布策略与可复现性

SNAPSHOT 版本（如 1.0.0-SNAPSHOT）表示开发中的可变版本，允许同一坐标重复发布，Maven 会按 updatePolicy 检查远程更新；RELEASE 版本是稳定、不可变版本，发布后内容固定，用于正式发布。开发阶段模块间依赖常用 SNAPSHOT 以便快速迭代，但正式发布与可复现构建必须用 RELEASE 并锁定版本。发布流水线应确保 SNAPSHOT 不进入生产依赖。

SNAPSHOT 的可变性带来便利也带来不确定性，是影响可复现性的关键因素。发布时应切到 RELEASE 并打 tag。

• dependencyManagement 管理依赖版本
• pluginManagement 管理插件版本与配置
• 二者都不主动引入，只提供默认值

dependencyManagement 在父 POM 中声明依赖的版本与 scope，子模块使用依赖时无需再写版本，实现版本统一管理；pluginManagement 管理插件的版本与配置，子模块声明使用该插件时继承这些默认配置。二者的共同点是"只提供默认/约束，不主动引入"——dependencyManagement 不会自动把依赖加进类路径，pluginManagement 不会自动执行插件，子模块仍需显式声明。

二者是父 POM 统一治理的核心，避免各模块版本漂移。理解"不主动引入"这一语义很重要，否则易误以为声明了版本就会生效。

• 统一版本、消除重复声明
• BOM 复用版本管理
• 避免版本冲突与升级困难

dependencyManagement 把依赖版本集中到一处，子模块无需重复写版本，避免版本漂移与冲突；BOM 则把这组版本管理作为可复用制品发布，供多个项目 import，实现跨项目版本统一。二者结合，让 Spring Boot 生态、第三方库的版本在团队内保持一致，升级时只需改一处，提升可维护性与可复现性。

版本统一管理是工程化治理的核心，BOM 是其跨项目复用形态。它不引入依赖，只约束版本。

• enforce 目标与规则（rules）
• requireJavaVersion、bannedDependencies 等
• 构建失败阻止违规

maven-enforcer-plugin 的 enforce goal 在构建早期执行一组规则，规则如 requireJavaVersion（校验 JDK 版本）、requireMavenVersion、bannedDependencies（禁止依赖）、dependencyConvergence（依赖收敛）等。任一规则失败即构建失败，从而把环境、依赖、版本等约束作为硬性门禁。规则通常配置在父 POM 的 pluginManagement 中统一生效。

Enforcer 将"团队规范"代码化，防止违规进入构建。规则可在 CI 中强制，也能在本地提前发现。

• flatten 生成扁平 POM（去除构建私有配置）
• 与 CI-friendly 版本变量（${revision}）配合
• 版本收敛与消费 POM 干净化

flatten-maven-plugin 在发布时把构建 POM 扁平化，生成一个干净的、不包含构建私有配置（如 profile、插件、CI-friendly 变量）的 POM 供发布，使下游消费者不受到构建细节污染。它与 CI-friendly 版本变量（${revision}、${sha1}）配合，把占位符替换为实际版本后发布，确保消费者得到的版本是解析后的具体值。这有助于依赖版本收敛与消费者侧解析的确定性。

flatten 是 Maven 4 构建/消费者 POM 分离思想的前身，作用是让发布 POM 清晰、可复现。

• archetype 生成项目模板
• archetype-metadata.xml 与占位符
• 自定义骨架

Maven Archetype 用模板生成项目骨架，mvn archetype:generate 可选择内置或自定义 archetype，按模板填充 groupId、artifactId 等参数，生成标准目录结构、pom.xml 与基础代码。自定义 archetype 通过 archetype-metadata.xml 定义参数与文件集，用 velocity 模板中的 ${...} 占位符注入用户输入。它帮助团队统一工程初始化、减少重复搭建。

Archetype 是"项目脚手架"的 Maven 实现，保证新项目遵循团队规范与目录标准。

• deploy 目标与 distributionManagement
• 发布到私有仓库（Nexus/Artifactory）
• 发布流程与制品管理

maven-deploy-plugin 的 deploy goal 把构建产物（JAR/POM 等）上传到 distributionManagement 中配置的远程仓库地址。发布流程通常是 mvn clean deploy：先构建、测试，再上传制品到 Nexus/Artifactory 等私服，供其他项目或下游消费者解析。发布涉及版本管理（RELEASE 不可变）、制品签名与元数据，是 CI/CD 中制品管理的关键环节。

deploy 是制品进入仓库的入口。发布前应保证测试通过、制品可复现，并遵守版本策略。

• profile 与资源过滤（resource filtering）结合
• 配置模板化（application.properties 占位符）
• 配置管理的取舍（profile 数量、环境隔离）

Maven profile 配合 maven-resources-plugin 的 filtering，可在构建时把 application.properties 等资源文件中的 ${env} 占位符替换为对应 profile 的值，实现"一份模板、多环境产物"。工程取舍上：profile 能灵活按环境生成配置，但过多 profile 会降低可维护性、易造成配置漂移；更推荐把环境无关的配置放代码、环境相关配置放外部（如 K8s ConfigMap、环境变量），避免把敏感信息写进镜像。实践中需平衡 profile 数量与外部化配置。

resource filtering 是"构建期配置注入"，与"运行期配置注入"（ConfigMap/环境变量）是两种思路，后者通常更安全、更利于环境隔离。

• versions:display-dependency-updates 查看可升级版本
• versions:use-latest-versions / versions:set 更新版本
• 依赖升级的工程流程

versions-maven-plugin 提供 versions:display-dependency-updates 展示依赖可升级的新版本，versions:set 批量修改 pom 中的版本号，versions:use-latest-versions 等自动化升级。它能帮助团队发现并升级过期/有漏洞的依赖，是依赖生命周期管理的重要工具。工程实践上，升级后需跑测试与依赖分析，避免破坏性变更，并配合 Dependabot/Renovate 做自动化升级。

依赖升级是安全与维护的刚需，versions 插件提供手动与批量手段，配合 CI 验证可控制升级风险。

• compile：编译与运行可见
• test：仅测试可见
• runtime：仅运行可见

Maven 的 scope 控制依赖在哪些阶段可见：compile 是默认，编译与运行都可见；test 仅测试类路径可见（如 JUnit）；runtime 编译不需要、运行需要（如 JDBC 驱动）；provided 编译期可见、运行期由容器提供（如 Servlet API），不打入可执行 JAR；system 类似 provided 但指向本地系统路径，一般不用。正确使用 scope 能控制制品体积与传递依赖。

scope 影响传递依赖与最终制品。provided 防止把容器提供的类打进 JAR 造成冲突，runtime 避免编译期引入不必要依赖。

• 坐标唯一标识制品
• 三要素的命名规范
• 与仓库解析的关系

Maven 坐标由 groupId（组织/命名空间）、artifactId（构件名）、version（版本）唯一标识一个制品，依赖声明用它定位仓库中的制品。groupId 通常采用反向域名（如 com.example），artifactId 是模块名，version 区分版本。坐标是 Maven 解析、下载、缓存制品的依据，也是依赖管理的基础。

坐标是"制品的唯一身份证"，理解它才能正确声明依赖与避免坐标冲突。

• 私有仓库托管与分发
• 远程仓库代理与缓存
• 制品管理与团队共享

Maven 私服（如 Nexus/Artifactory）提供：托管团队私有制品（deploy 到私服）、代理远程仓库（Maven Central）并缓存，避免每个成员重复下载、加速内网构建；统一版本管理与制品审计。工程价值在于构建加速、内网可用性、制品共享与供应链安全（可限制只信任私服）。

私服是制品管理的中心，CI 与开发都从私服解析依赖，提升一致性与可追踪性。

• <mirror> 的匹配与优先级
• 镜像与私服的共同存在
• HTTPS 与证书校验

settings.xml 的 <mirror> 通过 mirrorOf 指定要镜像的仓库（如 *、central），配置镜像后对匹配仓库的请求被重定向到镜像地址。当同时配置阿里云镜像与公司私服时，应让镜像覆盖外部仓库（central），而私服作为独立仓库通过 <repositories> 声明，避免镜像把私服也绕走。HTTPS 校验策略上，应使用 HTTPS 链接并信任证书，避免 insecure 或关闭校验带来中间人风险，必要时用 -Dmaven.wagon.http.ssl.insecure 等临时规避但生产应严格校验。

镜像优先级与镜像匹配规则相关，配置不当会绕过私服或走错地址。HTTPS 校验是供应链安全的关键。

• Tekton 的 Task/Pipeline 声明式模型
• Dagger 的可编程 DAG 构建
• 云原生 CI 与 Kubernetes 的集成

Tekton 是 Kubernetes 原生的 CI 框架，用 Task、Pipeline、PipelineRun 等 CRD 声明式描述流水线，每个 step 运行在容器中，天然适配云原生与可复用；Dagger 用可编程 SDK（Go/TypeScript 等）构建 DAG 图，把流水线定义为代码，可跨平台执行。二者都强调声明式/可编程、可复用、可并行，与 Jenkins 的脚本式相比更贴近云原生。

Tekton 强调 YAML 声明与 K8s 集成，Dagger 强调代码生成 DAG 的通用性。选择取决于团队对 K8s 与可编程性的偏好。

• 构建 POM 与消费者 POM 的区分
• flattener 移除构建私有配置
• CI-friendly 版本变量（${revision}）的解析

flatten-maven-plugin 在构建时保留完整的构建 POM 用于开发，在发布（deploy/install）时生成扁平化的消费者 POM，移除 profile、插件、CI-friendly 等构建私有配置，并替换版本变量。CI-friendly 版本变量（如 ${revision}、${sha1}、${changelist}）在构建时由 Maven 解析为实际值，flatten 插件确保发布出去的 POM 中版本是具体数值而非占位符，使下游消费者能正确解析。

该机制是"构建时用完整模型、发布时用干净模型"的落地，保证消费者 POM 干净可解析。

• Shade 的 Fat JAR（依赖合并）
• Spring Boot Loader 的可执行 Jar 分层
• JDK 25 模块化（JPMS）的兼容

Maven Shade Plugin 把依赖 classes 直接合并进一个 jar，可能遇到 META-INF/services 文件冲突、签名冲突等问题，需用 transformer 处理；Spring Boot Loader 采用嵌套 Jar 结构（BOOT-INF/lib），通过自定义类加载器加载外部依赖，支持分层与优雅启动，更适合 Spring Boot。在 JDK 25 模块化下，两种方式都需注意模块系统对类路径的约束——Shade 合并后的 jar 不含模块描述符则按类路径处理，而 JPMS 下若涉及模块化依赖需保证 module-info 与类路径兼容。

Shade 适合简单可执行 Jar，Spring Boot Loader 更适合 Spring Boot 应用。模块化下需留意模块描述符与类路径的边界。

• 插件 threadSafe 属性
• 并行构建的竞态
• 共享输出目录（target）的冲突

插件的 threadSafe 声明表明该插件在多线程构建中是安全的，Maven 并行构建（-T）会基于该声明决定是否并发执行模块。若插件不 threadSafe，并行时可能产生竞态。共享输出目录（如同一 target 目录、同一临时文件）被多个模块并发写入时，会产生文件覆盖、内容损坏、构建结果不确定等竞态。并行构建应保证模块间输出目录隔离、插件线程安全。

并行构建提速的前提是正确性。threadSafe 是插件作者的契约，使用方应避免共享输出目录。

• 可复现构建（Reproducible Builds）
• 时间戳、文件顺序、环境变量的确定性
• 逐字节一致验证

可复现构建要求同一输入在相同环境下产生逐字节一致的制品。需控制：输出时间戳（如 JAR 的 project.build.outputTimestamp 固定时间）、文件顺序（JAR 内条目排序稳定）、环境变量（去除本机路径/随机数）。验证方式：构建两次，用 sha256sum 比较制品哈希，或使用 diffoscope 对比差异。Maven 支持 project.build.outputTimestamp 使 jar 时间戳确定。

可复现构建提升供应链安全与可追溯性。固定时间戳与稳定排序是关键，构建在干净环境验证。

• mvnd 的守护进程机制
• 缩短构建时间
• CI 中的使用与缓存

Maven Daemon（mvnd）是 Maven 的守护进程版本，常驻后台进程复用 JVM 与依赖解析缓存，避免每次构建冷启动，配合并行构建显著缩短构建时间。在 CI 中，mvnd 能减少重复构建的开销，但需注意守护进程的资源占用与 CI 环境隔离，以及缓存与更新策略的一致性。

mvnd 适合 CI 的重复构建场景，通过复用进程与缓存提速。但需评估资源与管理复杂度。

• Surefire/Failsafe 生成的测试报告
• 上报到 CI 的制品 / 徽章
• 报告的可读性与质量门禁

Maven 的 Surefire/Failsafe 会生成 XML/HTML 测试报告（target/surefire-reports），CI 可收集这些报告展示测试结果、失败原因与覆盖率，并作为质量门禁依据。构建报告（如 JaCoCo 覆盖率、Enforcer 规则结果）可发布到 CI 页面或制品库，供团队查看。报告发布让构建结果可观测、可追溯。

测试报告是 CI 反馈的核心，报告标准化（JUnit XML）让 CI 工具能解析并展示。

• 矩阵（matrix）在多个配置上并行构建
• 多 JDK、多 OS、多分支
• 覆盖与验证

构建矩阵（matrix）在 CI 中定义一组参数的组合（如 JDK 版本 × OS × 分支），对每个组合并行运行构建，以覆盖不同环境下的正确性。这是多环境构建的自动化形式，能发现仅特定环境才出现的兼容问题。矩阵需控制组合数量，避免构建爆炸，并合并结果判断整体通过。

矩阵提升覆盖广度，但增加资源消耗。合理选择组合（按支持的 JDK/OS）是关键。

• 构建节点 CPU/内存限制
• 并行构建的并发度
• 资源分配与构建速度

构建节点的资源（CPU/内存）决定可支撑的并行度。并行执行（如 -T 1C）按核数分配并发，但若内存不足，过多并行会触发 OOM 或 GC 抖动。合理配置：根据节点 CPU 核数设置并行线程数，限制容器内存并预留 JVM 堆，避免资源竞争导致构建变慢或失败。

资源限制直接影响并行收益，需按节点规格调优并发度，并监控构建稳定性。

• 状态徽章（build status badge）
• 质量门禁（quality gate）
• 阻断发布与反馈

构建状态徽章在 README 展示流水线当前状态（通过/失败），提供即时可见性；质量门禁是流水线中的硬性条件（如测试通过、覆盖率达标、无漏洞），不满足则阻断发布。二者结合：徽章是展示，门禁是执行，确保只有达标的产物能进入发布。

质量门禁把质量要求自动化、强制执行，是 CI/CD 保障交付质量的关键。

• Javadoc 插件的离线文档生成
• JDK 25 与 Project Leyden
• 模块描述符（module-info）与文档

Maven Javadoc Plugin 生成 API 文档（含模块信息），在 JDK 25 与 Project Leyden（常量折叠/静态镜像）背景下，javadoc 需处理模块化项目的模块描述符文档，使离线文档与模块边界一致。Project Leyden 关注静态化与可提前构建，Javadoc 应能离线生成完整模块文档，且文档与模块描述符（exports/opens）保持同步，反映真实的模块导出。

模块化项目文档需反映模块边界。协同重点是文档生成与 module-info 的一致性、离线可用性。

• 依赖校验和（checksum）证明完整性
• 制品签名证明来源与可信
• SBOM 证明成分清单

依赖校验和证明下载内容与发布者一致（完整性，未被篡改）；制品签名用私钥签名、公钥验证，证明制品来源可信（真实性）；SBOM 列出制品成分与依赖清单，证明"包含什么"（可见性）。HTTPS 只保证传输加密，不保证仓库内容本身可信，中央仓库也可能被投毒或存在恶意制品，因此供应链校验需结合校验和、签名与 SBOM 进行整体验证，而非仅依赖 HTTPS。

完整性、真实性、可见性三者互补，共同构成供应链安全。HTTPS 只解决传输层。

• GraalVM Native Image 与反射配置
• Spring Modulith 的模块化
• 最小 Maven 配置（native 插件、AOT）

在 GraalVM Native Image 下构建 Spring Modulith 应用，最小配置包括：spring-boot-maven-plugin 开启 AOT 处理（process-aot），native-maven-plugin 或 Spring Boot 的 native profile 生成原生镜像，并配置反射/资源 hint（@RegisterReflection 或 runtime-native-image.properties）以保留模块化运行所需的反射与资源。Spring Modulith 的模块验证在编译期完成，运行时需保证反射元数据完整。

Native Image 需要静态分析，反射、资源、Serialization 必须显式声明。Modulith 模块化分析在构建期完成，减少运行时开销。