聊聊RESTful - 接口设计篇（一）

原文链接：https://howardwchen.com/2017/09/18/talk-about-restful-popular-api-design-1/
（本文为“聊聊RESTful”系列文章第二篇，其他文章可通过篇尾链接查看）

大家好，欢迎大家来到“就浩这口”，今天我们继续聊聊RESTful。
在我的上一篇文章科普篇中为大家介绍了REST的起源与REST成熟度模型。同时我也指出网上有大量介绍RESTful接口设计的文章，如果我们不理解真正的REST，那么单纯的接口设计的讨论会让我们对REST产生误解。那么在我们了解了什么是真正的REST之后，再来讨论接口设计，就是学以致用。
所以，今天我们就来聊一聊RESTful的接口设计。我计划分以下几部分来介绍：

• URI命名
• HTTP方法
• 消息体格式
• 异常处理
• 版本化
• 鉴权
• 接口文档

今天先来说说URI命名和HTTP方法。

URI命名

资源与名词

了解RESTful接口的人都知道，URI的命名应该使用名词，为什么呢？因为REST对于信息的核心抽象是资源，而表示资源的词语天然的就是名词，所以这不是什么技术问题，而是常识。

看似简单的接口命名，其背后却是REST当中核心的资源概念。学过面向对象编程的人们都知道这么一句话，万物皆对象。类似的，对于REST则是，万物皆资源。资源这一概念是在Fielding的论文中5.2.1.1小节来介绍的

5.2.1.1 Resources and Resource Identifiers
The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. “today’s weather in Los Angeles”), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author’s hypertext reference must fit within the definition of a resource. A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time.

更详细的介绍请大家阅读论文。

不过相对于具体实践，论文中对资源的描述还是相当抽象的，很多开发人员不知从何下手。我觉得，所谓资源的设计，在简单项目中与我们传统面向对象编程的设计没有太大的区别。你要对你的需求做详细的需求分析，划分模块，梳理流程，抽象出需求背后的逻辑关系，数据结构等。但是在规模更大，或者业务更复杂的系统中，传统方式便显得力不从心。这里我觉得DDD的理论完全可以作为资源设计的方法论。DDD本身就是为了解决复杂系统而设计的，它提供了多种模式与方法，帮助我们更好的分析需求，以及长期迭代系统。DDD不是本文的重点，我也还在学习中，这里不做更具体的说明了。以后我会做一个DDD的专题跟大家细说。

总之URI的命名，其背后就是对系统的整体设计。大家要做好充足的前期工作，避免生米煮成熟饭时悔之晚矣。

命名规则

命名规则永远是一个具有争议的话题，在RESTful接口中，对于URI一个普遍接受的规则是：全部小写，用中划线连接。

之所以不混用大小写字母，是因为早期的URI一般都是表示服务器上的文件路径，而不同服务器对大小写的敏感性是不同的，为了兼容不同服务器所以才规定不能混用大小写字母，然后用中划线或下划线连接多个单词。

我们如今开发的api，URI一般不再表示服务器上的文件了，而是一种程序使用的路由，而各类开发程序对字符串的判断也都是区分大小写的，所以就算URI混用了大小写一般也不会有问题。但是为了与那些仍旧表示服务器文件路径的URI保持一致，更多的人仍旧愿意沿用全部使用小写字母的规则。至于连接多个单词使用中划线还是下划线，我只能说，中划线使用得更加广泛。

单数复数

在英文中，名词是有单复数之分的，所以在对资源命名时究竟是用单数还是复数，这也成为了一个有争议的问题。我在网上搜寻了很多相关资料，大部分人认为应该统一使用复数，但我在这里有不同的看法，我的使用习惯是，用单数来表示单个资源，用复数来表示集合资源。我们先来看下网上关于使用复数的说法：

1. 阮一峰的网络日志《RESTful 设计指南》

在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的”集合”（collection），所以API中的名词也应该使用复数。

这篇文章写于2014年，这段话中的数据库的表格名，我理解指的是mysql这类的关系型数据库的表名。我在科普篇中也提到过，基于资源的架构设计是不同于基于关系型数据的设计的，关系型数据库的数据结构和资源结构是不能完全对应的，所以作者这里用了往往一词，因为现实中确实有很多人在这么做，但严格来讲，一个良好的资源设计，是很难和关系型数据库一一对应上的。因此我并不赞同作者说的因为数据库中的表都是同种记录的”集合”（collection）而推导出我们的资源命名应该使用复数。另一方面，我们仔细想一下，我们给数据库表命名时可是很少用复数的啊，上网搜下数据库表名命名规则，同样有很多的争论，但我相信，你见过的单数要更多。而面向对象的开发中，对象的命名也大都是单数，集合变量的命名才使用复数。当然，所有这些情况其实都暗含着集合的含义，也许我们都用该用复数，可实际情况并非如此。

2. Best Practices for Designing a Pragmatic RESTful API及其译文

Should the endpoint name be singular or plural? The keep-it-simple rule applies here. Although y