115 lines
3.4 KiB
Markdown
115 lines
3.4 KiB
Markdown
# 开放API-学生列表 调用测试说明
|
||
|
||
> 作者：pangu
|
||
> 创建时间：2026-02-04
|
||
|
||
---
|
||
|
||
## 一、前置条件
|
||
|
||
1. **执行接口字典数据**（若尚未执行）：
|
||
```bash
|
||
# 在数据库中执行
|
||
mysql -u用户 -p 库名 < backend/pangu-modules/pangu-business/sql/open_api_dict_data.sql
|
||
```
|
||
或在客户端执行 `open_api_dict_data.sql` 中的 INSERT 语句。
|
||
|
||
2. **应用管理中**：
|
||
- 新增或编辑一个应用，在「接口授权」中勾选 **学生列表**，保存。
|
||
- 记录该应用的 **应用编码（appCode）** 和 **应用密钥（appSecret）**（重置密钥后可查看）。
|
||
|
||
---
|
||
|
||
## 二、签名算法
|
||
|
||
1. 将请求参数（仅 Query 参数，按参数名 **ASCII 升序**）拼接：
|
||
`key1=value1&key2=value2&...`
|
||
2. 末尾追加：`&appSecret=你的应用密钥`
|
||
3. 对整串做 **MD5**，结果转为 **大写**，即 `X-Sign`。
|
||
|
||
**示例（GET）**：
|
||
- 请求：`/open/api/student/list?pageNum=1&pageSize=10`
|
||
- 参数排序后：`pageNum=1&pageSize=10`
|
||
- 假设 appSecret=`abc123`，则参数字符串：`pageNum=1&pageSize=10&appSecret=abc123`
|
||
- sign = MD5(`pageNum=1&pageSize=10&appSecret=abc123`).toUpperCase()
|
||
|
||
---
|
||
|
||
## 三、请求头
|
||
|
||
| 请求头 | 说明 |
|
||
|-------------|-------------------------|
|
||
| X-App-Id | 应用编码（appCode） |
|
||
| X-Timestamp | 当前时间毫秒时间戳 |
|
||
| X-Sign | 按上述算法计算的签名 |
|
||
|
||
---
|
||
|
||
## 四、curl 示例
|
||
|
||
假设：
|
||
- 应用编码：`YY000001`
|
||
- 应用密钥：`a1b2c3d4e5f6789012345678901234ab`
|
||
- 基础地址：`http://localhost:8080`
|
||
|
||
**1. 先计算签名（示例用当前时间戳）**
|
||
|
||
参数：`pageNum=1&pageSize=10&appSecret=a1b2c3d4e5f6789012345678901234ab`
|
||
可用在线 MD5 或命令行（见下方脚本）得到大写 MD5 作为 X-Sign。
|
||
|
||
**2. 调用**
|
||
|
||
```bash
|
||
# 将 TIMESTAMP 和 SIGN 替换为实际值
|
||
TIMESTAMP=$(date +%s)000
|
||
# SIGN 需根据 当前参数+appSecret 用 MD5 计算，此处为占位
|
||
SIGN="这里填计算出的32位大写MD5"
|
||
|
||
curl -s -X GET "http://localhost:8080/open/api/student/list?pageNum=1&pageSize=10" \
|
||
-H "X-App-Id: YY000001" \
|
||
-H "X-Timestamp: $TIMESTAMP" \
|
||
-H "X-Sign: $SIGN"
|
||
```
|
||
|
||
---
|
||
|
||
## 五、测试脚本（含签名计算）
|
||
|
||
在项目根目录执行：
|
||
|
||
```bash
|
||
./scripts/openapi-student-list-test.sh <appCode> <appSecret> [baseUrl]
|
||
```
|
||
|
||
示例：
|
||
|
||
```bash
|
||
./scripts/openapi-student-list-test.sh YY000001 a1b2c3d4e5f6789012345678901234ab
|
||
# 指定环境
|
||
./scripts/openapi-student-list-test.sh YY000001 your_secret http://192.168.1.100:8080
|
||
```
|
||
|
||
---
|
||
|
||
## 六、预期结果
|
||
|
||
| 场景 | HTTP 状态 | 说明 |
|
||
|----------------|-----------|------------------------------|
|
||
| 签名正确且已授权 | 200 | 返回 rows、total 等分页数据 |
|
||
| 未勾选学生列表 | 403 | 无权访问该接口 |
|
||
| 签名错误 | 500 | 签名验证失败（业务异常） |
|
||
| 时间戳过期 | 500 | 请求已过期 |
|
||
| 缺少请求头 | 500 | 缺少认证参数 |
|
||
|
||
---
|
||
|
||
## 七、可选：学生列表查询参数
|
||
|
||
与后台 `/business/student/list` 一致，例如：
|
||
|
||
- `pageNum`、`pageSize`：分页
|
||
- `studentName`：学生姓名（模糊）
|
||
- `studentNo`：学号（模糊）
|
||
- `schoolId`：学校 ID
|
||
等，按需传递；**参与签名的参数需包含所有本次请求的 Query 参数**（按参数名排序后拼接再加 appSecret 做 MD5）。
|