这是一篇会长期更新的文章

什么样的 API 设计能被称为优秀当然是一个非常主观的标准，但是还是有一些客观可考量 API 质量的数据，比如

接了你设计的 API 的前端给好评的比例是多少，还是边接边骂
如果你的 API 本身就是你的产品的话（比如 Stripe，Algolia 或者 Github 等等），你的用户会对你的 API 好评吗
API 是不是一读即可以清晰地知道，对应接口是做什么的。换句话说，接入 API 时需要的交流时间成本有多高

不管是前端程序员还是后端程序员，都少不了跟 API 打交道。后端需要把 API 设计和实现出来，而前端程序员需要把界面逻辑和 API 接起来，因此对于 REST 的设计规则有一些基本了解，不管你是前端还是后端，都会有很大帮助。

之前在厂里设计了一些还算被广泛使用的 API，因此我写了这篇文章，结合之前的经验总结了一些要点。希望作为一个参考，可以帮助大家

文章请戳 => 优秀的 REST API 设计指南

当然我想要说明的是，设计 API 在一定范围内是有规律可循的，但是太过抠细节则会陷入无穷无尽地“宗教版”争论中，所以请大家理论讨论。

你们设计 API 的时候有些什么原则？有哪些好的规范和经验可以介绍和分享给大家？欢迎告诉我，我会加到文章中

ZacksT

2020-07-29 10:58:18 +08:00

你的 REST API 满足公司 /研发团队标准就是好的设计。接口标准可以帮助开发者规避（公司研发 /团队研发）遇见过的问题或可能遇到的问题，也可以让组内代码标准化，统一化。

就拿一个简单的例子，一个分页查询的接口。其包含分页条件与不定量的查询条件。
你可以通过 GET 方式请求，将参数定义在 url 上。也可以通过 POST 方式请求，将查询参数定义在 requestbody 里。
第一个方式，在遇到查询条件复杂的情况下，会导致 url 过长。
第二种方式，又会产生很多 VO 的定义。
采用混搭又让前后端代码变得混乱。

我个人认为，只要满足团队要求的 API，就是好的 API 。具体实现各有好处，看团队取舍了

这是一个专为移动设备优化的页面（即为了让你能够在 Google 搜索结果里秒开这个页面），如果你希望参与 V2EX 社区的讨论，你可以继续到 V2EX 上打开本讨论主题的完整版本。

https://www.v2ex.com/t/693907