ai-engineering-init 1.7.0 → 1.10.0

package/.codex/skills/error-handler/SKILL.md

@@ -1,371 +1,310 @@
 ---
 name: error-handler
 description: |
-  后端异常处理规范。包含 ServiceException 用法、全局异常处理器、参数校验、日志规范、错误码设计。
-
-  触发场景：
-  - 抛出业务异常（ServiceException）
-  - 全局异常处理器配置
-  - 参数校验异常处理
-  - 日志记录规范
-  - 错误码设计与国际化
-  - 事务异常处理
-
-  触发词：异常、ServiceException、throw、错误处理、全局异常、@Validated、参数校验、日志、log、错误码、事务、@Transactional、try-catch、异常捕获
-
-  注意：
-  - 如果是安全相关（认证授权、数据脱敏），请使用 security-guard。
-  - 如果是数据权限（@DataPermission），请使用 data-permission。
+  通用异常处理指南。涵盖自定义业务异常、全局异常处理器、参数校验等。
+  触发场景：异常设计、错误处理、参数校验、全局异常捕获。
+  触发词：异常处理、错误处理、参数校验、validation、异常捕获。
+  注意：如果项目有专属技能（如 `leniu-error-handler`），优先使用专属版本。
 ---
 
-# 后端异常处理指南
+# 异常处理指南
 
-> 本项目是纯后端项目，本文档专注于 Java 后端异常处理规范。
+> 通用模板。如果项目有专属技能（如 `leniu-error-handler`），优先使用。
 
----
+## 核心规范
 
-## 快速索引
+### 异常分层设计
 
-| 场景 | 推荐方式 |
-|------|---------|
-| 业务异常 | `throw new ServiceException("msg")` |
-| 带参数异常 | `throw new ServiceException("用户 {} 不存在", userId)` |
-| 带错误码 | `throw new ServiceException("msg", 200101)` |
-| 参数校验 | `@Validated(AddGroup.class)` |
-| 日志记录 | `log.error("msg: {}", e.getMessage(), e)` |
+```
+RuntimeException
+└── BusinessException          # 业务异常基类
+    ├── NotFoundException      # 资源不存在 (404)
+    ├── ForbiddenException     # 无权限 (403)
+    ├── BadRequestException    # 参数错误 (400)
+    └── ConflictException      # 数据冲突 (409)
+```
 
----
+### 异常处理原则
+
+1. **业务异常用自定义异常类**，不要直接抛 `RuntimeException`
+2. **全局统一捕获**，通过 `@RestControllerAdvice` 处理
+3. **区分异常层级**：Controller 层不 try-catch（交给全局处理器），Service 层只捕获需要转换的异常
+4. **异常信息面向用户**：不暴露堆栈、SQL 等技术细节
+5. **日志记录完整**：异常日志包含完整上下文和堆栈
 
-## 1. 业务异常 - ServiceException
+## 代码示例
 
-### 基本用法
+### 1. 自定义业务异常
 
 ```java
-import org.dromara.common.core.exception.ServiceException;
+package [你的包名].exception;
 
-// ✅ 基本用法：抛出业务异常
-throw new ServiceException("用户不存在");
+import lombok.Getter;
 
-// ✅ 带占位符（支持 {} 占位符，使用 Hutool StrFormatter）
-throw new ServiceException("用户 {} 不存在", userId);
-throw new ServiceException("订单 {} 状态 {} 无法支付", orderId, status);
+@Getter
+public class BusinessException extends RuntimeException {
 
-// ✅ 带错误码（第二个参数是 Integer code）
-throw new ServiceException("用户不存在", 200101);
+    private final int code;
 
-// ✅ 条件抛出（手动检查）
-if (ObjectUtil.isNull(user)) {
-    throw new ServiceException("用户不存在");
-}
+    public BusinessException(String message) {
+        super(message);
+        this.code = 500;
+    }
 
-// ✅ 参数校验
-if (StringUtils.isBlank(bo.getName())) {
-    throw new ServiceException("名称不能为空");
+    public BusinessException(int code, String message) {
+        super(message);
+        this.code = code;
+    }
+
+    public BusinessException(int code, String message, Throwable cause) {
+        super(message, cause);
+        this.code = code;
+    }
 }
 ```
 
