Clara BBS 为什么不用 SDK：原生签名实现省了什么、稳在哪

学完这篇，你能搞明白 Clara BBS 为什么宁可手写几行 PHP 也不引第三方 SDK，以及原生签名在部署、升级、排错上到底省掉了哪些环节、稳定性从哪儿来。

第一步：先看清"签名"这件事的本质

接口签名说穿了只有三步：把参数按约定规则规范化 → 拼上密钥 → 做一次哈希。剩下的都是细节。

而这一步所用的函数全是 PHP 自带：hash_hmac、hash、hash_equals。它们从 PHP 5.1 起就在核心扩展里，PHP 7.4 到 8.5 全都能跑。也就是说，"能不能做签名"从来不是 SDK 带来的能力，"做得顺不顺手"才是。

第二步：SDK 到底重在哪

官方 SDK 基本都靠 Composer 分发，落到项目里就是 vendor 目录、composer.json、composer.lock 和一堆自动加载文件。

Clara BBS 的定位是"上传文件 → 访问 install 安装向导 → 完成"，环境要求写明 PHP 7.4-8.5 + MySQL 5.7+，无需 Composer、无需命令行、无编译缓存。这两件事天然冲突：一旦把 SDK 塞进来，部署就多了一步 composer install，服务器上没装 Composer 或版本对不上，站点直接起不来。

注意：SDK 的目录结构和类名属于第三方，插件更新或整包覆盖时，vendor 目录很容易被交叉覆盖，出现"文件对不上"的诡异报错。

第三步：原生签名的最小实现

以最常见的 HMAC-SHA256 为例，一个函数就够：

function makeSign(array $params, string $secret): string
{
    unset($params['sign'], $params['sign_type']);
    ksort($params);                 // 按键名 ASCII 升序

    $pairs = [];
    foreach ($params as $k => $v) {
        if ($v === '' || $v === null) continue;   // 空值不参与签名
        $pairs[] = $k . '=' . $v;
    }

    $str = implode('&', $pairs) . '&key=' . $secret;
    return strtoupper(hash_hmac('sha256', $str, $secret));
}

验签侧同样是三行：

$expected = makeSign($input, $secret);
if (!hash_equals($expected, $input['sign'] ?? '')) {
    // 验签失败
}

这里每个函数都是 PHP 核心函数，没有任何外部依赖，改完保存即生效——正好对上系统"运行时插件钩子、保存即生效无需清缓存"的机制。

第四步：验签必须补上的三个动作

光有 makeSign 不算安全，验签侧还要做三件事：

1. 用 hash_equals 而不是 ==。普通比较会在第一个不同字符处提前返回，理论上可被时序探测；hash_equals 是恒定时间比较。
2. 加时间戳窗口 + 随机串（nonce）。只校验签名，同一份请求可以被无限重放。约定 timestamp 与 nonce，服务端检查时间偏差在允许窗口内、nonce 未用过。
3. 失败要留痕。验签失败别只返回一句"参数错误"，把原始参数（脱敏后）和计算出的待签串记进日志，否则线上对不上签名时只能靠猜。

注意：最常见的三个坑是——参数值做了两次 URL 编码、键名排序用了 sort 而不是 ksort（丢掉了键名关联）、签名结果一个用大写一个用小写。对接前先把这三条对齐。

第五步：省了什么，稳在哪

省掉的：一次 composer install 的部署步骤；vendor 目录的体积和文件数；Composer 版本与 PHP 版本的连锁冲突；SDK 大版本升级时悄悄改变的行为（比如默认算法、默认编码、默认超时）；以及"SDK 报错但堆栈全在第三方代码里"的排查成本。

稳在哪：签名算法是标准化的，HMAC-SHA256 的输出在任何语言、任何平台都一致，不存在"SDK 升级后签名对不上"的问题；行为完全由你自己的代码决定，出问题时错误堆栈落在自己写的文件里；无编译缓存意味着改动即时生效，调试不用反复清缓存。

值得一提的是，Clara BBS 本身提供 Cache::remember 缓存、Cron::register 定时任务、notify 通知和统一的货币记账 API 这类公共设施，插件开发时可以直接复用，需要做签名、验签、防重放这类逻辑时，也只在插件目录 content/plugins 里加文件即可，不引入任何外部包。

注意：原生实现不等于可以把密钥写在代码里。密钥只应存在于服务端配置中，绝不能出现在前端模板、JS 或者能被下载的路径下。

小结

• 签名的本质是"规范化参数 + 密钥 + 哈希"，PHP 核心函数就能完成，SDK 提供的是便利而非能力。
• 不引 SDK，省掉的是 Composer 依赖链、vendor 体积、版本冲突和升级带来的行为漂移。
• 稳定性的来源是算法标准化 + 行为自控 + 无编译缓存，改动保存即生效。
• 验签必做三件事：hash_equals 恒定时间比较、时间戳窗口 + nonce 防重放、失败留日志。
• 三个高频坑：参数重复 URL 编码、排序用错函数、签名大小写不一致。
• 密钥只放服务端配置，不进代码、不进模板、不进可下载路径。