@GetMapping("/users/{id}")
public User getUser(@PathVariable Long id) {
    return userService.getUserById(id);
}

@DeleteMapping("/users/{id}")
public String deleteUser(@PathVariable Long id) {
    userService.deleteById(id);
    return "删除成功";
}

@PostMapping("/users")
public Map<String, Object> createUser(@RequestBody User user) {
    Map<String, Object> result = new HashMap<>();
    try {
        userService.save(user);
        result.put("success", true);
        result.put("msg", "创建成功");
    } catch (Exception e) {
        result.put("success", false);
        result.put("error", e.getMessage());
    }
    return result;
}

// 开发者 A 的风格
return Map.of("code", 200, "data", user);

// 开发者 B 的风格
return Map.of("status", "ok", "result", user);

// 开发者 C 的风格
return Map.of("errcode", 0, "errmsg", "success", "data", user);

@PostMapping("/users")
public ResponseEntity<String> register(@RequestBody UserDTO dto) {
    if (userService.existsByUsername(dto.getUsername())) {
        return ResponseEntity.status(400).body("用户名已存在");
    }
    userService.save(dto);
    return ResponseEntity.ok("注册成功");
}

@PostMapping("/users")
public Result<Void> register(@RequestBody @Validated UserDTO dto) {
    userService.register(dto); // 内部会抛出 BusinessException
    return Result.success();
}

// Service 层
public void register(UserDTO dto) {
    if (existsByUsername(dto.getUsername())) {
        throw new BusinessException(ResultCode.USER_ALREADY_EXIST); // 业务状态码 5002
    }
    save(dto);
}

package com.example.demo.common;

import lombok.AllArgsConstructor;
import lombok.Getter;

/**
 * 统一响应状态码枚举
 * 
 * 设计原则：
 * 1. 200 表示业务处理成功
 * 2. 500 表示系统内部错误（如空指针、数据库异常等非预期错误）
 * 3. 4xxx 表示客户端问题（参数错误、权限不足等）
 * 4. 5xxx 表示业务逻辑校验未通过（用户不存在、库存不足等预期内的业务问题）
 */
@Getter
@AllArgsConstructor
public enum ResultCode {
    
    // ==================== 通用状态 ====================
    
    /**
     * 操作成功
     */
    SUCCESS(200, "操作成功"),
    
    /**
     * 系统内部错误
     * 注意：此消息会返回给前端，因此使用模糊化的描述，具体错误信息通过日志记录
     */
    FAILURE(500, "系统繁忙，请稍后重试"),
    
    // ==================== 客户端错误 (4000-4999) ====================
    
    /**
     * 参数校验失败
     * 由 JSR-303 校验框架触发
     */
    PARAM_VALID_ERROR(4000, "参数校验失败"),
    
    /**
     * 未登录或 Token 已失效
     */
    UNAUTHORIZED(4001, "您还未登录或登录已失效，请重新登录"),
    
    /**
     * 无权限访问
     */
    FORBIDDEN(4003, "您没有权限执行此操作"),
    
    /**
     * 请求的资源不存在
     */
    NOT_FOUND(4004, "请求的资源不存在"),
    
    /**
     * 请求方法不支持
     * 例如：接口只支持 POST，但客户端发送了 GET 请求
     */
    METHOD_NOT_SUPPORTED(4005, "不支持该请求方法"),
    
    /**
     * 请求的 Content-Type 不支持
     */
    MEDIA_TYPE_NOT_SUPPORTED(4006, "不支持的媒体类型"),
    
    // ==================== 业务逻辑错误 (5000-5999) ====================
    
    // --- 用户模块 (5001-5099) ---
    
    /**
     * 用户不存在
     */
    USER_NOT_EXIST(5001, "用户不存在"),
    
    /**
     * 用户已存在（注册时用户名或邮箱重复）
     */
    USER_ALREADY_EXIST(5002, "用户名或邮箱已被注册"),
    
    /**
     * 账号已被冻结
     */
    USER_ACCOUNT_LOCKED(5003, "您的账号已被冻结，请联系管理员"),
    
    /**
     * 用户名或密码错误
     */
    USER_PASSWORD_ERROR(5004, "用户名或密码错误"),
    
    /**
     * 验证码错误
     */
    USER_VERIFY_CODE_ERROR(5005, "验证码错误或已失效"),
    
    // --- 订单模块 (5101-5199) ---
    
    /**
     * 库存不足
     */
    ORDER_STOCK_NOT_ENOUGH(5101, "商品库存不足"),
    
