npm - @llryiop/avatar-boot-cli - Versions diffs - 1.0.0 - Mend

@llryiop/avatar-boot-cli 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (77) hide show

package/templates/.claude/rules/coding-standards.md ADDED Viewed

@@ -0,0 +1,56 @@
+# 编码规范
+> 规则类型: 🔴 强制执行
+> 更新频率: 中（团队规范调整时更新）
+> 相关规则: [architecture-redlines.md](architecture-redlines.md) | [git-commit.md](git-commit.md) | [version.md](version.md)
+---
+## Java 代码规范
+### 命名规范
+- 类名: PascalCase（如 `UserController`）
+- 方法名: camelCase（如 `getUserById`）
+- 常量: UPPER_SNAKE_CASE（如 `MAX_RETRY_COUNT`）
+- 包名: 全小写，使用点分隔（如 `com.iflytek.avatar.login`）
+### 代码长度限制
+- 方法长度不超过 50 行
+- 类文件长度不超过 500 行，超过需拆分
+- 单行代码长度不超过 120 字符
+### 注释规范
+- 公共 API 必须有 Javadoc 注释
+- 复杂业务逻辑必须有行内注释
+- 禁止无意义的注释（如 `// 获取用户` 在 `getUser()` 方法上）
+### 异常处理
+- 使用 `@RestControllerAdvice` 统一处理异常
+- 业务异常继承自自定义 `BusinessException`
+- 禁止捕获异常后不处理（空 catch 块）
+### 日志规范
+- 使用 SLF4J + Logback
+- 日志级别: ERROR（错误）、WARN（警告）、INFO（关键信息）、DEBUG（调试信息）
+- 禁止使用 `System.out.println()`
+---
+## Maven 配置规范
+> **完整规则详见**: [version.md](version.md)
+---
+## 提交前检查
+- [ ] 是否编写了单元测试
+- [ ] 测试覆盖率是否达标
+- [ ] 是否所有测试都通过
+- [ ] 是否有 `System.out.println()`
+- [ ] 是否有注释掉的大段代码

package/templates/.claude/rules/git-commit.md ADDED Viewed

@@ -0,0 +1,59 @@
+# Git 提交规范
+> 规则类型: 🔴 强制执行
+> 更新频率: 低
+> 相关规则: [coding-standards.md](coding-standards.md)
+---
+## Commit Message 格式
+```
+<type>(<scope>): <subject>
+<body>
+<footer>
+```
+## Type 类型
+| Type | 说明 |
+|------|------|
+| `feat` | 新功能 |
+| `fix` | 修复 bug |
+| `refactor` | 重构（不改变功能） |
+| `perf` | 性能优化 |
+| `style` | 代码格式调整（不影响逻辑） |
+| `test` | 测试相关 |
+| `docs` | 文档更新 |
+| `chore` | 构建/工具/依赖更新 |
+| `revert` | 回滚提交 |
+## 示例
+```
+feat(login): 添加手机号登录功能
+- 新增手机号验证码发送接口
+- 新增手机号登录接口
+- 集成短信服务
+Closes #123
+```
+```
+fix(user): 修复用户信息更新失败的问题
+用户更新时未正确处理空值字段，导致更新失败
+Fixes #456
+```
+## 提交规则
+- 每次提交必须附带有意义的描述
+- 一次提交只做一件事
+- 提交前必须通过本地测试
+- 禁止提交包含 `System.out.println()` 的代码
+- 禁止提交注释掉的大段代码

package/templates/.claude/rules/layered-architecture.md ADDED Viewed

