在目前移动端、前端趋于统一的大背景下，基于 RESTFul 的 API 也大放异彩，我们需要越来越多的与 API 打交到，设计可扩展，易于维护的 API 在我们的工作中也变得更加重要。那么，有没有可能，通过一定测策略与指导方法，让 API 的设计更规范，更有章可循，高效率的设计出好用的 API 呢？本文尝试总结笔者在这方面的思考，希望对读者有所启发。
在开始之前，我们先做一个定义，那就是什么样的 API 能够算得上优秀的 API，如下是笔者认为优秀 API 需要满足的四个要素：
- 遵循业界最佳实践
- 高度的统一性和一致性，优秀的 API 一定是高度一致和统一的，遵循一定的共性和约定
- 基于深刻理解业务的合理抽象
- 探索业务共性，总结规范
这四个要素层层递进，亦可以作为我们进行 API 设计的指导方法，下面详细介绍笔者对这四个要素的理解，必要的时候提供案例进行说明。
遵循业界最佳实践
遵循业界最佳实践我觉得是优秀 API 应具备最基本的一个要素，它能让相关人员最快的理解，建立统一的基础认知，如果我们的 API 对外的，这就显得更加重要。
就本文而言，笔者所说的业内最佳实践指的是基于 HTTP 的 RESTful API。它用 URI 表示资源，用 HTTP Verb 表示操作，要设计好 RESTFul API，很大程度上需要处理好对资源的抽象。
至于 RESTFul API 更具体是个什么东西，有哪些原则，本文不做更多探讨，互联网上相关的资料很多。
高度的统一性和一致性
如果说遵循业界最佳实践是基础，那么保持 API 的统一性和一致性就是设计合格 API 的保障。如果我们的 API 不统一、不一致，缺少必要约定，使用者必然会感到困惑，学习成本与维护成本必然大大增加。
下面是保证 API 高度统一和一致性需要考虑的一个列表，也许并不完整：
- 授权与鉴权方式的统一
- 每个 API 分页方式与对应参数的统一
- 排序参数与对应行为的统一一致
- 查询条件的写法经事先约定且保持一致
- 考虑存在于全局的参数，形成基础认知
- 等等等
深度理解业务的高度抽象
如果我们的 API 满足了前面两个要素，那它应该基本算是合格了，能够满足日常业务的需要，但对于优秀的 API，这才刚刚开始。
许多人在设计 API 的时候，没有大局观，仅仅为界面而设计，只有前台界面一变化，API 可能又需要重新设计，从而导致 API 扩展性差，频繁修改。
所以，我们在设计 API 的时候，就需要站在更高的维度，在深入理解业务的前提下，抽象出更高层次的 API。这样的 API 一般是界面无关的，即便界面变化，只要不是业务的调整，影响也不会很大。
优秀的 API 就像优秀的产品，不在于提供了多少 API （功能），而在于解决了多少问题。一个优秀的 API 能直接解决多个一般 API 才能解决的问题。
下面举一个例子：
假如，我们有这样一个需求，在一个博客系统中，我们需要获取全站访问最多和访问最少的文章，各n篇文章，应该怎样设计 API 呢？
有下面两个版本：
版本一:
提供两个API，如下：
GET /posts/most-viewed?limit=10 - 获取访问最多的文章
GET /posts/least-viewed?limit=10 - 获取访问最少的文章
版本二：
提供一个API，使用sort参数排序，间接实现需求
GET /posts?sort=total_views desc&limit=10 - 获取访问最多的文章
GET /posts?sort=total_views asc&limit=10 - 获取访问最少的文章
笔者认为，版本二会更好一些，直接使用已有 API 加排序完成需求，扩展性和抽象层次都更高。
探索业务共性，总结规范
每个业务都可能有它的共性，如果把这些共性提炼出来，形成规范，就会极大的提高 API 的设计及开发效率，API 的使用也会因此受益，因为整体 API 的理解会容易许多。
就比如笔者目前所在的公司，面临许多 toB 业务，有许许多多的聚合统计需求，如果把每个统计需求都写成单独的API，那 API 的数量恐怕浩如烟海，也很难维护。
所以，我们就在思考，如何把这些共性的统计需求就行抽象，总结成规范，变成 API 设计规范的一部分，从而指导 API 设计。
比如说，我们有如下的业务需求：
用户的状态（status）有 active, disabled 和 achieved 三种，需要统计满足条件用户三个状态各自的数量。
在我们目前API设计规范下，我们会用如下的方式解决这个需求，而非提供新的 API：
GET /users?kw=foo&$aggregate=status 按 status 就行聚合统计，kw是查询参数
这里我们引入了 $aggregate 的聚合方法，在不添加新 API 的情况下解决该需求，该方式也变成解决该类问题规范。
设计优秀 API 的四个要素介绍完了，希望对你有所帮助。
网友评论