    /**
     * 订单状态异常（例如：已取消的订单无法支付）
     */
    ORDER_STATUS_INVALID(5102, "订单状态异常，无法执行此操作"),
    
    /**
     * 订单不存在
     */
    ORDER_NOT_EXIST(5103, "订单不存在"),
    
    // --- 支付模块 (5201-5299) ---
    
    /**
     * 余额不足
     */
    BALANCE_NOT_ENOUGH(5201, "账户余额不足"),
    
    /**
     * 第三方支付服务异常
     */
    THIRD_PARTY_SERVICE_ERROR(5202, "支付服务暂时不可用，请稍后重试");

    /**
     * 状态码
     */
    private final int code;
    
    /**
     * 提示信息
     */
    private final String message;
}

package com.example.demo.common;

import com.fasterxml.jackson.annotation.JsonInclude;
import lombok.Getter;

/**
 * 统一 API 响应结果封装
 * 
 * 设计原则：
 * 1. 所有接口统一返回此类型
 * 2. 成功和失败使用相同的 JSON 结构
 * 3. 使用泛型 T 保证类型安全
 * 4. data 为 null 时不序列化该字段（通过 @JsonInclude 实现）
 * 
 * @param <T> 响应数据的类型
 */
@Getter
@JsonInclude(JsonInclude.Include.NON_NULL)
public class Result<T> {

    /**
     * 业务状态码
     * 200 表示成功，其他表示失败
     */
    private final int code;

    /**
     * 提示信息
     * 成功时通常是 "操作成功"
     * 失败时是具体的错误提示（如 "用户名已存在"）
     */
    private final String message;

    /**
     * 响应数据
     * 查询操作时返回查询结果
     * 新增操作时可以返回新增对象的 ID
     * 删除、修改操作时通常为 null
     */
    private final T data;

    /**
     * 响应时间戳（毫秒）
     * 用于前端显示响应时间，或后端排查问题时关联日志
     */
    private final long timestamp;

    /**
     * 私有构造器，禁止外部直接 new
     * 强制使用静态工厂方法创建对象，确保字段完整性
     */
    private Result(int code, String message, T data) {
        this.code = code;
        this.message = message;
        this.data = data;
        this.timestamp = System.currentTimeMillis();
    }

    // ==================== 成功响应工厂方法 ====================

    /**
     * 成功响应，无返回数据
     * 
     * 适用场景：
     * - 删除操作
     * - 更新操作
     * - 其他不需要返回业务数据的操作
     * 
     * 响应示例：
     * {
     *   "code": 200,
     *   "message": "操作成功",
     *   "timestamp": 1734422400000
     * }
     * 
     * @return Result对象
     */
    public static <T> Result<T> success() {
        return new Result<>(
            ResultCode.SUCCESS.getCode(), 
            ResultCode.SUCCESS.getMessage(), 
            null
        );
    }

    /**
     * 成功响应，带返回数据
     * 
     * 适用场景：
     * - 查询操作（返回查询结果）
     * - 新增操作（返回新增对象的ID或完整对象）
     * 
     * 响应示例：
     * {
     *   "code": 200,
     *   "message": "操作成功",
     *   "data": { "id": 1, "username": "zhangsan" },
     *   "timestamp": 1734422400000
     * }
     * 
     * @param data 业务数据
     * @return Result对象
     */
    public static <T> Result<T> success(T data) {
        return new Result<>(
            ResultCode.SUCCESS.getCode(), 
            ResultCode.SUCCESS.getMessage(), 
            data
        );
    }

    /**
     * 成功响应，自定义提示信息
     * 
     * 适用场景：
     * - 需要返回特定提示语的成功操作
     * 
     * 响应示例：
     * {
     *   "code": 200,
     *   "message": "邮件发送成功",
     *   "timestamp": 1734422400000
     * }
     * 
     * @param message 自定义提示信息
     * @return Result对象
     */
    public static <T> Result<T> success(String message) {
        return new Result<>(
            ResultCode.SUCCESS.getCode(), 
            message, 
            null
        );
    }

    /**
     * 成功响应，自定义提示信息 + 返回数据
     * 
     * @param message 自定义提示信息
     * @param data 业务数据
     * @return Result对象
     */
    public static <T> Result<T> success(String message, T data) {
        return new Result<>(
            ResultCode.SUCCESS.getCode(), 
            message, 
            data
        );
    }

    // ==================== 失败响应工厂方法 ====================

