微服务的接口设计(RESTful 规范)
基本知识
URI: 在 RESTful 架构中, 每个 URI 代表一种资源
URI 规范:
不用大写
用中杠 -, 不用下划线_
路径中不能有动词, 只能有名词
名词表示资源集合, 要使用复数形式
通过标准 HTTP 方法对资源进行 CRUD(将服务行为映射到标准 HTTP 动词)
CRUD: 增加 (Create), 检索(Retrieve), 更新(Update) 和删除 (Delete) 几个单词的首字母简写
GET(SELECT): 从服务器取出 / 请求资源
POST(CREATE): 在服务器新建资源
PUT(UPDATE): 在服务器更新资源
DELETE: 从服务器删除资源
使用 JSON 作为微服务提交和返回数据的通用语言
使用 HTTP 状态码来传达服务调用的状态
示例:
服务器维护资源如下(使用一张表存用户信息)
一般每种资源都会设计字段 id 来做唯一标识, 便于请求资源
- User {
- int id;
- int age;
- bool sex;
- String phone;
- role String;
- ...
- }
该资源的 URI 设计为
ip:port/service-name/users
获取全部用户的信息
GET ip:port/service-name/users
创建一个用户
POST ip:port/service-name/users
获取某个用户的信息
GET ip:port/service-name/users/id
修改某个用户的信息
PUT ip:port/service-name/users
删除某个用户的信息
DEL ip:port/service-name/users/id
错误设计如下:
创建一个用户
POST ip:port/service-name/users/add
获取某个用户的信息
GET ip:port/service-name/users/id/get
修改某个用户的信息
PUT ip:port/service-name/users/change
有时请求中需要带有很多条件, 这些条件可以放在 RequestParam(query)里.
比如用户管理 B 端, 做分页展示时, 如果每页展示 20 个用户, 接口的设计可能为
GET ip:port/service-name/users?offset=xxx&limit=20
比如返回所有管理员权限的用户, 接口的设计可能为
GET ip:port/service-name/users?role=admin
当然, 上述只是规范, 实际开发中可能会有很多 API 的设计会突破 RESTful 规范.
注意保证幂等
幂等: 请求一次和请求多次的效果是一样的.
GET: 由于 GET 请求仅仅是获取资源 并不修改资源, 所以能保证幂等
PUT: 同样的请求, 修改一次和修改多次是一样的, 能保证幂等
DEL: 同理, 能保证幂等. 但是多次请求, 只有第一次能返回 200, 其他都应该是 404
POST: 不幂等, 多次请求会在数据库表中生成多条记录
微服务接口设计(RESTful 规范)
来源: http://www.bubuko.com/infodetail-3684196.html