大家好，我是晓凡。
写在前面
一到月初或者月末（某些业务操作大规模爆发的时候），手机狂震，生产告警狂轰滥炸：xxx接口超时、用户中心 CPU 飙到 98%……
运维在群里疯狂 @ 你，你却只能回一句“我本地是好的”。
别问，问就是接口设计欠下的技术债。
下面，晓凡总结成 18 条可落地的接口设计“军规”。每条都配上“作死写法”与“保命写法”。
军规 1：路径必须永久不变
反面教材
@RestController
@RequestMapping("/getUserInfoByIdV2.3_beta")
public class UserController { ... }
产品说“V2.3_beta”只是临时版本，结果半年后，死活不敢下线。
正面写法
@RestController
@RequestMapping("/users")
public class UserController {@GetMapping("/{uid}")public UserDTO get(@PathVariable Long uid) { ... }
}
版本号放到 Header：Accept: application/vnd.myapp.v2+json
路由一旦上线，就是“墓碑”，永远不许动，哪怕老板喊重构。
军规 2：命名只准用名词，禁止动词
反面教材
@PostMapping("/createOrder")
@PostMapping("/addOrder")
@PostMapping("/insertOrder")
同一个业务三个入口，新人入职三天就开始迷路。
正面写法
@PostMapping("/orders")
public OrderDTO create(@RequestBody CreateOrderCommand cmd) { ... }
HTTP 动词已经表达“创建”语义，别再动词叠 buff。
军规 3：统一用复数
反面教材
@GetMapping("/order/{id}")
@GetMapping("/orders")
单复数混用，前端拼接 URL 得写 if/else，特别容易出错。
正面写法
@GetMapping("/orders/{id}")
@GetMapping("/orders")
集合与成员保持一致，前端直接模板字符串 ${host}/orders/${id}，代码干净又整洁。
军规 4：分页参数必须“三件套”
反面教材
@GetMapping("/orders")
public List<Order> list(@RequestParam int offset,@RequestParam int limit) { ... }
参数名随心所欲，前端封装 不知道骂了你多少次。
正面写法
@GetMapping("/orders")
public PageResult<OrderDTO> list(@RequestParam(defaultValue = "1") @Min(1) int page,@RequestParam(defaultValue = "20") @Min(1) @Max(100) int perPage) {long total = orderMapper.count();List<OrderDTO> data = orderMapper.selectPage((page - 1) * perPage, perPage);return PageResult.<OrderDTO>builder().data(data).totalCount(total).hasNext(page * perPage < total).build();
}
返回统一包装：
@Data
@Builder
public class PageResult<T> {private List<T> data;private long totalCount;private boolean hasNext;
}
军规 5：字段命名一律小写加下划线
反面教材
{"userName":"Jack","userAge":18}
前端 axios 自动把下划线转小驼峰，结果文档对不上，联调 2 小时。
正面写法
@JsonNaming(PropertyNamingStrategies.SnakeCaseStrategy.class)
public class UserDTO {private String userName;private Integer userAge;
}
返回即：
{"user_name":"Jack","user_age":18}
前后端一人一把尺子，永远对得上。
军规 6：枚举值禁止用魔法数字
反面教材
if (order.getStatus() == 3) { ... } // 3 代表啥？鬼知道
DB 改个值，线上直接 500。
正面写法
public enum OrderStatus {CREATED(10),PAID(20),SHIPPED(30),DONE(40);private final int code;OrderStatus(int code) { this.code = code; }public int getCode() { return code; }
}
实体与数据库均存 code：
@Converter(autoApply = true)
public class OrderStatusConverter implements AttributeConverter<OrderStatus, Integer> {public Integer convertToDatabaseColumn(OrderStatus s) { return s.getCode(); }public OrderStatus convertToEntityAttribute(Integer c) {return Arrays.stream(OrderStatus.values()).filter(e -> e.getCode() == c).findFirst().orElseThrow(() -> new IllegalArgumentException("unknown code " + c));}
}
代码里只有枚举，没有魔法数字。
军规 7：接收参数必须 DTO，禁止 Map
反面教材
@PostMapping("/orders")
public OrderDTO create(@RequestBody Map<String,Object> map) {Integer skuId = (Integer) map.get("skuId"); // 强转爆炸
}
Map 一把梭，编译期 0 提示，运行时 ClassCastException 随机出现。
正面写法
@PostMapping("/orders")
public OrderDTO create(@RequestBody @Valid CreateOrderCommand cmd) { ... }@Data
public class CreateOrderCommand {@NotNullprivate Long skuId;@NotNull @Min(1)private Integer quantity;
}
校验失败自动 400，错误信息一目了然：
{"field":"quantity","message":"must be greater than or equal to 1"}
军规 8：统一返回包装，禁止裸奔
反面教材
@GetMapping("/orders/{id}")
public OrderDTO get(@PathVariable Long id) { ... }
成功返回对象，失败返回字符串，前端得写三行 if 判断类型。
正面写法
@RestControllerAdvice
public class CommonResponseAdvice implements ResponseBodyAdvice<Object> {public boolean supports(MethodParameter returnType, Class converterType) { return true; }public Object beforeBodyWrite(Object body, MethodParameter returnType,MediaType selectedContentType, Class selectedConverterType,ServerHttpRequest request, ServerHttpResponse response) {if (body instanceof CommonResult) return body; // 避免二次包装return CommonResult.success(body);}
}public class CommonResult<T> {private int code;private String msg;private T data;public static <T> CommonResult<T> success(T data) {return new CommonResult<>(0, "ok", data);}
}
前端唯一判断 code === 0，其余按错误弹窗。
军规 9：错误码必须分段
反面教材
new RuntimeException("订单不存在");
日志里只有一行文字，定位靠天意。
正面写法
@Getter
@AllArgsConstructor
public enum ErrorEnum {ORDER_NOT_FOUND(20001, "订单不存在"),SKU_NOT_AVAILABLE(20002, "商品库存不足");private final int code;private final String message;
}
全局异常处理：
@RestControllerAdvice
public class GlobalExceptionHandler {@ExceptionHandler(BizException.class)public CommonResult<Void> handle(BizException ex) {return CommonResult.fail(ex.getErrorEnum().getCode(),ex.getErrorEnum().getMessage());}
}
前端按码弹窗，20001 跳转“订单列表”，20002 跳转“商品详情”。
军规 10：接口必须幂等
反面教材
@PostMapping("/orders")
public OrderDTO create(@RequestBody CreateOrderCommand cmd) {return orderService.create(cmd); // 每次调用都插新订单
}
用户狂点按钮，瞬间 5 单，客服哭晕。
正面写法
@PostMapping("/orders")
public OrderDTO create(@RequestBody @Valid CreateOrderCommand cmd,HttpServletRequest request) {String idempotencyKey = request.getHeader("Idempotency-Key");if (idempotencyKey == null) throw new BizException(ErrorEnum MISSING_KEY);return idempotencyService.execute(idempotencyKey, () -> orderService.create(cmd));
}
Redis 缓存 24h 唯一 KEY，重复请求直接返回第一次结果，0 重复订单。
军规 11：日期格式只准 ISO8601
反面教材
{"createTime":"06/18/2025 09:05:12"}
万一有国外项目，同事一脸懵：这是 6 月还是 18 月？
正面写法
@JsonFormat(pattern = "yyyy-MM-dd'T'HH:mm:ssXXX", timezone = "UTC")
private OffsetDateTime createTime;
返回即：
{"create_time":"2025-06-18T09:05:12+00:00"}
前端 new Date('2025-06-18T09:05:12+00:00') 直接解析，时区 0 歧义。
军规 12：Long 主键后端转 String
反面教材
{"orderId":9223372036854775807}
JS 最大安全整数 2^53-1，订单号精度丢失，用户 A 的订单跑到用户 B。
正面写法
@JsonSerialize(using = ToStringSerializer.class)
private Long orderId;
返回即：
{"order_id":"9223372036854775807"}
前端字符串传，精度不丢失。
军规 13：批量接口必须限制数量
反面教材
@PostMapping("/orders/batch")
public List<OrderDTO> batch(@RequestBody List<Long> ids) { ... }
对方一次丢 10w 个 id，线程池直接拉满。
正面写法
@PostMapping("/orders/batch")
public List<OrderDTO> batch(@RequestBody @Size(max = 100) List<Long> ids) { ... }
超过 100 直接 400，爱用不用。
军规 14：文件上传必须预签名
反面教材
@PostMapping("/upload")
public String upload(MultipartFile file) { ... }
1G 视频直接把带宽打爆，Tomcat OOM。
正面写法
@GetMapping("/upload/token")
public UploadTokenDTO token(@RequestParam String suffix) {String key = "private/" + UUID.randomUUID() + suffix;String uploadUrl = ossClient.generatePresignedUrl(key, ExpirationEnum.TEN_MINUTES);return new UploadTokenDTO(uploadUrl, key);
}
前端拿到直传 OSS，服务端只存 key，流量 0 占用。
军规15：禁止把「内部错误码」直接抛给前端
反面教材
catch (Exception e) {log.error("RPC失败", e);return CommonResult.fail(999, e.getMessage()); // 999 是什么？只有我自己懂
}
结果：
前端拿到 {code:999, msg:"Read timed out executing POST http://stock-service/lock"}，直接把超时堆栈展示给用户，页面弹出「Read timed out…」——用户一脸懵，黑客倒开心，内网地址全暴露。
正面写法
1.对外错误码只保留「用户可理解」枚举，统一收敛：
@AllArgsConstructor
public enum FrontEndErrorEnum {STOCK_UNAVAILABLE(5100, "商品库存不足"),SYSTEM_BUSY(5101, "系统繁忙，请稍后重试"),UNKNOWN_ERROR(5999, "网络走神了，稍后再试");final int code;final String message;
}
2.全局异常层做「内外翻译」——任何底层异常都不准穿透：
@RestControllerAdvice
public class ErrorTranslator {@ExceptionHandler(Exception.class)public CommonResult<Void> handle(Exception ex) {log.error("Fetal error", ex); // 详细堆栈只写日志if (ex instanceof FeignException) { // 下游超时return CommonResult.fail(FrontEndErrorEnum.SYSTEM_BUSY);}return CommonResult.fail(FrontEndErrorEnum.UNKNOWN_ERROR);}
}
3.前端拿到的是：
{"code":5100,"msg":"商品库存不足"}
既安全又友好，还方便做国际化——以后想换提示语，只改枚举即可
用户只需要知道「怎么办」，不需要知道「为什么炸了」。把堆栈留在日志，把尊严留给产品。
军规 16：对外暴露 Swagger，对内必须加注解
反面教材
@RestController
public class OrderController {@PostMapping("/orders")public OrderDTO create(CreateOrderCommand cmd) { ... }
}
文档靠口口相传，字段一旦改名，测试小姐姐提刀来找。
正面写法
@Tag(name = "订单模块")
@RestController
public class OrderController {@Operation(summary = "创建订单")@ApiResponse(responseCode = "200", description = "成功")@PostMapping("/orders")public OrderDTO create(@RequestBody @Valid CreateOrderCommand cmd) { ... }
}
启动后 http://localhost:8080/swagger-ui.html 实时可见，改字段即报错，0 沟通成本。
军规 17：关键接口必须打印入参出参
反面教材
@PostMapping("/orders")
public OrderDTO create(@RequestBody CreateOrderCommand cmd) {return orderService.create(cmd);
}
线上出错，日志只有一行“NullPointerException”，想复现？随缘。
正面写法
@PostMapping("/orders")
public OrderDTO create(@RequestBody CreateOrderCommand cmd) {log.info("create order req: {}", cmd);OrderDTO dto = orderService.create(cmd);log.info("create order rsp: {}", dto);return dto;
}
配合 Logback 异步 + 脱敏：
<appender name="ASYNC" class="ch.qos.logback.classic.AsyncAppender"><queueSize>2048</queueSize><appender-ref ref="FILE"/>
</appender>
性能损耗 < 5%,问题排查速度大大提升。
军规 18：发版前必须做向后兼容扫描
反面教材
// V1
public class UserDTO { private String name; }// V2 直接把 name 改成 username
public class UserDTO { private String username; }
旧应用直接解析失败，用户体验非常不好
正面写法
- 加新字段，不动旧字段：
public class UserDTO {private String name; // deprecatedprivate String username; // 新字段
}
- 使用
@Deprecated注解，Swagger 自动标灰。 - 配套单元测试：
@Test
void v1ClientShouldStillSeeNameField() throws Exception {mockMvc.perform(get("/users/1").header("Accept", "application/vnd.myapp.v1+json")).andExpect(jsonPath("$.name").exists()).andExpect(jsonPath("$.username").doesNotExist());
}
- 上线后观察 7 日，旧字段无调用再下线。
小结
接口设计不是炫技，而是写“半年后看了自己之前写的代码，还敢重构的代码勇气”。
这 18 条军规，一半来自我的踩坑，一半来自“别人踩过的坑”。
别嫌啰嗦，真正上线 0 告警的那天，你会来感谢我。
愿下次手机响起，只是外卖到了，不是 502。
我是晓凡，再小的帆也能远航
我们下期再见ヾ(•ω•`)o (●'◡'●)
)