    /**
     * 失败响应，使用枚举定义的状态码和消息
     * 
     * 适用场景：
     * - 标准的业务错误（如用户不存在、权限不足等）
     * 
     * 响应示例：
     * {
     *   "code": 5001,
     *   "message": "用户不存在",
     *   "timestamp": 1734422400000
     * }
     * 
     * @param resultCode 状态码枚举
     * @return Result对象
     */
    public static <T> Result<T> error(ResultCode resultCode) {
        return new Result<>(
            resultCode.getCode(), 
            resultCode.getMessage(), 
            null
        );
    }

    /**
     * 失败响应，使用枚举的状态码，但覆盖消息
     * 
     * 适用场景：
     * - 需要在枚举定义的基础上，提供更详细的错误信息
     * - 例如：ResultCode.PARAM_VALID_ERROR 默认是 "参数校验失败"，
     *   但我们需要告诉前端具体哪个字段错误
     * 
     * 响应示例：
     * {
     *   "code": 4000,
     *   "message": "用户名长度需在4-20字符之间",
     *   "timestamp": 1734422400000
     * }
     * 
     * @param resultCode 状态码枚举
     * @param customMessage 自定义错误信息
     * @return Result对象
     */
    public static <T> Result<T> error(ResultCode resultCode, String customMessage) {
        return new Result<>(
            resultCode.getCode(), 
            customMessage, 
            null
        );
    }

    /**
     * 失败响应，完全自定义状态码和消息
     * 
     * 注意：此方法应该谨慎使用，优先使用枚举定义的状态码
     * 
     * 适用场景：
     * - 处理第三方服务返回的错误码
     * - 临时测试
     * 
     * @param code 状态码
     * @param message 错误信息
     * @return Result对象
     */
    public static <T> Result<T> error(int code, String message) {
        return new Result<>(code, message, null);
    }

    /**
     * 失败响应，带错误数据
     * 
     * 适用场景：
     * - 参数校验失败时，返回字段级的错误信息
     * 
     * 响应示例：
     * {
     *   "code": 4000,
     *   "message": "参数校验失败",
     *   "data": {
     *     "username": "用户名长度需在4-20字符之间",
     *     "email": "邮箱格式不正确"
     *   },
     *   "timestamp": 1734422400000
     * }
     * 
     * @param resultCode 状态码枚举
     * @param data 错误数据（通常是 Map 结构）
     * @return Result对象
     */
    public static <T> Result<T> error(ResultCode resultCode, T data) {
        return new Result<>(
            resultCode.getCode(), 
            resultCode.getMessage(), 
            data
        );
    }

    /**
     * 失败响应，自定义消息 + 错误数据
     * 
     * @param resultCode 状态码枚举
     * @param customMessage 自定义错误信息
     * @param data 错误数据
     * @return Result对象
     */
    public static <T> Result<T> error(ResultCode resultCode, String customMessage, T data) {
        return new Result<>(
            resultCode.getCode(), 
            customMessage, 
            data
        );
    }
}

package com.example.demo.controller;

import com.example.demo.common.Result;
import com.example.demo.dto.UserDTO;
import com.example.demo.service.UserService;
import jakarta.validation.Valid;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping("/users")
@RequiredArgsConstructor
public class UserController {

    private final UserService userService;

    /**
     * 查询用户列表
     * 返回类型：Result<List<UserDTO>>
     */
    @GetMapping
    public Result<List<UserDTO>> listUsers() {
        List<UserDTO> users = userService.listAll();
        return Result.success(users);
    }

    /**
     * 根据ID查询用户
     * 返回类型：Result<UserDTO>
     */
    @GetMapping("/{id}")
    public Result<UserDTO> getUser(@PathVariable Long id) {
        // Service 层如果找不到用户，会抛出 BusinessException
        // 异常会被全局异常处理器捕获，自动转换为错误响应
        UserDTO user = userService.getById(id);
        return Result.success(user);
    }

    /**
     * 新增用户
     * 返回类型：Result<Long>（返回新增用户的ID）
     */
    @PostMapping
    public Result<Long> createUser(@RequestBody @Valid UserDTO dto) {
        Long userId = userService.create(dto);
        return Result.success(userId);
    }

    /**
     * 更新用户
     * 返回类型：Result<Void>（无返回数据）
     */
    @PutMapping("/{id}")
    public Result<Void> updateUser(
        @PathVariable Long id, 
        @RequestBody @Valid UserDTO dto
    ) {
        userService.update(id, dto);
        return Result.success();
    }

