微服务接口设计（RESTful规范）

微服务的接口设计（RESTful规范）

基本知识

• URI：在RESTful架构中，每个URI代表一种资源
• URI规范：
  1. 不用大写
  2. 用中杠-，不用下划线_
  3. 路径中不能有动词，只能有名词
  4. 名词表示资源集合，要使用复数形式
• 通过标准HTTP方法对资源进行CRUD（将服务行为映射到标准HTTP动词）
  1. CRUD：增加(Create)、检索(Retrieve)、更新(Update)和删除(Delete)几个单词的首字母简写
  2. GET（SELECT）：从服务器取出/请求资源
  3. POST（CREATE）：在服务器新建资源
  4. PUT（UPDATE）：在服务器更新资源
  5. 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：不幂等，多次请求会在数据库表中生成多条记录