《你不知道的 JAVA》💘 什么是好的 Web Api 设计 （第一章）

工程思维落地

《你不知道的 JAVA 》系列博客的工程理念与设计模式，已落地成一款 全新设计的 Java 脚手架 ，可与博客配套使用。

Web Api 的重要性

设计 api 端点是后端开发经常接触的工作，但你是否从来没有想过好的 web api 应该是什么样子？

Api 端点的设计就像名片一样——专业的名片可以在客户面前建立信任感；糟糕的名片会让你的产品在被使用前就给客户留下负面印象。一旦客户产生负面情绪，这种情绪可能就会蔓延到产品及其相关公司上。

今天就和大家分享一些 api 设计的套路与规范，让你也能设计出优雅、健壮、扩展性强的应用程序接口。

设计原则，如果有的话

先让我们回顾曾经提到过的关于设计模式的内容：设计模式的精髓在于设计原则，而非模式的生搬硬套。与此类似，优雅的 Web Api 有两个重要原则如下所示：

• 设计规范明确的内容必须遵守相关规范
• 没有设计规范的内容必须遵守相关事实标准

也许你依然对如何设计 web api 毫无头绪，但是别着急，好的创作总是从模仿开始的。

下面是一些国际大厂的 api 示例，给自己一些时间消化消化。

厂名	uri	备注
Twitter	api.twitter.com/1.1	"治国理政平台"
Google Calendar	www.googleapis.com/calendar/v3	"大厂"
instagram	api.instagram.com/v1/usrs/search?q=jack	"宠物自拍网站"
linkedin	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。

  api.sample.com/user/:id

• 不会暴露服务端架构的 URI。

  api.sample.com/servlet/login.do

• 规则统一的 URI。

  api.com.cn/Api/user-InfoById/info.json

• 当端点里出现两个以上的单词时，使用脊柱法（连词符号）。

  api.linkedin.com/v1/people-search

合理利用 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 生态推广的开发者。
• 您的回帖、点赞、收藏、就是我持续更新的动力。
• 举手之劳的一键三连，对我来说是莫大的支持，非常感谢！
• 关注我的账号，第一时间收到文章推送。

blog