    /**
     * 删除用户
     * 返回类型：Result<Void>
     */
    @DeleteMapping("/{id}")
    public Result<Void> deleteUser(@PathVariable Long id) {
        userService.deleteById(id);
        return Result.success("用户删除成功");
    }
}

// 定义一个受检异常
public class BusinessException extends Exception {
    public BusinessException(String message) {
        super(message);
    }
}

// Service 层代码
public void register(UserDTO dto) throws BusinessException {  // 必须声明 throws
    if (existsByUsername(dto.getUsername())) {
        throw new BusinessException("用户名已存在");
    }
    save(dto);
}

// Controller 层代码
@PostMapping("/register")
public Result<Void> register(@RequestBody @Valid UserDTO dto) {
    try {
        userService.register(dto);  // 必须 try-catch
        return Result.success();
    } catch (BusinessException e) {
        return Result.error(5002, e.getMessage());
    }
}

@Transactional
public void register(UserDTO dto) throws BusinessException {
    userMapper.insert(dto);  // 插入数据
    if (condition) {
        throw new BusinessException("xxx");
    }
}

@Transactional(rollbackFor = BusinessException.class)

// A 方法
public void methodA() throws BusinessException {
    methodB();
}

// B 方法
public void methodB() throws BusinessException {
    methodC();
}

// C 方法抛出异常
public void methodC() throws BusinessException {
    throw new BusinessException("错误");
}

// 定义一个非受检异常
public class BusinessException extends RuntimeException {
    private final int code;
    
    public BusinessException(ResultCode resultCode) {
        super(resultCode.getMessage());
        this.code = resultCode.getCode();
    }
}

// Service 层代码（无需 throws）
public void register(UserDTO dto) {
    if (existsByUsername(dto.getUsername())) {
        throw new BusinessException(ResultCode.USER_ALREADY_EXIST);
    }
    save(dto);
}

// Controller 层代码（无需 try-catch，交给全局异常处理器）
@PostMapping("/register")
public Result<Void> register(@RequestBody @Valid UserDTO dto) {
    userService.register(dto);
    return Result.success();
}

@Transactional  // 无需额外配置
public void register(UserDTO dto) {
    userMapper.insert(dto);
    if (condition) {
        throw new BusinessException(ResultCode.USER_ALREADY_EXIST);
    }
    // 抛出异常后，上面的 insert 会自动回滚
}

package com.example.demo.exception;

import com.example.demo.common.ResultCode;
import lombok.Getter;

/**
 * 自定义业务异常
 * 
 * 设计原则：
 * 1. 继承 RuntimeException，不需要强制捕获
 * 2. 携带业务状态码，方便全局异常处理器识别
 * 3. 用于表示"预期内的业务逻辑错误"，区别于系统故障
 * 
 * 使用场景：
 * - 用户不存在
 * - 用户名已存在
 * - 库存不足
 * - 余额不足
 * - 权限不足
 * 等所有可以预见的业务规则校验失败的情况
 */
@Getter
public class BusinessException extends RuntimeException {
    
    /**
     * 业务状态码
     */
    private final int code;

    /**
     * 构造器1：使用枚举（推荐）
     * 
     * 示例：
     * throw new BusinessException(ResultCode.USER_NOT_EXIST);
     * 
     * @param resultCode 状态码枚举
     */
    public BusinessException(ResultCode resultCode) {
        super(resultCode.getMessage());
        this.code = resultCode.getCode();
    }

    /**
     * 构造器2：使用枚举 + 自定义消息
     * 
     * 适用场景：需要在枚举定义的基础上，提供更详细的错误信息
     * 
     * 示例：
     * throw new BusinessException(
     *     ResultCode.PARAM_VALID_ERROR, 
     *     "用户名长度必须在4-20字符之间"
     * );
     * 
     * @param resultCode 状态码枚举
     * @param message 自定义错误信息
     */
    public BusinessException(ResultCode resultCode, String message) {
        super(message);
        this.code = resultCode.getCode();
    }

    /**
     * 构造器3：完全自定义（谨慎使用）
     * 
     * 注意：此构造器应该尽量避免使用，优先使用枚举定义的状态码
     * 
     * @param code 状态码
     * @param message 错误信息
     */
    public BusinessException(int code, String message) {
        super(message);
        this.code = code;
    }

