SpringBoot框架网站接口开发标准化规范

团队开发SpringBoot接口最怕的不是功能做不出来，而是十个人写出十种风格。返回码有人用0表示成功，有人用200；时间格式有人用yyyy-MM-dd，有人直接怼时间戳；异常处理有人抛RuntimeException，有人返回null。这些不一致积累到联调和维护阶段，成本会指数级上升。标准化规范解决的不是技术难题，是协作效率问题。下面直接拆解一套可落地的接口开发标准。

接口响应体必须采用固定结构，无论成功还是失败，外层格式完全一致。推荐的结构包含三个核心字段：code、message、data。code用整型数字，message用字符串描述，data用泛型承载业务数据。这样前端可以封装统一的拦截器，根据code判断业务状态，无需针对每个接口写不同的判断逻辑。

public class ApiResponse {
    private int code;
    private String message;
    private T data;

    public static  ApiResponse success(T data) {
        ApiResponse response = new ApiResponse<>();
        response.code = 200;
        response.message = "success";
        response.data = data;
        return response;
    }

    public static  ApiResponse error(int code, String message) {
        ApiResponse response = new ApiResponse<>();
        response.code = code;
        response.message = message;
        response.data = null;
        return response;
    }
}

这里有个容易被忽略的细节：成功时的code不要用0。很多团队习惯0表示成功，但HTTP层面已经有200表示正常响应，业务层再用0会造成两层语义割裂。直接用200与HTTP状态码对齐，前后端理解成本最低。失败码从400开始编排，按模块划分号段，比如用户模块用1000-1999，订单模块用2000-2999，这样看到错误码就能快速定位问题域。

业务代码中如果到处散落try-catch，不仅代码臃肿，还容易漏掉异常场景。SpringBoot提供了@RestControllerAdvice注解，可以全局拦截所有未捕获的异常，统一转换成标准响应体返回。这是接口规范中最核心的一环，做好了能让Controller层代码极度干净。

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(BusinessException.class)
    public ApiResponse handleBusinessException(BusinessException e) {
        return ApiResponse.error(e.getCode(), e.getMessage());
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ApiResponse handleValidationException(MethodArgumentNotValidException e) {
        String message = e.getBindingResult().getFieldErrors()
                .stream()
                .map(error -> error.getField() + ": " + error.getDefaultMessage())
                .collect(Collectors.joining(", "));
        return ApiResponse.error(400, message);
    }

    @ExceptionHandler(Exception.class)
    public ApiResponse handleException(Exception e) {
        log.error("系统异常", e);
        return ApiResponse.error(500, "服务器内部错误");
    }
}

自定义业务异常类BusinessException需要包含code和message两个属性，业务代码中遇到异常情况直接抛出即可。参数校验异常单独处理，配合@Valid注解使用，校验失败时把字段级别的错误信息拼接返回，前端可以直接展示到对应输入框下方。最底层的Exception兜底捕获是必须的，防止NPE这类未预料的异常直接暴露给前端，同时日志要完整记录堆栈，方便排查。

接口安全的第一道防线是参数校验，不能依赖前端校验，后端必须独立做。SpringBoot集成Hibernate Validator后，用注解声明校验规则是最简洁的方式。在DTO类的字段上标注@NotBlank、@NotNull、@Size、@Pattern等注解，Controller方法参数前加@Valid注解即可自动触发校验。

public class CreateUserRequest {
    @NotBlank(message = "用户名不能为空")
    @Size(min = 2, max = 20, message = "用户名长度需在2-20之间")
    private String username;

    @NotBlank(message = "手机号不能为空")
    @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确")
    private String phone;

    @NotNull(message = "年龄不能为空")
    @Min(value = 0, message = "年龄不能小于0")
    @Max(value = 150, message = "年龄不能大于150")
    private Integer age;
}

