189 lines
4.9 KiB
Plaintext
189 lines
4.9 KiB
Plaintext
|
===============================================
|
|||
|
|
开放接口 PHP 客户端 - 快速使用指南
|
|||
|
|
===============================================
|
|||
|
|
|
|||
|
|
📁 文件清单
|
|||
|
|
--------------
|
|||
|
|
✅ OpenApiClient.php - PHP 客户端类（核心）
|
|||
|
|
✅ quickstart.php - 快速开始示例
|
|||
|
|
✅ openapi-student-list-test.php - 完整测试示例
|
|||
|
|
✅ README.md - 详细使用文档
|
|||
|
|
✅ 使用说明.txt - 本文件
|
|||
|
|
|
|||
|
|
===============================================
|
|||
|
|
🚀 快速开始（3 步）
|
|||
|
|
===============================================
|
|||
|
|
|
|||
|
|
步骤 1：获取应用凭证
|
|||
|
|
-------------------
|
|||
|
|
1. 打开浏览器访问：http://localhost:80
|
|||
|
|
2. 登录管理后台
|
|||
|
|
3. 进入【应用管理】菜单
|
|||
|
|
4. 新增或查看应用，获取：
|
|||
|
|
- 应用编码（AppCode）：如 YY000001
|
|||
|
|
- 应用密钥（AppSecret）：如 2221c3d6f00c4baabfabfd4f679693f1
|
|||
|
|
|
|||
|
|
步骤 2：修改配置
|
|||
|
|
-------------------
|
|||
|
|
编辑 quickstart.php 文件，修改以下配置：
|
|||
|
|
|
|||
|
|
$config = [
|
|||
|
|
'baseUrl' => 'http://localhost:8080',
|
|||
|
|
'appCode' => 'YY000001', ← 替换为您的应用编码
|
|||
|
|
'appSecret' => 'xxxxx...', ← 替换为您的应用密钥
|
|||
|
|
];
|
|||
|
|
|
|||
|
|
步骤 3：运行测试
|
|||
|
|
-------------------
|
|||
|
|
在终端执行：
|
|||
|
|
|
|||
|
|
cd /Users/felix/pgWorkSpace/pangu-user-platform/scripts/test
|
|||
|
|
php quickstart.php
|
|||
|
|
|
|||
|
|
或使用命令行参数：
|
|||
|
|
|
|||
|
|
php openapi-student-list-test.php YY000001 your-app-secret
|
|||
|
|
|
|||
|
|
===============================================
|
|||
|
|
📖 使用示例
|
|||
|
|
===============================================
|
|||
|
|
|
|||
|
|
示例 1：基础调用
|
|||
|
|
-------------------
|
|||
|
|
<?php
|
|||
|
|
require_once 'OpenApiClient.php';
|
|||
|
|
|
|||
|
|
$client = new OpenApiClient(
|
|||
|
|
'http://localhost:8080',
|
|||
|
|
'YY000001',
|
|||
|
|
'your-app-secret',
|
|||
|
|
false // 调试模式
|
|||
|
|
);
|
|||
|
|
|
|||
|
|
$result = $client->get('/open/api/student/list', [
|
|||
|
|
'pageNum' => 1,
|
|||
|
|
'pageSize' => 10
|
|||
|
|
]);
|
|||
|
|
|
|||
|
|
if ($result['code'] === 200) {
|
|||
|
|
echo "总记录数: {$result['total']}\n";
|
|||
|
|
}
|
|||
|
|
?>
|
|||
|
|
|
|||
|
|
示例 2：带条件查询
|
|||
|
|
-------------------
|
|||
|
|
$result = $client->get('/open/api/student/list', [
|
|||
|
|
'pageNum' => 1,
|
|||
|
|
'pageSize' => 10,
|
|||
|
|
'studentName' => '张', // 姓名模糊查询
|
|||
|
|
'schoolId' => 1, // 按学校筛选
|
|||
|
|
'gradeId' => 2, // 按年级筛选
|
|||
|
|
'classId' => 3 // 按班级筛选
|
|||
|
|
]);
|
|||
|
|
|
|||
|
|
示例 3：开启调试模式
|
|||
|
|
-------------------
|
|||
|
|
$client = new OpenApiClient(
|
|||
|
|
'http://localhost:8080',
|
|||
|
|
'YY000001',
|
|||
|
|
'your-app-secret',
|
|||
|
|
true // 开启调试，查看签名计算过程
|
|||
|
|
);
|
|||
|
|
|
|||
|
|
===============================================
|
|||
|
|
🔐 签名算法说明
|
|||
|
|
===============================================
|
|||
|
|
|
|||
|
|
PHP 实现：
|
|||
|
|
-----------
|
|||
|
|
function calculateSign($params, $appSecret) {
|
|||
|
|
ksort($params); // 1. 排序
|
|||
|
|
|
|||
|
|
$signStr = '';
|
|||
|
|
foreach ($params as $key => $value) {
|
|||
|
|
if ($signStr) $signStr .= '&';
|
|||
|
|
$signStr .= $key . '=' . $value;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
$signStr .= '&appSecret=' . $appSecret; // 2. 追加密钥
|
|||
|
|
|
|||
|
|
return strtoupper(md5($signStr)); // 3. MD5 + 大写
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
示例：
|
|||
|
|
-----------
|
|||
|
|
参数：pageNum=1, pageSize=10
|
|||
|
|
密钥：a1b2c3d4e5f6789012345678901234ab
|
|||
|
|
|
|||
|
|
签名字符串：
|
|||
|
|
pageNum=1&pageSize=10&appSecret=a1b2c3d4e5f6789012345678901234ab
|
|||
|
|
|
|||
|
|
MD5 结果（大写）：
|
|||
|
|
A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6
|
|||
|
|
|
|||
|
|
===============================================
|
|||
|
|
❌ 常见错误处理
|
|||
|
|
===============================================
|
|||
|
|
|
|||
|
|
1. 签名验证失败
|
|||
|
|
原因：appSecret 错误或签名计算错误
|
|||
|
|
解决：开启调试模式检查签名计算过程
|
|||
|
|
|
|||
|
|
2. 请求已过期
|
|||
|
|
原因：时间戳超过 5 分钟
|
|||
|
|
解决：同步服务器时间
|
|||
|
|
|
|||
|
|
3. 无权访问该接口
|
|||
|
|
原因：应用未授权该接口
|
|||
|
|
解决：在管理后台配置接口授权
|
|||
|
|
|
|||
|
|
4. 应用已停用
|
|||
|
|
原因：应用状态为停用
|
|||
|
|
解决：在管理后台启用应用
|
|||
|
|
|
|||
|
|
===============================================
|
|||
|
|
📚 接口文档
|
|||
|
|
===============================================
|
|||
|
|
|
|||
|
|
接口路径：/open/api/student/list
|
|||
|
|
请求方法：GET
|
|||
|
|
|
|||
|
|
请求参数：
|
|||
|
|
- pageNum [必填] 页码
|
|||
|
|
- pageSize [必填] 每页条数
|
|||
|
|
- studentName [可选] 学生姓名（模糊）
|
|||
|
|
- schoolId [可选] 学校ID
|
|||
|
|
- gradeId [可选] 年级ID
|
|||
|
|
- classId [可选] 班级ID
|
|||
|
|
|
|||
|
|
响应字段：
|
|||
|
|
- studentId 学生ID
|
|||
|
|
- studentCode 学号
|
|||
|
|
- studentName 学生姓名（已脱敏）
|
|||
|
|
- gender 性别（0未知 1男 2女）
|
|||
|
|
- schoolName 学校名称
|
|||
|
|
- gradeName 年级名称
|
|||
|
|
- className 班级名称
|
|||
|
|
|
|||
|
|
===============================================
|
|||
|
|
🔗 相关资源
|
|||
|
|
===============================================
|
|||
|
|
|
|||
|
|
- 详细文档：README.md
|
|||
|
|
- 技术方案：/docs/应用管理-需求与技术设计方案.md
|
|||
|
|
- 实现说明：/docs/开放接口实现说明.md
|
|||
|
|
- Swagger：http://localhost:8080/doc.html
|
|||
|
|
|
|||
|
|
===============================================
|
|||
|
|
📞 技术支持
|
|||
|
|
===============================================
|
|||
|
|
|
|||
|
|
如有问题，请查看：
|
|||
|
|
1. README.md 详细文档
|
|||
|
|
2. /tmp/pangu-admin.log 后端日志
|
|||
|
|
3. 开启调试模式查看请求详情
|
|||
|
|
|
|||
|
|
pangu
|
|||
|
|
2026-02-04
|
|||
|
|
===============================================
|