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
|
||
===============================================
|