API 规范

接口命名规范

请求方法规范

方法	用途	幂等性	说明	使用理由
GET	读取数据	是	用于查询操作，不修改数据	GET 天然幂等，可被浏览器缓存，适合查询场景
POST	提交数据	否	用于创建或执行业务逻辑	POST 可携带复杂请求体，适合写入操作，统一使用 POST 便于后端统一处理

URI 结构规范

结构说明

层级	说明	示例	是否必需
模块名	后端模块标识	`iam`、`sys`、`cms`	是
权限标识	免鉴权接口标识	`public`	否
资源名	业务资源名称	`user`、`order`	是
操作后缀	具体操作类型	`page`、`list`、`info`	是

结构示例

完整 URI	模块名	权限标识	资源名	操作后缀	说明
`/iam/user/page`	`iam`	-	`user`	`page`	用户分页查询（需鉴权）
`/iam/user/list`	`iam`	-	`user`	`list`	用户列表查询（需鉴权）
`/iam/user/info/{id}`	`iam`	-	`user`	`info`	用户详情查询（需鉴权）
`/iam/user/save`	`iam`	-	`user`	`save`	用户保存（需鉴权）
`/iam/user/remove`	`iam`	-	`user`	`remove`	用户删除（需鉴权）
`/iam/public/login`	`iam`	`public`	`login`	-	用户登录（免鉴权）
`/iam/public/picture/captcha`	`iam`	`public`	`picture`	`captcha`	获取验证码（免鉴权）

操作后缀与 URI 示例

后缀	用途	HTTP 方法	URI 示例	接口描述	是否需要鉴权
`/page`	分页查询	GET	`/iam/user/page`	获取用户分页	是
`/list`	列表查询	GET	`/iam/user/list`	获取用户列表	是
`/info`	详情查询	GET	`/iam/user/info/{id}`	获取用户详情	是
`/save`	保存（新增/修改一体）	POST	`/iam/user/save`	保存用户信息	是
`/create`	新增（仅有新增需求）	POST	`/iam/user/create`	新增用户	是
`/update`	修改（仅有修改需求）	POST	`/iam/user/update`	修改用户信息	是
`/remove`	删除（单个/批量）	POST	`/iam/user/remove`	删除用户	是
`/options`	下拉选项查询	GET	`/iam/user/options`	获取用户下拉选项	是
-	登录接口	POST	`/iam/public/login`	用户登录	否
`/captcha`	获取验证码	GET	`/iam/public/picture/captcha`	获取图片验证码	否

接口组划分规则

规则	说明	示例
去除模块名	删除一级模块标识	`/user/page` → `user`
去除权限标识	删除 `public` 层级	`/public/login` → `login`
去除操作后缀	删除末尾操作标识	`/user/page` → `user`
剩余部分为接口组	相同接口组共享业务逻辑	`user` 接口组

接口参数规范

请求参数列表

参数名称	参数位置	类型	默认值	必填	说明
token	header	String	-	否	用户认证 token
current	query	Integer	1	否	页码
size	query	Integer	10	否	每页条数
orderBy	query	String	id desc	否	排序字段
timeFrom	query	String	-	否	时间范围开始
timeTo	query	String	-	否	时间范围结束

参数格式规范

参数类型	格式要求	示例
时间格式	yyyy-MM-dd HH:mm:ss	2024-01-01 12:00:00
日期格式	yyyy-MM-dd	2024-01-01
页码范围	≥ 1	current ≥ 1
每页条数	1-100	size: 1-100

接口返回值规范

通用返回字段

字段名	类型	说明
code	Integer	响应码
msg	String	响应消息
data	Object	业务数据
requestTime	Long	请求进入时间
responseTime	Long	响应返回时间
costTime	Long	请求耗时（毫秒）

响应码说明

响应码	含义	处理方式
-1	系统错误	需要开发人员处理
0	业务提示	只需反馈给页面
1	成功	正常业务处理
> 1	业务错误	参考错误码对照表

分页返回结构

字段名	类型	说明
current	Integer	当前页码
size	Integer	每页条数
page	Integer	总页码数
total	Integer	数据总条数
offset	Integer	偏移量
rows	Array	业务数据列表

返回值示例

成功响应：

json

{
  "code": 1,
  "msg": "success",
  "data": {
    "id": 1,
    "name": "John"
  },
  "requestTime": 1620000000000,
  "responseTime": 1620000000100,
  "costTime": 100
}

分页响应：

json

{
  "code": 1,
  "msg": "success",
  "data": {
    "current": 1,
    "size": 10,
    "page": 10,
    "total": 100,
    "offset": 0,
    "rows": [...]
  },
  "requestTime": 1620000000000,
  "responseTime": 1620000000150,
  "costTime": 150
}

错误码对照表

Token 相关错误

错误码	提示语	说明
10001	token 为空！	需要在 header 中传递 token
10002	token 不正确或已失效！	token 无效或过期
10003	非法传输 token！	token 位置不正确
10004	非法长度的 token！	token 格式异常
10005	token 签名校验失败！	token 内容被篡改

权限相关错误

错误码	提示语	说明
20001	用户登录环境改变！	终端改变，需重新登录
20002	api url can not be cors	接口地址不被允许
20003	origin url can not be cors	前端域名不被允许
20004	err routers, check the uri!	路由错误

登录验证错误

错误码	提示语	说明
30001	登录名或密码错误	防止用户猜测
30002	图片验证码错误	验证码校验失败
30003	需要图片验证码	需要传入验证码
30004	短信验证码错误	短信验证码校验失败

数据操作错误

错误码	提示语	说明
40001	操作需要带数据版本号！	需要提交 version 字段
40002	数据不存在或已不是最新的！	数据被更新或删除
40003	操作需要带数据标识！	需要传入 id

订单相关错误

错误码	提示语	说明
50001	订单支付超时已自动取消，请重新下单！	订单超时
50002	订单已完成支付，请不要重复支付！	重复支付
50003	订单状态异常，不能支付！	订单状态错误

权限校验规范

权限校验规则

规则	说明	示例
token 校验	需验证权限的接口必须在 header 传 token	Authorization: Bearer xxx
临时 token	一次性 token 从专用接口获取	仅支持 query 参数传递
Origin 判断	通过 Origin header 确定前端站点	可在 query 附加

免鉴权接口规则

规则	说明	示例
路径标识	URI 中包含 `public` 层级	`/iam/public/login`
白名单	配置在安全配置类中	无需登录即可访问
验证码接口	获取验证码无需鉴权	`/iam/public/captcha`

API 规范 ​

接口命名规范 ​

请求方法规范 ​

URI 结构规范 ​

结构说明 ​

结构示例 ​

操作后缀与 URI 示例 ​

接口组划分规则 ​

接口参数规范 ​

请求参数列表 ​

参数格式规范 ​

接口返回值规范 ​

通用返回字段 ​

响应码说明 ​

分页返回结构 ​

返回值示例 ​

错误码对照表 ​

Token 相关错误 ​

权限相关错误 ​

登录验证错误 ​

数据操作错误 ​

订单相关错误 ​

权限校验规范 ​

权限校验规则 ​

免鉴权接口规则 ​

API 规范

接口命名规范

请求方法规范

URI 结构规范

结构说明

结构示例

操作后缀与 URI 示例

接口组划分规则

接口参数规范

请求参数列表

参数格式规范

接口返回值规范

通用返回字段

响应码说明

分页返回结构

返回值示例

错误码对照表

Token 相关错误

权限相关错误

登录验证错误

数据操作错误

订单相关错误

权限校验规范

权限校验规则

免鉴权接口规则