基于工程经验的『RESTful接口设计规范』

前言

这篇文章，主要想总结自己在设计RESTful API的一系列经验于思考。

有些规范可能与标准规范有所出入，但是所有的考量都是基于『减少重复工作，增加可读性可维护性』而出发的。话说回来，我一直觉得 RESTful API 设计，确实没有很明显的公认规范（如果你是指发明者的那篇论文，估计没多少人详细阅读过，而且其作者只是提出了一系列概念而已）。网上的教程，似乎都是千篇一律的（我严重怀疑：都是 “借鉴or拷贝” 阮一峰老师的那几篇文章），僵硬而且呆板，有点教条化（从来没有人怀疑它们吗，反正我按照这些教条设计API，没有感受到多少乐趣）。

以上，并不是全部否定，好东西要充分吸收，不好的东西，要融合自己的理解，加以改造。

对 RESTful API 的认识

说到这个，似乎又要谈及『RESTful 是对资源的抽象』、『结合了HTTP 的特点』云云。不过这些都是一些没用的套话，没啥营养价值，而我想从另外的角度谈论这个。

既然是 API，一般都符合 API 的一般模式：

ResultType ApiName(ParamType )

1. 接口参数，即形参。可以是 string，int，以及其他任意可以称之为参数的东西
2. 接口返回值。可以是 string，int，以及其他任意可以称之为返回值的东西
3. 接口名（签名)
复制代码

我们来看看 RESTful 是如何对应上这个模式的：

HttpResponse URL(HttpRequest)

1. HttpRequest：包括请求头，URL参数，请求body参数
2. HttpResponse: 包括响应头，响应的body
复制代码

这样来看，RESTful API 无非是一种特殊的API 而已，通用的 API 设计法则，同样适合 RESTful，只不过非变换形式而已。

那么我们大概有哪些比较通用的标准呢？大概有这些：

1. 接口命名，必须做到清晰。一般来说，做到『动宾短语』即可。
2. 接口数量，越少越好。三个不如两个，两个不如一个，一个不如没有，最好的 API 就是『没有API』。
3. 有明确的输入输出。念念不忘必有回响，总是有返回值，告诉调用端，我到底做了什么，做得怎么样，即：反馈。

下面就来看看这些标准，是如何影响下文的内容的，：）。

URL设计，及其反模式

URL 就是接口签名，而签名必须做到清晰，没有歧义。

有统一的前缀 & 版本化

如果后端架构是服务化的，那么有可能每个服务会对外提供公共的 RESTful API，那么有个统一的前缀格式，会比较好，比如：

/SERVICE_NAME/v1/users
or
/APP_NAME/v2/users
复制代码

尽量短小

同一份资源，可以有不同的路径，去理解它。比如：

User -- 1：N --> Server-- 1:N --> Client ... 更加复杂的实体映射关系

1. /users/{user_id}/servers/{server_id}/clients
2. /clients

一般大家倾向于选项 1（但是实体关联关系特复杂时，会缩短URL），
不过选项2 也是一个不错的选择，总而言之，口味问题吧。
复制代码

数量尽量少

接口数量越少越好，能合并的接口就尽量合并。比如，这样的情况：

获取用户列表信息：GET /users
获取单个用户信息：GET /users/{id}

坦白说，获取一个与获取一批，似乎并没有什么语义上的差别，
但是后端的同学就不一样了，他可能需要写两个 View Class。
所以只保留批量的接口，查询一个时，用 URL 参数传递就行了。
复制代码

这样的情况：

PUT /users/{id}
PUT /users

直接合并到一个接口里面做就行了，PUT 一个 user与 PUT 一群 user，有啥本质的不同吗？
复制代码

还有这样极端的情况：

DELETE /users/{id}

删除一个user与删除一批user，有啥不同？
如果要一次删除100 个 user，难道让前端同学，调 100 次这个接口？
多一次调用，就多一次风险（如网络问题），
这个时候就别守着 RESTful 那些个教条了，接口的可用性、效率性，更加重要。

这个时候，不如设计成这样（至于 DELETE 接口能不能传Request body，这里不讨论）：
POST /users_deletion
{
    "user_ids": [1, 2, 3, 4, 5]
}
复制代码

返回值设计

前面有说到，HttpResponse中，我们可以利用：

Response Headers
可以做少量文章，如自定义一个Header

Status Code
按照基本规范来，该404的404，该200的200

Response body
基本都是围绕这个做文章
复制代码

Response body 既要能正常返回信息，出错了也要告诉出错原因（错误码），出错详情。所以我们大概可以设计成这样：

{
    是否成功
    boolean "is_success":
    错误码是多少
    number|null "err_code":
    错误信息
    string|null "err_msg": 
    错误详情（可选）
    string|null "err_detail":
    出错的时哪个服务
    string|null "provider": 
    
    正常返回时的数据
    "response_data": {

    }
}
复制代码

这样，前端调用 API ，就有章法可循了，不至于盲目。

字段命名规范

没有很明确的规范，但是尽量跟随数据库的风格，即：下划线风格。
这样，在 序列化整个 Model 时，也许会很方便。

其他规范

接口限流

参考 GitHub 的风格。

接口安全

这个没法系统化，可以参考网络上相关文章。