RestFul命名实践

最新推荐文章于 2024-01-07 10:58:31 发布

原创最新推荐文章于 2024-01-07 10:58:31 发布 · 434 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#restful #http #设计规范

背景

为什么你的RestFul接口看起来不那么好看，甚至有点膈应？大部分人自认自己的接口是restful风格，可事实上一点都不restful。

经常看到有同学定义以下命名接口：

POST /serviceX/createXXX
POST /serviceX/getXXX
POST /serviceX/createXXXByIds

常见问题：

不管什么接口都用POST，破坏了restful中使用httpMethod作为动词语义的最佳实践
httpMethod已经使用了POST，又在路径中出现create/update等动词
参数的语义直接通过ByXXX定义，看不出来参数对于“数据实体”的实际意义

基本规范

Http Method

充分使用http method的语义已经可以覆盖99%的命名场景

POST - 创建（当然也有部分复杂请求用POST，极特殊情况可以例外）
PUT - 更新，也可以表示追加
PATCH - 更新某条记录的某个属性
DELETE - 删除
GET - 查询
HEAD - 查看简要信息
OPTION - 查看备选信息（一般很少用）

URI

全称：统一资源标志符 (Uniform Resource Identifier)。
在HTTP语义中原本就是用于定位资源的（所以说uri中为什么不要出现动词，不然语义很奇怪）

命名场景及建议

主谓宾结构

A向B转账：追加一个"转账"

PUT /serviceX/transfer/{sourceAccountId}/to/{targetAccountId}
Content-Type: application/json

{
    "amount": 123124,
    "for": "stock"
    // ... other
}

拒绝某条审批

PUT /serviceX/approval/{approverUserId}/denial/{instanceId}
Content-Type: application/json

{
    "amount": 123124,
    "for": "stock"
    // ... other
}

精确查询

查询某个用户信息

GET /serviceX/user/{id}

查询用户职级

GET /serviceX/user/{id}/rank

关联查询

查询某个用户的支付记录

GET /serviceX/user/{id}/payments?startDate=x&endDate=y

条件查询list

查询操作日志

GET /serviceX/operation/logs?operator=xxx&date=2022-11-11&keywords=yyy&start=0&limit=100

创建实体

创建用户

POST /serviceX/user
Content-Type: application/json

{
    "username": "A",
    "phone": "1100...."
    // ... other
}

修改实体

修改用户信息

PUT /serviceX/user/{id}
Content-Type: application/json

{
    "phone": "1100....",
    "age": 22,
    // ... other
}

删除实体

DELETE /serviceX/user/{id}

修改实体属性

修改职级

PATCH /serviceX/user/{id}/rank
Content-Type: application/json

{
    "from": 1,
    "to": 2
}

创建关联记录

创建用户转账记录

POST /serviceX/user/{id}/payments
Content-Type: application/json

[{
    "sourceAccount": "AAA",
    "targetAccount": "BBB....",
    "amount": 123124
    // ... other
}]

更新关联记录