RESTful API 设计规范与统一响应封装

package com.example.common.api;import com.fasterxml.jackson.annotation.JsonInclude;import lombok.Getter;import java.io.Serializable;/** * 统一响应体 * code 与 HTTP 状态码解耦：HTTP 说明「传输/处理」层面，code 说明「业务」层面 */@Getter@JsonInclude(JsonInclude.Include.NON_NULL)public class Result<T> implements Serializable {    /** 业务码：0 表示成功，其余见 ErrorCode 枚举 */    private final int code;    private final String message;    private final T data;    private Result(int code, String message, T data) {        this.code = code;        this.message = message;        this.data = data;    }    public static <T> Result<T> ok(T data) {        return new Result<>(0, "success", data);    }    public static <T> Result<T> ok() {        return new Result<>(0, "success", null);    }    public static <T> Result<T> fail(int code, String message) {        return new Result<>(code, message, null);    }    public static <T> Result<T> fail(ErrorCode errorCode) {        return new Result<>(errorCode.getCode(), errorCode.getMessage(), null);    }}

package com.example.common.api;import org.springframework.core.MethodParameter;import org.springframework.http.MediaType;import org.springframework.http.converter.HttpMessageConverter;import org.springframework.http.server.ServerHttpRequest;import org.springframework.http.server.ServerHttpResponse;import org.springframework.web.bind.annotation.RestControllerAdvice;import org.springframework.web.servlet.mvc.method.annotation.ResponseBodyAdvice;/** * 自动把控制器返回值包装进 Result。 * 只处理标注了 @WrapResult 的接口，避免误伤文件下载 / 第三方回调。 */@RestControllerAdvicepublic class ResultWrapAdvice implements ResponseBodyAdvice<Object> {    @Override    public boolean supports(MethodParameter returnType,                            Class<? extends HttpMessageConverter<?>> converterType) {        // 已经是 Result 就不再包；标注了 @SkipWrap 的一律跳过        return returnType.getMethodAnnotation(SkipWrap.class) == null                && !Result.class.isAssignableFrom(returnType.getParameterType());    }    @Override    public Object beforeBodyWrite(Object body, MethodParameter returnType,                                  MediaType selectedContentType,                                  Class<? extends HttpMessageConverter<?>> converterType,                                  ServerHttpRequest request, ServerHttpResponse response) {        // 字符串返回值要单独处理，否则与 StringHttpMessageConverter 冲突        if (body instanceof String) {            return body; // 交由调用方自行返回 Result        }        return Result.ok(body);    }}

package com.example.common.exception;import lombok.Getter;@Getterpublic enum ErrorCode {    SUCCESS(0, "success"),    INVALID_PARAM(40000, "参数不合法"),    USER_NOT_FOUND(40401, "用户不存在"),    USERNAME_TAKEN(40901, "用户名已被占用"),    ORDER_STATE_CONFLICT(40902, "订单状态不允许该操作"),    PERMISSION_DENIED(40300, "没有操作权限"),    UNAUTHORIZED(40100, "登录已失效，请重新登录"),    SYSTEM_ERROR(50000, "系统繁忙，请稍后重试");    private final int code;    private final String message;    ErrorCode(int code, String message) {        this.code = code;        this.message = message;    }}

package com.example.common.exception;import lombok.Getter;/** 业务异常：可安全展示给用户的错误，禁止把 5xx 堆栈暴露出去 */@Getterpublic class BizException extends RuntimeException {    private final ErrorCode errorCode;    public BizException(ErrorCode errorCode) {        super(errorCode.getMessage());        this.errorCode = errorCode;    }    public BizException(ErrorCode errorCode, String message) {        super(message);        this.errorCode = errorCode;    }    // 省略堆栈，业务异常不需要栈信息，省下大量开销    @Override    public synchronized Throwable fillInStackTrace() {        return this;    }}

package com.example.common.api;import java.util.List;/** 分页结果：total 供前端算页数，list 是当前页数据 */public record PageResult<T>(long total, int page, int size, List<T> list) {    public static <T> PageResult<T> of(long total, int page, int size, List<T> list) {        return new PageResult<>(total, page, size, list);    }}

@GetMapping("/users")public PageResult<UserVO> page(        @RequestParam(defaultValue = "1") int page,        @RequestParam(defaultValue = "20") int size,        @RequestParam(defaultValue = "createdAt,desc") String sort) {    return userService.page(page, size, sort);}

package com.example.lab.rest;import org.springframework.http.HttpStatus;import org.springframework.http.ResponseEntity;import org.springframework.web.bind.annotation.*;import java.time.LocalDate;import java.util.List;import java.util.Map;import java.util.concurrent.ConcurrentHashMap;import java.util.concurrent.atomic.AtomicLong;@RestController@RequestMapping("/api/v1/books")              // 资源化 URL + URL 版本public class BookLabController {    public record Book(Long id, String title, LocalDate published) {}    public record CreateForm(@jakarta.validation.constraints.NotBlank String title, LocalDate published) {}    public record PageResult<T>(long total, int page, int size, List<T> list) {}    private static final Map<Long, Book> STORE = new ConcurrentHashMap<>();    private static final AtomicLong SEQ = new AtomicLong();    static {                                        // 造一点种子数据        SEQ.set(2);        STORE.put(1L, new Book(1L, "Domain-Driven Design", LocalDate.of(2003, 8, 20)));        STORE.put(2L, new Book(2L, "Spring in Action", LocalDate.of(2020, 5, 1)));    }    // 集合：分页 + 过滤统统走查询串 → 200    @GetMapping    public Map<String, Object> list(@RequestParam(defaultValue = "1") int page,                                   @RequestParam(defaultValue = "20") int size) {        var list = STORE.values().stream().sorted((a, b) -> a.id().compareTo(b.id()))                .skip((long) (page - 1) * size).limit(size).toList();        return Map.of("code", 0, "message", "success",                "data", new PageResult<>(STORE.size(), page, size, list));    }    // 单个资源：存在 → 200，不存在 → 真 404（不是 200 + code）    @GetMapping("/{id}")    public ResponseEntity<Map<String, Object>> get(@PathVariable Long id) {        Book book = STORE.get(id);        if (book == null) {            return ResponseEntity.status(HttpStatus.NOT_FOUND)                    .body(Map.of("code", 40401, "message", "图书不存在"));        }        return ResponseEntity.ok(Map.of("code", 0, "message", "success", "data", book));    }    // 创建 → 201 + Location    @PostMapping    public ResponseEntity<Map<String, Object>> create(@jakarta.validation.Valid @RequestBody CreateForm form) {        Long id = SEQ.incrementAndGet();        Book saved = new Book(id, form.title(), form.published() == null ? LocalDate.now() : form.published());        STORE.put(id, saved);        return ResponseEntity.created(java.net.URI.create("/api/v1/books/" + id))                .body(Map.of("code", 0, "message", "success", "data", saved));    }    // 删除 → 204，无响应体    @DeleteMapping("/{id}")    public ResponseEntity<Void> delete(@PathVariable Long id) {        return STORE.remove(id) == null                ? ResponseEntity.status(HttpStatus.NOT_FOUND).build()                : ResponseEntity.noContent().build();    }}

# 1) 列表 → 200curl -i "http://localhost:8080/api/v1/books?page=1&size=20"# 2) 单个资源 → 200curl -i http://localhost:8080/api/v1/books/1# 3) 资源不存在 → 404（关键：状态码真的是 404）curl -i http://localhost:8080/api/v1/books/999# 4) 创建 → 201 + Location 头curl -i -X POST http://localhost:8080/api/v1/books \     -H "Content-Type: application/json" -d '{"title":"Refactoring","published":"2018-11-19"}'# 5) 缺少必填字段 → 400（@Valid 触发 MethodArgumentNotValidException）curl -i -X POST http://localhost:8080/api/v1/books \     -H "Content-Type: application/json" -d '{"title":""}'

{  "code": 0,  "message": "success",  "data": { "id": 1, "title": "Domain-Driven Design", "published": "2003-08-20" }}