北京
我见过太多让开发者崩溃的接口。有的返回格式今天一个样明天一个变，有的查个列表要等十几秒，还有的错误提示就写个"出错了"——你知道那种想砸键盘的感觉吗？
反过来，好的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设计是做减法——把确定的东西做到极致，不确定的东西坚决不放进去。
特别声明：以上内容(如有图片或视频亦包括在内)为自媒体平台“网易号”用户上传并发布，本平台仅提供信息存储服务。
Notice: The content above (including the pictures and videos if any) is uploaded and posted by a user of NetEase Hao, which is a social media platform and only provides information storage services.
