引言

你有没有遇到过这些线上事故：

• 用户连续点了两次"提交订单"，结果创建了两个一样的订单
• 前端传了个 null 字段进来，接口直接 500 报错
• 不同的异常返回不同格式的错误信息，前端对接痛不欲生
• 上线一个新版本接口，老版本直接挂了

这些问题不是什么高深的技术难题，而是接口健壮性没做好。本文分享 5 个实战技巧，每个都有完整代码，直接抄进你的项目就能用。

一、接口幂等性：防止重复提交

1.1 问题场景

用户点击"提交订单" → 网络抖动，响应慢 → 用户又点了一次 → 创建了两个相同订单

或者更隐蔽的：支付回调重试机制触发，同一笔支付扣了两次款

1.2 方案设计

核心思路：每次请求携带唯一标识（幂等 Key），服务端用 Redis 记录该 Key 是否已处理过。

第一次请求：
  Client → 带 IdempotentKey=abc123 → Server
  Server → Redis 查 abc123 → 不存在 → 处理业务 → 存入 Redis
  Server → 返回正常结果

第二次请求（重复）：
  Client → 带 IdempotentKey=abc123 → Server
  Server → Redis 查 abc123 → 已存在 → 直接返回上次结果

1.3 代码实现

自定义注解：

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Idempotent {

    /**
     * 幂等 Key 的 SpEL 表达式
     * 支持 #param.field 形式
     */
    String key();

    /**
     * 幂等过期时间（秒），默认 10 秒
     */
    int expire() default 10;

    /**
     * 过期时的提示信息
     */
    String message() default "请勿重复提交";
}

AOP 切面实现：

@Aspect
@Component
@Slf4j
public class IdempotentAspect {

    private final StringRedisTemplate redisTemplate;

    public IdempotentAspect(StringRedisTemplate redisTemplate) {
        this.redisTemplate = redisTemplate;
    }

    @Around("@annotation(idempotent)")
    public Object around(ProceedingJoinPoint joinPoint, Idempotent idempotent) throws Throwable {
        // 1. 解析 SpEL 表达式获取幂等 Key
        String key = parseKey(joinPoint, idempotent.key());
        String redisKey = "idempotent:" + key;

        // 2. 尝试获取锁（SETNX）
        Boolean acquired = redisTemplate.opsForValue()
                .setIfAbsent(redisKey, "1", idempotent.expire(), TimeUnit.SECONDS);

        if (Boolean.FALSE.equals(acquired)) {
            // 3. Key 已存在，说明是重复请求
            log.warn("重复请求被拦截, key={}", redisKey);
            throw new BusinessException(idempotent.message());
        }

        try {
            // 4. 执行业务逻辑
            return joinPoint.proceed();
        } catch (Exception e) {
            // 5. 业务异常时删除 Key，允许重试
            redisTemplate.delete(redisKey);
            throw e;
        }
    }

    /**
     * 解析 SpEL 表达式
     */
    private String parseKey(JoinPoint joinPoint, String spel) {
        MethodSignature signature = (MethodSignature) joinPoint.getSignature();
        Method method = signature.getMethod();
        Object[] args = joinPoint.getArgs();
        String[] paramNames = signature.getParameterNames();

        // 构建 SpEL 上下文
        EvaluationContext context = new StandardEvaluationContext();
        for (int i = 0; i < args.length; i++) {
            context.setVariable(paramNames[i], args[i]);
        }

        ExpressionParser parser = new SpelExpressionParser();
        Expression expression = parser.parseExpression(spel);
        Object value = expression.getValue(context);

        if (value == null) {
            throw new BusinessException("幂等Key不能为空");
        }

        return value.toString();
    }
}

Controller 使用：

@RestController
@RequestMapping("/api/orders")
public class OrderController {

    @PostMapping
    @Idempotent(key = "#request.orderToken", expire = 10, message = "订单正在创建中，请勿重复提交")
    public Result<Order> createOrder(@RequestBody @Valid CreateOrderRequest request) {
        Order order = orderService.create(request);
        return Result.success(order);
    }
}

1.4 关键设计点

二、参数校验：分组校验 + 自定义校验器

2.1 问题场景