-### ServiceException 完整 API
-
-> **🔴 重要**：ServiceException **没有静态工厂方法**（如 `of()`）和条件检查方法（如 `throwIf()`, `notNull()`），必须使用 `new` 关键字创建异常对象。
-
-| 构造函数 | 说明 | 示例 |
-|---------|------|------|
-| `new ServiceException(String message)` | 只有错误消息 | `new ServiceException("操作失败")` |
-| `new ServiceException(String message, Object... args)` | 带占位符参数 | `new ServiceException("用户{}不存在", userId)` |
-| `new ServiceException(String message, Integer code)` | 带错误码 | `new ServiceException("用户不存在", 200101)` |
-
-**链式调用方法**：
-- `setMessage(String message)`: 设置错误消息
-- `setDetailMessage(String detailMessage)`: 设置详细错误（用于内部调试）
-
-**源码位置**: `ruoyi-common/ruoyi-common-core/src/main/java/org/dromara/common/core/exception/ServiceException.java`
+```java
+package [你的包名].exception;
 
----
+public class NotFoundException extends BusinessException {
 
-## 2. 全局异常处理器
+    public NotFoundException(String message) {
+        super(404, message);
+    }
 
-框架已提供全局异常处理器，自动捕获并处理各类异常。
+    public static NotFoundException of(String resource, Object id) {
+        return new NotFoundException(resource + " 不存在: " + id);
+    }
+}
+```
 
-**位置**: `ruoyi-common/ruoyi-common-web/src/main/java/org/dromara/common/web/handler/GlobalExceptionHandler.java`
+### 2. 全局异常处理器
 
-### 异常处理映射
+```java
+package [你的包名].handler;
 
-> **注意**：所有异常的 HTTP 响应状态码均为 200，错误码通过 `R.code` 字段返回。
+import [你的包名].exception.BusinessException;
+import [你的包名].exception.NotFoundException;
+import jakarta.validation.ConstraintViolation;
+import jakarta.validation.ConstraintViolationException;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.validation.FieldError;
+import org.springframework.web.bind.MethodArgumentNotValidException;
+import org.springframework.web.bind.MissingServletRequestParameterException;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.RestControllerAdvice;
 
-| 异常类型 | 处理方式 | R.code |
-|---------|---------|--------|
-| `ServiceException` | 返回业务错误信息 | 自定义 code 或 500 |
-| `BindException` | 返回参数绑定错误 | 500 |
-| `ConstraintViolationException` | 返回参数校验错误 | 500 |
-| `MethodArgumentNotValidException` | 返回参数校验错误 | 500 |
-| `HandlerMethodValidationException` | 返回 @Validated 校验错误 | 500 |
-| `HttpRequestMethodNotSupportedException` | 请求方式不支持 | 405 |
-| `NoHandlerFoundException` | 路由不存在 | 404 |
-| `JsonParseException` | JSON 解析失败 | 400 |
-| `HttpMessageNotReadableException` | 请求参数格式错误 | 400 |
-| `ExpressionException` | SpEL 表达式解析失败 | 500 |
-| `RuntimeException` / `Exception` | 系统错误 | 500 |
+import java.util.Map;
+import java.util.stream.Collectors;
 
----
+@Slf4j
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+
+    /**
+     * 业务异常
+     */
+    @ExceptionHandler(BusinessException.class)
+    public ResponseEntity<Result<Void>> handleBusinessException(BusinessException e) {
+        log.warn("业务异常: {}", e.getMessage());
+        return ResponseEntity
+                .status(HttpStatus.BAD_REQUEST)
+                .body(Result.fail(e.getCode(), e.getMessage()));
+    }
 
-## 3. 参数校验
+    /**
+     * 资源不存在
+     */
+    @ExceptionHandler(NotFoundException.class)
+    public ResponseEntity<Result<Void>> handleNotFoundException(NotFoundException e) {
+        log.warn("资源不存在: {}", e.getMessage());
+        return ResponseEntity
+                .status(HttpStatus.NOT_FOUND)
+                .body(Result.fail(404, e.getMessage()));
+    }
 
-### 使用 @Validated 自动校验
+    /**
+     * @RequestBody 参数校验失败
+     */
+    @ExceptionHandler(MethodArgumentNotValidException.class)
+    public ResponseEntity<Result<Map<String, String>>> handleValidationException(
+            MethodArgumentNotValidException e) {
+        Map<String, String> errors = e.getBindingResult().getFieldErrors().stream()
+                .collect(Collectors.toMap(
+                        FieldError::getField,
+                        fe -> fe.getDefaultMessage() != null ? fe.getDefaultMessage() : "校验失败",
+                        (v1, v2) -> v1
+                ));
+        log.warn("参数校验失败: {}", errors);
+        return ResponseEntity
+                .status(HttpStatus.BAD_REQUEST)
+                .body(Result.fail(400, "参数校验失败"));
+    }
 
-```java
-import org.dromara.common.core.validate.AddGroup;
-import org.dromara.common.core.validate.EditGroup;
+    /**
+     * @RequestParam / @PathVariable 校验失败
+     */
+    @ExceptionHandler(ConstraintViolationException.class)
+    public ResponseEntity<Result<Void>> handleConstraintViolation(ConstraintViolationException e) {
+        String message = e.getConstraintViolations().stream()
+                .map(ConstraintViolation::getMessage)
+                .collect(Collectors.joining("; "));
+        log.warn("约束校验失败: {}", message);
+        return ResponseEntity
+                .status(HttpStatus.BAD_REQUEST)
+                .body(Result.fail(400, message));
+    }
 
