Avatar Boot CLI 操作手册

简介

avatar-boot-cli 是 AvatarBoot Java 微服务项目的脚手架工具。通过交互式命令行，快速创建一个标准化的 AvatarBoot 微服务项目，包含 API + Service 双模块结构、Maven 配置、环境配置及可选的 AI Agent 配置。

环境要求

| 工具 | 版本要求 | 用途 | |------|---------|------| | Node.js | >= 18 | 运行 CLI 工具 | | Git | >= 2.0 | 克隆模板仓库 | | Maven | >= 3.8.6 | 构建生成的项目 | | JDK | 21 | 编译运行项目 |

安装与使用

方式一：npx 直接运行（推荐）

无需安装，直接运行：

npx avatar-boot-cli init

或指定项目名：

npx avatar-boot-cli init my-order-service

方式二：全局安装

npm install -g avatar-boot-cli
avatar-boot-cli init

方式三：本地运行（开发调试）

git clone <本仓库地址>
cd npx
npm install
node bin/cli.js init

交互式配置说明

运行 init 命令后，工具会依次提示以下配置项。所有配置都可以直接回车跳过，使用默认值。

1. 项目名称

? 项目名称: (my-avatar-service)

• 默认值： my-avatar-service
• 命名规则： 小写字母开头，只能包含小写字母、数字和连字符
• 示例： avatar-order-service、avatar-user-center
• 影响范围：
  • 项目根目录名
  • Maven artifactId
  • 子模块目录名（{项目名}-api、{项目名}-service）
  • spring.application.name

2. Maven groupId

? Maven groupId: (com.iflytek.avatar)

• 默认值： com.iflytek.avatar
• 命名规则： 小写字母开头，只能包含小写字母、数字和点号
• 示例： com.iflytek.avatar.order
• 影响范围：
  • pom.xml 中的 <groupId>
  • Java 源码的 package 声明和 import 路径
  • 源码目录结构（如 src/main/java/com/iflytek/avatar/order/）

3. Avatar Boot 版本

? Avatar Boot 版本: (Use arrow keys)
❯ v1.0.0
  v1.1.0
  latest (main branch)

• 默认值： 列表中第一个（最新 tag）
• 说明： 工具会自动从 Git 仓库获取可用的版本 tag。如果无法连接仓库，则只显示 latest (main branch) 选项
• 影响范围： 克隆的模板版本

4. Starter 模块选择

? 选择 Starter 模块: (Press <space> to select, <a> to toggle all)
 ◉ avatar-boot-starter-web (Web 基础设施)
 ◉ avatar-boot-starter-nacos (服务注册与配置)
 ◯ avatar-boot-starter-feign (服务间调用)
 ◯ avatar-boot-starter-mysql (MySQL 数据库)
 ◯ avatar-boot-starter-redis (Redis 缓存)
 ◯ avatar-boot-starter-kafka (Kafka 消息队列)
 ◯ avatar-boot-starter-rocketmq (RocketMQ 消息队列)
 ◯ avatar-boot-starter-job (XXL-Job 任务调度)
 ◯ avatar-boot-starter-oss (对象存储)

• 默认选中： web、nacos
• 操作方式：
  • 空格键 选中/取消单个模块
  • a 全选/全不选
  • 回车 确认选择
• 影响范围： service 模块 pom.xml 中的依赖（选中的取消注释，未选中的注释掉）

各 Starter 功能说明：

| Starter | 说明 | 典型场景 | |---------|------|---------| | web | Web 基础设施，含统一返回格式、全局异常处理 | 所有 Web 服务必选 | | nacos | Nacos 服务注册与配置中心 | 微服务环境必选 | | feign | 基于 OpenFeign 的服务间调用 | 需要调用其他微服务 | | mysql | MySQL 数据库 + MyBatis Plus | 需要持久化存储 | | redis | Redis 缓存 | 需要缓存、分布式锁 | | kafka | Kafka 消息队列 | 异步消息、事件驱动 | | rocketmq | RocketMQ 消息队列 | 异步消息（阿里系） | | job | XXL-Job 分布式任务调度 | 定时任务、批处理 | | oss | 对象存储 | 文件上传下载 |

5. 示例代码

? 是否生成示例代码 (login 模块): (Y/n)

• 默认值： 是（Y）
• 说明： 生成一个完整的 login 示例模块，包含 Controller、Service、Mapper、DTO、Feign Client 等标准分层代码，可作为业务开发参考
• 影响范围：
  • {项目名}-api/src/main/java/.../login/ — Feign 接口、DTO、常量、枚举、异常
  • {项目名}-service/src/main/java/.../login/ — Controller、Service、Mapper、Entity、Converter、Utils