POST /api/users
{
  "username": "",        // 用户名不能为空
  "email": "xxx",        // 邮箱格式不对
  "phone": "123",        // 手机号格式不对
  "age": 200             // 年龄超出范围
}

后端没校验 → 直接存入数据库 → 后续查询出错 / 业务逻辑混乱

2.2 方案：分组校验

同一个 DTO，不同场景有不同的校验规则：

@Data
public class UserRequest {

    @NotNull(groups = {Create.class, Update.class}, message = "ID不能为空")
    private Long id;

    @NotBlank(groups = Create.class, message = "用户名不能为空")
    @Size(min = 3, max = 20, groups = {Create.class, Update.class}, message = "用户名长度3-20")
    private String username;

    @NotBlank(groups = Create.class, message = "邮箱不能为空")
    @Email(groups = {Create.class, Update.class}, message = "邮箱格式不正确")
    private String email;

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

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

    // 校验分组
    public interface Create {}
    public interface Update {}
}

Controller 指定校验分组：

@RestController
@RequestMapping("/api/users")
public class UserController {

    @PostMapping
    public Result<User> create(@RequestBody @Validated(UserRequest.Create.class) UserRequest request) {
        return Result.success(userService.create(request));
    }

    @PutMapping("/{id}")
    public Result<User> update(@RequestBody @Validated(UserRequest.Update.class) UserRequest request) {
        return Result.success(userService.update(request));
    }
}

2.3 自定义校验器

标准注解不够用时，自己写：

/**
 * 自定义注解：禁止敏感词
 */
