一、文煞ZblogApi接口插件API接口文档
1. 接口基础信息
· 接口触发条件：请求地址需携带 GET 参数 wensha_api=index，例：http://你的博客域名/?wensha_api=index
· 请求方式：支持 GET/POST（权限验证参数必须用 POST，业务参数可任选）
· 响应格式：统一为 JSON，编码格式 UTF-8
· 通用响应码：
· 200：请求成功
· 400：业务参数错误
· 401：权限验证失败
· 404：数据不存在
· 500：服务器内部错误
2. 通用参数
（1）权限验证参数（必传，仅支持POST）
参数名 类型 说明
skid 字符串 接口访问密钥ID（从插件配置获取）
sgin 字符串 签名值（生成规则见下文）
random_str 字符串 随机字符串（用于防重放攻击）
签名生成规则：
$sign_string = $skid . $skey . $skid . $random_str; $sgin = encrypt($sign_string, $method); // method为md5/sha1/sha256
（2）业务公共参数（可选，GET/POST均可）
参数名 类型 说明 默认值
action 字符串 接口功能标识 list
page 整数 分页页码 1
perpage 整数 每页数据条数 10
order 字符串 排序方式 desc
cate 整数 分类ID 0
days 整数 时间范围（天） 0
3. 各接口详情
（1）文章列表接口（action=list）
curl -X POST "http://www.example.com/?wensha_api=index&action=list&page=1&perpage=10&cate=1&order=desc" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "skid=your_skid&sgin=generated_signature&random_str=abc123xyz"
（2）热门文章接口（action=hot）
curl -X POST "http://www.example.com/?wensha_api=index&action=hot&page=1&perpage=5&days=7" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "skid=your_skid&sgin=generated_signature&random_str=def456uvw"
（3）随机文章接口（action=random）
curl -X POST "http://www.example.com/?wensha_api=index&action=random&page=1&perpage=8&cate=2" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "skid=your_skid&sgin=generated_signature&random_str=ghi789rst"
（4）单篇文章详情接口（action=post）
curl -X POST "http://www.example.com/?wensha_api=index&action=post&id=101" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "skid=your_skid&sgin=generated_signature&random_str=jkl012uvx"
（5）作者文章列表接口（action=author）
curl -X POST "http://www.example.com/?wensha_api=index&action=author&author=1&page=1&perpage=10" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "skid=your_skid&sgin=generated_signature&random_str=mno345yza"
二、新版PHP SDK
<?php
/**
* wensha_api 插件 PHP SDK (新版)
* 兼容最新API接口规范
*/
class WenshaApiClient
{
// 基础配置
private $baseUrl;
private $skid;
private $secretKey;
private $encryptMethod;
/**
* 构造函数
* @param string $baseUrl 博客根URL
* @param string $skid 接口密钥ID
* @param string $secretKey 接口密钥
* @param string $encryptMethod 加密方式 (md5/sha1/sha256)
*/
public function __construct(string $baseUrl, string $skid, string $secretKey, string $encryptMethod = 'md5')
{
$this->baseUrl = rtrim($baseUrl, '/');
$this->skid = $skid;
$this->secretKey = $secretKey;
$this->encryptMethod = $encryptMethod;
}
/**
* 生成签名（与插件WenshaApiAuth类保持一致）
* @param string $randomStr 随机字符串
* @return string 签名值
*/
private function generateSign(string $randomStr): string
{
$signStr = $this->skid . $this->secretKey . $this->skid . $randomStr;
switch ($this->encryptMethod) {
case 'sha1':
return sha1($signStr);
case 'sha256':
return hash('sha256', $signStr);
case 'md5':
default:
return md5($signStr);
}
}
/**
* 生成随机字符串
* @param int $length 长度
* @return string
*/
private function generateRandomString(int $length = 16): string
{
$characters = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ';
$randomString = '';
for ($i = 0; $i < $length; $i++) {
$randomString .= $characters[rand(0, strlen($characters) - 1)];
}
return $randomString;
}
/**
* 发送API请求
* @param array $getParams GET参数
* @return array 响应数据
* @throws Exception
*/
private function sendRequest(array $getParams = []): array
{
// 生成随机字符串和签名
$randomStr = $this->generateRandomString();
$sign = $this->generateSign($randomStr);
// 构建请求URL
$getParams['wensha_api'] = 'index';
$requestUrl = $this->baseUrl . '?' . http_build_query($getParams);
// 准备POST数据
$postData = [
'skid' => $this->skid,
'sgin' => $sign,
'random_str' => $randomStr
];
// 初始化curl
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $requestUrl,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query($postData),
CURLOPT_TIMEOUT => 15,
CURLOPT_SSL_VERIFYPEER => false,
CURLOPT_USERAGENT => 'WenshaApiClient/1.0'
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$curlError = curl_error($ch);
curl_close($ch);
if ($curlError) {
throw new Exception("HTTP请求失败: " . $curlError);
}
$result = json_decode($response, true);
if (json_last_error() !== JSON_ERROR_NONE) {
throw new Exception("响应格式错误: " . json_last_error_msg());
}
if ($result['code'] !== 200) {
throw new Exception("API错误 ({$result['code']}): {$result['message']}");
}
return $result;
}
/**
* 获取文章列表
* @param int $cateId 分类ID
* @param int $page 页码
* @param int $perpage 每页条数
* @param string $order 排序方式
* @return array
* @throws Exception
*/
public function getPostList(int $cateId = 0, int $page = 1, int $perpage = 10, string $order = 'desc'): array
{
$getParams = [
'action' => 'list',
'cate' => $cateId,
'page' => $page,
'perpage' => $perpage,
'order' => $order
];
return $this->sendRequest($getParams);
}
/**
* 获取热门文章
* @param int $cateId 分类ID
* @param int $page 页码
* @param int $perpage 每页条数
* @param int $days 时间范围（天）
* @return array
* @throws Exception
*/
public function getHotPosts(int $cateId = 0, int $page = 1, int $perpage = 10, int $days = 0): array
{
$getParams = [
'action' => 'hot',
'cate' => $cateId,
'page' => $page,
'perpage' => $perpage,
'days' => $days
];
return $this->sendRequest($getParams);
}
/**
* 获取随机文章
* @param int $cateId 分类ID
* @param int $page 页码
* @param int $perpage 每页条数
* @return array
* @throws Exception
*/
public function getRandomPosts(int $cateId = 0, int $page = 1, int $perpage = 10): array
{
$getParams = [
'action' => 'random',
'cate' => $cateId,
'page' => $page,
'perpage' => $perpage
];
return $this->sendRequest($getParams);
}
/**
* 获取文章详情
* @param int $postId 文章ID
* @return array
* @throws Exception
*/
public function getPostDetail(int $postId): array
{
if ($postId <= 0) {
throw new Exception("文章ID必须大于0");
}
$getParams = [
'action' => 'post',
'id' => $postId
];
return $this->sendRequest($getParams);
}
/**
* 获取作者文章列表
* @param int $authorId 作者ID
* @param int $page 页码
* @param int $perpage 每页条数
* @param string $order 排序方式
* @return array
* @throws Exception
*/
public function getAuthorPosts(int $authorId, int $page = 1, int $perpage = 10, string $order = 'desc'): array
{
if ($authorId <= 0) {
throw new Exception("作者ID必须大于0");
}
$getParams = [
'action' => 'author',
'author' => $authorId,
'page' => $page,
'perpage' => $perpage,
'order' => $order
];
return $this->sendRequest($getParams);
}
/**
* 获取API配置信息（用于调试）
* @return array
*/
public function getConfigInfo(): array
{
return [
'base_url' => $this->baseUrl,
'skid' => $this->skid,
'encrypt_method' => $this->encryptMethod,
'secret_key_length' => strlen($this->secretKey)
];
}
}三、SDK使用示例
<?php
// 引入SDK
require_once 'WenshaApiClient.php';
// 配置信息（从插件后台获取）
$config = [
'base_url' => 'http://www.your-blog.com',
'skid' => '1001', // 插件配置中的skid
'secret_key' => 'your_secret_key_here', // 插件配置中的skey
'encrypt_method' => 'md5' // 与插件配置保持一致
];
try {
// 初始化客户端
$client = new WenshaApiClient(
$config['base_url'],
$config['skid'],
$config['secret_key'],
$config['encrypt_method']
);
echo "=== 文煞API SDK测试 ===\n\n";
// 测试1：获取文章列表
echo "1. 获取文章列表\n";
$result = $client->getPostList(0, 1, 5);
echo " 成功获取 {$result['pagination']['total']} 篇文章\n";
echo " 当前页: " . count($result['data']) . " 篇\n\n";
// 测试2：获取热门文章
echo "2. 获取热门文章（7天内）\n";
$result = $client->getHotPosts(0, 1, 5, 7);
echo " 成功获取热门文章\n\n";
// 测试3：获取随机文章
echo "3. 获取随机文章\n";
$result = $client->getRandomPosts(0, 1, 3);
echo " 成功获取随机文章\n\n";
// 测试4：获取文章详情（如果有文章的话）
if (isset($result['data'][0]['id'])) {
$postId = $result['data'][0]['id'];
echo "4. 获取文章详情 (ID: {$postId})\n";
$detail = $client->getPostDetail($postId);
echo " 标题: {$detail['data']['title']}\n";
echo " 作者: {$detail['data']['author']}\n\n";
}
// 测试5：获取作者文章
echo "5. 获取作者文章\n";
$result = $client->getAuthorPosts(1, 1, 5);
echo " 成功获取作者文章\n\n";
echo "=== 所有测试完成 ===\n";
} catch (Exception $e) {
echo "错误: " . $e->getMessage() . "\n";
}四、主要更新内容
1. 签名生成规则：更新为 skid + skey + skid + random_str 格式
2. 新增接口：增加了 random 随机文章接口
3. 参数更新：热门文章接口增加了 days 参数
4. 错误处理：完善了异常处理和错误提示
5. 响应格式：统一了返回数据的结构处理
6. 配置验证：增加了配置信息的验证和调试方法
这个新版SDK完全兼容最新的API接口，包含了所有可用的功能，并提供了完善的错误处理和调试信息。
