pangu-user-platform/docs/05-模块技术方案/开放API-学生列表授权-调用测试说明.md

开放API-学生列表 调用测试说明

作者：pangu
创建时间：2026-02-04

---

一、前置条件

1. 执行接口字典数据（若尚未执行）：

   # 在数据库中执行
   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. 调用

# 将 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"

---

五、测试脚本（含签名计算）

在项目根目录执行：

./scripts/openapi-student-list-test.sh <appCode> <appSecret> [baseUrl]

示例：

./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）。