@@ -0,0 +1,201 @@
+# Spring Boot 分层架构规范
+> 规则类型: 🔴 强制执行
+> 更新频率: 低（架构调整时更新）
+> 相关规则: [architecture-redlines.md](architecture-redlines.md) | [coding-standards.md](coding-standards.md)
+---
+## Controller 层职责
+Controller 层**仅负责**参数校验和 Result 封装，禁止包含业务逻辑。
+### ✅ 正确示例
+```java
+@RestController
+@RequestMapping("/api/user")
+@RequiredArgsConstructor
+public class UserController {
+    private final UserService userService;
+    @GetMapping("/{id}")
+    public Result<UserResponse> getById(@PathVariable Long id) {
+        return Result.success(userService.getById(id));
+    }
+    @PostMapping
+    public Result<Void> create(@RequestBody @Validated UserCreateRequest request) {
+        userService.create(request);
+        return Result.success();
+    }
+    @PutMapping("/{id}")
+    public Result<Void> update(@PathVariable Long id,
+                               @RequestBody @Validated UserUpdateRequest request) {
+        userService.update(id, request);
+        return Result.success();
+    }
+    @DeleteMapping("/{id}")
+    public Result<Void> delete(@PathVariable Long id) {
+        userService.delete(id);
+        return Result.success();
+    }
+    @GetMapping("/page")
+    public Result<IPage<UserResponse>> page(UserPageRequest request) {
+        return Result.success(userService.page(request));
+    }
+}
+```
+### ❌ 错误示例
+```java
+@RestController
+public class UserController {
+    @Autowired
+    private UserMapper userMapper; // ❌ Controller 直接依赖 Mapper
+    @GetMapping("/api/user/{id}")
+    public UserEntity getById(@PathVariable Long id) { // ❌ 直接返回 Entity，未用 Result<T>
+        UserEntity user = userMapper.selectById(id); // ❌ Controller 包含数据访问逻辑
+        if (user == null) {
+            throw new RuntimeException("用户不存在"); // ❌ 应使用 BusinessException
+        }
+        return user;
+    }
+}
+```
+---
+## Service 层职责
+Service 层负责**业务逻辑编排和事务管理**。
+### 规范要点
+- Service 接口定义在 `service/` 包下，实现类使用 `Impl` 后缀
+- 事务注解 `@Transactional` 只加在 Service 实现类方法上
+- 写操作必须加 `@Transactional(rollbackFor = Exception.class)`
+- 只读操作加 `@Transactional(readOnly = true)`
+- Service 之间可以互相调用，但禁止循环依赖
+### ✅ 正确示例
+```java
+public interface UserService extends IService<UserEntity> {
+    UserResponse getById(Long id);
+    void create(UserCreateRequest request);
+    IPage<UserResponse> page(UserPageRequest request);
+}
+@Service
+@RequiredArgsConstructor
+public class UserServiceImpl extends ServiceImpl<UserMapper, UserEntity>
+        implements UserService {
+    @Override
+    @Transactional(readOnly = true)
+    public UserResponse getById(Long id) {
+        UserEntity entity = getBaseMapper().selectById(id);
+        if (entity == null) {
+            throw new BusinessException("用户不存在");
+        }
+        return convertToResponse(entity);
+    }
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public void create(UserCreateRequest request) {
+        UserEntity entity = convertToEntity(request);
+        save(entity);
+    }
+}
+```
+### ❌ 错误示例
+```java
+@Service
+public class UserServiceImpl {
+    @Transactional // ❌ 缺少 rollbackFor，默认只回滚 RuntimeException
+    public void create(UserCreateRequest request) {
+        // ...
+    }
+    public Result<UserResponse> getById(Long id) { // ❌ Service 不应返回 Result，那是 Controller 的职责
+        // ...
+    }
+}
+```
+---
+## Mapper（DAO）层职责
+Mapper 层负责**纯数据访问**，禁止包含业务逻辑。
+### 规范要点
+- Mapper 接口继承 `BaseMapper<T>`，放在 `dao/` 包下
+- 数据库实体类放在 `dao/beans/` 包下
+- 复杂 SQL 使用 XML 映射文件或 `@Select` 等注解
+- 禁止在 Mapper 中编写业务判断逻辑
+### ✅ 正确示例
+```java
+@Mapper
+public interface UserMapper extends BaseMapper<UserEntity> {
+    @Select("SELECT * FROM t_user WHERE email = #{email} AND is_deleted = 0")
+    UserEntity selectByEmail(@Param("email") String email);
+}
+```
+---
+## Entity / DTO / VO 严格区分
+> 完整的模块包结构详见 [architecture-redlines.md](architecture-redlines.md#目录组织规范)
+| 类型 | 所在模块 | 包路径 | 用途 |
+|------|---------|--------|------|
+| Entity (DO/PO) | Service 模块 | `dao/beans/` | 数据库表映射，仅在 Mapper 和 Service 层流转 |
+| Request DTO | API 模块 | `entity/request/` | 接收前端/调用方请求参数 |
+| Response DTO | API 模块 | `entity/response/` | 返回给前端/调用方的数据 |
+### 🔴 跨层依赖规则
+```
+Controller  →  Service  →  Mapper
+    ↓             ↓           ↓
+Request DTO   Entity      Entity
+Response DTO  Request DTO
+              Response DTO
+```
+- ❌ Controller 禁止直接使用 Entity
+- ❌ Entity 禁止出现在 API 模块中
+- ❌ Mapper 层禁止使用 DTO
+- ✅ Service 层负责 Entity ↔ DTO 的转换
+---
+## 分层检查清单
+- [ ] Controller 是否只做参数校验和 Result 封装
+- [ ] Controller 是否返回 `Result<T>` 类型
+- [ ] Service 写操作是否加了 `@Transactional(rollbackFor = Exception.class)`
+- [ ] Service 只读操作是否加了 `@Transactional(readOnly = true)`
+- [ ] Entity 是否只在 Service 和 Mapper 层使用
+- [ ] DTO 和 Entity 之间是否在 Service 层做了转换
+- [ ] Mapper 是否继承了 `BaseMapper<T>`
+- [ ] 是否存在 Controller 直接调用 Mapper 的情况
+- [ ] 是否存在 Service 返回 `Result<T>` 的情况

package/templates/.claude/rules/mybatis-plus.md ADDED Viewed

@@ -0,0 +1,263 @@
+# MyBatis Plus 使用规范
+> 规则类型: 🔴 强制执行
+> 更新频率: 低（框架升级时更新）
+> 相关规则: [version.md](version.md)（MyBatis Plus 3.5.15）| [layered-architecture.md](layered-architecture.md)
+---
+## Entity 注解规范
+### 基础 Entity 模板
+```java
+@Data
+@TableName("t_user")
+public class UserEntity {
+    @TableId(type = IdType.ASSIGN_ID)
+    private Long id;
+    @TableField("username")
+    private String username;
+    @TableField("email")
+    private String email;
+    @TableField("status")
+    private Integer status;
+    @TableField(fill = FieldFill.INSERT)
+    private LocalDateTime createTime;
+    @TableField(fill = FieldFill.INSERT_UPDATE)
+    private LocalDateTime updateTime;
+    @TableLogic
+    @TableField("is_deleted")
+    private Integer isDeleted;
+}
+```
+### 注解说明
+| 注解 | 用途 | 规范 |
+|------|------|------|
+| `@TableName` | 表名映射 | 🔴 必须显式指定，使用 `t_` 前缀 |
+| `@TableId` | 主键 | 🔴 必须指定，推荐 `IdType.ASSIGN_ID`（雪花算法） |
+| `@TableField` | 字段映射 | 🟡 字段名与列名不一致时必须指定 |
+| `@TableLogic` | 逻辑删除 | 🔴 必须使用逻辑删除，字段名 `is_deleted` |
+| `FieldFill` | 自动填充 | 🔴 `createTime` 和 `updateTime` 必须自动填充 |
+### ❌ 错误的 Entity 写法
+```java
+@Data
+public class User { // ❌ 缺少 @TableName
+    private Long id; // ❌ 缺少 @TableId
+    private Date createTime; // ❌ 使用 Date 而非 LocalDateTime，缺少自动填充
+    // ❌ 缺少 isDeleted 逻辑删除字段
+}
+```
+---
+## 自动填充配置
+```java
+@Component
+public class AvatarMetaObjectHandler implements MetaObjectHandler {
+    @Override
+    public void insertFill(MetaObject metaObject) {
+        this.strictInsertFill(metaObject, "createTime", LocalDateTime::now, LocalDateTime.class);
+        this.strictInsertFill(metaObject, "updateTime", LocalDateTime::now, LocalDateTime.class);
+    }
+    @Override
+    public void updateFill(MetaObject metaObject) {
+        this.strictUpdateFill(metaObject, "updateTime", LocalDateTime::now, LocalDateTime.class);
+    }
+}
+```
+---
+## Mapper 规范
+```java
+@Mapper
+public interface UserMapper extends BaseMapper<UserEntity> {
+    // 简单 CRUD 直接继承 BaseMapper，无需手写
+    // 复杂查询使用 XML 或注解
+}
+```
+- 🔴 必须继承 `BaseMapper<T>`
+- 🔴 必须添加 `@Mapper` 注解（或在启动类加 `@MapperScan`）
+---
+## Service 规范
+### ✅ 正确：继承 IService / ServiceImpl
+```java
+public interface UserService extends IService<UserEntity> {
+    // 自定义业务方法
+    UserResponse getUserDetail(Long id);
+}
+@Service
+public class UserServiceImpl extends ServiceImpl<UserMapper, UserEntity>
+        implements UserService {
+    @Override
+    public UserResponse getUserDetail(Long id) {
+        UserEntity entity = getById(id);
+        // 转换为 DTO ...
+        return response;
+    }
+}
+```
+### ❌ 错误：不继承 IService
+```java
+@Service
+public class UserService { // ❌ 未继承 IService，无法使用内置 CRUD 方法
+    @Autowired
+    private UserMapper userMapper;
+    public UserEntity getById(Long id) {
+        return userMapper.selectById(id); // ❌ 手动调用 Mapper，重复造轮子
+    }
+}
+```
+---
+## 查询规范
+### 🔴 LambdaQueryWrapper 优先
+```java
+// ✅ 正确：使用 LambdaQueryWrapper，类型安全
+LambdaQueryWrapper<UserEntity> wrapper = new LambdaQueryWrapper<>();
+wrapper.eq(UserEntity::getStatus, 1)
+       .like(StringUtils.isNotBlank(name), UserEntity::getUsername, name)
+       .orderByDesc(UserEntity::getCreateTime);
+List<UserEntity> users = userMapper.selectList(wrapper);
+// ❌ 错误：使用 QueryWrapper 字符串硬编码
+QueryWrapper<UserEntity> wrapper = new QueryWrapper<>();
+wrapper.eq("status", 1); // ❌ 字段名硬编码，重构不友好
+```
+### 🔴 分页查询必须使用 Page<T>
+```java
+// ✅ 正确：使用 MyBatis Plus 分页
+public IPage<UserEntity> pageQuery(int current, int size) {
+    Page<UserEntity> page = new Page<>(current, size);
+    LambdaQueryWrapper<UserEntity> wrapper = new LambdaQueryWrapper<>();
+    wrapper.eq(UserEntity::getStatus, 1);
+    return userMapper.selectPage(page, wrapper);
+}
+// ❌ 错误：手写 LIMIT 分页
+@Select("SELECT * FROM t_user WHERE status = 1 LIMIT #{offset}, #{size}")
+List<UserEntity> pageQuery(@Param("offset") int offset, @Param("size") int size);
+```
+### 分页插件配置
+```java
+@Configuration
+public class MyBatisPlusConfig {
+    @Bean
+    public MybatisPlusInterceptor mybatisPlusInterceptor() {
+        MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
+        interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
+        return interceptor;
+    }
+}
+```
+---
+## 逻辑删除配置
+```yaml
+mybatis-plus:
+  global-config:
+    db-config:
+      logic-delete-field: isDeleted
+      logic-delete-value: 1
+      logic-not-delete-value: 0
+```
+配置后，所有继承 `BaseMapper` 的查询/更新/删除方法自动追加逻辑删除条件。
+---
+## 性能反模式
+### ❌ N+1 查询问题
+```java
+// ❌ 错误：循环查询数据库
+List<OrderEntity> orders = orderMapper.selectList(null);
+for (OrderEntity order : orders) {
+    UserEntity user = userMapper.selectById(order.getUserId()); // N 次查询！
+}
+// ✅ 正确：批量查询
+List<OrderEntity> orders = orderMapper.selectList(null);
+Set<Long> userIds = orders.stream().map(OrderEntity::getUserId).collect(Collectors.toSet());
+List<UserEntity> users = userMapper.selectBatchIds(userIds); // 1 次查询
+Map<Long, UserEntity> userMap = users.stream().collect(Collectors.toMap(UserEntity::getId, Function.identity()));
+```
+### ❌ 无 limit 的 selectList
+```java
+// ❌ 危险：无条件全表查询，数据量大时 OOM
+List<UserEntity> allUsers = userMapper.selectList(null);
+// ✅ 正确：始终带条件或分页
+Page<UserEntity> page = new Page<>(1, 100);
+IPage<UserEntity> users = userMapper.selectPage(page, wrapper);
+```
+### ❌ 在循环中执行数据库操作
+```java
+// ❌ 错误：循环插入
+for (UserEntity user : userList) {
+    userMapper.insert(user);
+}
+// ✅ 正确：批量操作
+userService.saveBatch(userList);
+// 或指定批次大小
+userService.saveBatch(userList, 500);
+```
+---
+## MyBatis Plus 使用检查清单
+- [ ] Entity 是否标注 `@TableName` 并使用 `t_` 前缀
+- [ ] 主键是否使用 `@TableId(type = IdType.ASSIGN_ID)`
+- [ ] 是否包含 `createTime`、`updateTime` 自动填充字段
+- [ ] 是否包含 `isDeleted` 逻辑删除字段
+- [ ] Mapper 是否继承 `BaseMapper<T>`
+- [ ] Service 是否继承 `IService<T>` / `ServiceImpl<M, T>`
+- [ ] 查询是否使用 `LambdaQueryWrapper` 而非 `QueryWrapper`
+- [ ] 分页是否使用 `Page<T>` 而非手写 LIMIT
+- [ ] 是否存在 N+1 查询问题
+- [ ] 是否存在无条件的 `selectList(null)` 全表查询
+- [ ] 批量操作是否使用 `saveBatch` / `updateBatchById`
+- [ ] 时间字段是否使用 `LocalDateTime` 而非 `Date`

package/templates/.claude/rules/tech-stack.md ADDED Viewed

@@ -0,0 +1,41 @@
+# 技术栈约束
+> 规则类型: 🔴 强制执行
+> 更新频率: 低（框架升级时更新）
+> 相关规则: [architecture-redlines.md](architecture-redlines.md) | [version.md](version.md)
+---
+## 必须使用的技术
+| 模块 | 技术栈 | 版本 |
+|------|--------|------|
+| Java | OpenJDK | 21 |
+| 构建工具 | Maven | 3.8.6+ |
+| 框架核心 | Spring Boot | 3.5.3 |
+| 微服务框架 | Spring Cloud | 2025.0.0 |
+| 服务治理 | Spring Cloud Alibaba | 2023.0.3.2 |
+| 注册中心 | Nacos | 通过 avatar-boot-starter-nacos |
+| 服务调用 | OpenFeign | 通过 avatar-boot-starter-feign |
+| 数据库 | MySQL | 通过 avatar-boot-starter-mysql |
+| 缓存 | Redis | 通过 avatar-boot-starter-redis |
+| ORM | MyBatis Plus | 3.5.15 |
+| 工具库 | Hutool | 5.8.34 |
+| JSON | Fastjson2 | 2.0.54 |
+---
+## 核心原则
+### 🔴 必须使用 Avatar Boot 封装组件
+- ❌ **禁止**直接引用 Spring Boot、Spring Cloud 原生 starter
+- ✅ **必须**使用 Avatar Boot 封装的 starter 组件
+- ✅ **必须**配置 iFlytek Maven 仓库
+### 🔴 必须使用 Jakarta 命名空间
+- ❌ `javax.*` 已废弃
+- ✅ `jakarta.*` 是正确的命名空间
+> **详细配置、示例和版本信息请参考**: [version.md](version.md)