REST API 设计

REST 是什么

REST（Representational State Transfer，表述性状态转移）不是一种协议或标准，而是 Roy Fielding 在其 2000 年博士论文中提出的软件架构风格。RESTful API 利用 HTTP 协议本身的能力（方法、状态码、URL）来表达资源操作，而无需额外的协议层。

Richardson 成熟度模型将 REST API 分为四个级别：

实际项目中绝大多数团队实现到 Level 2 即认为是"RESTful"，Level 3 的 HATEOAS 因实现成本高而较少使用。

核心注解名词解释

HTTP 方法语义

正确使用 HTTP 方法是 RESTful 设计的基础，每种方法有明确的语义和幂等性要求：

请求处理链（架构图）

完整用户 CRUD API 实现

请求/响应 DTO

// 创建用户请求 DTO（包含校验注解）
@Data  // Lombok：自动生成 getter/setter/toString/equals
public class UserCreateDTO {
    @NotBlank(message = "用户名不能为空")
    @Size(min = 2, max = 20, message = "用户名长度 2-20 位")
    private String username;

    @NotBlank(message = "邮箱不能为空")
    @Email(message = "邮箱格式不正确")
    private String email;

    @NotBlank
    @Size(min = 8, message = "密码至少 8 位")
    @Pattern(regexp = ".*[A-Z].*", message = "密码须含大写字母")
    private String password;
}

// 响应 DTO（不包含密码等敏感字段）
@Data
@Builder
public class UserResponseDTO {
    private Long id;
    private String username;
    private String email;
    private LocalDateTime createdAt;
}

Controller 层

@RestController
@RequestMapping("/users")
@RequiredArgsConstructor  // Lombok：生成包含 final 字段的构造器
public class UserController {

    private final UserService userService;

    // 查询所有用户（支持分页）
    @GetMapping
    public ApiResponse<Page<UserResponseDTO>> listUsers(
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "20") int size) {
        return ApiResponse.ok(userService.findAll(PageRequest.of(page, size)));
    }

    // 查询单个用户
    @GetMapping("/{id}")
    public ApiResponse<UserResponseDTO> getUser(@PathVariable Long id) {
        return ApiResponse.ok(userService.findById(id));
    }

    // 创建用户（@Valid 触发校验）
    @PostMapping
    public ResponseEntity<ApiResponse<UserResponseDTO>> createUser(
            @Valid @RequestBody UserCreateDTO dto) {
        UserResponseDTO created = userService.create(dto);
        URI location = URI.create("/users/" + created.getId());
        return ResponseEntity.created(location).body(ApiResponse.ok(created));
    }

    // 删除用户
    @DeleteMapping("/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void deleteUser(@PathVariable Long id) {
        userService.delete(id);
    }
}

统一响应格式封装

生产级 API 通常会定义一个统一的响应包装类，包含 code（业务状态码）、message（提示信息）和 data（实际数据），方便前端统一处理。

@Data
@AllArgsConstructor
public class ApiResponse<T> {
    private int code;
    private String message;
    private T data;

    public static <T> ApiResponse<T> ok(T data) {
        return new ApiResponse<>(200, "success", data);
    }

    public static <T> ApiResponse<T> error(int code, String message) {
        return new ApiResponse<>(code, message, null);
    }
}

全局异常处理

@RestControllerAdvice  // = @ControllerAdvice + @ResponseBody
public class GlobalExceptionHandler {

    // 处理 @Valid 校验失败
    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public ApiResponse<Map<String, String>> handleValidation(
            MethodArgumentNotValidException ex) {
        Map<String, String> errors = new LinkedHashMap<>();
        ex.getBindingResult().getFieldErrors()
          .forEach(e -> errors.put(e.getField(), e.getDefaultMessage()));
        return ApiResponse.error(400, "参数校验失败");
    }

    // 处理资源不存在
    @ExceptionHandler(EntityNotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public ApiResponse<Void> handleNotFound(EntityNotFoundException ex) {
        return ApiResponse.error(404, ex.getMessage());
    }

    // 处理业务异常
    @ExceptionHandler(BusinessException.class)
    @ResponseStatus(HttpStatus.UNPROCESSABLE_ENTITY)
    public ApiResponse<Void> handleBusiness(BusinessException ex) {
        return ApiResponse.error(ex.getCode(), ex.getMessage());
    }

    // 兜底：处理所有未预期异常
    @ExceptionHandler(Exception.class)
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    public ApiResponse<Void> handleGeneral(Exception ex) {
        // 内部异常不暴露给前端，记录日志
        log.error("Unhandled exception", ex);
        return ApiResponse.error(500, "服务器内部错误");
    }
}