一.接口定义
1.1 HTTP方式(暂不使用路径中带{id},注意看1.3)RESTFUL风格: 通过标准HTTP方法对资源CRUD
GET: 查询
GET /v1/student
GET /v1/student/{id}
GET /v1/student/{id}/course
POST: 新增
POST /v1/student
POST /v1/student/{id}/course
PUT: 更新
PUT /v1/student/{id}
PUT /v1/student/{id}/course
DELETE: 删除
POST /v1/student/{id}
POST /v1/student/{id}/course
1.2 RPC方式
RPC风格:api命名是一种动词,比如getUserInfo , createUser,一般使用GET ,POST两种请求方式
GET: 查询
GET /v1/get-student
GET /v1/get-student-list
POST: 增/删/改
POST /v1/create-student
POST /v1/update-student
POST /v1/del-student
1.3 特殊说明
目前由于存在JAVA和golang两种开发语言,golang对RESTFUL风格接口支持暂不友好,目前统一采用RPC风格的接口命名方式,如下:
URL请求中不采用大小写混合的驼峰命名方式,尽量采用全小写单词,如果需要连接多个单词,则采用连接符“-”连接单词
命名方式
● 查询单个对象接口用:get 做前缀 get-order
● 查询多个对象接口用:list 做前缀 list-order
● 获取统计值的方法用: count做前缀 count-order
● 插入单个对象接口用:save /insert 做前缀 save-order
● 批量插入多个对象接口用: batch-save 做前缀 batch-save-order
● 插入单个对象接口用:update /edit 做前缀 update-order
● 批量插入多个对象接口用: batch-update 做前缀 batch-update-order
● 删除单个对象接口用:delete /remove 做前缀 delete-order
● 批量插入多个对象接口用: batch-delete 做前缀 batch-delete-order
二. 接口组成
/{module}/{adapter}/{version}/{function-path}
{module} : 应用所属模块(领域)
{adapter} : 接口面向的应用端,如 pc/qw/app等等
{version} : 版本号,接口版本号,用于接口的迭代升级,如v1/v2/v3
{function-path} : 具体功能方法,如 get-user , save-user , update-user , delete-user
接口所有的特殊说明都需要在Yapi上面提现,尤其是参数枚举值+特殊说明
三. 基础出入参
3.1 基础分页入参
参数名称 类型 是否必须 默认值 说明
page integer 否 1 页码
pageSize integer 否 20 分页数量(视业务协定)
orderBy string 否 createTime 排序字段(视业务协定)
orderDirect string 否 desc 排序规则 desc为降序,asc为升序
3.2 基础分页出参
参数名称 类型 是否必须 默认值 说明
code integer 是 500200 状态码(500200成功,其他失败)
msg string 是 空字符串 消息
data object 是 空对象 具体返回数据
data.list object [] 否 空数组 具体数据
data.page integer 否 1 当前页码
data.pageSize integer 否 20 每页大小
data.total Long 否 0 总数量
traceId string 否 调用链日志id
success boolean 是 true 是否成功
{
“code”:500200,
“msg”:“ok”,
“data”:{
“list”:[{}],
“page”:1,
“paseSize”:20,
“total”:200
}
“traceId”: “链路id”,
“success”:true / false
}
3.3 基础出参(无分页)
参数名称 类型 是否必须 默认值 说明
code integer 是 500200 状态码(500200成功,其他失败)
msg string 是 空字符串 消息
data object 是 空对象 具体返回数据
traceId string 否 调用链日志id
success boolean 是 true 是否成功
{
“code”:500200,
“msg”:“success”,
“data”:{}
“traceId”: “链路id”,
“success”:true / false
}
四. 旧接口参数说明
已经存在的接口不进行任何改动,此规范对后续新接口生效