阅读 4198

基于工程经验的『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 的风格。

接口安全

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