第二章
Web Api 的重要性
设计 api 端点是后端开发经常接触的工作，但你是否从来没有想过好的 web api 应该是什么样子呢？
其实 Api 端点就像一张名片一样——专业的名片可以迅速帮助你与客户之间建立信任感；糟糕的名片会让你的产品在被使用前，就给客户留下负面印象。一旦客户对你的产品产生负面情绪，这种情绪就会蔓延到产品生态圈甚至于相关公司上。
本篇文章我和大家分享一些 api 设计的套路与规范，让你也能设计出优雅、健壮、扩展性强的应用程序接口。
设计原则，如果有的话
先让我们回顾曾经提到过的关于设计模式的内容：设计模式的精髓在于设计原则，而非模式的生搬硬套。与此类似，优雅的 Web Api 有两个重要原则如下所示：
- 设计规范明确的内容必须遵守相关规范
- 没有设计规范的内容必须遵守相关事实标准
也许你依然对如何设计 web api 毫无头绪，但是别着急，好的创作总是从模仿开始的。
下面是一些国际大厂的 api 示例，给自己一些时间消化消化。
| 厂名 | uri | 备注 |
|---|---|---|
| api.twitter.com/1.1 | “治国理政平台” | |
| Google Calendar | www.googleapis.com/calendar/v3 | “大厂” |
| api.instagram.com/v1/usrs/search?q=jack | “宠物自拍网站” | |
| api.linkedin.com/v1/people-search | “招工” | |
| Tumblr | api.tumblr.com/v2 | “真的不是成人网站” |
| foursquare | api.foursquare.com/v2/venues/search?q=apple&categoryId=asad123456 | “基于地理位置射交” |
如何设计出国际范儿的 Api
背口诀
观察和分析上一小节中的国际大厂的设计往往都具备以下几个特点：
-
短小便于输入的 URI。
没人喜欢复杂的单词。
-
人可以读懂的 URI。
名片是拿给人读的。不要把机器码和 16 进制写到 URI 里。
-
没有大小写混用的 URI。
实际上一般的事实规范是建议全部小写。
-
修改方便的 URI。
-
不会暴露服务端架构的 URI。
-
规则统一的 URI。
-
当端点里出现两个以上的单词时，使用脊柱法（连词符号）。
合理利用 REST API
REST API 的概念首先出现在 Roy Fielding 的论文中。
- 狭义上的 REST API 实际上就是指符合 Fielding 的 REST 架构风格的 Web 服务系统。REST API 的设计风格严谨，考虑周全，结构优美。但过于苛刻的标准一直是狭义 REST API 推广壮大的绊脚石。
- 广义上的 REST API 指符合 RPC 风格的 JSON + Http 的接口的系统。这样的 REST API 定义却又过于粗犷和随意了。
于是，针对 WEB API 的发展以及广义 REST 与 狭义 REST 的特点， Martin Fowler 提出在达到完美的 REST API 之前有以下几种 API 的设计级别。
- REST LEVEL0: 使用 HTTP
- REST LEVEL1: 引入资源的概念
- REST LEVEL2: 引入 HTTP 动词
- REST LEVEL3: 引入 HATEOAS 概念
按照 HTTP 协议中，URI 代表资源，而 HTTP method 代表对资源的操作。
我以此理论作为基础，再参照上述 REST LEVEL，设计了一个符合 REST LEVEL2 标准的示例 URI ，如下所示
| 目的 | 端点 | 方法 |
|---|---|---|
| 获取用户信息列表 | api.example.com/v1/users | GET |
| 新用户注册 | api.example.com/v1/users | POST |
| 获取特定用户信息 | api.example.com/v1/users/:id | GET |
| 更新用户信息 | api.example.com/v1/users/:id/ | PUT/PATCH |
| 删除用户信息 | api.example.com/v1/users/:id | DELETE |
从今以后，你的 WEB API 只要参照以上示例，那就是符合基本标准看起来还不错的设计。
写在最后
- 我是 Chuck1sn，一个长期致力于现代 Jvm 生态推广的开发者。
- 您的回帖、点赞、收藏、就是我持续更新的动力。
- 举手之劳的一键三连，对我来说是莫大的支持，非常感谢！
- 关注我的账号，第一时间收到文章推送。
ps：本篇文章是通用概念，和 Java 关系不大。不过为了和我之前的 blog 关联在一起，我统一取了《你不知道的 Java》这个名字。如果需要查看之前的文章，请在论坛搜索关键词。
有问题欢迎在回复中留言，大家一起探讨。
看了后发现我设计的是什么哇！一般都是直接拿业务起名笑死