336 lines
7.2 KiB
Markdown
336 lines
7.2 KiB
Markdown
# 开放接口 PHP 客户端使用指南
|
||
|
||
## 📋 文件说明
|
||
|
||
| 文件 | 说明 | 用途 |
|
||
|------|------|------|
|
||
| `OpenApiClient.php` | PHP 客户端类 | 封装签名计算、请求发送等逻辑 |
|
||
| `quickstart.php` | 快速开始示例 | 最简单的调用示例 |
|
||
| `openapi-student-list-test.php` | 完整测试示例 | 演示多种查询场景 |
|
||
| `README.md` | 使用文档 | 本文件 |
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 准备工作
|
||
|
||
**环境要求**：
|
||
- PHP 7.4 或以上
|
||
- 启用 curl 扩展
|
||
|
||
**检查 PHP 版本**：
|
||
```bash
|
||
php -v
|
||
```
|
||
|
||
**检查 curl 扩展**：
|
||
```bash
|
||
php -m | grep curl
|
||
```
|
||
|
||
### 2. 获取应用凭证
|
||
|
||
在盘古管理后台获取您的应用凭证：
|
||
1. 登录管理后台：http://localhost:80
|
||
2. 进入【应用管理】菜单
|
||
3. 新增或查看应用，获取：
|
||
- **应用编码**（AppCode）：如 `YY000001`
|
||
- **应用密钥**（AppSecret）：如 `a1b2c3d4e5f6789012345678901234ab`
|
||
|
||
### 3. 运行快速示例
|
||
|
||
```bash
|
||
cd /Users/felix/pgWorkSpace/pangu-user-platform/scripts/test
|
||
|
||
# 方式一：使用命令行参数
|
||
php quickstart.php
|
||
|
||
# 方式二：修改 quickstart.php 中的配置后运行
|
||
php quickstart.php
|
||
```
|
||
|
||
---
|
||
|
||
## 📖 详细使用
|
||
|
||
### 方式一：使用完整测试脚本
|
||
|
||
```bash
|
||
# 基本用法
|
||
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. 引入客户端类**：
|
||
```php
|
||
require_once '/path/to/OpenApiClient.php';
|
||
```
|
||
|
||
**2. 创建客户端实例**：
|
||
```php
|
||
$client = new OpenApiClient(
|
||
'http://localhost:8080', // API 基础地址
|
||
'YY000001', // 应用编码
|
||
'a1b2c3d4e5f6789012345678901234ab', // 应用密钥
|
||
false // 调试模式（true=开启, false=关闭）
|
||
);
|
||
```
|
||
|
||
**3. 调用接口**：
|
||
```php
|
||
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 加密并转大写**
|
||
```php
|
||
$sign = strtoupper(md5($signStr));
|
||
```
|
||
|
||
### PHP 实现示例
|
||
|
||
```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 结果未转大写
|
||
- 签名字符串拼接错误
|
||
|
||
**解决方法**：
|
||
```bash
|
||
# 开启调试模式，查看签名计算过程
|
||
$client = new OpenApiClient($baseUrl, $appCode, $appSecret, true);
|
||
```
|
||
|
||
### 2. 请求已过期
|
||
|
||
**错误信息**：`请求已过期`
|
||
|
||
**可能原因**：
|
||
- 服务器时间与客户端时间相差超过 5 分钟
|
||
|
||
**解决方法**：
|
||
```bash
|
||
# 同步服务器时间
|
||
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 |
|
||
|
||
**响应数据**：
|
||
|
||
```json
|
||
{
|
||
"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**
|