    /**
     * 构造器4：包装原始异常（用于异常转换）
     * 
     * 适用场景：
     * - 调用第三方服务时，将第三方异常转换为我方业务异常
     * 
     * 示例：
     * try {
     *     wxApiClient.pay(order);
     * } catch (WxApiException e) {
     *     throw new BusinessException(
     *         ResultCode.THIRD_PARTY_SERVICE_ERROR, 
     *         "支付服务暂时不可用", 
     *         e
     *     );
     * }
     * 
     * @param resultCode 状态码枚举
     * @param message 错误信息
     * @param cause 原始异常
     */
    public BusinessException(ResultCode resultCode, String message, Throwable cause) {
        super(message, cause);
        this.code = resultCode.getCode();
    }
}

@Service
public class UserService {

    @Autowired
    private UserMapper userMapper;

    public UserDTO getById(Long id) {
        User user = userMapper.selectById(id);
        if (user == null) {
            // 直接抛出业务异常，无需返回 null 或 Optional
            throw new BusinessException(ResultCode.USER_NOT_EXIST);
        }
        return convertToDTO(user);
    }
}

// 传统做法1：返回 null
public UserDTO getById(Long id) {
    User user = userMapper.selectById(id);
    if (user == null) {
        return null;  // Controller 层需要判断 null
    }
    return convertToDTO(user);
}

// 传统做法2：返回 Optional
public Optional<UserDTO> getById(Long id) {
    User user = userMapper.selectById(id);
    return Optional.ofNullable(user)
                   .map(this::convertToDTO);  // Controller 层需要判断 isPresent
}

// 传统做法3：返回 Result
public Result<UserDTO> getById(Long id) {
    User user = userMapper.selectById(id);
    if (user == null) {
        return Result.error(ResultCode.USER_NOT_EXIST);  // Service 层返回 Result，职责混乱
    }
    return Result.success(convertToDTO(user));
}

public void register(UserDTO dto) {
    // 校验用户名是否已存在
    if (userMapper.existsByUsername(dto.getUsername())) {
        throw new BusinessException(ResultCode.USER_ALREADY_EXIST);
    }
    
    // 校验邮箱是否已被注册
    if (userMapper.existsByEmail(dto.getEmail())) {
        throw new BusinessException(
            ResultCode.USER_ALREADY_EXIST, 
            "该邮箱已被注册"
        );
    }
    
    // 如果走到这里，说明校验都通过了
    User user = convertToEntity(dto);
    userMapper.insert(user);
}

@Transactional
public void transfer(Long fromId, Long toId, BigDecimal amount) {
    // 1. 扣减转出方余额
    Account fromAccount = accountMapper.selectById(fromId);
    if (fromAccount.getBalance().compareTo(amount) < 0) {
        // 抛出异常后，事务自动回滚，上面的所有数据库操作都会撤销
        throw new BusinessException(ResultCode.BALANCE_NOT_ENOUGH);
    }
    fromAccount.setBalance(fromAccount.getBalance().subtract(amount));
    accountMapper.updateById(fromAccount);
    
    // 2. 增加转入方余额
    Account toAccount = accountMapper.selectById(toId);
    toAccount.setBalance(toAccount.getBalance().add(amount));
    accountMapper.updateById(toAccount);
    
    // 如果这里抛出任何 RuntimeException，上面的两次 update 都会回滚
}

public void sendSms(String mobile, String code) {
    try {
        // 调用第三方短信服务
        smsClient.send(mobile, code);
    } catch (SmsClientException e) {
        // 将第三方异常转换为我方业务异常
        // 这样全局异常处理器可以统一处理
        log.error("短信发送失败, mobile: {}", mobile, e);
        throw new BusinessException(
            ResultCode.THIRD_PARTY_SERVICE_ERROR, 
            "短信发送失败，请稍后重试",
            e  // 保留原始异常，方便排查问题
        );
    }
}

@RestControllerAdvice = @ControllerAdvice + @ResponseBody

// 默认作用于所有 Controller
@RestControllerAdvice
public class GlobalExceptionHandler { }

// 指定作用于某个包下的 Controller
@RestControllerAdvice(basePackages = "com.example.demo.controller")
public class GlobalExceptionHandler { }

// 指定作用于某些注解标注的类
@RestControllerAdvice(annotations = RestController.class)
public class GlobalExceptionHandler { }

package com.example.demo.handler;

