---

title: GraphQL持久化查询与缓存治理

keywords:

• Persisted Queries
• APQ
• 缓存
• GET
• CDN

description: 以持久化查询降低请求开销并增强缓存命中，规范 GET/POST 与错误处理，实现安全与高效的 GraphQL 访问层。

categories:

• 文章资讯
• 技术教程

---

GraphQL持久化查询与缓存治理

概览

• 持久化查询以哈希标识在服务器注册，客户端仅发送标识；结合 GET 与 CDN 提升缓存效率。
• 未注册查询回退到完整查询或拒绝，保障安全。

技术参数（已验证）

• 标识：使用 SHA-256 作为查询 ID；Apollo APQ 协议支持自动注册与回退。
• 方法选择：查询使用 GET 以启用 CDN 缓存；变更使用 POST；通过 Vary 控制头部影响。
• 错误处理：未知 ID 返回明确错误；可选回退发送完整查询以注册。
• 安全：生产环境禁止任意动态查询；白名单管理；记录注册与命中率。
• 版本与失效：查询变更触发 ID 更新；旧查询保留到过渡完成。

实战清单

• 为高频查询启用 APQ 与 GET；在边缘做缓存治理。
• 建立查询注册流程与发布；监控命中与失败。
• 将查询与版本管理纳入 CI；防止不兼容变更。