pangu-user-platform/scripts/test/README.md

开放接口 PHP 客户端使用指南

📋 文件说明

文件	说明	用途
OpenApiClient.php	PHP 客户端类	封装签名计算、请求发送等逻辑
quickstart.php	快速开始示例	最简单的调用示例
openapi-student-list-test.php	完整测试示例	演示多种查询场景
README.md	使用文档	本文件

---

🚀 快速开始

1. 准备工作

环境要求：

• PHP 7.4 或以上
• 启用 curl 扩展

检查 PHP 版本：

php -v

检查 curl 扩展：

php -m | grep curl

2. 获取应用凭证

在盘古管理后台获取您的应用凭证：

1. 登录管理后台：http://localhost:80
2. 进入【应用管理】菜单
3. 新增或查看应用，获取：
   • 应用编码（AppCode）：如 YY000001
   • 应用密钥（AppSecret）：如 a1b2c3d4e5f6789012345678901234ab

3. 运行快速示例

cd /Users/felix/pgWorkSpace/pangu-user-platform/scripts/test

# 方式一：使用命令行参数
php quickstart.php

# 方式二：修改 quickstart.php 中的配置后运行
php quickstart.php

---

📖 详细使用

方式一：使用完整测试脚本

# 基本用法
php openapi-student-list-test.php <appCode> <appSecret> [baseUrl]

# 示例：连接本地服务
php openapi-student-list-test.php YY000001 a1b2c3d4e5f6789012345678901234ab

# 示例：连接远程服务
php openapi-student-list-test.php YY000001 a1b2c3d4e5f6789012345678901234ab http://your-domain.com:8080

输出示例：

========================================
【开放接口调用】
========================================
【请求方法】GET
【请求 URL】http://localhost:8080/open/api/student/list?pageNum=1&pageSize=10
【请求头】
  X-App-Id: YY000001
  X-Timestamp: 1738656000000
  X-Sign: A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6
  Content-Type: application/json
【请求参数】
{
    "pageNum": 1,
    "pageSize": 10
}
【签名计算】
  签名字符串: pageNum=1&pageSize=10&appSecret=a1b2c3d4e5f6789012345678901234ab
  MD5 结果: A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6
========================================

【响应状态码】200
【响应内容】
{"code":200,"msg":"操作成功","rows":[...],"total":100}

✅ 调用成功！

方式二：在您的项目中使用

1. 引入客户端类：

require_once '/path/to/OpenApiClient.php';

2. 创建客户端实例：

$client = new OpenApiClient(
    'http://localhost:8080',  // API 基础地址
    'YY000001',               // 应用编码
    'a1b2c3d4e5f6789012345678901234ab',  // 应用密钥
    false                     // 调试模式（true=开启, false=关闭）
);

3. 调用接口：

try {
    // GET 请求
    $result = $client->get('/open/api/student/list', [
        'pageNum' => 1,
        'pageSize' => 10,
        'studentName' => '张',
        'schoolId' => 1
    ]);

    // 处理响应
    if ($result['code'] === 200) {
        echo "总记录数: {$result['total']}\n";
        foreach ($result['rows'] as $student) {
            echo "{$student['studentName']} - {$student['studentCode']}\n";
        }
    } else {
        echo "调用失败: {$result['msg']}\n";
    }
} catch (Exception $e) {
    echo "异常: {$e->getMessage()}\n";
}

---

🔐 签名算法说明

签名计算步骤

1. 收集请求参数（不含签名本身）

   pageNum=1, pageSize=10, studentName=张
   

2. 按参数名 ASCII 码升序排序

   pageNum=1, pageSize=10, studentName=张
   

3. 拼接键值对，末尾追加 appSecret

   pageNum=1&pageSize=10&studentName=张&appSecret=a1b2c3d4e5f6789012345678901234ab
   

4. MD5 加密并转大写

   $sign = strtoupper(md5($signStr));
   

PHP 实现示例

function calculateSign(array $params, string $appSecret): string
{
    // 1. 按 key 升序排序
    ksort($params);

    // 2. 拼接参数
    $signStr = '';
    foreach ($params as $key => $value) {
        if ($value === '' || $value === null) continue;
        if ($signStr !== '') $signStr .= '&';
        $signStr .= $key . '=' . $value;
    }

    // 3. 追加密钥
    if ($signStr !== '') $signStr .= '&';
    $signStr .= 'appSecret=' . $appSecret;

    // 4. MD5 加密并转大写
    return strtoupper(md5($signStr));
}

---

🔍 常见问题

1. 签名验证失败

错误信息：签名验证失败

可能原因：

• appSecret 不正确
• 参数排序错误（必须按 ASCII 码升序）
• MD5 结果未转大写
• 签名字符串拼接错误

解决方法：

# 开启调试模式，查看签名计算过程
$client = new OpenApiClient($baseUrl, $appCode, $appSecret, true);

2. 请求已过期

错误信息：请求已过期

可能原因：

• 服务器时间与客户端时间相差超过 5 分钟

解决方法：

# 同步服务器时间
sudo ntpdate -u time.apple.com

3. 无权访问该接口

错误信息：无权访问该接口

可能原因：

• 应用未授权访问该接口

解决方法：

1. 登录管理后台
2. 进入【应用管理】
3. 编辑应用，勾选需要的接口
4. 保存配置

4. 应用已停用

错误信息：应用已停用

可能原因：

• 应用状态为停用

解决方法：

1. 登录管理后台
2. 进入【应用管理】
3. 编辑应用，将状态改为正常
4. 保存配置

---

📚 接口参数说明

学生列表查询

接口路径：/open/api/student/list

请求方法：GET

请求参数：

参数名	类型	必填	说明	示例
pageNum	int	是	页码（从 1 开始）	1
pageSize	int	是	每页条数	10
studentName	string	否	学生姓名（模糊查询）	张
schoolId	int	否	学校 ID	1
gradeId	int	否	年级 ID	1
classId	int	否	班级 ID	1

响应数据：

{
  "code": 200,
  "msg": "操作成功",
  "rows": [
    {
      "studentId": 1,
      "studentCode": "S2024001",
      "studentName": "张*",
      "gender": "1",
      "schoolId": 1,
      "schoolName": "第一小学",
      "gradeId": 1,
      "gradeName": "三年级",
      "classId": 1,
      "className": "1班"
    }
  ],
  "total": 100
}

字段说明：

字段	类型	说明
studentId	int	学生 ID
studentCode	string	学号
studentName	string	学生姓名（已脱敏）
gender	string	性别（0未知 1男 2女）
schoolId	int	学校 ID
schoolName	string	学校名称
gradeId	int	年级 ID
gradeName	string	年级名称
classId	int	班级 ID
className	string	班级名称

---

🔗 相关链接

• 技术文档：/docs/应用管理-需求与技术设计方案.md
• 实现说明：/docs/开放接口实现说明.md
• Swagger 文档：http://localhost:8080/doc.html

---

📝 更新日志

v1.0 (2026-02-04)

• 初始版本
• 支持学生列表查询接口
• 提供完整的签名计算实现
• 提供调试模式

---

🤝 技术支持

如有问题，请联系技术支持或查看项目文档。

pangu