快乐的一天

接口规范用来约束接口的一致性。一堆不统一的接口，不利于前后端代码复用，增加前后端接口联调成本，降低开发效率。 下面是我们团队的接口规范。 协议 为确保数据交互安全，正式地址用HTTPS协议。 接口url 路径以 api 开始。如 /api/student/list 路径中的英文字母使用小写字母。 路径中的单词分隔用-。 请求方法 不改变数据的接口用 GET。如: 获取列表接口，详情接口。 改变数据的接口用 POST。如: 新增接口，编辑接口，删除接口。 说明: 如果严格的按照HTTP方法的语义，新增接口应该用 PUT，删除接口应该用 DELETE。我们团队认为新增，删除接口均用 POST，易于记忆。这个细节，对整体的代码质量也没有影响。 请求参数 POST 的数据都会放在body里。用 x-www-form-urlencoded 格式。 token 放请求头中的 Authorization 字段。Authorization值的格式: Bearer token值。 接口版本 放请求头中的 Version 字段。 响应 返回json类型数据。如 { "errorCode": 0, "errorMsg": "", "data": {}// 或 [] } 说明: errorCode: 错误码。errorCode 为 0: 没有报错。 401: 未登录或登录过期，需重新登录。 errorMsg: 错误信息。没有报错，不返回 errorMsg 字段。 data: 主体内容。对于列表接口，data 是数组类型的。 响应字段用驼峰命名法。 列表接口 url 以 list 结尾。 如: /api/goods/list。 请求方法 GET。 请求参数 筛选条件 筛选条件: where。where 的值是 encodeURIComponent(JSON.stringify({列名1: 值, 列名2: 值, ...}))。如: 筛选年龄(age)为20的学生，url 是 /api/student/list?where=%7B%22age%22%3A20%7D。 列的筛选规则： 精确搜索: 列名。 模糊搜索: 列名__like。 大于: 列名__gt。 用于数字和日期的列。 大于等于: 列名__gte。 小于: 列名__lt。 小于等于: 列名__lte。 分页信息 页数: pageAt。 每页的数量: pageLimit。 如: /api/student/list?pageAt=2&pageLimit=10。 如果不传分页参数，默认返回第一页的10条数据。 排序信息 排序信息: order。order的值为: encodeURIComponent(JSON.stringify([{列名1: "asc(升序) 或 desc(降序)"}]))。 支持多个排序值。 响应 { "errorCode": 0, "errorMsg": "", "data": [], "pager": { "pageAt": 1,// 当前页 "total": 21// 总条数 } } 详情接口 url 以 detail/:id 结尾。 如: /api/goods/detail/3。 请求方法 GET。 响应 { "errorCode": 0, "errorMsg": "", "data": { "id": 1, // 更多字段 } } 新增接口 url 以 add 结尾。 如: /api/goods/add。 请求方法 POST。 响应 { "errorCode": 0, "errorMsg": "", "data": { "id": 1, } } data中的id为新增成功的数据的id。 编辑接口 url 以 edit/:id 结尾。如: /api/goods/edit/3。 请求方法 POST。 响应 { "errorCode": 0, "errorMsg": "", "data": {} } 删除接口 url 以 del/:id 结尾。如: /api/goods/del/3。 请求方法 POST。 响应 { "errorCode": 0, "errorMsg": "", "data": {} } 审核接口 url 以 audit/:id 结尾。如: /api/goods/audit/3。 请求方法 POST。 响应 { "errorCode": 0, "errorMsg": "", "data": {} } 接口文档要求 用 Postman 写。 每个字段必须有备注。 变化的值配置在环境中。如接口的域名。环境指一系列包含接口上下文变量的集合。