接口标准化

[any86]

为了开发效率以及可维护, 设计了如下标准.

接口返回值要求

错误代码仅用 http 状态码表示, 如:

状态码	描述
200	成功
401	无权限
301-400 & 402-5xx	各种错误, 下面会解释为什么
返回值内容依然还是 JSON 表示, 要求只返回需要的数据, 一般情况如下:

// 增删改
{
    "msg": "添加/编辑/删除成功/xxx",
}

或:

// 列表
{
    "list": [{"id":1},{"id":2},{"id":3}],
    "total": 19
}

// 列表无数据

{
    "total": 0
}

为什么这么表示?

接口状态在前端只是用来区分交互, 比如:
在"CURD" 中, "200" 只用来渲染表格 "401" 用来跳转到登陆,其他情况页面只是弹出错误提示,不论哪种错误页面也只是提示: "网络错误(httpStatus)", 比如"网络错误(502)"

用户不关心是哪种错误,因为他不解决 bug, 错误详情可以存储日志, 开发通过后台查询并解决 bug.

接口命名

使用基于"RESTful"的表示形式. 把所有接口地址都描述为一种"资源", 通过 http 请求方式来区分"增删改查", 比如"/user"表示用户, 针对用户的"增删改查"接口设计成如下:

请求方式	接口地址	描述
Get	/user	用户列表
Get	/user/{id}	单个用户信息
Post	/user	新增用户
Put	/user/{id}	编辑用户
Delete	/user/{id}	删除用户

特殊情况

简化的列表(下拉菜单/单选/复选/树)

下拉菜单是常见的表现形式, 但其接口数据比普通的表格数据都简单, 是个"键和值"对象的数组, 针对他的接口命名可以写成'/list/user',"键/值"字段用"label/value"表示:

// /list/user
[
    {label:'张三',value:1, ifNeed:'xxx'}
    {label:'李四',value: 2, ifNeed:'xxx'}
]

树

实际开发中, 可以给前端树形数据也可以只给列表, 列表只要数据中给出对应的"父 id"即可,根节点没有"父 id":

// /tree/user
[
    {label:'张三',value:1, ifNeed:'xxx'}
    {label:'李四',value: 2, ifNeed:'xxx', children:[
        {label:'李小五',value:21}
    ]}
]

或者

// /list/user
[
    {name:'张三',id:1, ifNeed:'xxx'},
    {name:'李四',id: 2, ifNeed:'xxx'},
    {name:'李小五',value:21,pid:2}
]

关于列表的参数

参数	说明
pageNum	页码
pageSize	每页信息数
condition	筛选条件,condition=id=1&age=20
sort	排序,sort=id=1&age=-1,表示id正序,age倒序