排查 GraphQL 持久化查询未命中

目标

客户端在部署后偶发 PersistedQueryNotFound，被迫上传完整查询并增加延迟。本配方先复现未命中并读取扩展错误码，再在客户端按服务端相同规则计算 sha256 哈希并与注册表比对，定位是空白或顺序差异导致哈希不一致，最后通过预热注册表或允许一次上传后持久化来修复。

步骤要点

1. 复现未命中并读取 PersistedQueryNotFound 错误码。
2. 按相同规则计算查询文本哈希并与注册表比对。
3. 部署时预热注册表，或允许客户端上传一次后持久化。
4. 统一两端的空白与规范化规则，保证哈希稳定。

curl -s -X POST https://api.example.com/graphql \
  -H 'content-type: application/json' \
  -d '{"extensions":{"persistedQuery":{"version":1,"sha256Hash":"deadbeef"}},"operationName":"Feed"}' | jq .errors

排错提示

• 注册表必须跨所有实例共享。
• 查询文本的空白差异会改变哈希。
• 客户端从未发送的查询无法预热。

适用边界

• 依赖两端哈希规则完全一致。
• 不处理客户端从未发送的查询。