接口设计最开始看起来只是路径和字段。

比如 GET /users、POST /orders，再加几个 JSON 字段，前后端就能联调。但一个接口好不好用，往往不是第一天体现出来的，而是在报错、重试、排查线上问题、兼容旧客户端的时候体现出来。

第一个细节是错误结构。

很多接口只返回一句 error: "failed"，开发阶段还能靠控制台猜，到了线上就很难受。一个更实用的错误响应至少应该有稳定的错误码、人能读懂的 message，以及可选的 details。

比如：

{
  "code": "ORDER_STOCK_NOT_ENOUGH",
  "message": "库存不足",
  "details": {
    "skuId": "sku_123",
    "available": 2
  }
}

前端需要的是 code，用户看到的是 message，排查问题时看 details。三者服务的对象不一样，不应该混在一起。

第二个细节是幂等。

只要接口可能被重试，就要考虑幂等。下单、支付回调、创建任务、发送通知，这些接口如果没有幂等设计，网络抖一下就可能制造重复数据。幂等不一定复杂，可以是业务唯一键，也可以是客户端传 Idempotency-Key，关键是后端要承认“请求可能会重复到达”。

第三个细节是分页。

偏移分页简单，但数据变化频繁时会出现重复或漏数据。后台管理页用 page + pageSize 没问题，时间线、消息流、同步任务更适合 cursor 分页。分页方式不只是技术选择，也决定了前端交互能不能稳定。

第四个细节是状态码别太随意。

不是所有错误都应该返回 200，也不是所有失败都应该返回 500。参数错是 400，没登录是 401，没权限是 403，资源不存在是 404，冲突是 409。状态码用准一点，网关、监控、客户端请求库都会更好处理。

第五个细节是日志上下文。

接口一旦进入生产环境，最重要的问题会变成：这次请求到底发生了什么。每个请求最好有 requestId，关键日志里带上 userId、业务 id、耗时、下游调用结果。没有这些信息，排查问题就会变成翻日志猜谜。

我喜欢把接口设计看成一种长期契约。字段可以简单，路径可以朴素，但契约要稳定。稳定不是永远不改，而是改的时候知道谁会受影响，旧客户端还能不能工作，错误能不能被识别，问题能不能被追踪。

很多后端质量感，不来自用了多高级的框架，而来自这些不显眼的小地方。