跳至主要內容

Cactus li...大约 6 分钟

一、本章介绍

在 ai-agent-scaffold 脚手架工程中配置 maven-archetype-plugin，用于生成项目脚手架；同时，也支持通过命令行调用该脚手架（以 jar 形式发布）来快速创建全新的工程。

脚手架的核心价值正体现在这里：基于一套通用的基础代码与工程结构，在创建不同项目时仅需替换 工程名称、包名、版本号 等关键参数，就能自动搭建出具备相同基础能力的新项目，从而实现标准化、快速启动与一致性维护。

从直观理解来看，maven-archetype-plugin 可以视为 Maven 体系中的“项目模板生成工具”。它将可复用的工程骨架沉淀为模板，让项目初始化不再依赖手工复制与反复改配置。

如果把软件开发比作建房子，那么该插件就相当于提供了成熟的设计图与预制框架：你无需每次都从打地基、砌墙开始，只要选定合适的模板，它便会自动生成规范的目录结构，并同步完成基础配置（如 pom.xml），从而把项目启动成本降到最低。

二、流程设计

如图，从工程使用 maven 构建脚手架到使用的过程；

![AI Agent 脚手架-Maven脚手架配置.drawio](https://beauties.eu.org/blogimg/main/img1/AI Agent 脚手架-Maven脚手架配置.drawio.png)

  • 左侧部分，通过引入 Maven 官方提供的 maven-archetype-plugin 插件，对现有项目进行脚手架化处理，将当前工程封装为可复用的 Archetype 模板。这样后续创建新项目时，无需重复搭建基础结构，能够直接基于模板快速生成完整工程。

  • 中间部分是脚手架模板的发布与使用阶段。生成的 Archetype 模板既可以安装到本地 Maven 仓库供个人开发使用，也可以上传至企业私有 Maven 仓库，供团队成员统一引用和创建项目。关于私服发布与管理相关内容，后续章节会进行专门讲解。

  • 右侧部分则是脚手架的实际应用场景。开发者可以通过 Maven 命令行的方式快速生成项目，也可以在 IntelliJ IDEA 中配置 Maven Archetype 模板，通过可视化界面完成工程创建。本节将优先介绍命令行方式，帮助大家快速体验脚手架生成项目的完整流程。

三、功能实现

1. 工程结构

image-20260624165253327
image-20260624165253327

  • 首先，在 ai-agent-scaffold-lite 工程的 pom.xml 文件中，于 build 配置节点下增加 maven-archetype-plugin 插件。与此同时，可以配置脚手架生成后的输出目录以及 Archetype 名称。如果不进行相关配置，Maven 会按照默认规则将生成结果输出到当前工程的 target 目录下，并使用默认命名。

  • 完成插件配置后，在 IntelliJ IDEA 右侧的 Maven 面板中，展开 Plugins 节点，即可看到 archetype:create-from-project 命令。执行该命令后，便能够基于当前项目生成对应的 Maven Archetype 脚手架模板。不过需要注意的是，Maven 默认生成的模板还需要进行部分调整和优化，否则在后续创建项目时可能无法正常使用。

  • 最后是脚手架的实际验证过程。课程中已提供 create-project.sh 示例脚本，可以直接复制其中的命令执行，快速完成基于脚手架的新项目创建。如果使用的是 Windows 环境，建议在 PowerShell 中执行相关命令，以确保脚本能够正常运行。

相关命令介绍

Goal（命令）作用使用场景示例
archetype:crawl扫描指定目录，查找所有 Archetype，并生成 Archetype Catalog（目录索引）。当公司维护多个自定义 Archetype 时，用于生成 catalog。mvn archetype:crawl
archetype:create-from-project将现有 Maven 项目转换成一个 Archetype（项目模板）。想把自己的项目做成模板供别人使用。mvn archetype:create-from-project
archetype:generate根据指定 Archetype 创建一个新的 Maven 项目。最常用。创建 SpringBoot、Java、Web 等新项目。mvn archetype:generate
archetype:help查看 Maven Archetype Plugin 的帮助信息。查询插件参数和 Goal 的用法。mvn archetype:help -Ddetail=true
archetype:integration-test对自定义 Archetype 进行集成测试，验证模板生成的项目是否正确。开发自定义 Archetype 时测试模板。mvn archetype:integration-test
archetype:jar将 Archetype 打包成一个 JAR 文件，以便发布到 Maven 仓库。制作模板发布给团队或公司。mvn archetype:jar
archetype:update-local-catalog更新本地 Maven 的 Archetype Catalog，使新模板可以在本地被识别。新安装或生成 Archetype 后刷新本地目录。mvn archetype:update-local-catalog

2. 生成框架

image-20260624172439364
image-20260624172439364

  • 当使用 maven-archetype-plugin 的 archetype:create-from-project 命令后，即可基于现有工程生成对应的 Maven 脚手架。生成的脚手架会保留原项目的整体结构和功能实现，同时将部分目录和文件参数化，支持后续创建项目时进行动态替换。

  • 需要注意的是，在生成的 -app 模块 pom.xml 文件中，mainClass 配置默认不会自动替换为带有 ${groupId} 占位符的形式，因此需要手动调整。否则，基于该脚手架创建的新项目在启动时还需额外修改配置，无法直接运行。

  • 此外，当打开生成后的 ai-agent-scaffold-lite-archetype 工程时，可以直接通过 IntelliJ IDEA 的 Maven 面板执行 install 操作，将脚手架打包并安装到本地仓库。后续创建新项目时，实际上就是基于这个安装后的 Archetype Jar 包来完成工程生成的。

3. 使用框架

3.1 命令使用

# 找个空的文件夹进行运行
mvn archetype:generate -X -DarchetypeCatalog=local
image-20260625093526041
image-20260625093526041

之后，如图，要输入你的信息。如 groupId = com.fastn.ai、artifactId =ai-fastn 这个过程，就类似于你使用 IntelliJ IDEA 创建项目的过程。

image-20260625102435608
image-20260625102435608

执行完成后，你就可以获得到一个对应的项目，现在可以使用 IntelliJ IDEA 打开这个项目。如果没有被加载成 Maven 工程，可以删掉 .idea 在重新用 IntelliJ IDEA 打开即可。

image-20260625105815872
image-20260625105815872

最后就可以启动运行项目了。

3.2 配置使用

3.2.1 添加框架
image-20260625110347154
image-20260625110347154
      <groupId>cn.cactusli.ai</groupId>
      <artifactId>ai-agent-scaffold-lite-archetype</artifactId>
      <version>1.0</version>
      <description>ai-agent-scaffold-lite</description>
    </archetype>

在 IntelliJ IDEA 配置脚手架。不过这个是一次性的，配置后没有保存。

3.2.2 使用框架
image-20260625110614926
image-20260625110614926

添加创建项目的信息。

3.2.3 创建项目
image-20260625111231711
image-20260625111231711

执行创建项目即可。

默认页脚
Copyright © 2018-2026 Cactus li