Webman中接口签名验证失败主因是字段映射不一致，需严格核对fields配置中app_id、app_key、timestamp、noncestr、signature的大小写及来源位置是否与客户端完全匹配。
Webman 项目里做接口签名验证，不能只套用通用 PHP 签名逻辑——webman-api-sign2 插件已封装好防重放、RSA 加密、字段映射等关键能力，直接集成比手写更稳。但配置错一个参数，比如 encrypt 和实际客户端用的哈希算法不一致，或 fields 里把 app_key 写成 appKey，签名就必然失败。
签名验证总失败？先核对这四个字段映射是否严格一致
服务端从请求中提取参数的位置（header/get/post）和字段名必须与客户端完全匹配，大小写、下划线、驼峰都不能差。插件默认的 fields 配置是：
['app_id' => 'appId', 'app_key' => 'appKey', 'timestamp' => 'timestamp', 'noncestr' => 'nonceStr', 'signature' => 'signature']
常见错误现象：客户端传的是 App-Key header，但配置里写的是 app_key → 服务端取不到值 → 签名计算缺参数 → 失败。
- 检查客户端实际发送的字段名（用 curl -v 或抓包确认），再对照
fields键值对是否一一对应 -
app_key字段在启用 RSA 时才需要传，且它不是密钥本身，而是前端随机生成的临时密钥，用于加密 body 和 sign；真正参与签名计算的是数据库或数组里配的app_secret - 如果客户端用 JSON body 提交，需确保中间件已解析为
$_POST或$request->post()，否则post类型字段提取会为空 - Nginx 或代理可能自动解码 URL 参数，导致
rawurldecode()被执行两次；建议在插件前置中间件统一用rawurldecode()处理原始$_GET和$_POST
启用 replay 防重放时，redis 缓存 key 设计要避开 IP + noncestr 的组合陷阱
replay 开启后，插件默认用 ip:noncestr 作为 redis key 存储时间戳。但若客户端走代理或 CDN，$_SERVER['REMOTE_ADDR'] 可能全是同一个出口 IP，导致不同用户被误判为重复请求。
立即学习“PHP免费学习笔记（深入）”；
- 改用客户端真实标识：比如从 header 中取
X-Real-IP或X-Forwarded-For（需 Nginx 配置信任该 header） - 避免直接拼接字符串作 key，应做哈希处理防止 key 过长或含非法字符：
md5($ip . ':' . $noncestr) -
replay_timeout设为604800（7 天）看似保险，但若并发高、redis 内存不足，大量未过期 key 会堆积；建议设为300～1800秒，配合 redis 的 LRU 淘汰策略更稳妥 - 注意插件不会自动清理过期 key，依赖 redis 自身的 expire 机制；确认 redis 配置中
maxmemory-policy不是noeviction
使用 DatabaseDriver 时，ThinkORM 查询缓存容易被忽略的两个条件
当 driver 设为 \Wengg\WebmanApiSign\Driver\DatabaseDriver::class，插件会查 app_sign 表并按 app_id 缓存结果。但缓存生效有前提：
-
db_cache_time必须是非 null 数值（如3600），设为null或0都不缓存 - 缓存 key 是
"app_sign_{$app_id}"，如果表里app_id字段类型是字符串但数据库里存了带空格或不可见字符（比如从 Excel 导入），查出来$app_id和缓存 key 对不上 → 每次都查库 - ThinkORM 默认不开启查询缓存，需确认
config/database.php中'cache' => true已启用，且缓存驱动（如 redis）可连通 - 若应用启用了多租户或分库分表，
table配置的app_sign必须指向实际存储应用密钥的那张表，不能是通用系统表
body 加密启用后，客户端解密失败的典型原因
当 encrypt_body 设为 1，插件会对 POST/PUT 的原始 body 做 aes-128-cbc 加密，密钥是 app_secret。但客户端解密时经常出错：
- PHP 侧用的是
openssl_encrypt($data, 'AES-128-CBC', $key, 0, $iv)，其中$iv是 16 字节随机值，且随每次请求变化；客户端必须从响应 header（如X-IV）或响应体中拿到该$iv才能正确解密 -
app_secret必须严格 16 字节，不足补\0，超长截断；若数据库里存的是 hex 格式（如D24668E7B3F24F4DAB32E5B88EAE25AC），需先hex2bin()再用 - 某些安卓/IOS 加密库默认填充方式是 PKCS#7，而 PHP
openssl默认是 zero-padding；需显式指定OPENSSL_PKCS1_PADDING并确保两端一致 - 不要在加签前对 body 做
json_encode()或urldecode()—— 插件签名计算时用的是原始 raw body，二次处理会导致签名和加密不匹配
最易被忽略的是：签名验证中间件执行顺序。如果自定义中间件（如日志、权限）放在签名验证之前，且提前读取了 php://input，会导致后续插件无法获取原始 body，encrypt_body 和签名计算同时失效。
