定义接口出入参规范

一.接口定义

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
}

四. 旧接口参数说明

已经存在的接口不进行任何改动，此规范对后续新接口生效