Restful风格的接口命名规范

最近换了工作，入职以后写的代码review时被一直提及restful风格命名，被别人拿来无限鞭尸，今天做个总结，供参考！

REST是一个术语的缩写，REpresentational State Transfer，中文直译是“表征状态转移”。
REST是一套风格约定，RESTful是它的形容词形式。比如一套实现了REST风格的接口，可以称之为RESTful接口。

很多项目或公司要求用post 或get 放弃put、delete等，在效果上可以同样实现，但是无疑浪费了 HTTP 协议的潜力，而 REST 则充分利用了 HTTP 规范中的方法，达到接口描述的语义化。

restful风格命名可以分为两种思考方式，所以的都从这两种思路出发思考

• 请求 API 的 URL 表示用来定位资源；
• 请求的 METHOD 表示对这个资源进行的操作；

下面示例中的 get、create、search 等动词，都不应该出现在 REST 架构的后端接口路径中。比如：

/api/v1/getUser
/api/v1/createApp
/api/v1/searchResult
/api/v1/deleteAllUsers

总结：

首先加上了动词，肯定是使 URL 更长了；其次对一个资源实体进行不同的操作就是一个不同的 URL，造成 URL 过多难以管理。

其实当你回过头看“URL”这个术语的定义时，更能理解这一点。URL 的意思是统一资源定位符，这个术语已经清晰的表明，一个 URL 应该用来定位资源，而不应该掺入对操作行为的描述。其中 METHOD中的POST、GET、PUT、DELETE已经有了操作行为的描述

在 REST 架构的链接应该是这个样子：

• URL 中不应该出现任何表示操作的动词，链接只用于对应资源；

• URL 中应该单复数区分，推荐的实践是永远只用复数；比如GET /api/users表示获取用户的列表；如果获取单个资源，传入 ID，比如/api/users/123表示获取单个用户的信息；

• 按照资源的逻辑层级，对 URL 进行嵌套，比如一个用户属于某个团队，而这个团队也是众多团队之一；那么获取这个用户的接口可能是这样：GET /api/teams/123/members/234 表示获取 id 为 123 的小组下，id 为234 的成员信息。

  按照类似的规则，可以写出如下的接口

  /api/teams （对应团队列表）

  /api/teams/123 （对应 ID 为 123 的团队）

  /api/teams/123/members （对应 ID 为 123 的团队下的成员列表）

  /api/teams/123/members/456 （对应 ID 为 123 的团队下 ID 未 456 的成员）

1. 其他规范

   一些其他规范：
   规则1：URI结尾不应包含（/）
   规则2：正斜杠分隔符（/）必须用来指示层级关系
   规则3：应使用连字符（ - ）来提高URI的可读性
   规则4：不得在URI中使用下划线（_）
   规则5：URI路径中全都使用小写字母

2. 附上总结的一些实例

   Restful 场景示例

   /api/v1/objects
   
   创建
   ●参数放于body。
   ●POST 方法。
   
   ●POST /api/v1/objects : 创建一个主资源
   ●POST /api/v1/objects/{objectId}/sub_objects : 创建一个子资源
   ●POST /api/v1/objects/{objectId}/sub_objects/{sub_objectId}/名词 ： 对子资源做"名词"描述的动作，示例：
   ○/api/v1/enterprises/{enterpriseId}/week_reports/{weekReportsId}/comment 对企业下周报做评论(创建一个评论)
   ○/api/v1/enterprises/{enterprise}/members : 添加或邀请企业成员
   单个资源查询
   ●参数放于路径。
   ●GET 方法。
   
   ●GET /api/v5/enterprises/{enterprise}?access_token : 获取一个企业
   ●GET /api/v5/enterprises/{enterprise}/members/search?query_type=email&query_value=xxx : 获取企业成员信息(通过用户名/邮箱)
   ●GET /api/v5/enterprises/{enterprise}/week_reports/{id}?access_token=xxx ： 获取某个企业下某个周报的详情
   更新
   ●参数放于body。
   ●PUT 方法。
   
   ●PUT /api/v1/users/{id} : 更新用户信息
   ●PUT /api/v5/enterprises/{enterprise}/week_reports/{id}: 更新企业下某个周报的信息
   删除
   ●DELETE 方法。
   
   ●DELETE /api/v5/enterprises/{enterprise}/week_reports/{id} ：删除企业下某个周报
   列表查询(不带分页)
   ●参数放于路径。
   ●GET 方法。
   
   ●GET /api/v1/objects?access_token=xxx: 列出所有对象，如果数据量范围考虑不需要分页，则不分页
   
   分页查询(非模糊匹配)
   ●参数放于路径。
   ●GET 方法。
   
   ●GET /api/v5/enterprises/{enterprise}/week_reports/{id}/comments?access_token=xxx&page=1&limit=10 : 获取企业某个周报评论列表
   搜索(带模糊匹配，带分页)
   ●参数放于路径。
   ●GET 方法。
   
   ●GET /api/v5/search/users?access_token=xxx&page=1&limit=10&query_key=xxx&sort=xx_sort_type&order=desc/asc 搜索用户