API设计的艺术：好API和坏API的十个区别

一个好的 API 设计，开发者看一眼就知道怎么用。一个坏的 API 设计，开发者看完文档还是不确定该怎么调。

API 是系统与系统之间的契约。它的设计质量直接影响到集成效率、系统可维护性、开发者体验。但很多团队对 API 设计不够重视，觉得"能用就行"。

"能用"和"好用"之间，差距可能比你想象的大。

区别一：命名一致性

好 API 的命名是统一的。获取数据用 get，创建用 create，更新用 update，删除用 delete。所有端点遵循相同的命名规则。

坏 API 的命名是混乱的。同样是获取数据，有的叫 get，有的叫 fetch，有的叫 retrieve，有的叫 query。开发者需要记忆每个端点的具体命名，心智负担很重。

命名一致性不只是风格问题，它直接影响开发者的效率。当命名规则统一时，开发者可以"猜"出 API 的端点，不需要每次都查文档。

区别二：错误信息质量

好 API 的错误信息包含三个要素：错误码、错误描述、修复建议。比如"400 INVALID_EMAIL: Email format is invalid. Expected format: user@domain.com"。

坏 API 的错误信息只告诉你"出错了"。比如"400 Bad Request"。开发者不知道是哪个字段有问题、是什么格式错误、应该怎么修改。

好的错误信息能把调试时间从几小时缩短到几分钟。这个投入的回报是巨大的。

区别三：版本管理

好 API 有清晰的版本管理策略。通过 URL 路径（/v1/users）或者请求头来区分版本。旧版本在合理的时间内保持兼容，新版本有明确的变更日志。

坏 API 没有版本管理，或者频繁做不兼容的变更。调用方的代码突然就不能用了，查了半天才发现是 API 端做了变更。

版本管理的本质是对调用方的承诺：我不会在不通知你的情况下破坏你的代码。

区别四：分页设计

好 API 的分页是标准化的。所有列表接口使用相同的分页参数（page、page_size 或者 cursor），返回值包含总数、是否有下一页、下一页的请求参数。

坏 API 的分页是混乱的。有的用 offset，有的用 page，有的用 cursor。返回值的格式也各不相同。开发者需要为每个列表接口写不同的分页逻辑。

区别五：认证方式

好 API 使用标准的认证方式。OAuth 2.0、JWT、API Key，选择一种并保持一致。认证失败时返回标准的 401 状态码和清晰的错误信息。

坏 API 使用自定义的认证方式。每个接口的认证方式可能不同，认证失败时返回的错误信息含糊不清。开发者需要花大量时间理解认证流程。

区别六：文档质量

好 API 的文档不只是接口参考。它包含快速开始指南、认证说明、常见场景的代码示例、错误码列表、最佳实践建议。文档和实际行为保持一致。

坏 API 的文档只是自动生成的接口列表。没有示例，没有说明，甚至和实际行为不一致。开发者花在读文档上的时间比写代码还多。

Stripe 的 API 文档是行业标杆。它不仅详细描述了每个接口，还提供了可以直接运行的代码示例和交互式的 API 探索器。

区别七：幂等性设计

好 API 的写操作是幂等的。同样的请求多次执行，结果和执行一次相同。这对于网络不稳定环境下的重试非常重要。

坏 API 的写操作不是幂等的。同样的请求执行两次，可能创建两条重复的记录。调用方需要自己处理去重逻辑，增加了复杂性。

幂等性的实现通常依赖请求 ID。客户端生成一个唯一的请求 ID，服务端用这个 ID 来判断是否是重复请求。

区别八：批量操作

好 API 支持批量操作。一次请求可以创建/更新/删除多条记录。这减少了网络往返次数，提升了效率。

坏 API 只支持单条操作。创建一百条记录需要发一百次请求。在网络延迟较高的场景下，这种设计的效率很低。

批量操作需要考虑部分失败的情况。一百条记录中可能有几条处理失败，API 需要明确返回每条记录的处理结果。

区别九：过滤和排序

好 API 支持灵活的过滤和排序。通过查询参数来指定过滤条件和排序规则。比如 GET /users?status=active&sort=-created_at。

坏 API 不支持过滤和排序，或者支持的方式不一致。调用方需要在客户端进行过滤和排序，当数据量大时效率很低。

区别十：向后兼容

好 API 把向后兼容当作最重要的承诺。新增字段不会破坏现有客户端，废弃的接口会提前通知并保持一段时间的兼容。

坏 API 频繁做破坏性变更。删除字段、修改类型、改变行为，这些变更会导致现有客户端突然出错。

向后兼容的关键原则是：只能添加，不能删除和修改。新增的字段对旧客户端是透明的，旧客户端会忽略不认识的字段。

我的建议

API 设计是一个需要长期积累的技能。以下是一些实用的建议。

第一是遵循行业标准。REST、OAuth 2.0、JSON:API、OpenAPI，这些标准已经经过了大量实践验证。除非有充分的理由，否则不要自创标准。

第二是站在调用方的角度思考。设计 API 时想象自己是第一次使用这个 API 的开发者。什么信息是你需要的？什么错误会让你困惑？什么操作会让你觉得繁琐？

第三是重视文档。好的文档是最好的 API 营销。投入时间写文档，回报是更低的 support 成本和更高的采用率。

第四是保持演进。API 设计不是一次性的工作。随着业务的变化和用户反馈的积累，API 需要持续改进。但改进的同时要保持向后兼容。

好的 API 是无声的。开发者用起来顺畅，不会特别注意到 API 的存在。差的 API 是有声的，开发者会不停地抱怨和求助。