后端接口设计：先把幂等、分页和错误码定下来

接口设计最怕的是每个开发者各写一套：有人用 code: 0 表示成功，有人用 code: 200；有人分页从 1 开始，有人从 0 开始。等前端接了十几个接口才发现规律不一致，返工成本极高。这篇整理三个最值得在项目初期就定死的约定。

一、幂等：写接口默认要能重复调用

网络抖动时客户端会重试，用户也会连点两次。凡是创建、扣款、发货这类写操作，都要允许重复请求得到同一个结果。

常见的两种做法：

1. 业务唯一键：订单号、流水号上建唯一索引，重复插入直接冲突
2. 幂等令牌：客户端先申请 token，请求带上它，服务端用 SETNX 占位

令牌方式要注意占位的有效期，太短会导致真实重试被放过，太长会占内存。一般设成比接口超时略长，例如 30 秒。

实现时有个细节容易错：先占位再执行业务，业务失败要主动释放令牌，否则用户改完参数重试会被挡住。

页码分页（page + size）实现简单，但数据持续写入时翻页会重复或漏掉记录。列表页可以用页码， feed 流、消息、日志这类场景建议用游标：

{"items": [], "next_cursor": "eyJpZCI6MTAyNH0=", "has_more": true}

游标里编码上一页最后一条的排序键，查询条件写成 WHERE id < ? ORDER BY id DESC LIMIT ?。这样即使中间插入新数据，翻页也稳定。

不管选哪种，都要约定 size 上限，别让客户端传 size=100000 把数据库拉爆。

建议业务错误码分段，前端能按区间做统一处理：

HTTP 状态码仍然要正确返回：参数错 400、未登录 401、无权限 403、不存在 404、限流 429、服务端异常 500。不要全部返回 200 再靠 body 区分，否则网关、监控、CDN 缓存全都失效。

这三条约定写进一份接口规范文档，配合一个统一的响应封装，比事后逐个接口整改省事得多。规范越早定，后面加接口越省事。