校验失败时由全局异常处理器统一捕获MethodArgumentNotValidException，返回结构化的错误信息。这里有一个实践经验：校验注解的message要写清楚给用户看的提示语，不要写“字段不能为空”这种技术性描述，直接写“用户名不能为空”，前端可以直接展示。对于复杂的业务校验逻辑，比如用户名是否已存在，放在Service层处理，校验不通过直接抛BusinessException。

URL设计遵循资源命名规范，用名词表示资源，用HTTP方法表示操作。GET查询、POST新增、PUT修改、DELETE删除，这是基本约定。不要在URL里出现动词，比如/getUserList、/deleteOrder这种写法应该杜绝。正确的做法是/users表示用户集合，/users/{id}表示单个用户资源。

版本控制建议放在URL路径中，比如/api/v1/users。虽然有人推崇请求头版本控制，但URL显式声明版本对调试和文档生成更友好。资源命名统一用复数形式，保持一致性。多级资源嵌套不要超过两层，/users/{userId}/orders/{orderId}是合理的，再深就要考虑拆分接口了。对于非标准CRUD操作，比如发送验证码、导出报表，可以定义为资源的子动作，/users/{id}/send-verification-code，这是RESTful实践中被广泛接受的扩展方式。

列表查询接口几乎每个项目都会遇到，分页参数不统一会让前端对接效率大打折扣。建议统一使用pageNum和pageSize两个参数，pageNum从1开始计数，pageSize设置默认值和上限。返回结果除了列表数据，还要包含总条数和总页数，方便前端渲染分页组件。

public class PageResult {
    private long total;
    private int pageNum;
    private int pageSize;
    private int totalPages;
    private List list;

    public static  PageResult of(long total, int pageNum, int pageSize, List list) {
        PageResult result = new PageResult<>();
        result.total = total;
        result.pageNum = pageNum;
        result.pageSize = pageSize;
        result.totalPages = (int) Math.ceil((double) total / pageSize);
        result.list = list;
        return result;
    }
}

分页查询的Controller方法接收pageNum和pageSize参数，Service层计算offset后传给MyBatis或JPA。这里要注意pageSize必须设置上限，比如最大100，防止客户端传入超大值导致数据库压力过大。如果业务需要游标分页或滚动加载，可以单独定义CursorPageResult结构，但绝大多数场景传统分页足够使用。

时间格式是前后端扯皮的重灾区。规范必须明确：所有接口传输的日期时间统一使用ISO 8601格式，即yyyy-MM-dd HH:mm:ss，时区默认为东八区。不要返回时间戳，虽然前端处理方便，但可读性差，排查问题时一眼看不出具体时间。SpringBoot配置文件中全局设置Jackson序列化格式即可一劳永逸。

spring:
  jackson:
    date-format: yyyy-MM-dd HH:mm:ss
    time-zone: GMT+8
    serialization:
      write-dates-as-timestamps: false

如果某些字段只需要日期不需要时间，比如生日，单独在字段上标注@JsonFormat(pattern = "yyyy-MM-dd")覆盖全局配置。对于null值的处理也要统一，建议全局配置不返回null字段，减少响应体体积，前端也不用做空值判断。

spring:
  jackson:
    default-property-inclusion: non_null

创建订单、扣减库存这类写操作接口必须考虑幂等性。客户端网络超时重试、用户重复点击，都可能导致同一请求被处理多次。推荐的做法是引入幂等令牌机制：客户端在提交前先调用一个获取令牌的接口，服务端生成唯一token返回，客户端提交业务请求时携带这个token，服务端校验token有效性后执行业务，同时标记token已使用。

实现上可以用Redis存储token，设置合理的过期时间。拦截器或AOP统一处理幂等校验逻辑，业务代码通过注解声明即可。对于数据库层面的幂等，可以利用唯一索引约束，比如订单号设置唯一索引，重复插入时捕获DuplicateKeyException并返回已有结果，这也是一种有效的兜底策略。