-// Controller 层校验
-@PostMapping
-public R<Long> add(@Validated(AddGroup.class) @RequestBody XxxBo bo) {
-    // 参数校验失败会自动抛出异常
-    // 全局异常处理器会自动捕获并返回错误信息
-    return R.ok(xxxService.insert(bo));
-}
+    /**
+     * 缺少请求参数
+     */
+    @ExceptionHandler(MissingServletRequestParameterException.class)
+    public ResponseEntity<Result<Void>> handleMissingParam(MissingServletRequestParameterException e) {
+        log.warn("缺少请求参数: {}", e.getParameterName());
+        return ResponseEntity
+                .status(HttpStatus.BAD_REQUEST)
+                .body(Result.fail(400, "缺少参数: " + e.getParameterName()));
+    }
 
-@PutMapping
-public R<Void> edit(@Validated(EditGroup.class) @RequestBody XxxBo bo) {
-    return toAjax(xxxService.update(bo));
+    /**
+     * 兜底：未知异常
+     */
+    @ExceptionHandler(Exception.class)
+    public ResponseEntity<Result<Void>> handleException(Exception e) {
+        log.error("系统异常", e);
+        return ResponseEntity
+                .status(HttpStatus.INTERNAL_SERVER_ERROR)
+                .body(Result.fail(500, "系统繁忙，请稍后重试"));
+    }
 }
 ```
 
-### BO 类校验注解
+### 3. 参数校验（jakarta.validation）
 
 ```java
