You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
435 lines
16 KiB
435 lines
16 KiB
广东保伦电子股份有限公司
|
|
|
|
产品接口说明书
|
|
|
|
|
|
|
|
|
|
产品名称：
|
|
产品型号：
|
|
撰 写 人：
|
|
所属部门：
|
|
审 核：
|
|
文件标题 文档编号
|
|
|
|
当前版本
|
|
产品接口说明书
|
|
生效日期
|
|
|
|
文档密级：机密
|
|
文档状态：[√] 草案 [ ] 正式发布 [ ] 正在修订
|
|
|
|
|
|
变更履历
|
|
|
|
|
|
序号 版本 变更描述 修订人/日期 审核/日期 批准/日期
|
|
目录
|
|
一、 概述................................................................................................................................... 4
|
|
1.1 编写目的................................................................................................................. 4
|
|
1.2 适用范围................................................................................................................. 4
|
|
1.3 术语说明................................................................................................................. 4
|
|
二、 通用规范........................................................................................................................... 4
|
|
2.1 基础 URL 与接口风格............................................................................................. 4
|
|
2.2 认证......................................................................................................................... 5
|
|
2.3 请求约定................................................................................................................. 6
|
|
2.4 统一响应格式......................................................................................................... 7
|
|
2.5 分页......................................................................................................................... 8
|
|
2.6 通用业务状态码..................................................................................................... 9
|
|
2.7 信封例外：文件导出........................................................................................... 10
|
|
2.8 数据字典............................................................................................................... 10
|
|
2.9 链路追踪............................................................................................................... 11
|
|
一、概述
|
|
1.1 编写目的
|
|
本文档面向前端开发，定义业务中台后端所有接口共同遵守的全局规范与开发契约，包括认证方式、请求与响
|
|
|
|
应格式、分页结构、错误码体系等跨接口恒成立的规则。
|
|
|
|
具体业务接口的入参/出参字段，以后续接口文档为准；本文档描述的规则对所有接口恒成立。
|
|
|
|
|
|
1.2 适用范围
|
|
本文档适用于所有参与业务中台前端设计、开发、测试的团队及个人。
|
|
|
|
|
|
1.3 术语说明
|
|
JWT Token：登录后签发的身份令牌，后续所有请求以请求头 Authorization: Bearer {token} 携带。
|
|
|
|
数据字典：由后台统一维护的 label/value 键值对，用于下拉框等可配置选项的数据源。
|
|
|
|
Trace Id：单次请求的全链路日志标识，通过响应头 X-Trace-Id 返回，用于问题排查。
|
|
|
|
|
|
二、通用规范
|
|
2.1 基础 URL 与接口风格
|
|
项 约定
|
|
|
|
Base URL 按环境提供：http://{host}:{port}（开发/测试/生产地址由后端
|
|
|
|
另行下发）
|
|
|
|
字符集 UTF-8
|
|
|
|
URL 形态 /api/{模块}/{资源或动作}，如 /api/auth/login/dingtalk、
|
|
|
|
/api/customer/customers/page
|
|
|
|
接口风格 非严格 RESTful：单条详情用 GET，其余（含分页查询、
|
|
|
|
保存、删除）一律 POST + 动作后缀（/page、/saveOrUpdate、/delete
|
|
|
|
等）
|
|
|
|
为什么不用严格 RESTful（PUT / DELETE / 语义化 URL）：
|
|
|
|
1. 解决 GET 传输复杂查询的天然缺陷
|
|
|
|
管理系统的查询条件通常复杂：多选过滤、日期范围、嵌套条件、批量 ID 数组……这些塞在 GET query 里
|
|
|
|
受 URL 长度限制，难以表达结构化参数。
|
|
|
|
2. 权限控制、日志审计与限流便利性
|
|
系统绕不开按钮级/接口级的权限控制和操作日志审计。/save、/delete 这种 URL 自身就说明操作，「一个操
|
|
|
|
作一个 URL」意味着权限点位、审计规则、网关限流都只需匹配 URL 字符串。
|
|
|
|
|
|
2.2 认证
|
|
（1）登录：通过钉钉扫码登录换取 token：
|
|
|
|
POST /api/auth/login/dingtalk
|
|
|
|
Content-Type: application/x-www-form-urlencoded
|
|
|
|
|
|
|
|
|
|
authCode=xxxxxx
|
|
|
|
成功后 data 中返回：
|
|
|
|
{
|
|
|
|
"code": 0,
|
|
|
|
"success": true,
|
|
|
|
"message": "success",
|
|
|
|
"data": {
|
|
|
|
"token": "eyJhbGciOiJIUzI1NiJ9.xxx.yyy",
|
|
|
|
"userInfo": { "userId": "1946xxxxxxxxxxxxx", "nickname": "张三" }
|
|
|
|
}
|
|
|
|
}
|
|
|
|
（2）携带 token：除登录接口外，所有请求都必须携带请求头：
|
|
|
|
Authorization: Bearer {token}
|
|
|
|
（3）token 生命周期：
|
|
|
|
• token 由后端滑动续期：只要持续在用，剩余有效期不足一半时后端自动续满。
|
|
|
|
• token 字符串自签发起固定不变（字符串内不含过期时间，有效期由服务端管理），续期发生在服务端内
|
|
|
|
部，前端无感知、无需替换本地 token。
|
|
|
|
• 前端不需要定时刷新 token，也没有 refresh token 机制。
|
|
|
|
• 收到 HTTP 401（响应体 code=40103）即代表未登录或登录已过期，此时才清除本地 token 并跳转登
|
|
|
|
录页。
|
|
|
|
（4）登出：POST /api/auth/logout（携带 token）。登出后该 token 立即失效（即使 JWT 本身未过期）。
|
|
|
|
（5）当前用户：GET /api/auth/me（携带 token）。
|
|
2.3 请求约定
|
|
（1）读操作（查询单条 / 列表 / 详情）
|
|
|
|
• 方法：GET
|
|
|
|
• 参数：全部放 URL query，如 GET /api/auth/dict/items?dictCode=customer_source
|
|
|
|
（2）写操作（保存 / 删除 / 登录等）与分页查询
|
|
|
|
• 方法：POST
|
|
|
|
• Content-Type：默认 application/x-www-form-urlencoded；仅文件上传接口使用 multipart/form-data。
|
|
|
|
• 参数：全部为表单字段，不使用 JSON body。
|
|
|
|
POST /api/auth/system/menus/save
|
|
|
|
Content-Type: application/x-www-form-urlencoded
|
|
|
|
Authorization: Bearer {token}
|
|
|
|
|
|
|
|
|
|
parentId=0&menuName=客户管理&menuType=2&path=/customer&sort=1&visible=true
|
|
|
|
（3）复杂字段：JSON 字符串嵌表单
|
|
|
|
当某个入参是对象或数组时，前端将其 JSON.stringify 后作为一个普通表单字段传递（是「各复杂字段各自
|
|
|
|
stringify」，不是整个 body 打包成一个 JSON）：
|
|
|
|
POST /api/customer/customers/save
|
|
|
|
Content-Type: application/x-www-form-urlencoded
|
|
|
|
Authorization: Bearer {token}
|
|
|
|
|
|
|
|
|
|
name=测试客户&ownerId=1946xxx&contacts=[{"name":"李四","phone":"13800000000"},{"name":"王五
|
|
|
|
","phone":"13900000000"}]
|
|
上例中 contacts 字段的值是 JSON 数组字符串（实际发送时需 URL 编码）。哪些字段是 JSON 字符串字段、
|
|
|
|
其内部结构长什么样，以接口文档中该接口的参数说明为准。
|
|
|
|
（4）数据类型约定
|
|
|
|
类型 约定
|
|
|
|
ID（含所有雪花 ID） 一律按字符串收发。后端返回时已序列化为字符串（超出 JS
|
|
|
|
Number 安全范围，转 Number 会丢精度），前端回传原样传字
|
|
|
|
符串即可
|
|
|
|
日期时间 yyyy-MM-dd HH:mm:ss，时区 GMT+8
|
|
|
|
日期 yyyy-MM-dd
|
|
|
|
时间 HH:mm:ss
|
|
|
|
布尔 true / false
|
|
|
|
|
|
2.4 统一响应格式
|
|
所有接口（文件导出除外，见 2.7）返回统一 JSON 结构：
|
|
|
|
{
|
|
|
|
"code": 0,
|
|
|
|
"success": true,
|
|
|
|
"message": "success",
|
|
|
|
"data": { }
|
|
|
|
}
|
|
|
|
字段 类型 说明
|
|
|
|
code number 结果码，0 为成功，其余见 2.6 通用
|
|
|
|
业务状态码
|
|
|
|
success boolean 是否成功
|
|
|
|
message string 提示信息。失败时为面向用户的中文
|
|
|
|
提示，前端可直接 toast 展示，无需自行
|
|
|
|
映射文案
|
|
|
|
data any 业务数据，可能为 null（如保存/删除
|
|
|
|
类接口成功时，对于列表查询，空列表返
|
|
|
|
回 [] 而不是 null），前端须判空
|
|
|
|
判定规则：
|
|
• 判成功：只看 success === true。
|
|
|
|
• 判失败后的分支处理（跳登录、回填表单等）：再看 code。
|
|
|
|
HTTP 状态码：业务失败（参数错误、业务规则不满足等）HTTP 状态码仍是 200，只能通过响应体的
|
|
|
|
success/code 判断。仅以下场景 HTTP 状态码非 200：
|
|
|
|
HTTP 场景 响应体 code
|
|
|
|
401 未登录 / 登录过期 40103
|
|
|
|
403 已登录但无权限 40301
|
|
|
|
404 接口路径不存在 40401
|
|
|
|
500 系统内部异常 50001
|
|
|
|
即使 HTTP 状态码非 200，响应体仍然是统一信封结构，前端全局拦截器可统一解析。
|
|
|
|
|
|
2.5 分页
|
|
（1）入参（POST 表单字段，所有分页接口通用），各业务分页接口在此基础上追加自己的过滤字段：
|
|
|
|
字段 类型 默认 说明
|
|
|
|
current number 1 当前页码，从 1 开始
|
|
|
|
size number 10 每页条数，上限 500，超
|
|
|
|
出自动收敛为 500
|
|
|
|
orderBy string - 排序字段，驼峰或下划线
|
|
|
|
均可（如 createTime）。仅允
|
|
|
|
许字母、数字、下划线，含非
|
|
|
|
法字符时排序被忽略
|
|
|
|
asc boolean false 是否升序，默认 false（新
|
|
|
|
数据在前）
|
|
|
|
（2）出参（data 为统一分页结构）
|
|
|
|
{
|
|
|
|
"code": 0,
|
|
|
|
"success": true,
|
|
|
|
"message": "success",
|
|
|
|
"data": {
|
|
|
|
"content": [ { "id": "1946xxx", "name": "测试客户" } ],
|
|
|
|
"total": 57,
|
|
"size": 10,
|
|
|
|
"current": 1,
|
|
|
|
"pages": 6,
|
|
|
|
"empty": false
|
|
|
|
}
|
|
|
|
}
|
|
|
|
字段 类型 说明
|
|
|
|
content array 当前页数据列表
|
|
|
|
total number 总条数
|
|
|
|
size number 每页条数
|
|
|
|
current number 当前页码（从 1 开始）
|
|
|
|
pages number 总页数
|
|
|
|
empty boolean 是否空结果（total == 0），前端无需
|
|
|
|
再判断 content.length
|
|
|
|
|
|
2.6 通用业务状态码
|
|
错误码分段规则（新业务模块会按段扩展，前端按段兜底处理即可）：
|
|
|
|
区间 含义
|
|
|
|
400xx 参数类错误
|
|
|
|
401xx 认证/身份类错误
|
|
|
|
403xx 权限类错误
|
|
|
|
404xx 资源不存在
|
|
|
|
405xx 请求方式错误
|
|
|
|
500xx 系统/外部调用错误
|
|
|
|
6xxxx 业务错误
|
|
标准通用状态码列表：
|
|
|
|
code 含义 前端处理建议
|
|
|
|
0 成功 -
|
|
|
|
40001 请求参数缺失或格式错误 展示 message（含具体字段信息）
|
|
|
|
40002 无效的请求体 展示 message
|
|
|
|
40101 API 签名验证失败 展示 message
|
|
|
|
40102 请求时间戳已过期 展示 message
|
|
|
|
40103 未登录或登录已过期 清除本地 token，跳转登录页
|
|
|
|
40301 操作权限不足 提示无权限，不跳登录
|
|
|
|
40401 请求的资源不存在 展示 message
|
|
|
|
40501 错误的请求方式 检查 GET/POST 是否用反
|
|
|
|
50001 系统内部错误 提示「系统繁忙，请稍后重试」，报
|
|
|
|
障时附 X-Trace-Id（见 2.9）
|
|
|
|
50002 外部服务调用失败 同上
|
|
|
|
60001 通用业务错误 直接展示 message
|
|
|
|
61001 不支持的登录方式 展示 message
|
|
|
|
61002 三方授权失败（钉钉 authCode 无效/ 提示重新扫码
|
|
|
|
过期）
|
|
|
|
61003 账号已被禁用 展示 message
|
|
|
|
-1 未知错误 展示 message
|
|
|
|
|
|
2.7 信封例外：文件导出
|
|
Excel 导出类接口不返回 JSON 信封，直接返回二进制流：
|
|
|
|
• 成功：响应头含 Content-Disposition: attachment;filename=xxx.xlsx（文件名已 URL 编码），响应体为文
|
|
|
|
件流，前端按 blob 接收后触发下载。
|
|
|
|
• 失败：响应体是 JSON 错误信封（统一结构）。
|
|
|
|
因此前端处理导出接口时先检测响应的 Content-Type：
|
|
|
|
• application/json → 按信封解析并提示 message；
|
|
|
|
• 其他 → 按 blob 下载。
|
|
|
|
|
|
2.8 数据字典
|
|
• 字典项分 label / value 两部分：label 是前端展示值（如「官网注册」），value 是存储值（如 "1"）。
|
|
提交和回显一律用 value，label 仅用于展示。
|
|
|
|
• 下拉框数据源是否走字典接口，以原型标注为准：
|
|
|
|
- 原型标注了字典编码（dictCode）的 → 调 GET /api/auth/dict/items?dictCode=xxx 获取 label/value 列
|
|
|
|
表；
|
|
|
|
- 是/否、启用/禁用等简单枚举 → 前端直接硬编码，不走字典。
|
|
|
|
|
|
2.9 链路追踪
|
|
• 每个响应都带响应头 X-Trace-Id，标识本次请求的全链路日志。
|
|
|
|
• 前端报障时请附上出错请求的 X-Trace-Id，后端可据此直接定位日志。
|
|
|
|
• 前端也可主动在请求头传 X-Trace-Id（无则后端自动生成）。
|
|
|