接口文档如果靠人工维护，迟早会和代码脱节。SpringBoot项目推荐集成Knife4j或SpringDoc OpenAPI，通过注解自动生成在线文档。Controller类和方法上添加@Tag和@Operation注解描述功能，DTO字段上添加@Schema注解描述含义和约束，文档就能自动生成并可在线调试。

@RestController
@RequestMapping("/api/v1/users")
@Tag(name = "用户管理", description = "用户相关接口")
public class UserController {

    @PostMapping
    @Operation(summary = "创建用户", description = "根据请求参数创建新用户")
    public ApiResponse createUser(@Valid @RequestBody CreateUserRequest request) {
        return ApiResponse.success(userService.createUser(request));
    }
}

文档生成的Swagger UI地址建议配置权限拦截，生产环境可以关闭。文档不仅给前端看，也是后端之间联调的契约，接口有任何变更，文档自动同步更新，彻底告别Word文档传来传去的低效协作方式。

每个接口请求都应该记录关键日志，包括请求参数、响应结果、处理耗时。但不要在Controller里手动写log.info，应该用AOP切面统一处理。定义切面拦截所有Controller方法，记录入参和出参，异常时记录完整堆栈。日志中必须包含traceId，方便分布式环境下串联调用链。

traceId可以在拦截器或过滤器中生成，存入MDC，日志配置中通过%X{traceId}占位符输出。响应体中也可以考虑返回traceId，这样用户反馈问题时直接提供traceId，开发能快速定位到具体请求。日志级别要区分清楚：正常业务日志用info，调试信息用debug，异常用error。生产环境默认info级别，避免日志量过大影响性能。

接口返回的手机号、身份证号、银行卡号等敏感信息必须脱敏。不要把这个责任推给前端，后端返回出去的数据就应该是脱敏后的。可以在Jackson序列化时通过自定义注解和序列化器实现字段级别的自动脱敏。

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@JacksonAnnotationsInside
@JsonSerialize(using = SensitiveSerializer.class)
public @interface Sensitive {
    SensitiveType value();
}

public enum SensitiveType {
    PHONE,      // 手机号脱敏 1381234
    ID_CARD,    // 身份证脱敏 320*1234
    NAME        // 姓名脱敏 张*
}

在VO类的敏感字段上标注@Sensitive注解，序列化时自动替换中间字符。这样做的好处是业务代码完全无感知，不需要手动处理脱敏逻辑，也不会遗漏。对于日志中可能打印的敏感信息，在AOP日志切面中同样需要做脱敏处理，防止敏感数据泄露到日志系统。

前后端分离项目必然涉及跨域问题。SpringBoot中通过CorsRegistry全局配置即可，不要在每个Controller上加@CrossOrigin注解，那样分散管理容易遗漏。配置时明确指定允许的域名，生产环境严禁使用allowedOrigins("*")这种全放开的配置。

@Configuration
public class CorsConfig implements WebMvcConfigurer {
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/api/")
                .allowedOrigins("https://www.example.com")
                .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
                .allowedHeaders("*")
                .allowCredentials(true)
                .maxAge(3600);
    }
}

allowedMethods中必须显式列出允许的方法，OPTIONS预检请求也要包含在内。allowCredentials设为true时，allowedOrigins不能使用通配符，这是浏览器的安全限制。maxAge设置预检请求缓存时间，减少不必要的OPTIONS请求。

以上规范覆盖了接口开发的核心环节：响应结构、异常处理、参数校验、URL设计、分页、时间格式、幂等性、文档、日志、脱敏、跨域。每一条都经过大量项目验证，直接落地就能见效。规范的价值在执行，建议将响应体类、异常处理器、分页结构、切面逻辑抽取成公共模块，新项目直接依赖，避免重复造轮子。代码评审时对照规范逐项检查，坚持一段时间后团队就会形成肌肉记忆，接口质量自然提升。