@llryiop/avatar-boot-cli 1.0.0

package/templates/.claude/skills/crud-generator/SKILL.md

@@ -0,0 +1,824 @@
+---
+name: crud-generator
+description: |
+  根据数据库表 DDL 或业务描述，自动生成完整的 CRUD 代码，包括 Entity、Mapper、Service、Controller、DTO 和 Feign API。
+  触发词: CRUD, generate code, 增删改查, 代码生成, create entity, generate CRUD, 生成代码, scaffold
+---
+
+# CRUD 代码生成技能 (CRUD Generator Skill)
+
+## 概述
+
+本技能根据数据库表 DDL 或表结构描述，自动生成符合 Avatar Boot 项目规范的完整 CRUD 代码。生成的代码遵循 API + Service 双模块架构，采用垂直功能组织方式。
+
+> **与 api-service-module-creator 的区别**：本 Skill 专注于**从 DDL 快速生成单个功能的 CRUD 代码**（Entity/Mapper/Service/Controller/DTO）。如需**创建完整的 API + Service 双模块项目结构**（包括 pom.xml、包结构、配置文件），请使用 [api-service-module-creator](../api-service-module-creator/) Skill。
+
+---
+
+## 输入要求
+
+### 方式一：提供表 DDL
+
+```sql
+CREATE TABLE t_user (
+    id BIGINT NOT NULL COMMENT '主键ID',
+    username VARCHAR(64) NOT NULL COMMENT '用户名',
+    email VARCHAR(128) DEFAULT NULL COMMENT '邮箱',
+    phone VARCHAR(20) DEFAULT NULL COMMENT '手机号',
+    status TINYINT NOT NULL DEFAULT 1 COMMENT '状态：0-禁用 1-启用',
+    create_time DATETIME NOT NULL COMMENT '创建时间',
+    update_time DATETIME NOT NULL COMMENT '更新时间',
+    is_deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除：0-未删除 1-已删除',
+    PRIMARY KEY (id),
+    UNIQUE KEY uk_username (username),
+    KEY idx_email (email)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户表';
+```
+
+### 方式二：提供表结构描述
+
+```
+表名: t_user (用户表)
+字段:
+- username: 用户名, VARCHAR(64), 必填, 唯一
+- email: 邮箱, VARCHAR(128), 可选
+- phone: 手机号, VARCHAR(20), 可选
+- status: 状态, TINYINT, 必填, 默认1 (0-禁用 1-启用)
+```
+
+> 注意：`id`, `create_time`, `update_time`, `is_deleted` 为必需字段，无需在描述中指定，会自动添加。
+
+---
+
+## 输出文件列表
+
+以 `t_user` 表为例，生成的文件按垂直功能组织：
+
+### API 模块 (`avatar-api`)
+
+| 文件 | 路径 |
+|------|------|
+| Request DTO | `com/iflytek/avatar/entity/request/UserCreateRequest.java` |
+| Request DTO | `com/iflytek/avatar/entity/request/UserUpdateRequest.java` |
+| Request DTO | `com/iflytek/avatar/entity/request/UserPageRequest.java` |
+| Response DTO | `com/iflytek/avatar/entity/response/UserResponse.java` |
+| Feign API | `com/iflytek/avatar/api/UserApi.java` |
+
+### Service 模块 (`avatar-service`)
+
+| 文件 | 路径 |
+|------|------|
+| Entity | `com/iflytek/avatar/dao/beans/User.java` |
+| Mapper | `com/iflytek/avatar/dao/mapper/UserMapper.java` |
+| Service 接口 | `com/iflytek/avatar/service/UserService.java` |
+| Service 实现 | `com/iflytek/avatar/service/impl/UserServiceImpl.java` |
+| Controller | `com/iflytek/avatar/controller/UserController.java` |
+
+---
+
+## 代码模板
+
+### 1. Entity — `dao/beans/User.java`
+
+```java
+package com.iflytek.avatar.dao.beans;
+
+import com.baomidou.mybatisplus.annotation.*;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+/**
+ * 用户表实体
+ *
+ * @author avatar-generator
+ */
+@Data
+@TableName("t_user")
+public class User {
+
+    /**
+     * 主键ID
+     */
+    @TableId(type = IdType.ASSIGN_ID)
+    private Long id;
+
+    /**
+     * 用户名
+     */
+    private String username;
+
+    /**
+     * 邮箱
+     */
+    private String email;
+
+    /**
+     * 手机号
+     */
+    private String phone;
+
+    /**
+     * 状态：0-禁用 1-启用
+     */
+    private Integer status;
+
+    /**
+     * 创建时间
+     */
+    @TableField(fill = FieldFill.INSERT)
+    private LocalDateTime createTime;
+
+    /**
+     * 更新时间
+     */
+    @TableField(fill = FieldFill.INSERT_UPDATE)
+    private LocalDateTime updateTime;
+
+    /**
+     * 逻辑删除：0-未删除 1-已删除
+     */
+    @TableLogic
+    private Integer isDeleted;
+}
+```
+
+### 2. Mapper — `dao/mapper/UserMapper.java`
+
+```java
+package com.iflytek.avatar.dao.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.iflytek.avatar.dao.beans.User;
+import org.apache.ibatis.annotations.Mapper;
+
+/**
+ * 用户表 Mapper 接口
+ *
+ * @author avatar-generator
+ */
+@Mapper
+public interface UserMapper extends BaseMapper<User> {
+
+}
+```
+
+### 3. Service 接口 — `service/UserService.java`
+
+```java
+package com.iflytek.avatar.service;
+
+import com.baomidou.mybatisplus.core.metadata.IPage;
+import com.baomidou.mybatisplus.extension.service.IService;
+import com.iflytek.avatar.dao.beans.User;
+import com.iflytek.avatar.entity.request.UserCreateRequest;
+import com.iflytek.avatar.entity.request.UserPageRequest;
+import com.iflytek.avatar.entity.request.UserUpdateRequest;
+import com.iflytek.avatar.entity.response.UserResponse;
+
+/**
+ * 用户表 Service 接口
+ *
+ * @author avatar-generator
+ */
+public interface UserService extends IService<User> {
+
+    /**
+     * 创建用户
+     *
+     * @param request 创建请求
+     * @return 用户信息
+     */
+    UserResponse create(UserCreateRequest request);
+
+    /**
+     * 根据ID查询用户
+     *
+     * @param id 用户ID
+     * @return 用户信息
+     */
+    UserResponse getDetail(Long id);
+
+    /**
+     * 更新用户
+     *
+     * @param id      用户ID
+     * @param request 更新请求
+     * @return 用户信息
+     */
+    UserResponse update(Long id, UserUpdateRequest request);
+
+    /**
+     * 删除用户
+     *
+     * @param id 用户ID
+     */
+    void delete(Long id);
+
+    /**
+     * 分页查询用户
+     *
+     * @param request 分页请求
+     * @return 分页结果
+     */
+    IPage<UserResponse> page(UserPageRequest request);
+}
+```
+
+### 4. ServiceImpl — `service/impl/UserServiceImpl.java`
+
+```java
+package com.iflytek.avatar.service.impl;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.core.metadata.IPage;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
+import com.iflytek.avatar.dao.beans.User;
+import com.iflytek.avatar.dao.mapper.UserMapper;
+import com.iflytek.avatar.entity.request.UserCreateRequest;
+import com.iflytek.avatar.entity.request.UserPageRequest;
+import com.iflytek.avatar.entity.request.UserUpdateRequest;
+import com.iflytek.avatar.entity.response.UserResponse;
+import com.iflytek.avatar.service.UserService;
+import lombok.RequiredArgsConstructor;
+import org.springframework.beans.BeanUtils;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.Objects;
+
+/**
+ * 用户表 Service 实现类
+ *
+ * @author avatar-generator
+ */
+@Service
+@RequiredArgsConstructor
+public class UserServiceImpl extends ServiceImpl<UserMapper, User> implements UserService {
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public UserResponse create(UserCreateRequest request) {
+        User user = new User();
+        BeanUtils.copyProperties(request, user);
+        this.save(user);
+        return toResponse(user);
+    }
+
+    @Override
+    @Transactional(readOnly = true)
+    public UserResponse getDetail(Long id) {
+        User user = this.getById(id);
+        if (Objects.isNull(user)) {
+            throw new RuntimeException("用户不存在，ID: " + id);
+        }
+        return toResponse(user);
+    }
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public UserResponse update(Long id, UserUpdateRequest request) {
+        User user = this.getById(id);
+        if (Objects.isNull(user)) {
+            throw new RuntimeException("用户不存在，ID: " + id);
+        }
+        BeanUtils.copyProperties(request, user);
+        user.setId(id);
+        this.updateById(user);
+        return toResponse(user);
+    }
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public void delete(Long id) {
+        User user = this.getById(id);
+        if (Objects.isNull(user)) {
+            throw new RuntimeException("用户不存在，ID: " + id);
+        }
+        this.removeById(id);
+    }
+
+    @Override
+    @Transactional(readOnly = true)
+    public IPage<UserResponse> page(UserPageRequest request) {
+        Page<User> page = new Page<>(request.getPageNum(), request.getPageSize());
+        LambdaQueryWrapper<User> wrapper = new LambdaQueryWrapper<>();
+
+        // 条件查询（按需添加）
+        if (request.getUsername() != null) {
+            wrapper.like(User::getUsername, request.getUsername());
+        }
+        if (request.getStatus() != null) {
+            wrapper.eq(User::getStatus, request.getStatus());
+        }
+
+        // 默认按创建时间倒序
+        wrapper.orderByDesc(User::getCreateTime);
+
+        IPage<User> result = this.page(page, wrapper);
+        return result.convert(this::toResponse);
+    }
+
+    /**
+     * Entity 转 Response DTO
+     */
+    private UserResponse toResponse(User user) {
+        UserResponse response = new UserResponse();
+        BeanUtils.copyProperties(user, response);
+        return response;
+    }
+}
+```
+
+### 5. Controller — `controller/UserController.java`
+
+```java
+package com.iflytek.avatar.controller;
+
+import com.baomidou.mybatisplus.core.metadata.IPage;
+import com.iflytek.avatar.common.result.Result;
+import com.iflytek.avatar.entity.request.UserCreateRequest;
+import com.iflytek.avatar.entity.request.UserPageRequest;
+import com.iflytek.avatar.entity.request.UserUpdateRequest;
+import com.iflytek.avatar.entity.response.UserResponse;
+import com.iflytek.avatar.service.UserService;
+import jakarta.validation.Valid;
+import lombok.RequiredArgsConstructor;
+import org.springframework.web.bind.annotation.*;
+
+/**
+ * 用户管理接口
+ *
+ * @author avatar-generator
+ */
+@RestController
+@RequestMapping("/api/v1/users")
+@RequiredArgsConstructor
+public class UserController {
+
+    private final UserService userService;
+
+    /**
+     * 创建用户
+     */
+    @PostMapping
+    public Result<UserResponse> create(@Valid @RequestBody UserCreateRequest request) {
+        return Result.success(userService.create(request));
+    }
+
+    /**
+     * 根据ID查询用户
+     */
+    @GetMapping("/{id}")
+    public Result<UserResponse> getById(@PathVariable Long id) {
+        return Result.success(userService.getDetail(id));
+    }
+
+    /**
+     * 更新用户
+     */
+    @PutMapping("/{id}")
+    public Result<UserResponse> update(@PathVariable Long id,
+                                       @Valid @RequestBody UserUpdateRequest request) {
+        return Result.success(userService.update(id, request));
+    }
+
+    /**
+     * 删除用户
+     */
+    @DeleteMapping("/{id}")
+    public Result<Void> delete(@PathVariable Long id) {
+        userService.delete(id);
+        return Result.success();
+    }
+
+    /**
+     * 分页查询用户
+     */
+    @GetMapping
+    public Result<IPage<UserResponse>> page(@Valid UserPageRequest request) {
+        return Result.success(userService.page(request));
+    }
+}
+```
+
+### 6. Request DTO — `entity/request/UserCreateRequest.java`
+
+```java
+package com.iflytek.avatar.entity.request;
+
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.Size;
+import lombok.Data;
+
+/**
+ * 用户创建请求
+ *
+ * @author avatar-generator
+ */
+@Data
+public class UserCreateRequest {
+
+    /**
+     * 用户名
+     */
+    @NotBlank(message = "用户名不能为空")
+    @Size(max = 64, message = "用户名长度不能超过64个字符")
+    private String username;
+
+    /**
+     * 邮箱
+     */
+    @Size(max = 128, message = "邮箱长度不能超过128个字符")
+    private String email;
+
+    /**
+     * 手机号
+     */
+    @Size(max = 20, message = "手机号长度不能超过20个字符")
+    private String phone;
+
+    /**
+     * 状态：0-禁用 1-启用
+     */
+    private Integer status;
+}
+```
+
+### 7. Request DTO — `entity/request/UserUpdateRequest.java`
+
+```java
+package com.iflytek.avatar.entity.request;
+
+import jakarta.validation.constraints.Size;
+import lombok.Data;
+
+/**
+ * 用户更新请求
+ *
+ * @author avatar-generator
+ */
+@Data
+public class UserUpdateRequest {
+
+    /**
+     * 用户名
+     */
+    @Size(max = 64, message = "用户名长度不能超过64个字符")
+    private String username;
+
+    /**
+     * 邮箱
+     */
+    @Size(max = 128, message = "邮箱长度不能超过128个字符")
+    private String email;
+
+    /**
+     * 手机号
+     */
+    @Size(max = 20, message = "手机号长度不能超过20个字符")
+    private String phone;
+
+    /**
+     * 状态：0-禁用 1-启用
+     */
+    private Integer status;
+}
+```
+
+### 8. Request DTO — `entity/request/UserPageRequest.java`
+
+```java
+package com.iflytek.avatar.entity.request;
+
+import jakarta.validation.constraints.Max;
+import jakarta.validation.constraints.Min;
+import lombok.Data;
+
+/**
+ * 用户分页查询请求
+ *
+ * @author avatar-generator
+ */
+@Data
+public class UserPageRequest {
+
+    /**
+     * 页码，默认1
+     */
+    @Min(value = 1, message = "页码最小为1")
+    private Integer pageNum = 1;
+
+    /**
+     * 每页条数，默认10
+     */
+    @Min(value = 1, message = "每页条数最小为1")
+    @Max(value = 100, message = "每页条数最大为100")
+    private Integer pageSize = 10;
+
+    /**
+     * 用户名（模糊查询）
+     */
+    private String username;
+
+    /**
+     * 状态（精确查询）
+     */
+    private Integer status;
+}
+```
+
+### 9. Response DTO — `entity/response/UserResponse.java`
+
+```java
+package com.iflytek.avatar.entity.response;
+
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+/**
+ * 用户响应
+ *
+ * @author avatar-generator
+ */
+@Data
+public class UserResponse {
+
+    /**
+     * 主键ID
+     */
+    private Long id;
+
+    /**
+     * 用户名
+     */
+    private String username;
+
+    /**
+     * 邮箱
+     */
+    private String email;
+
+    /**
+     * 手机号
+     */
+    private String phone;
+
+    /**
+     * 状态：0-禁用 1-启用
+     */
+    private Integer status;
+
+    /**
+     * 创建时间
+     */
+    private LocalDateTime createTime;
+
+    /**
+     * 更新时间
+     */
+    private LocalDateTime updateTime;
+}
+```
+
+### 10. Feign API 接口 — `api/UserApi.java`
+
+```java
+package com.iflytek.avatar.api;
+
+import com.baomidou.mybatisplus.core.metadata.IPage;
+import com.iflytek.avatar.common.result.Result;
+import com.iflytek.avatar.entity.request.UserCreateRequest;
+import com.iflytek.avatar.entity.request.UserPageRequest;
+import com.iflytek.avatar.entity.request.UserUpdateRequest;
+import com.iflytek.avatar.entity.response.UserResponse;
+import org.springframework.cloud.openfeign.FeignClient;
+import org.springframework.web.bind.annotation.*;
+
+/**
+ * 用户服务 Feign API
+ *
+ * @author avatar-generator
+ */
+@FeignClient(name = "avatar-service", path = "/api/v1/users")
+public interface UserApi {
+
+    @PostMapping
+    Result<UserResponse> create(@RequestBody UserCreateRequest request);
+
+    @GetMapping("/{id}")
+    Result<UserResponse> getById(@PathVariable("id") Long id);
+
+    @PutMapping("/{id}")
+    Result<UserResponse> update(@PathVariable("id") Long id,
+                                @RequestBody UserUpdateRequest request);
+
+    @DeleteMapping("/{id}")
+    Result<Void> delete(@PathVariable("id") Long id);
+
+    @GetMapping
+    Result<IPage<UserResponse>> page(UserPageRequest request);
+}
+```
+
+---
+
+## 单元测试骨架
+
+```java
+package com.iflytek.avatar.service;
+
+import com.iflytek.avatar.dao.beans.User;
+import com.iflytek.avatar.dao.mapper.UserMapper;
+import com.iflytek.avatar.entity.request.UserCreateRequest;
+import com.iflytek.avatar.entity.response.UserResponse;
+import com.iflytek.avatar.service.impl.UserServiceImpl;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.*;
+
+/**
+ * UserService 单元测试
+ */
+@ExtendWith(MockitoExtension.class)
+class UserServiceTest {
+
+    @InjectMocks
+    private UserServiceImpl userService;
+
+    @Mock
+    private UserMapper userMapper;
+
+    @Test
+    @DisplayName("创建用户 - 正常流程")
+    void create_shouldReturnUserResponse_whenValidRequest() {
+        // Given
+        UserCreateRequest request = new UserCreateRequest();
+        request.setUsername("testuser");
+        request.setEmail("test@example.com");
+
+        when(userMapper.insert(any(User.class))).thenReturn(1);
+
+        // When
+        UserResponse response = userService.create(request);
+
+        // Then
+        assertNotNull(response);
+        assertEquals("testuser", response.getUsername());
+        verify(userMapper, times(1)).insert(any(User.class));
+    }
+
+    @Test
+    @DisplayName("查询用户 - 用户不存在")
+    void getDetail_shouldThrowException_whenUserNotFound() {
+        // Given
+        Long userId = 999L;
+        when(userMapper.selectById(userId)).thenReturn(null);
+
+        // When & Then
+        assertThrows(RuntimeException.class, () -> userService.getDetail(userId));
+    }
+
+    @Test
+    @DisplayName("删除用户 - 正常流程")
+    void delete_shouldSucceed_whenUserExists() {
+        // Given
+        Long userId = 1L;
+        User user = new User();
+        user.setId(userId);
+        when(userMapper.selectById(userId)).thenReturn(user);
+        when(userMapper.deleteById(userId)).thenReturn(1);
+
+        // When
+        userService.delete(userId);
+
+        // Then
+        verify(userMapper, times(1)).deleteById(userId);
+    }
+
+    // TODO: 补充更多测试用例
+    // - 更新用户 - 正常流程
+    // - 更新用户 - 用户不存在
+    // - 分页查询 - 无条件
+    // - 分页查询 - 带条件
+}
+```
+
+---
+
+## 自定义选项
+
+### 指定生成文件范围
+
+用户可以指定只生成部分文件：
+
+```
+请根据以下 DDL 只生成 Entity 和 Mapper：
+CREATE TABLE t_order (...);
+```
+
+### 自定义字段映射
+
+用户可以指定字段的特殊处理：
+
+```
+请生成 CRUD 代码，其中：
+- price 字段使用 BigDecimal 类型
+- status 字段生成枚举类 OrderStatus
+- description 字段不在列表查询中返回
+```
+
+### 自定义业务异常
+
+生成代码时，将 `RuntimeException` 替换为项目的自定义业务异常类：
+
+```java
+// 替换前
+throw new RuntimeException("用户不存在，ID: " + id);
+
+// 替换后（根据项目实际异常类调整）
+throw new BusinessException(ErrorCode.USER_NOT_FOUND, "用户不存在，ID: " + id);
+```
+
+---
+
+## 命名转换规则
+
+| 数据库命名 | Java 命名 | 示例 |
+|-----------|-----------|------|
+| 表名 `t_user_order` | 类名 `UserOrder` | 去掉 `t_` 前缀，转 PascalCase |
+| 列名 `user_name` | 字段名 `userName` | 转 camelCase |
+| 表名 `t_user` | URL `/api/v1/users` | 去掉 `t_` 前缀，复数形式 |
+| 表名 `t_user` | Mapper `UserMapper` | 类名 + Mapper |
+| 表名 `t_user` | Service `UserService` | 类名 + Service |
+| 表名 `t_user` | ServiceImpl `UserServiceImpl` | 类名 + ServiceImpl |
+| 表名 `t_user` | Controller `UserController` | 类名 + Controller |
+
+---
+
+## 依赖规则
+
+生成代码时必须遵循以下规则文件中的规范：
+
+- **分层架构规范**: 确保代码按 Controller → Service → Mapper 分层
+- **MyBatis Plus 规范**: 确保 Entity 注解、Mapper 继承、Service 继承正确
+- **编码规范**: 确保命名、注释、格式符合项目标准
+
+---
+
+## 最佳实践
+
+1. **先设计 DDL，再生成代码** — 确保表结构设计合理后再生成
+2. **生成后检查并调整** — 自动生成的代码是起点，需根据业务需求调整
+3. **补充业务逻辑** — 生成的代码只包含基础 CRUD，复杂业务逻辑需手动补充
+4. **完善单元测试** — 基于测试骨架补充完整的测试用例
+5. **敏感字段处理** — 检查 Response DTO，确保密码等敏感字段不暴露
+6. **校验规则完善** — 根据业务需求补充 Request DTO 中的校验注解
+
+---
+
+## 常见问题排查
+
+### Q: 生成的 Entity 字段类型与数据库不匹配？
+
+常见的类型映射关系：
+
+| MySQL 类型 | Java 类型 |
+|-----------|-----------|
+| BIGINT | Long |
+| INT / INTEGER | Integer |
+| TINYINT | Integer |
+| VARCHAR / CHAR | String |
+| TEXT / LONGTEXT | String |
+| DECIMAL | BigDecimal |
+| DATETIME | LocalDateTime |
+| DATE | LocalDate |
+| TIME | LocalTime |
+| BIT(1) / BOOLEAN | Boolean |
+
+### Q: 如何处理表关联查询？
+
+基础 CRUD 不包含关联查询。如需关联查询：
+1. 在 Mapper 中添加自定义 SQL 或 XML 映射
+2. 在 Service 中组装关联数据
+3. 在 Response DTO 中添加关联字段
+
+### Q: 如何支持批量操作？
+
+在 Service 接口中添加批量方法：
+
+```java
+void batchCreate(List<UserCreateRequest> requests);
+void batchDelete(List<Long> ids);
+```
+
+使用 MyBatis Plus 的 `saveBatch` / `removeBatchByIds` 实现。