@Target({ElementType.FIELD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = NoSensitiveWordValidator.class)
public @interface NoSensitiveWord {

    String message() default "包含敏感词";

    Class<?>[] groups() default {};

    Class<? extends Payload>[] payload() default {};

    String[] words() default {};
}

/**
 * 敏感词校验器
 */
public class NoSensitiveWordValidator implements ConstraintValidator<NoSensitiveWord, String> {

    private String[] sensitiveWords;

    @Override
    public void initialize(NoSensitiveWord annotation) {
        this.sensitiveWords = annotation.words();
    }

    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {
        if (value == null || value.isEmpty()) {
            return true; // null 交给 @NotBlank 处理
        }
        for (String word : sensitiveWords) {
            if (value.contains(word)) {
                return false;
            }
        }
        return true;
    }
}

使用自定义校验器：

@Data
public class ArticleRequest {

    @NotBlank(message = "标题不能为空")
    @NoSensitiveWord(words = {"广告", "诈骗", "赌博"}, message = "标题包含敏感词")
    private String title;

    @NotBlank(message = "内容不能为空")
    @NoSensitiveWord(words = {"广告", "诈骗", "赌博"}, message = "内容包含敏感词")
    private String content;
}

三、统一响应体：Result 泛型封装

3.1 问题场景

没有统一响应体的接口：

// 成功时直接返回数据
{"id": 1, "name": "张三"}

// 失败时返回错误信息
{"error": "用户不存在"}

// 500 时返回 HTML
<html><body>500 Internal Server Error</body></html>

前端对接：每次都要判断返回的是数据还是错误，格式不统一，代码混乱。

3.2 方案：Result 泛型封装

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class Result<T> implements Serializable {

    /**
     * 业务状态码
     */
    private int code;

    /**
     * 提示信息
     */
    private String message;

    /**
     * 响应数据
     */
    private T data;

    /**
     * 时间戳
     */
    private long timestamp;

    // ==================== 成功 ====================

    public static <T> Result<T> success() {
        return success(null);
    }

    public static <T> Result<T> success(T data) {
        return Result.<T>builder()
                .code(ResultCode.SUCCESS.getCode())
                .message(ResultCode.SUCCESS.getMessage())
                .data(data)
                .timestamp(System.currentTimeMillis())
                .build();
    }

    public static <T> Result<T> success(T data, String message) {
        return Result.<T>builder()
                .code(ResultCode.SUCCESS.getCode())
                .message(message)
                .data(data)
                .timestamp(System.currentTimeMillis())
                .build();
    }

    // ==================== 失败 ====================

    public static <T> Result<T> fail(ResultCode resultCode) {
        return fail(resultCode.getCode(), resultCode.getMessage());
    }

    public static <T> Result<T> fail(ResultCode resultCode, String message) {
        return fail(resultCode.getCode(), message);
    }

    public static <T> Result<T> fail(int code, String message) {
        return Result.<T>builder()
                .code(code)
                .message(message)
                .data(null)
                .timestamp(System.currentTimeMillis())
                .build();
    }

    // ==================== 判断 ====================

    public boolean isSuccess() {
        return this.code == ResultCode.SUCCESS.getCode();
    }
}

状态码枚举：

@Getter
@AllArgsConstructor
public enum ResultCode {

    // 成功
    SUCCESS(200, "成功"),

    // 客户端错误 4xx
    BAD_REQUEST(400, "请求参数错误"),
    UNAUTHORIZED(401, "未认证"),
    FORBIDDEN(403, "无权限"),
    NOT_FOUND(404, "资源不存在"),
    METHOD_NOT_ALLOWED(405, "请求方法不支持"),
    REQUEST_TIMEOUT(408, "请求超时"),
    TOO_MANY_REQUESTS(429, "请求过于频繁"),

    // 服务端错误 5xx
    INTERNAL_ERROR(500, "系统内部错误"),
    SERVICE_UNAVAILABLE(503, "服务暂不可用"),
    GATEWAY_TIMEOUT(504, "网关超时"),

    // 业务错误 1xxx
    PARAM_VALIDATE_FAILED(1001, "参数校验失败"),
    REPEATED_REQUEST(1002, "重复请求"),
    BUSINESS_ERROR(1003, "业务异常"),

    // 订单业务 2xxx
    ORDER_NOT_FOUND(2001, "订单不存在"),
    ORDER_STATUS_ERROR(2002, "订单状态异常"),
    ORDER_ALREADY_PAID(2003, "订单已支付");

    private final int code;
    private final String message;
}

Controller 使用：

@GetMapping("/{id}")
public Result<User> getUser(@PathVariable Long id) {
    User user = userService.findById(id);
    if (user == null) {
        return Result.fail(ResultCode.NOT_FOUND);
    }
    return Result.success(user);
}

统一响应格式：

{
  "code": 200,
  "message": "成功",
  "data": {
    "id": 1,
    "name": "张三"
  },
  "timestamp": 1722384000000
}

四、全局异常拦截：按异常类型分级处理

4.1 问题场景

没有全局异常处理的代码：

@GetMapping("/{id}")
public Result<User> getUser(@PathVariable Long id) {
    try {
        User user = userService.findById(id);
        if (user == null) {
            throw new RuntimeException("用户不存在");
        }
        return Result.success(user);
    } catch (RuntimeException e) {
        return Result.fail(500, e.getMessage());
    } catch (Exception e) {
        return Result.fail(500, "系统错误");
    }
}
// 每个接口都要写一堆 try-catch，代码又臭又长

4.2 方案：@RestControllerAdvice 分级处理

@RestControllerAdvice
@Slf4j
public class GlobalExceptionHandler {

    // ==================== 1. 业务异常（最常见，INFO 级别） ====================

    @ExceptionHandler(BusinessException.class)
    public Result<Void> handleBusiness(BusinessException e) {
        log.info("业务异常: {}", e.getMessage());
        return Result.fail(e.getCode(), e.getMessage());
    }

    // ==================== 2. 参数校验异常（WARN 级别） ====================

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public Result<Void> handleValidation(MethodArgumentNotValidException e) {
        String message = e.getBindingResult().getFieldErrors().stream()
                .map(error -> error.getField() + ": " + error.getDefaultMessage())
                .collect(Collectors.joining("; "));
        log.warn("参数校验失败: {}", message);
        return Result.fail(ResultCode.PARAM_VALIDATE_FAILED, message);
    }

    @ExceptionHandler(ConstraintViolationException.class)
    public Result<Void> handleConstraintViolation(ConstraintViolationException e) {
        String message = e.getConstraintViolations().stream()
                .map(v -> v.getPropertyPath() + ": " + v.getMessage())
                .collect(Collectors.joining("; "));
        log.warn("约束校验失败: {}", message);
        return Result.fail(ResultCode.PARAM_VALIDATE_FAILED, message);
    }

    @ExceptionHandler(BindException.class)
    public Result<Void> handleBind(BindException e) {
        String message = e.getFieldErrors().stream()
                .map(error -> error.getField() + ": " + error.getDefaultMessage())
                .collect(Collectors.joining("; "));
        log.warn("参数绑定失败: {}", message);
        return Result.fail(ResultCode.PARAM_VALIDATE_FAILED, message);
    }

    // ==================== 3. 请求相关异常（WARN 级别） ====================

    @ExceptionHandler(HttpRequestMethodNotSupportedException.class)
    public Result<Void> handleMethodNotSupported(HttpRequestMethodNotSupportedException e) {
        log.warn("请求方法不支持: {}", e.getMessage());
        return Result.fail(ResultCode.METHOD_NOT_ALLOWED);
    }

    @ExceptionHandler(MissingServletRequestParameterException.class)
    public Result<Void> handleMissingParam(MissingServletRequestParameterException e) {
        log.warn("缺少请求参数: {}", e.getParameterName());
        return Result.fail(ResultCode.BAD_REQUEST, "缺少参数: " + e.getParameterName());
    }

    @ExceptionHandler(HttpMessageNotReadableException.class)
    public Result<Void> handleNotReadable(HttpMessageNotReadableException e) {
        log.warn("请求体格式错误: {}", e.getMessage());
        return Result.fail(ResultCode.BAD_REQUEST, "请求体格式错误");
    }

    // ==================== 4. 幂等异常 ====================

    @ExceptionHandler(IdempotentException.class)
    public Result<Void> handleIdempotent(IdempotentException e) {
        log.warn("重复请求: {}", e.getMessage());
        return Result.fail(ResultCode.REPEATED_REQUEST, e.getMessage());
    }

    // ==================== 5. 兜底异常（ERROR 级别，不可预期） ====================

    @ExceptionHandler(Exception.class)
    public Result<Void> handleException(Exception e) {
        log.error("未预期异常", e);
        return Result.fail(ResultCode.INTERNAL_ERROR);
    }
}

4.3 自定义异常体系

/**
 * 基础业务异常
 */
@Getter
public class BusinessException extends RuntimeException {

    private final int code;

    public BusinessException(String message) {
        super(message);
        this.code = ResultCode.BUSINESS_ERROR.getCode();
    }

    public BusinessException(int code, String message) {
        super(message);
        this.code = code;
    }

    public BusinessException(ResultCode resultCode) {
        super(resultCode.getMessage());
        this.code = resultCode.getCode();
    }
}

4.4 异常处理分级

核心原则：业务异常不是 Error，不需要打印堆栈；未预期异常才需要完整堆栈。

五、接口版本管理：URL 路径 vs Header 版本号

5.1 为什么需要版本管理

v1 接口返回：{"name": "张三", "phone": "13800138000"}
v2 接口需要返回：{"username": "zhangsan", "mobile": "13800138000"}

如果不做版本管理 → 升级 v2 → 前端还在用 v1 格式 → 直接挂了

5.2 方案一：URL 路径版本（推荐）

/api/v1/users
/api/v2/users

实现方式：多 Controller 继承

// 基础接口定义
public interface UserApi {
    Result<UserV1Response> getUser(Long id);
}

// V1 实现
@RestController
@RequestMapping("/api/v1/users")
public class UserV1Controller implements UserApi {

    @GetMapping("/{id}")
    @Override
    public Result<UserV1Response> getUser(@PathVariable Long id) {
        User user = userService.findById(id);
        return Result.success(UserV1Response.from(user));
    }
}

// V2 实现
@RestController
@RequestMapping("/api/v2/users")
public class UserV2Controller {

    @GetMapping("/{id}")
    public Result<UserV2Response> getUser(@PathVariable Long id) {
        User user = userService.findById(id);
        return Result.success(UserV2Response.from(user));
    }
}

V1/V2 响应体：

// V1: 旧格式
@Data
public class UserV1Response {
    private String name;
    private String phone;

    public static UserV1Response from(User user) {
        UserV1Response resp = new UserV1Response();
        resp.setName(user.getUsername());
        resp.setPhone(user.getPhone());
        return resp;
    }
}

// V2: 新格式，字段更语义化
@Data
public class UserV2Response {
    private String username;
    private String mobile;
    private String avatar;
    private LocalDateTime createTime;

    public static UserV2Response from(User user) {
        UserV2Response resp = new UserV2Response();
        resp.setUsername(user.getUsername());
        resp.setMobile(user.getPhone());
        resp.setAvatar(user.getAvatar());
        resp.setCreateTime(user.getCreateTime());
        return resp;
    }
}

5.3 方案二：Header 版本号

GET /api/users
X-API-Version: 2

实现方式：自定义 @Version 注解 + 条件匹配

@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface Version {
    int value();
}

public class VersionRequestCondition implements RequestCondition<VersionRequestCondition> {

    private final int version;

    public VersionRequestCondition(int version) {
        this.version = version;
    }

    @Override
    public VersionRequestCondition combine(VersionRequestCondition other) {
        // 方法上的版本优先于类上的版本
        return new VersionRequestCondition(other.version);
    }

    @Override
    public VersionRequestCondition getMatchingCondition(HttpServletRequest request) {
        String header = request.getHeader("X-API-Version");
        if (header == null) {
            // 没有版本头，默认匹配 V1
            return this.version == 1 ? this : null;
        }
        int requestVersion = Integer.parseInt(header);
        return requestVersion == this.version ? this : null;
    }

    @Override
    public int compareTo(VersionRequestCondition other, HttpServletRequest request) {
        return other.version - this.version;
    }
}

5.4 两种方案对比

建议：优先用 URL 路径版本，简单直观，团队沟通成本低。

5.5 版本废弃策略

@RestController
@RequestMapping("/api/v1/users")
public class UserV1Controller {

    @GetMapping("/{id}")
    @Deprecated
    public Result<UserV1Response> getUser(@PathVariable Long id) {
        // 在响应头中添加废弃提示
        HttpServletResponse response = ...
        response.setHeader("X-API-Deprecated", "true");
        response.setHeader("X-API-Deprecated-Message", "此接口将在 2025-12-31 下线，请迁移至 /api/v2/users");
        response.setHeader("X-API-Sunset", "2025-12-31");

        User user = userService.findById(id);
        return Result.success(UserV1Response.from(user));
    }
}

六、五个技巧整合：完整 Controller 示例

@RestController
@RequestMapping("/api/v2/orders")
public class OrderController {

    private final OrderService orderService;

    public OrderController(OrderService orderService) {
        this.orderService = orderService;
    }

    /**
     * 创建订单
     * - 幂等性：防重复提交
     * - 参数校验：Create 分组
     * - 统一响应：Result 泛型
     * - 全局异常：自动拦截
     */
    @PostMapping
    @Idempotent(key = "#request.orderToken", expire = 10, message = "订单正在创建中，请勿重复提交")
    public Result<Order> createOrder(@RequestBody @Validated(OrderRequest.Create.class) OrderRequest request) {
        Order order = orderService.create(request);
        return Result.success(order);
    }

    /**
     * 更新订单
     * - 参数校验：Update 分组
     */
    @PutMapping("/{id}")
    public Result<Order> updateOrder(
            @PathVariable Long id,
            @RequestBody @Validated(OrderRequest.Update.class) OrderRequest request) {
        Order order = orderService.update(id, request);
        return Result.success(order);
    }

    /**
     * 查询订单
     */
    @GetMapping("/{id}")
    public Result<Order> getOrder(@PathVariable Long id) {
        Order order = orderService.findById(id);
        if (order == null) {
            throw new BusinessException(ResultCode.ORDER_NOT_FOUND);
        }
        return Result.success(order);
    }
}

七、总结

五个技巧速查表

实施优先级

第一天：统一响应体 + 全局异常拦截（基础设施，必须有）
第二天：参数校验（快速见效，减少大量脏数据问题）
第三天：接口幂等性（支付/订单等关键场景必须）
第四天：接口版本管理（有多个客户端版本时必须有）

一句话总结

接口健壮性不是锦上添花，而是底线保障。这 5 个技巧每个都不复杂，但组合起来能挡住 90% 的低级线上事故。

互动话题：你的项目中做了哪些接口防护措施？有没有踩过接口健壮性的坑？欢迎留言分享！

参考资料

• Spring Validation 官方文档
• Hibernate Validator 文档
• Spring AOP 官方文档