我见过太多让开发者崩溃的接口。有的返回格式今天一个样明天一个变，有的查个列表要等十几秒，还有的错误提示就写个"出错了"——你知道那种想砸键盘的感觉吗？

反过来，好的API也有规律。用了几百个接口后，我发现被开发者真心喜欢的那些，几乎都遵循下面这8个模式。

打开网易新闻 查看精彩图片

1. 响应格式保持一致

好的API永远用同一个结构包装数据：

不管查用户、查订单还是查报表，外层都是data加meta。开发者写一次解析逻辑，全站通用。最怕那种今天{ "user": {...} }明天{ "result": {...} }的，每个接口都要单独处理。

2. 分页别偷懒

数据量大的场景用游标分页：

小数据集用偏移量分页更直观。唯一不能做的是——不分页。一次性返回几千条记录，前端直接卡死，后端数据库也跟着挂。

3. HTTP状态码要用对

200、201、400、401、404、500，每个都有明确含义。别什么都返回200然后在body里塞错误信息，那是自欺欺人。

4. 查询能力给足

精确过滤、范围查询、多字段排序、全文搜索、字段裁剪、关联预加载——这六项基本功决定了一个API好不好用。让用户只取需要的字段，比一股脑全返更省带宽。

5. 版本控制是底线

URL里带/v1/、/v2/是最常见的做法，也有团队用Header控制。关键是旧版本至少维护6个月，别让调用方半夜被迫改代码。

6. 错误信息要能用

差的错误响应就一句"Something went wrong"。好的错误告诉你：什么错了、哪个字段、为什么错、怎么修，还附带文档链接和请求ID方便排查。

7. 异步任务别让用户干等

生成报表、批量导出这种耗时操作，先返回202 Accepted给个任务ID，让用户去查进度。配合取消链接更贴心——谁都有手滑点错的时候。

8. 能用Webhook就别让人轮询

订单状态变了主动推过去，比让用户每隔5秒问一次"好了吗"优雅一百倍。省的是双方的资源。

这些规则说起来简单，执行起来需要克制。每个"顺便加一下"的功能，都是未来维护的债。好的API设计是做减法——把确定的东西做到极致，不确定的东西坚决不放进去。