-public class XxxBo extends BaseEntity {
+package [你的包名].dto;
 
-    @NotNull(message = "ID不能为空", groups = { EditGroup.class })
-    private Long id;
+import jakarta.validation.constraints.*;
+import lombok.Data;
 
-    @NotBlank(message = "名称不能为空", groups = { AddGroup.class, EditGroup.class })
-    @Size(max = 100, message = "名称长度不能超过100个字符")
-    private String name;
+@Data
+public class UserCreateDTO {
 
+    @NotBlank(message = "用户名不能为空")
+    @Size(min = 2, max = 32, message = "用户名长度 2-32 位")
+    private String username;
+
+    @NotBlank(message = "邮箱不能为空")
     @Email(message = "邮箱格式不正确")
     private String email;
 
+    @NotNull(message = "年龄不能为空")
+    @Min(value = 1, message = "年龄最小为 1")
+    @Max(value = 150, message = "年龄最大为 150")
+    private Integer age;
+
     @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确")
     private String phone;
-
-    @Min(value = 0, message = "数量不能小于0")
-    @Max(value = 9999, message = "数量不能大于9999")
-    private Integer count;
 }
 ```
 
-### 手动校验（Service 层）
-
+**Controller 中使用**：
 ```java
-import org.dromara.common.core.utils.ValidatorUtils;
-
-// 手动触发校验
-ValidatorUtils.validate(bo, AddGroup.class);
-ValidatorUtils.validate(bo, EditGroup.class);
+@PostMapping
+public ResponseEntity<Result<Long>> create(@Valid @RequestBody UserCreateDTO dto) {
+    return ResponseEntity.ok(Result.ok(userService.create(dto)));
+}
 ```
 
----
-
-## 4. 日志规范
-
-### 日志级别
-
-| 级别 | 使用场景 | 示例 |
-|------|---------|------|
-| ERROR | 系统错误、业务异常 | 数据库连接失败、第三方接口超时 |
-| WARN | 警告信息、潜在问题 | 缓存未命中、重试操作 |
-| INFO | 重要业务流程、操作记录 | 用户登录、订单创建 |
-| DEBUG | 开发调试信息 | 方法入参、中间变量 |
-| TRACE | 详细追踪信息 | 循环内部数据 |
-
-### 日志最佳实践
+### 4. 分组校验
 
 ```java
-import lombok.extern.slf4j.Slf4j;
-
-@Slf4j
-@Service
-public class XxxServiceImpl implements IXxxService {
+public interface CreateGroup {}
+public interface UpdateGroup {}
 
-    // ✅ 好的：使用占位符（性能更好）
-    log.info("处理订单: {}, 状态: {}", orderId, status);
+@Data
+public class UserDTO {
 
-    // ❌ 不好：字符串拼接（每次都会拼接，即使日志级别不输出）
-    log.info("处理订单: " + orderId + ", 状态: " + status);
-
-    // ✅ 好的：异常日志带堆栈（第三个参数传异常对象）
-    log.error("处理失败: {}", e.getMessage(), e);
-
-    // ❌ 不好：只记录消息，丢失堆栈
-    log.error("处理失败: {}", e.getMessage());
+    @Null(groups = CreateGroup.class, message = "创建时不能指定 ID")
+    @NotNull(groups = UpdateGroup.class, message = "更新时必须指定 ID")
+    private Long id;
 
-    // ✅ 好的：判断日志级别（避免不必要的序列化开销）
-    if (log.isDebugEnabled()) {
-        log.debug("详细数据: {}", JsonUtils.toJsonString(data));
-    }
+    @NotBlank(groups = {CreateGroup.class, UpdateGroup.class})
+    private String username;
+}
 
-    // ✅ 好的：敏感信息脱敏
-    log.info("用户登录，手机: {}", DesensitizedUtil.mobilePhone(phone));
+// Controller 使用
+@PostMapping
+public Result<Long> create(@Validated(CreateGroup.class) @RequestBody UserDTO dto) { ... }
 
-    // ❌ 不好：记录敏感信息
-    log.info("用户登录，手机: {}", phone);
-}
+@PutMapping("/{id}")
+public Result<Void> update(@Validated(UpdateGroup.class) @RequestBody UserDTO dto) { ... }
 ```
 
-### Service 层日志示例
+### 5. Service 层异常使用
 
 ```java
-@Slf4j
-@RequiredArgsConstructor
 @Service
-public class SysUserServiceImpl implements ISysUserService {
-
-    private final SysUserMapper baseMapper;
+public class UserServiceImpl implements IUserService {
 
     @Override
-    @Transactional(rollbackFor = Exception.class)
-    public Long insertUser(SysUserBo bo) {
-        log.info("开始新增用户，用户名: {}", bo.getUserName());
-
-        // 1. 业务校验
-        SysUser existUser = baseMapper.selectUserByUserName(bo.getUserName());
-        if (ObjectUtil.isNotNull(existUser)) {
-            throw new ServiceException("用户名 {} 已存在", bo.getUserName());
+    public UserVO getById(Long id) {
+        User user = userMapper.selectById(id);
+        if (user == null) {
+            throw NotFoundException.of("用户", id);
         }
-
-        // 2. 执行插入
-        SysUser user = MapstructUtils.convert(bo, SysUser.class);
-        baseMapper.insert(user);
-
-        log.info("新增用户成功，用户ID: {}, 用户名: {}", user.getUserId(), user.getUserName());
-        return user.getUserId();
+        // ... 转换为 VO
+        return userVO;
     }
 
     @Override
-    public SysUserVo selectUserById(Long userId) {
-        SysUser user = baseMapper.selectById(userId);
-        if (ObjectUtil.isNull(user)) {
-            throw new ServiceException("用户 {} 不存在", userId);
+    public void updateEmail(Long id, String email) {
+        // 检查邮箱是否已被使用
+        User existing = userMapper.selectByEmail(email);
+        if (existing != null && !existing.getId().equals(id)) {
+            throw new BusinessException(409, "邮箱已被其他用户使用");
         }
-        return MapstructUtils.convert(user, SysUserVo.class);
+        // ... 更新逻辑
     }
 }
 ```
 
----
-
-## 5. 错误码设计
-
-### 错误码规范
+### 6. 日志规范
 
 ```java
-// 格式: 模块(2位) + 类型(2位) + 序号(2位)
-// 模块: 10-系统, 20-用户, 30-订单, 40-商品
-// 类型: 01-参数错误, 02-业务错误, 03-权限错误, 04-系统错误
-
-public class ErrorCode {
-    // 通用错误
-    public static final int SUCCESS = 200;
-    public static final int ERROR = 500;
-    public static final int UNAUTHORIZED = 401;
-    public static final int FORBIDDEN = 403;
-
-    // 用户模块 20xxxx
-    public static final int USER_NOT_FOUND = 200201;      // 用户不存在
-    public static final int USER_PASSWORD_ERROR = 200202; // 密码错误
-    public static final int USER_DISABLED = 200203;       // 用户已禁用
-
-    // 订单模块 30xxxx
-    public static final int ORDER_NOT_FOUND = 300201;     // 订单不存在
-    public static final int ORDER_STATUS_ERROR = 300202;  // 订单状态错误
-}
-
-// 使用示例
-throw new ServiceException("用户不存在", ErrorCode.USER_NOT_FOUND);
-```
-
-### 错误消息国际化
-
-```java
-import org.dromara.common.core.utils.MessageUtils;
-
-// 使用 MessageUtils.message() 获取国际化消息
-throw new ServiceException(MessageUtils.message("user.not.exists"));
-
-// 带参数的国际化消息
-throw new ServiceException(MessageUtils.message("user.password.retry.limit.exceed", maxRetryCount));
-```
-
----
-
-## 6. 用户友好提示
-
-### 错误提示规范
-
-```java
-// ✅ 好的：用户友好提示
-throw new ServiceException("订单已发货，无法取消");
-throw new ServiceException("库存不足，请减少购买数量");
-throw new ServiceException("验证码已过期，请重新获取");
-throw new ServiceException("该用户名已被注册，请换一个试试");
-
-// ❌ 不好：技术术语
-throw new ServiceException("order.status.invalid");
-throw new ServiceException("NullPointerException at line 123");
-throw new ServiceException("数据库连接失败");
-throw new ServiceException("Duplicate entry for key 'uk_username'");
-```
+@Slf4j
+@Service
+public class OrderServiceImpl {
 
----
+    // 使用占位符（性能更好）
+    log.info("创建订单: orderNo={}, amount={}", dto.getOrderNo(), dto.getAmount());
 
-## 7. 事务异常处理
+    // 异常日志带堆栈（第三个参数传异常对象）
+    log.error("处理失败: {}", e.getMessage(), e);
 
-```java
-@Transactional(rollbackFor = Exception.class)  // 所有异常都回滚
-public void batchOperation() {
-    // 业务逻辑
+    // 事务方法：所有异常都回滚
+    @Transactional(rollbackFor = Exception.class)
+    public void createOrder(OrderCreateDTO dto) {
+        log.info("开始创建订单, orderNo={}", dto.getOrderNo());
+        // ... 业务逻辑
+        log.info("订单创建成功, id={}", order.getId());
+    }
 }
-
-// ✅ 好的：指定回滚异常类型
-@Transactional(rollbackFor = Exception.class)
-
-// ❌ 不好：使用默认（只回滚 RuntimeException）
-@Transactional
 ```
 
----
-
-## 错误处理检查清单
-
-- [ ] 业务异常使用 `new ServiceException()`（不是 `ServiceException.of()`）
-- [ ] 条件检查使用 `if + ObjectUtil.isNull()` 判断
-- [ ] 参数校验使用 `@Validated(XxxGroup.class)`
-- [ ] 事务方法添加 `@Transactional(rollbackFor = Exception.class)`
-- [ ] 日志记录异常堆栈：`log.error("msg: {}", e.getMessage(), e)`
-- [ ] 日志使用占位符 `{}`，不使用字符串拼接
-- [ ] 敏感信息脱敏后再记录日志
-- [ ] 重要操作记录 INFO 日志
-- [ ] 错误提示使用用户友好语言
-
----
+## 常见错误
 
-## 快速对照表
-
-| ❌ 错误写法 | ✅ 正确写法 |
-|-----------|-----------|
-| `throw ServiceException.of("msg")` | `throw new ServiceException("msg")` |
-| `ServiceException.throwIf(cond, "msg")` | `if (cond) { throw new ServiceException("msg"); }` |
-| `ServiceException.notNull(obj, "msg")` | `if (ObjectUtil.isNull(obj)) { throw new ServiceException("msg"); }` |
-| `log.error("失败: " + e.getMessage())` | `log.error("失败: {}", e.getMessage(), e)` |
-| `@Transactional` | `@Transactional(rollbackFor = Exception.class)` |
-| `throw new ServiceException("DB error")` | `throw new ServiceException("数据保存失败，请重试")` |
-
----
-
-## 相关技能
-
-| 需要了解 | 激活 Skill |
-|---------|-----------|
-| Java 异常规范 | `java-exception` |
-| Service 层规范 | `java-service` |
-| Controller 层规范 | `java-controller` |
+| 错误 | 正确做法 |
+|------|---------|
+| 抛 `RuntimeException("xxx")` | 使用自定义业务异常类 |
+| Controller 里 try-catch 所有异常 | 交给 `@RestControllerAdvice` 统一处理 |
+| 异常信息暴露 SQL / 堆栈 | 对用户返回友好提示，日志记录完整信息 |
+| 用 `javax.validation` 包 | JDK 17+ 使用 `jakarta.validation` |
+| 吞掉异常：`catch (Exception e) {}` | 至少记录日志 `log.error("...", e)` |
+| 所有异常都返回 200 状态码 | 根据异常类型返回对应 HTTP 状态码 |
+| 用 `e.getMessage()` 直接返回给用户 | 第三方异常信息可能包含敏感信息，需要包装 |
+| 校验逻辑写在 Controller 里 | 用 `@Valid` + DTO 注解声明式校验 |
+| 日志用字符串拼接 `"失败:" + msg` | 用占位符 `log.error("失败: {}", msg, e)` |
+| `@Transactional` 不指定回滚 | 加 `rollbackFor = Exception.class` |