【接口设计】如何设计统一 RESTful 风格的数据接口

近年来，随着移动互联网的发展，各种类型的客户端层出不穷。如果不统一数据接口，则会造成冗余编码，增加成本。RESTful 风格的 API 正适合通过一套统一的接口为 PC、手机 APP 等设备提供数据服务。

1.版本控制

随着业务需求的变更、功能的选代，API 的更改是不可避免的。当一个 API 修改时，就会出现很多问题，比如，可能会在 API 中新增参数、修改返回的数据类型。这就要考虑根据原先版本 API 编写的客户端如何保留或顺利过渡。所以，需要进行版本控制。

REST 不提供版本控制指南，常用的方法可以分为 3 种。

1.1 通过 URL

通过 URL 是最直接的方法，尽管它违背了 URI 应该引用唯一资源的原则。当版本更新时，还可以保障客户端不会受到影响，如下面使用不同 URL 来确定不同版本。

二级目录 的方式：

• API 版本 V1：http://eg.com/api/v1。
• API 版本 V2：http://eg.com/api/v2。

二级域名 的方式：

• API 版本 V1：http://v1.eg.com。
• API 版本 V2：http://v2.eg.com。

还可以包括日期、项目名称或其他标识符。这些标识符对于开发 API 的团队来说足够有意义并且随着版本的变化也足够灵活。

1.2 通过自定义请求头

自定义头（例如，Accept-version）允许在版本之间保留 URL。

1.3 通过 Accept 标头

客户端在请求资源之前，必须要指定特定头，然后 API 接口负责确定要发送哪个版本的资源。

2.过滤信息

如果记录数量很多，则服务器不可能一次都将它们返回给用户。API 应该提供参数，实现分页返回结果。下面是一些常用的参数。

• ?limit=10：指定返回记录的数量。
• ?page=5&size=10：指定第几页，以及每页的记录数。
• ?search_type=1：指定筛选条件。

3.确定 HTTP 的方法

在 RESTful 中，HTTP 的方法有以下几种。

• GET：代表 请求资源。
• POST：代表 添加资源。
• PUT：代表 修改资源。PUT 是进行全部的修改，大家在编写修改功能时可能会遇到这样的情况：只修改了一个字段，但提交之后导致其他字段为空。这是因为，其他字段的值没有一起提交，数据库默认为空值。如果只修改一个或几个字段，则可以使用 PATCH 方法。
• DELETE：代表 删除资源。
• HEAD：代表发送 HTTP 头消息，GET 中其实也带了 HTTP 头消息。
• PATCH：PUT 与 PATCH 方法比较相似，但它们的用法却完全不同，PUT 用于替换资源，而 PATCH 用于 更新部分资源。
• OPTIONS：用于获取 URI 所支持的方法。返回的响应消息会在 HTTP 头中包含 Allow 的信息，其值是所支持的方法，如 GET。

4.确定 HTTP 的返回状态

HTTP 的返回状态一般有以下几种。

• $200$：成功。
• $400$：错误请求。
• $404$：没找到资源。
• $403$：禁止。
• $406$：不能使用请求内容特性来响应请求资源，比如请求的是 HTML 文件，但是消费者的 HTTP 头包含了 JSON 要求。
• $500$：服务器内部错误。

5.定义统一返回的格式

为了保障前后端的数据交互的顺畅，建议规范数据的返回，并采用固定的数据格式封装。如：

异常信息：

{"code": 10001, "msg": "异常信息", "data": null
}

成功信息：

{"code": 200, "msg": "成功"， "data": {"id": 1,"name": "pipi", "age": 26}
}