5.9 KiB

Raw Permalink Blame History

开放API-学生列表授权需求设计方案

作者：pangu
创建时间：2026-02-04
评审状态：待评审

一、背景与目标

1.1 背景

盘古用户认证中心已具备「应用管理」能力：可创建第三方应用、分配应用编码（appCode）与密钥（appSecret），并在管理后台为应用勾选「接口授权」。当前缺少对外暴露的开放 API 及基于应用身份的签名鉴权与接口授权校验，外部系统无法在未登录用户的前提下，以应用身份安全调用已授权接口。

1.2 目标

需求侧：支持外部系统以「应用身份」调用指定已授权接口（首期以学生列表查询为真实场景），不依赖用户登录 Token。
安全侧：请求必须携带应用编码、时间戳、签名，服务端校验签名并校验该应用是否已授权访问该接口，未授权或签名错误一律拒绝。
可评审：提供完整需求说明与技术方案，便于评审与后续扩展更多开放接口。

二、范围与边界

2.1 本期范围

序号	内容	说明
1	开放 API 机制	统一路径前缀 `/open/api/**`，请求头鉴权（X-App-Id、X-Timestamp、X-Sign）
2	学生列表查询	提供 GET `/open/api/student/list`，与现有业务逻辑一致，仅鉴权方式不同
3	应用管理侧	新增/编辑应用时保存「接口授权」到 pg_app_api；查询应用详情时回显已选接口
4	接口字典	pg_api_dict 中至少包含「学生列表」开放接口配置，供授权勾选与校验使用

2.2 边界（本期不做）

仅实现「学生列表」一个开放接口作为示例；其他业务接口（如学校、会员等）后续按同机制扩展。
不涉及 OAuth2/第三方登录；仅做「应用级」签名鉴权与接口授权。

三、用户角色与使用场景

3.1 角色

角色	说明
运营/管理员	在应用管理中创建应用、为应用勾选「学生列表」等接口授权
外部系统	使用 appCode + appSecret 对请求签名，调用 GET `/open/api/student/list` 获取学生列表（分页、筛选与现有一致）

3.2 典型场景

配置授权
管理员在「应用管理」中新增应用「XX 学情系统」，保存后获得 appCode（如 YY000001）、appSecret（32 位）。在编辑该应用时勾选「学生列表」接口授权并保存。
外部调用
XX 学情系统在服务端使用 appCode、appSecret 生成签名，请求 GET /open/api/student/list?pageNum=1&pageSize=10，并携带请求头 X-App-Id、X-Timestamp、X-Sign。平台校验通过且该应用已授权「学生列表」后返回分页数据。
未授权/签名错误
若未勾选「学生列表」或签名错误，返回 401/403 及明确错误信息，不返回业务数据。

四、功能需求

4.1 开放 API 鉴权与授权

FR-1 请求必须携带请求头：X-App-Id（应用编码）、X-Timestamp（毫秒时间戳）、X-Sign（签名）。
FR-2 时间戳与服务器时间差超过 5 分钟视为过期，拒绝请求。
FR-3 根据 X-App-Id 查询应用信息；应用不存在或已停用则拒绝。
FR-4 签名算法：请求参数（query+body 按参数名 ASCII 排序）拼接为 key1=value1&key2=value2&...&appSecret=应用密钥，再对该字符串做 MD5，结果转大写，与 X-Sign 比对；不一致则拒绝。
FR-5 请求 URI 对应的「开放接口」必须在当前应用的授权列表中（以 pg_api_dict.api_path 与 pg_app_api 关联为准），否则拒绝访问。

4.2 学生列表开放接口

FR-6 提供 GET /open/api/student/list，支持与现有学生列表一致的查询参数（如 studentName、studentNo、schoolId 等）及分页参数（pageNum、pageSize）。
FR-7 响应格式与现有管理端学生列表一致（TableDataInfo：rows、total 等），便于对接方使用。

4.3 应用管理侧

FR-8 新增/编辑应用时，请求体可携带接口授权标识（如 apiCodes：接口编码列表）；保存时同步更新 pg_app_api（先删该应用原有授权，再按 apiCodes 插入）。
FR-9 查询应用详情（含列表展示）时，返回该应用已授权的接口信息（如 apiCodes 或等效），供前端勾选回显。

4.4 接口字典

FR-10 pg_api_dict 中至少有一条「学生列表」开放接口记录：api_path 为 /open/api/student/list，api_method 为 GET，供应用管理勾选与鉴权校验使用。

五、非功能需求

NFR-1 鉴权失败时返回 HTTP 状态码与 JSON 错误信息（如 401 签名错误、403 无权限、400 参数缺失/过期）。
NFR-2 授权关系变更后，建议在较短时间内生效（可为实时或短 TTL 缓存，技术方案中约定）。
NFR-3 文档与示例：提供开放 API 调用说明及学生列表调用示例（含签名算法与示例请求），便于对接方自测与联调。

六、验收标准

在应用管理中为某应用勾选「学生列表」并保存后，该应用使用正确签名调用 GET /open/api/student/list 可返回学生列表数据。
未勾选「学生列表」的应用调用同一接口，返回 403 无权限。
错误签名或过期时间戳，返回 401 或 400，且不返回业务数据。
应用管理新增/编辑时接口授权勾选可保存并回显；列表/详情中可看到已授权接口信息。

七、附录：术语

术语	说明
appCode	应用编码，如 YY000001，唯一标识一个应用
appSecret	应用密钥，32 位，用于参与签名计算，需保密
接口授权	应用与 pg_api_dict 中某条 API 的关联关系，存储在 pg_app_api
开放 API	以 `/open/api/**` 为前缀、使用应用签名鉴权的接口，无需用户登录