GraphQL 持久化查询与CDN缓存（Persisted Queries、Cache 与验证）

---

title: GraphQL 持久化查询与CDN缓存（Persisted Queries、Cache 与验证）

date: 2025-11-26

keywords:

• Persisted Query
• CDN 缓存
• SHA256
• GET 请求
• 缓存键

description: 通过持久化查询将查询映射为哈希并使用GET请求与CDN缓存，降低带宽与提升性能，提供客户端与服务端实现与验证方法。

categories:

• 文章资讯
• 编程技术

---

概述

持久化查询将GraphQL查询预注册为哈希, 客户端仅发送哈希与变量, 使用GET请求可命中CDN缓存。结合缓存键策略与失效机制, 降低延迟与带宽。

关键实践与参数

• 哈希算法: SHA256 生成查询ID
• 请求方式: GET /graphql?queryId=...&vars=...
• 缓存键: 按 queryId+vars 构造
• 失效与更新: 版本与TTL策略

示例/配置/实现

import crypto from 'crypto'
function idOf(query) { return crypto.createHash('sha256').update(query).digest('hex') }
const q = `query($id: ID!){ product(id:$id){ id name } }`
const id = idOf(q)

import express from 'express'
const app = express()
const store = new Map()
app.get('/graphql', (req, res) => {
  const id = req.query.queryId
  const vars = JSON.parse(req.query.vars || '{}')
  const query = store.get(id)
  if (!query) return res.status(404).end()
  res.set('Cache-Control', 'public, max-age=60')
  res.json({ data: { product: { id: vars.id, name: 'Demo' } } })
})

location /graphql {
  proxy_cache mycache;
  proxy_cache_key "$arg_queryId:$arg_vars";
  proxy_cache_valid 200 60s;
  proxy_pass http://api;
}

验证

• 哈希与映射: 注册查询后哈希稳定且服务端可解析
• CDN命中: GET请求在相同变量下命中缓存
• 失效策略: 更新查询或变量后缓存失效并回源
• 带宽与延迟: 相比POST原文请求下降

注意事项

• 变量影响缓存键, 需合理设计
• 查询更新需版本管理与灰度发布
• 安全校验避免未注册查询绕过
• 与权限与审计协同