Hyperf RPC Filter 通过实现 ServerFilterInterface 在 handle 方法开头提取 headers 中的 X-Sign、X-Timestamp、X-Nonce，依次校验时间戳有效期、nonce 去重（Redis）、参数排序拼接后 HMAC-SHA256 签名，并用 hash_equals 恒定时间比对，失败则抛出 RpcException。
Hyperf RPC Filter 如何拦截并校验请求签名
Hyperf 的 JsonRpcService 默认不经过 HTTP 中间件，但可通过 ClientFilterInterface（客户端侧）或 ServerFilterInterface（服务端侧）在 RPC 调用链路中插入校验逻辑。签名校验必须落在服务端 Filter，否则无法防止绕过客户端的恶意调用。
关键点：服务端 Filter 在 handle 方法中能拿到原始 $request（即 JsonRpcRequest 实例），其 getParams() 返回的是反序列化后的参数数组，而签名通常放在 headers 或参数顶层字段（如 sign、timestamp、nonce）中——必须提前提取，不能等框架自动解包后才校验。
- 推荐把签名、时间戳、随机串统一放在
headers里（如X-Sign、X-Timestamp、X-Nonce），避免污染业务参数结构 - Filter 类需继承
Hyperf\RpcServer\Contract\ServerFilterInterface，并配置到对应服务的@RpcService注解中（通过filter属性） - 校验失败必须抛出
Hyperf\Rpc\Exception\RpcException（或子类），否则框架可能静默吞掉错误或返回 500
签名验证逻辑该放在 Filter 的哪个位置
必须在 handle 方法开头做校验，且在调用 $next->handle($request) 之前完成。一旦放行，后续就无法中断执行流。
典型校验顺序：nonce 去重 → timestamp 有效期（如 ±300 秒）→ 拼接待签名字符串 → 计算本地签名 → 对比 X-Sign。其中 nonce 需配合 Redis 存储（如 SETNX + 过期时间），避免重放攻击。
public function handle(JsonRpcRequest $request, callable $next)
{
$headers = $request->getHeaders();
$sign = $headers['X-Sign'][0] ?? '';
$ts = (int) ($headers['X-Timestamp'][0] ?? 0);
$nonce = $headers['X-Nonce'][0] ?? '';
<pre class="brush:php;toolbar:false;">if (abs(time() - $ts) > 300) {
throw new RpcException('Invalid timestamp', StatusCode::INVALID_TIMESTAMP);
}
if (! $this->redis->setnx("rpc:nonce:{$nonce}", 1)) {
throw new RpcException('Nonce reused', StatusCode::NONCE_REUSED);
}
$this->redis->expire("rpc:nonce:{$nonce}", 600);
$params = $request->getParams();
ksort($params); // 签名前需对参数键排序
$toSign = http_build_query($params) . "×tamp={$ts}&nonce={$nonce}";
$expected = hash_hmac('sha256', $toSign, $this->secret);
if (! hash_equals($expected, $sign)) {
throw new RpcException('Invalid sign', StatusCode::INVALID_SIGN);
}
return $next($request);}
为什么用 hash_equals 而不是 == 比较签名
防止时序攻击（timing attack）。== 在字符串长度不同时会提前退出，攻击者可通过响应时间差异推测签名前缀；hash_equals 是 PHP 内置的恒定时间比较函数，无论输入是否相等、长度是否一致，执行时间都相同。
注意：hash_equals 要求两个参数都为 string。如果 $sign 是空或非字符串（如 null），会触发 warning 并返回 false。务必先做类型兜底：
- 用
is_string($sign) && strlen($sign) === 64初筛（假设是 sha256 hex） - 校验前统一转成小写（某些客户端可能输出大写 hex）
- 避免直接传入未过滤的 header 值，防止注入空字节或控制字符
Filter 配置失效或不触发的常见原因
最常被忽略的是 Filter 没有正确绑定到具体 RPC 服务。Hyperf 的 RPC Filter 不是全局注册的，必须显式指定：
- 确保
@RpcService注解中filter属性值是完整类名（如App\Filter\SignServerFilter::class），不是短名或别名 - 类必须已通过
@Aspect或容器自动加载（建议加@Inject注解保证扫描到） - 若使用多协议（如同时启用了
jsonrpc-http和jsonrpc-tcp），Filter 只对匹配协议生效；ServerFilterInterface仅作用于服务端，不影响客户端发起的调用链路 - 调试时可在
handle开头加var_dump(__METHOD__); exit;快速确认是否进入，避免因配置路径错误白忙活
签名密钥千万别硬编码在 Filter 类里，应从 config/autoload/rpc_server.php 或环境变量注入；另外，生产环境务必关闭调试信息输出，防止 RpcException 泄露内部结构。
