如何利用ThinkPHP实现API接口签名验证机制【安全】

签名验证必须放在中间件而非控制器中，这一点可以说是API签名安全的核心底线。控制器一旦开始执行，路由已经匹配、参数已经解析、日志可能已经写入，甚至数据库操作都已经准备就绪——这时候再去验签，相当于把门锁装在屋子里，早就失去了拦截的意义。 实际上，一个常见的陷阱是：服务端和客户端参数看起来完全一致，却始终提示 `Invalid signature`。问题往往出在控制器里用了 `$this->request->param()`。这个方法会自动执行 `urldecode()`、过滤空格、转义特殊字符，而客户端签名用的是原始URL编码字节流，哈希值算出来当然不一样。 正确的做法是新建一个中间件，比如 `app/middleware/ApiSignVerify.php`，在 `app/middleware.php` 中注册，位置放在 `ValidateRequest` 之后、业务中间件之前。在 `handle()` 方法开头就执行验签逻辑，失败直接返回401，不再放行。这里必须警惕的是：不要在中间件里分开调用 `$request->get()` 或 `$request->post()` 来取参，顺序和编码都不可控。统一走原始输入流处理，才能保证一致性。

GET/POST/JSON 请求参数必须统一提取并归一化

不同的请求方式，参数藏的位置各不相同：GET在query string，POST form在body，JSON在raw input。如果不统一提取，必然漏字段或者重复拼接，签名原文根本对不上。 服务端构造签名原文时，必须还原客户端原始的拼串逻辑。可以说，90%的验签失败，根源都在这一步没有对齐。 - 先用 `$request->getInput()` 读取原始输入流（即 `php://input`） - 判断 `$request->header('content-type')` 是否包含 `application/json`：如果是，就 `json_decode($raw, true)`；否则用 `parse_str($raw, $body)` - 显式合并：`array_merge($request->get(), $body)`，确保 query 和 body 全覆盖 - 对每个值做 `trim()` 和 `str_replace(["\r", "\n"], '', $v)`，清除隐藏字符和BOM - 剔除 `sign`、`signature`、`nonce`、`timestamp` 等非业务字段前，务必确认它们真实存在于数组中，避免 `unset()` 时报错

签名原文拼接规则必须严格一致

客户端和服务端拼出来的字符串，哪怕只差一个空格，或者编码方式不同，`hash_hmac('sha256', ...)` 的结果就完全不同。路径、参数顺序、编码方式、密钥接入方式，缺一不可。 一个典型的错误案例是：用 `http_build_query()` 拼参，但没有指定 `PHP_QUERY_RFC3986`，导致空格被编码成 `+` 而不是 `%20`；或者对整个数组使用 `rawurlencode()`，而不是对每个 `$k` 和 `$v` 单独编码。 正确的拼接流程是这样的： - 路径取 `$request->url(true)`（如 `/api/v1/user`），不含域名、query、`index.php` - 剩余参数用 `ksort()` 按 key 字典序升序排列 - 遍历参数，对每个 `$k` 和 `$v` 分别调用 `rawurlencode()`（注意不是 `urlencode()`） - 拼成 `k1=v1&k2=v2` 格式，末尾不加 `&` - 追加 `&sign_version=1`（如果启用版本控制），再拼接 `rawurlencode($secretKey)` - 最终传给 `hash_hmac('sha256', $stringToSign, $secretKey)`，结果转小写

密钥管理与风控必须按子域名或渠道隔离

所有业务共用一个密钥，等于把所有房门钥匙焊死在同一把锁上。一旦泄露，全线沦陷。ThinkPHP 本身不提供密钥轮换机制，必须靠配置和路由结构来实现物理隔离。 需要意识到的是：二级域名不只是“换个地址”，它是独立安全上下文的载体。`api.example.com` 和 `pay.example.com` 应该加载完全不同的密钥、限流策略和验签中间件。 - 在 `config/app.php` 开启 `'url_domain_deploy' => true`，并确保 Nginx/Apache 透传 `Host` 头 - 路由中显式注册子域名：`Route::domain('api.example.com', function () { /* API 路由 */ });` - 密钥存放在独立配置文件中（如 `config/api_sign.php`），禁止 Web 直接访问；或者按子域名创建 `config/api.api.example.com.php` - 中间件内通过 `$request->host()` 提取子域名，动态加载：`Config::get('api.sign_key_' . str_replace('.', '_', $host))` - `nonce` 去重必须用 Redis 的原子操作：`cache()->handler()->setNx("sign:nonce:{$nonce}", 1, 300)`，不能依赖 session 或本地缓存 还有一个容易被忽略的细节：开发环境常常会加一句 `if (env('APP_DEBUG')) return true;`，上线后却容易忘记删掉。更稳妥的做法是配置一个开关项 `config('api.sign_enabled')`，上线前统一设为 `true`，而不是靠 debug 状态来判断。