import com.example.demo.common.Result;
import com.example.demo.common.ResultCode;
import com.example.demo.exception.BusinessException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.validation.ConstraintViolation;
import jakarta.validation.ConstraintViolationException;
import lombok.extern.slf4j.Slf4j;
import org.springframework.http.HttpStatus;
import org.springframework.validation.BindingResult;
import org.springframework.validation.FieldError;
import org.springframework.web.HttpMediaTypeNotSupportedException;
import org.springframework.web.HttpRequestMethodNotSupportedException;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.servlet.NoHandlerFoundException;

import java.util.HashMap;
import java.util.Map;
import java.util.Set;
import java.util.stream.Collectors;

/**
 * 全局异常处理器
 * 
 * 作用：
 * 1. 统一捕获所有 Controller 抛出的异常
 * 2. 将异常转换为标准的 Result 格式
 * 3. 记录异常日志，方便排查问题
 * 4. 向前端返回友好的错误提示，避免暴露技术细节
 * 
 * 注意事项：
 * 1. @ExceptionHandler 的处理顺序：从具体到抽象（子类异常优先于父类异常）
 * 2. 多个 Handler 可以处理同一个异常，但只有最具体的那个会生效
 * 3. 日志级别：业务异常用 WARN，系统异常用 ERROR
 */
@Slf4j
@RestControllerAdvice
public class GlobalExceptionHandler {

    // ==================== 1. 参数校验异常 (JSR-303) ====================

