366 lines
12 KiB
HTML
366 lines
12 KiB
HTML
|
<!DOCTYPE html>
|
|||
|
|
<html lang="zh-CN">
|
|||
|
|
<head>
|
|||
|
|
<meta charset="UTF-8">
|
|||
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|||
|
|
<title>开放接口 PHP 客户端 - 使用指南</title>
|
|||
|
|
<style>
|
|||
|
|
* {
|
|||
|
|
margin: 0;
|
|||
|
|
padding: 0;
|
|||
|
|
box-sizing: border-box;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
body {
|
|||
|
|
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
|
|||
|
|
line-height: 1.6;
|
|||
|
|
color: #333;
|
|||
|
|
background: #f5f7fa;
|
|||
|
|
padding: 20px;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
.container {
|
|||
|
|
max-width: 1000px;
|
|||
|
|
margin: 0 auto;
|
|||
|
|
background: white;
|
|||
|
|
border-radius: 8px;
|
|||
|
|
box-shadow: 0 2px 12px rgba(0,0,0,0.1);
|
|||
|
|
padding: 40px;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
h1 {
|
|||
|
|
color: #409eff;
|
|||
|
|
font-size: 32px;
|
|||
|
|
margin-bottom: 20px;
|
|||
|
|
border-bottom: 3px solid #409eff;
|
|||
|
|
padding-bottom: 10px;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
h2 {
|
|||
|
|
color: #303133;
|
|||
|
|
font-size: 24px;
|
|||
|
|
margin-top: 30px;
|
|||
|
|
margin-bottom: 15px;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
.file-list {
|
|||
|
|
display: grid;
|
|||
|
|
grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
|
|||
|
|
gap: 15px;
|
|||
|
|
margin: 20px 0;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
.file-card {
|
|||
|
|
border: 1px solid #dcdfe6;
|
|||
|
|
border-radius: 6px;
|
|||
|
|
padding: 20px;
|
|||
|
|
transition: all 0.3s;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
.file-card:hover {
|
|||
|
|
border-color: #409eff;
|
|||
|
|
box-shadow: 0 2px 12px rgba(64, 158, 255, 0.2);
|
|||
|
|
transform: translateY(-2px);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
.file-icon {
|
|||
|
|
font-size: 40px;
|
|||
|
|
margin-bottom: 10px;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
.file-name {
|
|||
|
|
font-weight: 600;
|
|||
|
|
color: #409eff;
|
|||
|
|
margin-bottom: 8px;
|
|||
|
|
font-size: 16px;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
.file-desc {
|
|||
|
|
color: #606266;
|
|||
|
|
font-size: 14px;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
.quick-start {
|
|||
|
|
background: #f0f9ff;
|
|||
|
|
border-left: 4px solid #409eff;
|
|||
|
|
padding: 20px;
|
|||
|
|
margin: 20px 0;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
.quick-start h3 {
|
|||
|
|
color: #409eff;
|
|||
|
|
margin-bottom: 10px;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
.step {
|
|||
|
|
margin: 15px 0;
|
|||
|
|
padding-left: 30px;
|
|||
|
|
position: relative;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
.step::before {
|
|||
|
|
content: attr(data-step);
|
|||
|
|
position: absolute;
|
|||
|
|
left: 0;
|
|||
|
|
top: 0;
|
|||
|
|
background: #409eff;
|
|||
|
|
color: white;
|
|||
|
|
width: 24px;
|
|||
|
|
height: 24px;
|
|||
|
|
border-radius: 50%;
|
|||
|
|
text-align: center;
|
|||
|
|
line-height: 24px;
|
|||
|
|
font-size: 12px;
|
|||
|
|
font-weight: bold;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
pre {
|
|||
|
|
background: #f5f7fa;
|
|||
|
|
padding: 15px;
|
|||
|
|
border-radius: 4px;
|
|||
|
|
overflow-x: auto;
|
|||
|
|
margin: 10px 0;
|
|||
|
|
border: 1px solid #dcdfe6;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
code {
|
|||
|
|
font-family: "Monaco", "Courier New", monospace;
|
|||
|
|
font-size: 14px;
|
|||
|
|
color: #e96900;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
.command {
|
|||
|
|
background: #282c34;
|
|||
|
|
color: #abb2bf;
|
|||
|
|
padding: 15px;
|
|||
|
|
border-radius: 4px;
|
|||
|
|
margin: 10px 0;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
.command code {
|
|||
|
|
color: #61afef;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
.info-box {
|
|||
|
|
background: #fff9f0;
|
|||
|
|
border-left: 4px solid #e6a23c;
|
|||
|
|
padding: 15px;
|
|||
|
|
margin: 15px 0;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
.success-box {
|
|||
|
|
background: #f0f9ff;
|
|||
|
|
border-left: 4px solid #67c23a;
|
|||
|
|
padding: 15px;
|
|||
|
|
margin: 15px 0;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
.footer {
|
|||
|
|
margin-top: 40px;
|
|||
|
|
padding-top: 20px;
|
|||
|
|
border-top: 1px solid #dcdfe6;
|
|||
|
|
text-align: center;
|
|||
|
|
color: #909399;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
a {
|
|||
|
|
color: #409eff;
|
|||
|
|
text-decoration: none;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
a:hover {
|
|||
|
|
text-decoration: underline;
|
|||
|
|
}
|
|||
|
|
</style>
|
|||
|
|
</head>
|
|||
|
|
<body>
|
|||
|
|
<div class="container">
|
|||
|
|
<h1>🚀 开放接口 PHP 客户端</h1>
|
|||
|
|
<p style="color: #606266; margin-bottom: 30px;">
|
|||
|
|
完整的 PHP 客户端实现，包含签名计算、请求封装、错误处理等功能。
|
|||
|
|
</p>
|
|||
|
|
|
|||
|
|
<h2>📁 文件清单</h2>
|
|||
|
|
<div class="file-list">
|
|||
|
|
<div class="file-card">
|
|||
|
|
<div class="file-icon">📦</div>
|
|||
|
|
<div class="file-name">OpenApiClient.php</div>
|
|||
|
|
<div class="file-desc">PHP 客户端类，封装所有调用逻辑</div>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<div class="file-card">
|
|||
|
|
<div class="file-icon">⚡</div>
|
|||
|
|
<div class="file-name">quickstart.php</div>
|
|||
|
|
<div class="file-desc">快速开始示例，最简单的调用方式</div>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<div class="file-card">
|
|||
|
|
<div class="file-icon">🧪</div>
|
|||
|
|
<div class="file-name">openapi-student-list-test.php</div>
|
|||
|
|
<div class="file-desc">完整测试示例，演示多种查询场景</div>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<div class="file-card">
|
|||
|
|
<div class="file-icon">📖</div>
|
|||
|
|
<div class="file-name">README.md</div>
|
|||
|
|
<div class="file-desc">详细使用文档，包含所有接口说明</div>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<div class="file-card">
|
|||
|
|
<div class="file-icon">📝</div>
|
|||
|
|
<div class="file-name">使用说明.txt</div>
|
|||
|
|
<div class="file-desc">纯文本快速参考指南</div>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<div class="file-card">
|
|||
|
|
<div class="file-icon">🌐</div>
|
|||
|
|
<div class="file-name">index.html</div>
|
|||
|
|
<div class="file-desc">本页面，可视化使用指南</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<div class="quick-start">
|
|||
|
|
<h3>🚀 快速开始（3 步）</h3>
|
|||
|
|
|
|||
|
|
<div class="step" data-step="1">
|
|||
|
|
<strong>获取应用凭证</strong>
|
|||
|
|
<p>登录管理后台 → 应用管理 → 获取 AppCode 和 AppSecret</p>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<div class="step" data-step="2">
|
|||
|
|
<strong>修改配置</strong>
|
|||
|
|
<p>编辑 <code>quickstart.php</code>，填入您的应用信息</p>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<div class="step" data-step="3">
|
|||
|
|
<strong>运行测试</strong>
|
|||
|
|
<div class="command">
|
|||
|
|
<code>php quickstart.php</code>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<h2>💻 使用示例</h2>
|
|||
|
|
|
|||
|
|
<h3>方式一：命令行调用</h3>
|
|||
|
|
<div class="command">
|
|||
|
|
<code># 基本用法
|
|||
|
|
php openapi-student-list-test.php <appCode> <appSecret>
|
|||
|
|
|
|||
|
|
# 示例
|
|||
|
|
php openapi-student-list-test.php YY000001 a1b2c3d4e5f6789012345678901234ab
|
|||
|
|
|
|||
|
|
# 指定服务地址
|
|||
|
|
php openapi-student-list-test.php YY000001 a1b2c3d4e5f6789012345678901234ab http://your-domain.com:8080</code>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<h3>方式二：代码集成</h3>
|
|||
|
|
<pre><code><?php
|
|||
|
|
require_once 'OpenApiClient.php';
|
|||
|
|
|
|||
|
|
// 1. 创建客户端
|
|||
|
|
$client = new OpenApiClient(
|
|||
|
|
'http://localhost:8080',
|
|||
|
|
'YY000001',
|
|||
|
|
'your-app-secret',
|
|||
|
|
false // 调试模式
|
|||
|
|
);
|
|||
|
|
|
|||
|
|
// 2. 调用接口
|
|||
|
|
$result = $client->get('/open/api/student/list', [
|
|||
|
|
'pageNum' => 1,
|
|||
|
|
'pageSize' => 10,
|
|||
|
|
'studentName' => '张'
|
|||
|
|
]);
|
|||
|
|
|
|||
|
|
// 3. 处理响应
|
|||
|
|
if ($result['code'] === 200) {
|
|||
|
|
echo "总记录数: {$result['total']}\n";
|
|||
|
|
foreach ($result['rows'] as $student) {
|
|||
|
|
echo "{$student['studentName']}\n";
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
?></code></pre>
|
|||
|
|
|
|||
|
|
<h2>🔐 签名算法</h2>
|
|||
|
|
<div class="info-box">
|
|||
|
|
<strong>签名计算步骤：</strong>
|
|||
|
|
<ol style="margin-top: 10px; padding-left: 20px;">
|
|||
|
|
<li>收集请求参数（不含签名）</li>
|
|||
|
|
<li>按参数名 ASCII 码升序排序</li>
|
|||
|
|
<li>拼接：<code>key1=value1&key2=value2&appSecret=xxx</code></li>
|
|||
|
|
<li>MD5 加密并转大写</li>
|
|||
|
|
</ol>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<pre><code>function calculateSign($params, $appSecret) {
|
|||
|
|
ksort($params);
|
|||
|
|
$signStr = '';
|
|||
|
|
foreach ($params as $key => $value) {
|
|||
|
|
if ($signStr) $signStr .= '&';
|
|||
|
|
$signStr .= $key . '=' . $value;
|
|||
|
|
}
|
|||
|
|
$signStr .= '&appSecret=' . $appSecret;
|
|||
|
|
return strtoupper(md5($signStr));
|
|||
|
|
}</code></pre>
|
|||
|
|
|
|||
|
|
<h2>❌ 常见错误</h2>
|
|||
|
|
<table style="width: 100%; border-collapse: collapse; margin: 20px 0;">
|
|||
|
|
<thead>
|
|||
|
|
<tr style="background: #f5f7fa;">
|
|||
|
|
<th style="padding: 12px; border: 1px solid #dcdfe6; text-align: left;">错误信息</th>
|
|||
|
|
<th style="padding: 12px; border: 1px solid #dcdfe6; text-align: left;">原因</th>
|
|||
|
|
<th style="padding: 12px; border: 1px solid #dcdfe6; text-align: left;">解决方法</th>
|
|||
|
|
</tr>
|
|||
|
|
</thead>
|
|||
|
|
<tbody>
|
|||
|
|
<tr>
|
|||
|
|
<td style="padding: 12px; border: 1px solid #dcdfe6;">签名验证失败</td>
|
|||
|
|
<td style="padding: 12px; border: 1px solid #dcdfe6;">appSecret 错误</td>
|
|||
|
|
<td style="padding: 12px; border: 1px solid #dcdfe6;">检查应用密钥</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr>
|
|||
|
|
<td style="padding: 12px; border: 1px solid #dcdfe6;">请求已过期</td>
|
|||
|
|
<td style="padding: 12px; border: 1px solid #dcdfe6;">时间戳超过5分钟</td>
|
|||
|
|
<td style="padding: 12px; border: 1px solid #dcdfe6;">同步服务器时间</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr>
|
|||
|
|
<td style="padding: 12px; border: 1px solid #dcdfe6;">无权访问该接口</td>
|
|||
|
|
<td style="padding: 12px; border: 1px solid #dcdfe6;">未授权</td>
|
|||
|
|
<td style="padding: 12px; border: 1px solid #dcdfe6;">在管理后台配置授权</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr>
|
|||
|
|
<td style="padding: 12px; border: 1px solid #dcdfe6;">应用已停用</td>
|
|||
|
|
<td style="padding: 12px; border: 1px solid #dcdfe6;">应用状态异常</td>
|
|||
|
|
<td style="padding: 12px; border: 1px solid #dcdfe6;">启用应用</td>
|
|||
|
|
</tr>
|
|||
|
|
</tbody>
|
|||
|
|
</table>
|
|||
|
|
|
|||
|
|
<div class="success-box">
|
|||
|
|
<strong>💡 调试技巧：</strong>
|
|||
|
|
<p style="margin-top: 10px;">
|
|||
|
|
创建客户端时设置 <code>debug = true</code>，可以查看完整的请求详情和签名计算过程。
|
|||
|
|
</p>
|
|||
|
|
<div class="command" style="margin-top: 10px;">
|
|||
|
|
<code>$client = new OpenApiClient($url, $code, $secret, true);</code>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<h2>🔗 相关资源</h2>
|
|||
|
|
<ul style="line-height: 2; margin: 20px 0; padding-left: 20px;">
|
|||
|
|
<li><a href="README.md">README.md</a> - 详细使用文档</li>
|
|||
|
|
<li><a href="../../docs/应用管理-需求与技术设计方案.md">技术设计方案</a></li>
|
|||
|
|
<li><a href="../../docs/开放接口实现说明.md">实现说明</a></li>
|
|||
|
|
<li><a href="http://localhost:8080/doc.html" target="_blank">Swagger 文档</a></li>
|
|||
|
|
<li><a href="http://localhost:80" target="_blank">管理后台</a></li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<div class="footer">
|
|||
|
|
<p>pangu</p>
|
|||
|
|
<p style="margin-top: 5px;">2026-02-04</p>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</body>
|
|||
|
|
</html>
|