6. Nacos 地址（选了 nacos 模块时出现）

? Nacos 地址: (127.0.0.1:8848)

• 默认值： 127.0.0.1:8848
• 示例： 172.29.242.247:8848
• 影响范围： application-dev.yaml 中的 spring.cloud.nacos.server-addr

7. 数据库地址（选了 mysql 模块时出现）

? 数据库地址 (host:port/dbname): (localhost:3306/avatar)

• 默认值： localhost:3306/avatar
• 示例： 192.168.1.100:3306/order_db
• 影响范围： application-dev.yaml 中的数据库连接配置

8. AI Agent 配置

? 是否生成 .claude/ AI Agent 配置: (Y/n)

• 默认值： 是（Y）
• 说明： 生成 .claude/ 目录和 CLAUDE.md，包含项目规则（架构规范、编码标准、技术栈约束等）和技能定义，让 Claude 等 AI 编程助手更好地理解项目
• 影响范围：
  • .claude/rules/ — 8 个规则文件（架构红线、编码规范、分层架构等）
  • .claude/skills/ — 24 个技能定义（模块创建、CRUD 生成、API 设计等）
  • CLAUDE.md — 项目总览文档

9. 服务端口

? 服务端口: (8888)

• 默认值： 8888
• 影响范围： application.yaml 中的 server.port

完整使用示例

示例 1：快速创建（全部默认值）

npx avatar-boot-cli init my-order-service
# 然后一路回车

生成结果：

my-order-service/
├── my-order-service-api/          # API 模块
│   ├── pom.xml
│   └── src/main/java/com/iflytek/avatar/
│       └── login/                 # 示例模块
│           ├── api/               # Feign 接口
│           ├── dto/               # 请求/响应对象
│           ├── constant/          # 常量
│           ├── enums/             # 枚举
│           └── exception/         # 自定义异常
├── my-order-service-service/      # Service 模块
│   ├── pom.xml
│   └── src/main/java/com/iflytek/avatar/
│       ├── Application.java       # 启动类
│       └── login/                 # 示例模块
│           ├── controller/        # REST 接口
│           ├── service/           # 业务逻辑
│           ├── repository/        # 数据访问 (Mapper + Entity)
│           ├── converter/         # 对象转换
│           ├── config/            # 模块配置
│           ├── feign/             # Feign 调用
│           └── utils/             # 工具类
├── .claude/                       # AI Agent 配置
├── CLAUDE.md
└── pom.xml                        # 父 POM

示例 2：自定义配置

npx avatar-boot-cli init

? 项目名称: avatar-user-center
? Maven groupId: com.iflytek.avatar.user
? Avatar Boot 版本: v1.0.0
? 选择 Starter 模块: web, nacos, feign, mysql, redis
? 是否生成示例代码 (login 模块): No
? Nacos 地址: 172.29.242.247:8848
? 数据库地址 (host:port/dbname): 172.29.242.247:3306/user_center
? 是否生成 .claude/ AI Agent 配置: Yes
? 服务端口: 9090

项目创建后

1. 进入项目目录

cd my-order-service

2. 初始化 Git 仓库

git init
git add .
git commit -m "init: 初始化项目"

3. 编译项目

mvn clean compile

4. 本地启动（需要 Nacos）

cd my-order-service-service
mvn spring-boot:run -Dspring-boot.run.profiles=dev

5. 创建新业务模块

参考 login 示例模块的结构，在对应目录下创建新的业务包：

# API 模块中创建
{项目名}-api/src/main/java/{groupId路径}/{模块名}/
├── api/                    # Feign 接口
├── dto/request/            # 请求 DTO
├── dto/response/           # 响应 DTO
├── constant/               # 常量
├── enums/                  # 枚举
└── exception/              # 异常

# Service 模块中创建
{项目名}-service/src/main/java/{groupId路径}/{模块名}/
├── controller/             # Controller
├── service/                # Service 接口
├── service/impl/           # Service 实现
├── repository/mapper/      # MyBatis Mapper
├── repository/entity/      # 数据库实体
├── converter/              # 对象转换器
└── config/                 # 配置类

常见问题

Q: 克隆模板失败？

检查网络连接是否能访问 code.iflytek.com，确保 Git 已配置正确的凭据。

Q: 目录已存在？

工具不会覆盖已有目录。删除同名目录后重新运行，或使用其他项目名。

Q: 版本列表为空？

如果无法连接 Git 仓库获取 tag，工具会显示 latest (main branch) 选项，使用主分支最新代码。

Q: 如何添加新的 Starter 依赖？

项目创建后，手动编辑 {项目名}-service/pom.xml，取消注释或添加对应的 avatar-boot-starter-* 依赖即可。