API 规范
接口命名规范
- 请求方法规范：只能定义 GET, POST 请求
- GET 请求用于读取数据，天然幂等
- POST 用于请求逻辑。需要考虑幂等
- uri 规范
- 接口需要自解释。从接口的命名，即可猜测接口的用途。
- 一级为后端模块名，如：sys,iam,cms 等
- 免鉴权接口：二级为 public
- 特殊用途接口可不按一级二级三级规范，但建议按此规范
- 后缀规范：
- /page 分页查询
- /list 列表查询
- /info 详情查询
- /save 保存（新增修改一体，依赖于id判断）
- /create 新增（仅有新增需求时）
- /update 修改（仅有修改需求时）
- /remove 删除（需要考虑单个及批量）
- /options 列表查询（返回信息很简洁，一般用于生成下拉菜单）
- 去除一级，public 级，和后缀，其余部分可视为接口组
- uri 示例
- 获取用户分页: GET /iam/user/page
- 修改用户信息: POST /iam/user/update
- 登录界面获取验图片证码: GET /iam/public/picture/captcha
接口参数规范
- 若接口不支持，忽略对应参数
| 参数名称 | 参数含意 | 类型 | 默认值 |
|---|---|---|---|
| token | [header]用户token | String | NaN |
| current | 页码 | Integer | 1 |
| size | 每页数 | Integer | 10 |
| orderBy | 排序字段 | String | id desc |
| timeFrom | 时间范围开始 | yyyy-MM-dd HH:mm:ss | NaN |
| timeTo | 时间范围结束 | yyyy-MM-dd HH:mm:ss | NaN |
接口的返回值规范
| 参数名称 | 参数值 | 参数含意 |
|---|---|---|
| code | 200 | 功能无异常，正常返回 |
| x | 400 | 业务提示，只需反馈给页面 |
| x | 401 | 未认证，需要登录 |
| x | 403 | 无权限 |
| x | 404 | 资源不存在 |
| x | 429 | 请求过于频繁，被限流 |
| x | 500 | 系统错误，需要开发人员处理 |
| x | > 10000 | 请看 code 对照表 |
| msg | 提示消息 | 正常为 Success，异常时为具体提示 |
| requestTime | 请求时间 | 请求进入 controller 的时间 |
| responseTime | 响应时间 | 请求在Controller 进行set 结果的时间 |
| costTime | 时间消耗 | 在 Controller 内消耗的时间，单位为毫秒 |
| data | 详情 | 正常返回时为业务数据【无具体业务数据时返回 true】 |
| ==分页== | ==查询== | ==有返回== |
| current | Integer | 页码 |
| size | Integer | 每页数 |
| page | Integer | 总页码数 |
| total | Integer | 叫数据条数 |
| offset | Integer | 偏移量 |
| rows | Array | 具体的业务数据 |
返回特殊 code 代码对照表
code 定义与 sh-framework 的 ResultCode 枚举保持一致；认证失败统一返回 401，不再使用 token/登录态类业务码
| 代码 | 提示语 | 说明 |
|---|---|---|
| 10101 | 无法识别应用编码，请设置请求头或应用域名 | 缺少 appCode 识别信息 |
| 10102 | 无法识别租户编码，请设置请求头或租户域名 | 缺少租户识别信息 |
| x | x | x |
| 20002 | api url can not be cors | 接口地址不被允许使用 |
| 20003 | origin url can not be cors | 前端域名不被允许使用 |
| 20004 | err routers, check the uri! | 错误的路由 |
| x | x | x |
| 30001 | 登录名或密码错误 | 防止用户猜测，用户名和密码错误都使用同一个提示 |
| 30002 | 图片验证码错误 | 图片验证码错误 |
| 30003 | 需要图片验证码 | 需要图片验证码 |
| 30004 | 验证码错误 | 短信验证码错误 |
| 30005 | 验证码错误 | 邮箱验证码错误 |
| x | x | x |
| 40001 | 操作需要带数据版本号！ | 需要提交 version 字段 |
| 40002 | 数据不存在或已不是最新的！ | 数据id 不正确或已被更新 |
| 40003 | 数据不存在！ | 数据 id 不正确或已被删除 |
| 40004 | ID 不存在！ | 操作需要带 id |
| 40005 | 参数不存在！ | 缺少必要参数 |
| 40006 | 数据重复，唯一性校验失败！ | 唯一性校验失败 |
| x | x | x |
| 50001 | network error！ | 网络错误 |
| 50002 | no available server！ | 无可用服务节点 |
| 50003 | unknown ribbon error！ | 负载均衡未知错误 |
| x | x | x |
| 60001 | 订单支付超时已自动取消，请重新下单！ | 订单超时 |
| 60002 | 订单已完成支付，请不要重复支付！ | 订单已支付 |
| 60003 | 订单状态异常，不能支付 | 订单其他异常状态 |
权限校验
- 所有需要验证权限的接口，都需要验证 token，需要在 header 中传值。
- 对于只能使用一次的 token, 请从临时 token 接口获取token。临时 token 只能获取一次，只能 ? 传参
- 后端确定前端为哪个站点，是通过 headers 里面的 Origin 获取的，可选在 ? 上附加此参数。如果需要区分 Origin，在 postman 上可以进行模拟