Springboot3统一返回类设计全过程(从问题到实现)

public enum ResultCode {
    // 成功状态
    SUCCESS(200, "操作成功"),
    // 客户端错误
    PARAM_ERROR(400, "参数格式错误"),
    AUTH_FAILED(401, "认证失败"),
    // 服务端错误
    SYSTEM_ERROR(500, "系统异常");
    private final int code;
    private final String message;
    // 构造方法、getter 略
}

import lombok.AllArgsConstructor;
import lombok.Getter;
@Getter
@AllArgsConstructor
public enum ResultCode {
    // 成功
    SUCCESS(200, "操作成功"),
    // 客户端错误
    PARAM_ERROR(400, "参数格式错误"),
    AUTH_FAILED(401, "认证失败"),
    FORBIDDEN(403, "没有权限"),
    NOT_FOUND(404, "资源不存在"),
    // 服务端错误
    SYSTEM_ERROR(500, "系统异常"),
    REMOTE_CALL_FAILED(501, "远程调用失败");
    private final int code;
    private final String message;
}

import lombok.Data;
import java.time.Instant;
@Data
public class R<T> {
    private int code;
    private String message;
    private T data;
    private long timestamp;
    // 私有构造，避免直接 new
    private R(int code, String message, T data) {
        this.code = code;
        this.message = message;
        this.data = data;
        this.timestamp = Instant.now().toEpochMilli(); // 自动填充时间戳
    }
    // 成功响应：无数据
    public static <T> R<T> success() {
        return new R<>(ResultCode.SUCCESS.getCode(), ResultCode.SUCCESS.getMessage(), null);
    }
    // 成功响应：带数据
    public static <T> R<T> success(T data) {
        return new R<>(ResultCode.SUCCESS.getCode(), ResultCode.SUCCESS.getMessage(), data);
    }
    // 错误响应：使用枚举定义的状态
    public static <T> R<T> error(ResultCode code) {
        return new R<>(code.getCode(), code.getMessage(), null);
    }
    // 错误响应：自定义状态码和消息
    public static <T> R<T> error(int code, String message) {
        return new R<>(code, message, null);
    }
}

import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
@RestControllerAdvice
public class GlobalExceptionHandler {
    // 处理自定义业务异常（假设定义了 BusinessException）
    @ExceptionHandler(BusinessException.class)
    public R<Void> handleBusinessException(BusinessException e) {
        // 业务异常通常携带具体错误码和消息
        return R.error(e.getCode(), e.getMessage());
    }
    // 处理参数绑定异常（如 @RequestParam 格式错误）
    @ExceptionHandler(IllegalArgumentException.class)
    public R<Void> handleIllegalArgument(IllegalArgumentException e) {
        return R.error(ResultCode.PARAM_ERROR.getCode(), e.getMessage());
    }
    // 处理所有未捕获的异常（兜底）
    @ExceptionHandler(Exception.class)
    public R<Void> handleException(Exception e) {
        // 生产环境可记录日志，此处简化
        return R.error(ResultCode.SYSTEM_ERROR);
    }
}

import lombok.Data;
import java.util.List;
@Data
public class PageResult<T> {
    private long total; // 总条数
    private int pageNum; // 当前页
    private int pageSize; // 每页大小
    private List<T> list; // 数据列表
    // 构造方法略
}

PageResult<User> pageResult = new PageResult<>(total, pageNum, pageSize, userList);
return R.success(pageResult);

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class UserController {
    @GetMapping("/user")
    public R<User> getUser(@RequestParam Long id) {
        if (id == null || id <= 0) {
            // 参数错误，返回错误响应
            return R.error(ResultCode.PARAM_ERROR);
        }
        User user = userService.getUserById(id); // 假设从服务层获取用户
        if (user == null) {
            // 资源不存在，返回自定义消息
            return R.error(ResultCode.NOT_FOUND.getCode(), "用户不存在");
        }
        // 成功返回数据
        return R.success(user);
    }
}

// 成功带数据
{
  "code": 200,
  "message": "操作成功",
  "data": { "id": 1, "name": "张三" },
  "timestamp": 1711234567890
}
// 失败
{
  "code": 404,
  "message": "用户不存在",
  "data": null,
  "timestamp": 1711234567900
}