    /**
     * 处理 @RequestBody 参数校验失败抛出的异常
     * 
     * 触发场景：
     * - Controller 方法参数前有 @Valid 或 @Validated 注解
     * - 请求体中的字段不满足 DTO 上定义的校验规则
     * 
     * 示例：
     * @PostMapping("/users")
     * public Result<Void> create(@RequestBody @Validated UserDTO dto) { }
     * 
     * 如果 dto 中的 username 为空，会抛出此异常
     */
    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)  // HTTP 400
    public Result<Map<String, String>> handleMethodArgumentNotValidException(
        MethodArgumentNotValidException e
    ) {
        BindingResult bindingResult = e.getBindingResult();
        
        // 提取所有字段错误信息，构建成 Map
        // 格式：{ "fieldName": "errorMessage" }
        Map<String, String> errors = new HashMap<>();
        for (FieldError fieldError : bindingResult.getFieldErrors()) {
            String fieldName = fieldError.getField();
            String errorMessage = fieldError.getDefaultMessage();
            errors.put(fieldName, errorMessage);
        }
        
        // WARN 级别日志：这是客户端传参问题，不是服务器故障
        log.warn("请求体参数校验失败, URI: {}, 错误详情: {}", 
            getCurrentRequestURI(), errors);
        
        // 返回字段级的错误信息
        return Result.error(ResultCode.PARAM_VALID_ERROR, errors);
    }

    /**
     * 处理 @PathVariable 和 @RequestParam 参数校验失败抛出的异常
     * 
     * 触发场景：
     * - Controller 类上有 @Validated 注解
     * - @PathVariable 或 @RequestParam 参数前有校验注解（如 @Min, @NotBlank）
     * 
     * 示例：
     * @RestController
     * @RequestMapping("/users")
     * @Validated
     * public class UserController {
     *     @GetMapping("/{id}")
     *     public Result<UserDTO> getUser(@PathVariable @Min(1) Long id) { }
     * }
     * 
     * 如果 id = 0，会抛出此异常
     */
    @ExceptionHandler(ConstraintViolationException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)  // HTTP 400
    public Result<Void> handleConstraintViolationException(
        ConstraintViolationException e
    ) {
        // 提取所有违反约束的错误信息
        Set<ConstraintViolation<?>> violations = e.getConstraintViolations();
        String errorMsg = violations.stream()
            .map(violation -> violation.getMessage())
            .collect(Collectors.joining("; "));
        
        log.warn("URL参数校验失败, URI: {}, 错误信息: {}", 
            getCurrentRequestURI(), errorMsg);
        
        return Result.error(ResultCode.PARAM_VALID_ERROR, errorMsg);
    }

    // ==================== 2. 业务逻辑异常 ====================

    /**
     * 处理 Service 层主动抛出的 BusinessException
     * 
     * 触发场景：
     * - Service 层检测到业务规则不满足，主动抛出异常
     * 
     * 示例：
     * if (user == null) {
     *     throw new BusinessException(ResultCode.USER_NOT_EXIST);
     * }
     * 
     * 特点：
     * - 这是"预期内"的异常，是业务流程的一部分
     * - HTTP 状态码返回 200（通信成功）
     * - 业务状态码返回具体的错误码（如 5001）
     */
    @ExceptionHandler(BusinessException.class)
    @ResponseStatus(HttpStatus.OK)  // HTTP 200（业务层面失败，但通信成功）
    public Result<Void> handleBusinessException(BusinessException e) {
        // WARN 级别日志：记录业务阻断情况，便于统计分析
        log.warn("业务异常, code: {}, message: {}, URI: {}", 
            e.getCode(), e.getMessage(), getCurrentRequestURI());
        
        // 直接返回异常中携带的状态码和消息
        return Result.error(e.getCode(), e.getMessage());
    }

    // ==================== 3. 404 路径不存在异常 ====================

    /**
     * 处理请求路径不存在的异常
     * 
     * 触发场景：
     * - 客户端请求的路径没有对应的 Controller 映射
     * 
     * 前置条件（必须配置）：
     * spring:
     *   mvc:
     *     throw-exception-if-no-handler-found: true
     *   web:
     *     resources:
     *       add-mappings: false
     * 
     * 如果没有上述配置，404 不会抛出异常，而是返回默认错误页
     */
    @ExceptionHandler(NoHandlerFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)  // HTTP 404
    public Result<Void> handleNotFoundException(NoHandlerFoundException e) {
        log.warn("请求路径不存在, Method: {}, URI: {}", 
            e.getHttpMethod(), e.getRequestURL());
        
        String message = String.format(
            "请求路径 [%s %s] 不存在", 
            e.getHttpMethod(), 
            e.getRequestURL()
        );
        
        return Result.error(ResultCode.NOT_FOUND, message);
    }

    // ==================== 4. 请求方法不支持异常 ====================

    /**
     * 处理 HTTP 请求方法不支持的异常
     * 
     * 触发场景：
     * - 接口定义为 POST，但客户端发送了 GET 请求
     * 
     * 示例：
     * @PostMapping("/users")  // 只支持 POST
     * public Result<Void> create(@RequestBody UserDTO dto) { }
     * 
     * 如果客户端发送 GET /users，会抛出此异常
     */
    @ExceptionHandler(HttpRequestMethodNotSupportedException.class)
    @ResponseStatus(HttpStatus.METHOD_NOT_ALLOWED)  // HTTP 405
    public Result<Void> handleMethodNotSupportedException(
        HttpRequestMethodNotSupportedException e
    ) {
        log.warn("请求方法不支持, Method: {}, URI: {}, 支持的方法: {}", 
            e.getMethod(), getCurrentRequestURI(), e.getSupportedHttpMethods());
        
        String message = String.format(
            "不支持 %s 请求，请使用 %s", 
            e.getMethod(), 
            e.getSupportedHttpMethods()
        );
        
        return Result.error(ResultCode.METHOD_NOT_SUPPORTED, message);
    }

    // ==================== 5. Content-Type 不支持异常 ====================

    /**
     * 处理 Content-Type 不支持的异常
     * 
     * 触发场景：
     * - 接口要求 application/json，但客户端发送了 application/x-www-form-urlencoded
     * 
     * 示例：
     * @PostMapping(value = "/users", consumes = "application/json")
     * public Result<Void> create(@RequestBody UserDTO dto) { }
     * 
     * 如果客户端的 Content-Type 不是 application/json，会抛出此异常
     */
    @ExceptionHandler(HttpMediaTypeNotSupportedException.class)
    @ResponseStatus(HttpStatus.UNSUPPORTED_MEDIA_TYPE)  // HTTP 415
    public Result<Void> handleMediaTypeNotSupportedException(
        HttpMediaTypeNotSupportedException e
    ) {
        log.warn("Content-Type 不支持, ContentType: {}, URI: {}, 支持的类型: {}", 
            e.getContentType(), getCurrentRequestURI(), e.getSupportedMediaTypes());
        
        String message = String.format(
            "不支持 %s 格式，请使用 %s", 
            e.getContentType(), 
            e.getSupportedMediaTypes()
        );
        
        return Result.error(ResultCode.MEDIA_TYPE_NOT_SUPPORTED, message);
    }

    // ==================== 6. 系统兜底异常（最重要）====================

    /**
     * 处理所有未被上述 Handler 捕获的异常
     * 
     * 触发场景：
     * - 空指针异常（NullPointerException）
     * - 数据库异常（SQLException）
     * - 第三方服务调用异常
     * - 其他所有未预期的 RuntimeException
     * 
     * 注意事项：
     * 1. 这是最后的兜底Handler，必须放在最后
     * 2. 必须打印完整的异常堆栈，这是排查 Bug 的唯一线索
     * 3. 绝对不能向前端返回 e.getMessage()，避免暴露技术细节
     * 4. 使用 ERROR 级别日志，触发监控告警
     */
    @ExceptionHandler(Exception.class)
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)  // HTTP 500
    public Result<Void> handleSystemException(Exception e) {
        // ERROR 级别日志：这是系统故障，需要立即修复
        // 打印完整堆栈，包括异常链
        log.error("系统发生未处理异常, URI: {}, 异常类型: {}", 
            getCurrentRequestURI(), e.getClass().getName(), e);
        
        // 安全红线：绝不向前端返回技术细节
        // 原因：
        // 1. 用户看不懂技术术语，体验差
        // 2. 可能暴露表结构、SQL语句等敏感信息，给攻击者提供线索
        return Result.error(ResultCode.FAILURE);
    }

    // ==================== 辅助方法 ====================

    /**
     * 获取当前请求的 URI
     * 用于日志记录
     */
    private String getCurrentRequestURI() {
        try {
            HttpServletRequest request = 
                ((org.springframework.web.context.request.ServletRequestAttributes)
                org.springframework.web.context.request.RequestContextHolder
                    .getRequestAttributes())
                .getRequest();
            return request.getRequestURI();
        } catch (Exception e) {
            return "Unknown";
        }
    }
}

