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, "服务器内部错误");
    }
}

HTTP 状态码最佳实践

正确的 HTTP 状态码是 RESTful API 契约的重要组成部分。以下是常见场景与对应状态码的规范使用：

Bean Validation 进阶：自定义校验注解

标准的 @NotBlank、@Email 无法满足复杂业务校验时，可以自定义注解：

// 1. 定义校验注解
@Target({ ElementType.FIELD })
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = PhoneNumberValidator.class)
public @interface ChinesePhone {
    String message() default "手机号格式不正确";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

// 2. 实现校验逻辑
public class PhoneNumberValidator
        implements ConstraintValidator<ChinesePhone, String> {

    // 中国大陆手机号正则：1 开头，第二位 3-9，共 11 位
    private static final Pattern PATTERN =
        Pattern.compile("^1[3-9]\\d{9}$");

    @Override
    public boolean isValid(String value, ConstraintValidatorContext ctx) {
        if (value == null) return true;  // null 由 @NotBlank 处理
        return PATTERN.matcher(value).matches();
    }
}

// 3. 在 DTO 中使用
@Data
public class RegisterDTO {
    @NotBlank
    @ChinesePhone   // 自定义校验注解
    private String phone;
}

分页查询的标准实现

Spring Data 提供 Pageable 接口和 Page<T> 结果类，实现分页无需手写 LIMIT/OFFSET SQL：

// Controller：接收分页参数
@GetMapping
public ApiResponse<PageResult<UserResponseDTO>> listUsers(
        @RequestParam(defaultValue = "0") int page,
        @RequestParam(defaultValue = "20") int size,
        @RequestParam(defaultValue = "createdAt") String sortBy) {

    // 构建分页和排序对象
    Pageable pageable = PageRequest.of(page, size,
        Sort.by(Sort.Direction.DESC, sortBy));

    Page<UserResponseDTO> result = userService.findAll(pageable);

    // 包装分页元信息
    return ApiResponse.ok(PageResult.of(result));
}

// 自定义分页结果封装（比直接返回 Page<T> 更友好）
@Data
@AllArgsConstructor
public class PageResult<T> {
    private List<T> content;
    private long total;       // 总记录数
    private int page;         // 当前页码
    private int size;         // 每页大小
    private int totalPages;   // 总页数

    public static <T> PageResult<T> of(Page<T> page) {
        return new PageResult<>(
            page.getContent(),
            page.getTotalElements(),
            page.getNumber(),
            page.getSize(),
            page.getTotalPages()
        );
    }
}