@llryiop/avatar-boot-cli 1.0.1 → 1.0.2

package/templates/.claude/skills/avatar-boot-starter-mysql/README.md

@@ -0,0 +1,572 @@
+---
+name: avatar-boot-starter-mysql
+description: 当涉及 MySQL、数据库、Druid、数据源、MyBatis Plus、SQL 相关功能时使用此技能 - 为 Spring Boot 3.5.3 应用提供基于 Druid 1.2.24 连接池和 MyBatis Plus 3.5.15 的数据库访问能力，包含自动配置、SQL 监控、多数据源支持。
+---
+
+Avatar Boot 的 MySQL 数据库集成模块，基于 Druid 1.2.24 连接池和 MyBatis Plus 3.5.15 提供开箱即用的数据库访问能力。
+
+## 功能特性
+
+- ✅ **Druid 连接池** - 内置 Druid 1.2.24，提供高性能连接池管理和 SQL 监控
+- ✅ **MyBatis Plus 集成** - 基于 mybatis-plus-spring-boot3-starter 3.5.15，提供增强 CRUD 能力
+- ✅ **SQL 监控** - Druid 内置 SQL 监控面板，实时查看慢 SQL 和连接池状态
+- ✅ **自动分页** - 内置分页插件，支持多种数据库方言
+- ✅ **代码生成** - 支持 MyBatis Plus 代码生成器，快速生成 Entity/Mapper/Service
+- ✅ **多数据源** - 支持多数据源配置和动态切换
+
+## 快速开始
+
+### 1. 添加依赖
+
+在项目的 `pom.xml` 中添加依赖：
+
+```xml
+<dependency>
+    <groupId>com.iflytek.avatar.boot</groupId>
+    <artifactId>avatar-boot-starter-mysql</artifactId>
+</dependency>
+```
+
+> 版本由 Avatar Boot BOM 统一管理，无需指定 version。
+
+### 2. 配置文件
+
+在 `application.yml` 中配置数据源：
+
+```yaml
+spring:
+  datasource:
+    type: com.alibaba.druid.pool.DruidDataSource
+    driver-class-name: com.mysql.cj.jdbc.Driver
+    url: jdbc:mysql://localhost:3306/your_db?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
+    username: root
+    password: your-password
+    druid:
+      # 连接池配置
+      initial-size: 5          # 初始化连接数
+      min-idle: 5              # 最小空闲连接数
+      max-active: 20           # 最大活跃连接数
+      max-wait: 60000          # 获取连接最大等待时间（毫秒）
+      # 连接检测
+      validation-query: SELECT 1
+      test-while-idle: true
+      test-on-borrow: false
+      test-on-return: false
+      time-between-eviction-runs-millis: 60000  # 检测间隔
+      min-evictable-idle-time-millis: 300000    # 最小空闲时间
+      # 监控统计
+      filters: stat,wall,slf4j  # 启用统计、防火墙、日志过滤器
+      stat-view-servlet:
+        enabled: true
+        url-pattern: /druid/*
+        login-username: admin
+        login-password: admin123
+        allow: ""
+      web-stat-filter:
+        enabled: true
+        url-pattern: /*
+        exclusions: "*.js,*.gif,*.jpg,*.png,*.css,*.ico,/druid/*"
+      filter:
+        stat:
+          slow-sql-millis: 2000        # 慢 SQL 阈值（毫秒）
+          log-slow-sql: true           # 记录慢 SQL
+          merge-sql: true              # 合并 SQL 统计
+        wall:
+          config:
+            multi-statement-allow: false  # 禁止多语句执行
+            delete-allow: true
+```
+
+### 3. MyBatis Plus 配置
+
+```yaml
+mybatis-plus:
+  mapper-locations: classpath*:mapper/**/*.xml    # Mapper XML 文件位置
+  type-aliases-package: com.example.entity        # 实体类包路径
+  configuration:
+    map-underscore-to-camel-case: true            # 驼峰命名映射
+    log-impl: org.apache.ibatis.logging.slf4j.Slf4jImpl  # SQL 日志
+  global-config:
+    db-config:
+      id-type: assign_id          # 主键策略：雪花算法
+      logic-delete-field: deleted  # 逻辑删除字段
+      logic-delete-value: 1       # 已删除值
+      logic-not-delete-value: 0   # 未删除值
+      table-prefix: t_            # 表名前缀（可选）
+```
+
+## Entity / Mapper / Service 模式
+
+### Entity 实体类
+
+```java
+package com.example.entity;
+
+import com.baomidou.mybatisplus.annotation.*;
+import lombok.Data;
+
+import java.io.Serial;
+import java.io.Serializable;
+import java.time.LocalDateTime;
+
+@Data
+@TableName("t_user")
+public class User implements Serializable {
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    /**
+     * 主键（雪花算法）
+     */
+    @TableId(type = IdType.ASSIGN_ID)
+    private Long id;
+
+    /**
+     * 用户名
+     */
+    private String username;
+
+    /**
+     * 邮箱
+     */
+    private String email;
+
+    /**
+     * 状态：0-禁用，1-启用
+     */
+    private Integer status;
+
+    /**
+     * 创建时间（自动填充）
+     */
+    @TableField(fill = FieldFill.INSERT)
+    private LocalDateTime createTime;
+
+    /**
+     * 更新时间（自动填充）
+     */
+    @TableField(fill = FieldFill.INSERT_UPDATE)
+    private LocalDateTime updateTime;
+
+    /**
+     * 逻辑删除标识
+     */
+    @TableLogic
+    private Integer deleted;
+}
+```
+
+### Mapper 接口
+
+```java
+package com.example.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.example.entity.User;
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Param;
+import org.apache.ibatis.annotations.Select;
+
+import java.util.List;
+
+@Mapper
+public interface UserMapper extends BaseMapper<User> {
+
+    /**
+     * 自定义查询（注解方式）
+     */
+    @Select("SELECT * FROM t_user WHERE status = #{status}")
+    List<User> selectByStatus(@Param("status") Integer status);
+}
+```
+
+### Service 接口与实现
+
+```java
+package com.example.service;
+
+import com.baomidou.mybatisplus.extension.service.IService;
+import com.example.entity.User;
+
+public interface UserService extends IService<User> {
+    /**
+     * 根据用户名查询
+     */
+    User getByUsername(String username);
+}
+```
+
+```java
+package com.example.service.impl;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
+import com.example.entity.User;
+import com.example.mapper.UserMapper;
+import com.example.service.UserService;
+import org.springframework.stereotype.Service;
+
+@Service
+public class UserServiceImpl extends ServiceImpl<UserMapper, User> implements UserService {
+
+    @Override
+    public User getByUsername(String username) {
+        return this.getOne(new LambdaQueryWrapper<User>()
+                .eq(User::getUsername, username));
+    }
+}
+```
+
+### 分页查询
+
+```java
+package com.example.config;
+
+import com.baomidou.mybatisplus.annotation.DbType;
+import com.baomidou.mybatisplus.extension.plugins.MybatisPlusInterceptor;
+import com.baomidou.mybatisplus.extension.plugins.inner.PaginationInnerInterceptor;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration
+public class MybatisPlusConfig {
+
+    @Bean
+    public MybatisPlusInterceptor mybatisPlusInterceptor() {
+        MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
+        interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
+        return interceptor;
+    }
+}
+```
+
+```java
+@Service
+@RequiredArgsConstructor
+public class UserQueryService {
+
+    private final UserService userService;
+
+    /**
+     * 分页查询用户
+     */
+    public IPage<User> pageQuery(int current, int size, String username) {
+        Page<User> page = new Page<>(current, size);
+        LambdaQueryWrapper<User> wrapper = new LambdaQueryWrapper<User>()
+                .like(StringUtils.isNotBlank(username), User::getUsername, username)
+                .eq(User::getDeleted, 0)
+                .orderByDesc(User::getCreateTime);
+        return userService.page(page, wrapper);
+    }
+}
+```
+
+## Druid 监控面板
+
+启动应用后，访问 `http://localhost:8080/druid/` 即可查看 Druid 监控面板。
+
+### 监控内容
+
+| 面板 | 功能 |
+|------|------|
+| 数据源 | 连接池状态、活跃连接数、等待线程数 |
+| SQL 监控 | SQL 执行次数、耗时统计、慢 SQL 列表 |
+| SQL 防火墙 | 拦截的危险 SQL 统计 |
+| Web 应用 | 请求 URI 统计、关联 SQL |
+| Spring 监控 | Spring Bean 方法调用统计 |
+
+### 安全配置
+
+生产环境建议限制访问：
+
+```yaml
+spring:
+  datasource:
+    druid:
+      stat-view-servlet:
+        enabled: true
+        allow: 10.0.0.0/8     # 仅内网访问
+        deny: ""
+        login-username: ${DRUID_USERNAME}
+        login-password: ${DRUID_PASSWORD}
+```
+
+## 事务管理
+
+### @Transactional 使用规范
+
+```java
+@Service
+@RequiredArgsConstructor
+public class OrderService {
+
+    private final OrderMapper orderMapper;
+    private final OrderItemMapper orderItemMapper;
+
+    /**
+     * 创建订单（事务）
+     * 注意：@Transactional 默认只回滚 RuntimeException
+     */
+    @Transactional(rollbackFor = Exception.class)
+    public Long createOrder(OrderDTO dto) {
+        // 1. 创建主订单
+        Order order = new Order();
+        order.setOrderNo(generateOrderNo());
+        order.setTotalAmount(dto.getTotalAmount());
+        orderMapper.insert(order);
+
+        // 2. 创建订单明细
+        for (OrderItemDTO item : dto.getItems()) {
+            OrderItem orderItem = new OrderItem();
+            orderItem.setOrderId(order.getId());
+            orderItem.setProductId(item.getProductId());
+            orderItem.setQuantity(item.getQuantity());
+            orderItemMapper.insert(orderItem);
+        }
+
+        return order.getId();
+    }
+}
+```
+
+### 事务最佳实践
+
+1. **必须指定 `rollbackFor = Exception.class`**：默认只回滚 RuntimeException
+2. **避免在事务方法中调用同类方法**：Spring AOP 代理限制，同类内部调用不生效
+3. **事务方法必须是 public**：非 public 方法事务不生效
+4. **控制事务粒度**：不要在大方法上加 @Transactional，只在需要事务的方法上使用
+5. **避免事务中做耗时操作**：如 HTTP 调用、文件上传，会长时间占用数据库连接
+
+```java
+// 错误示例：事务中调用远程服务
+@Transactional(rollbackFor = Exception.class)
+public void badExample() {
+    orderMapper.insert(order);
+    // 不要在事务中做远程调用！
+    httpClient.callRemoteService();  // 如果超时，数据库连接被长时间占用
+}
+
+// 正确示例：将远程调用移出事务
+public void goodExample() {
+    createOrderInTransaction(order);
+    httpClient.callRemoteService();  // 事务外调用
+}
+
+@Transactional(rollbackFor = Exception.class)
+public void createOrderInTransaction(Order order) {
+    orderMapper.insert(order);
+}
+```
+
+## 多数据源配置
+
+### 配置文件
+
+```yaml
+spring:
+  datasource:
+    primary:
+      type: com.alibaba.druid.pool.DruidDataSource
+      driver-class-name: com.mysql.cj.jdbc.Driver
+      url: jdbc:mysql://localhost:3306/primary_db?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
+      username: root
+      password: password1
+      druid:
+        initial-size: 5
+        max-active: 20
+    secondary:
+      type: com.alibaba.druid.pool.DruidDataSource
+      driver-class-name: com.mysql.cj.jdbc.Driver
+      url: jdbc:mysql://localhost:3306/secondary_db?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
+      username: root
+      password: password2
+      druid:
+        initial-size: 5
+        max-active: 20
+```
+
+### 数据源配置类
+
+```java
+package com.example.config;
+
+import com.alibaba.druid.pool.DruidDataSource;
+import com.baomidou.mybatisplus.extension.spring.MybatisSqlSessionFactoryBean;
+import org.apache.ibatis.session.SqlSessionFactory;
+import org.mybatis.spring.annotation.MapperScan;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Primary;
+import org.springframework.core.io.support.PathMatchingResourcePatternResolver;
+
+import javax.sql.DataSource;
+
+@Configuration
+@MapperScan(basePackages = "com.example.mapper.primary",
+        sqlSessionFactoryRef = "primarySqlSessionFactory")
+public class PrimaryDataSourceConfig {
+
+    @Primary
+    @Bean("primaryDataSource")
+    @ConfigurationProperties(prefix = "spring.datasource.primary")
+    public DataSource primaryDataSource() {
+        return new DruidDataSource();
+    }
+
+    @Primary
+    @Bean("primarySqlSessionFactory")
+    public SqlSessionFactory primarySqlSessionFactory(DataSource primaryDataSource) throws Exception {
+        MybatisSqlSessionFactoryBean factory = new MybatisSqlSessionFactoryBean();
+        factory.setDataSource(primaryDataSource);
+        factory.setMapperLocations(
+                new PathMatchingResourcePatternResolver()
+                        .getResources("classpath:mapper/primary/**/*.xml"));
+        return factory.getObject();
+    }
+}
+```
+
+## 自动填充配置
+
+```java
+package com.example.config;
+
+import com.baomidou.mybatisplus.core.handlers.MetaObjectHandler;
+import lombok.extern.slf4j.Slf4j;
+import org.apache.ibatis.reflection.MetaObject;
+import org.springframework.stereotype.Component;
+
+import java.time.LocalDateTime;
+
+@Slf4j
+@Component
+public class MyMetaObjectHandler 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);
+    }
+}
+```
+
+## 慢 SQL 排查
+
+### 1. Druid 慢 SQL 监控
+
+通过 Druid 监控面板查看：
+- 访问 `/druid/sql.html` 查看所有 SQL 统计
+- 按执行时间排序，找到慢 SQL
+- 查看 SQL 执行计划和参数
+
+### 2. MySQL EXPLAIN 分析
+
+```sql
+-- 分析查询执行计划
+EXPLAIN SELECT * FROM t_user WHERE username = 'zhangsan';
+
+-- 关注以下字段：
+-- type: ALL（全表扫描，需优化）、index、range、ref、const
+-- rows: 扫描行数
+-- Extra: Using filesort（需优化）、Using temporary（需优化）
+```
+
+### 3. 索引优化建议
+
+- 为 WHERE 条件的字段添加索引
+- 避免在索引列上使用函数或计算
+- 联合索引遵循最左前缀原则
+- 使用覆盖索引减少回表查询
+
+## 最佳实践
+
+### 1. 连接池配置
+
+- **initial-size 和 min-idle 相同**：避免连接池频繁创建/销毁连接
+- **max-active 合理设置**：建议 20-50，根据服务器配置和并发量调整
+- **启用 test-while-idle**：定期检测空闲连接有效性
+- **设置 max-wait**：避免无限等待连接
+
+### 2. SQL 规范
+
+- **禁止 SELECT ***：明确指定需要的列
+- **分页查询必须加 LIMIT**：避免全表查询
+- **批量操作使用 batch**：MyBatis Plus 的 `saveBatch()` 方法
+- **大表查询走索引**：通过 EXPLAIN 验证
+
+### 3. MyBatis Plus 使用
+
+- **优先使用 LambdaQueryWrapper**：类型安全，重构友好
+- **合理使用逻辑删除**：高频查询表注意索引包含 deleted 字段
+- **Entity 实现 Serializable**：支持缓存序列化
+- **使用自动填充**：createTime、updateTime 统一处理
+
+## 常见问题
+
+### 1. 连接池耗尽（Pool exhausted）
+
+**原因**：并发量过大或连接泄漏
+
+**解决**：
+- 增大 `max-active` 配置
+- 检查是否有未关闭的连接（使用 try-with-resources）
+- 启用 Druid 的 `removeAbandoned` 配置回收泄漏连接
+- 检查事务方法中是否有耗时操作占用连接
+
+### 2. 连接超时（Connection timeout）
+
+**原因**：MySQL 服务端关闭了空闲连接
+
+**解决**：
+- 启用 `test-while-idle: true` 检测空闲连接
+- 设置 `time-between-eviction-runs-millis` 小于 MySQL 的 `wait_timeout`
+- 检查 MySQL `max_connections` 配置
+
+### 3. 慢查询导致性能问题
+
+**原因**：缺少索引或 SQL 不合理
+
+**解决**：
+- 通过 Druid 监控面板定位慢 SQL
+- 使用 EXPLAIN 分析执行计划
+- 添加合适的索引
+- 优化 SQL 写法，避免全表扫描
+
+### 4. MyBatis Plus 逻辑删除不生效
+
+**原因**：配置缺失或字段注解错误
+
+**解决**：
+- 检查 `global-config.db-config.logic-delete-field` 配置
+- 确保实体类字段添加 `@TableLogic` 注解
+- 自定义 SQL 不会自动添加逻辑删除条件，需手动处理
+
+### 5. 批量插入性能差
+
+**原因**：逐条插入产生大量 SQL
+
+**解决**：
+- 使用 `saveBatch()` 方法批量插入
+- JDBC URL 添加 `rewriteBatchedStatements=true` 参数
+- 控制每批次大小（推荐 500-1000 条）
+
+## 依赖版本
+
+- Druid: 1.2.24
+- MyBatis Plus: 3.5.15（mybatis-plus-spring-boot3-starter）
+- MySQL Connector/J: 由 Spring Boot 3.5.3 BOM 管理
+- Spring Boot: 3.5.3
+- Java: 21
+
+## 参考文档
+
+- [MyBatis Plus 官方文档](https://baomidou.com/pages/24112f/)
+- [Druid 官方文档](https://github.com/alibaba/druid/wiki)
+- [Spring Boot 数据访问](https://docs.spring.io/spring-boot/reference/data/sql.html)