import org.springframework.boot.web.servlet.error.ErrorController;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import javax.servlet.http.HttpServletRequest;

@RestController
public class GlobalErrorController implements ErrorController {
    
    /**
     * 接管 /error 路径，处理所有 Spring Boot 转发过来的错误。
     */
    @RequestMapping("/error")
    public Result<Void> handleError(HttpServletRequest request) {
        // 从 request 中获取 HTTP 状态码
        Integer statusCode = (Integer) request.getAttribute("javax.servlet.error.status_code");
        
        // 专门处理 404 Not Found 错误
        if (statusCode != null && statusCode == HttpStatus.NOT_FOUND.value()) {
            return Result.error(ResultCode.NOT_FOUND, "您访问的资源不存在");
        }
        
        // 也可以根据其他状态码返回不同的错误信息
        // if (statusCode == HttpStatus.INTERNAL_SERVER_ERROR.value()) { ... }
        
        // 对于其他所有未特定处理的错误，返回一个通用的失败响应
        return Result.error(ResultCode.FAILURE, "服务器发生未知错误");
    }
}

@Data
public class UserRegisterDTO {
    
    @NotBlank(message = "用户名不能为空")
    @Size(min = 4, max = 20, message = "用户名长度需在4-20字符之间")
    private String username;
    
    @NotBlank(message = "密码不能为空")
    @Pattern(
        regexp = "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)[\\s\\S]{8,16}$",
        message = "密码必须8-16位，且包含大小写字母和数字"
    )
    private String password;
    
    @NotBlank(message = "邮箱不能为空")
    @Email(message = "邮箱格式不正确")
    private String email;
}

@ExceptionHandler(MethodArgumentNotValidException.class)
@ResponseStatus(HttpStatus.BAD_REQUEST)
public Result<Map<String, String>> handleMethodArgumentNotValidException(
    MethodArgumentNotValidException e
) {
    BindingResult bindingResult = e.getBindingResult();
    
    // 关键：构建字段名 -> 错误信息的 Map
    Map<String, String> errors = new HashMap<>();
    for (FieldError fieldError : bindingResult.getFieldErrors()) {
        String fieldName = fieldError.getField();        // "username"
        String errorMessage = fieldError.getDefaultMessage();  // "用户名长度需在4-20字符之间"
        errors.put(fieldName, errorMessage);
    }
    
    log.warn("请求体参数校验失败, URI: {}, 错误详情: {}", 
        getCurrentRequestURI(), errors);
    
    // 将错误 Map 作为 data 返回
    return Result.error(ResultCode.PARAM_VALID_ERROR, errors);
}

@Data
public class OrderDTO {
    
    @NotNull
    private Long productId;
    
    @Valid  // 嵌套对象必须加 @Valid
    @NotNull
    private AddressDTO address;
}

@Data
public class AddressDTO {
    
    @NotBlank(message = "收货人姓名不能为空")
    private String receiverName;
    
    @NotBlank(message = "收货人电话不能为空")
    private String receiverPhone;
}