wp-headless-and-wpgraphql

WordPress 无头架构与 WPGraphQL 技能

概述

为通过 WPGraphQL 或相关 API 提供内容的无头 WordPress 项目提供系统化审查指导。**核心原则：**架构应反映持久稳定的内容边界和可预测的前端需求，同时，身份验证、预览、缓存和构建流水线必须明确说明信任边界和失效规则。

适用场景

适用于：

• 审查由 WPGraphQL 驱动的主题、插件或无头集成
• 审计自定义架构扩展和解析器代码
• 审查 WordPress 内容的前端数据获取模式
• 规划预览、草稿、身份验证或重新验证流程
• 检查构建流水线、Webhook 失效机制或持久化查询配置

不适用于：

• 没有 GraphQL 接口的纯 REST WordPress 集成（请使用 wp-rest-api-development）
• 不涉及无头前端的 ACF 字段组设计（请使用 wp-acf-and-content-modeling）
• 不涉及解耦前端的一般插件架构审查（请使用 wp-plugin-development）
• 纯 Playground 演示配置（请使用 wp-playground-development）

代码审查工作流

1. 确定集成接口

   • WPGraphQL 插件的使用情况和版本假设
   • 自定义架构注册（register_graphql_field、register_graphql_connection、register_graphql_object_type）
   • 前端查询、片段和路由／数据加载器
   • 预览、身份验证、Webhook 和缓存失效流程

2. 首先检查数据模型边界

   • GraphQL 结构是否反映了实际内容模型？
   • 分类法／CPT／选项是否经过有意配置后才公开，而非偶然暴露？
   • 是否通过持久稳定的架构设计来满足前端需求，而不是依赖临时的解析器逻辑？

3. 审查身份验证和预览行为

   • 谁可以读取草稿、修订版本、私有内容或预览令牌？
   • 前端预览端点是否明确执行权限检查和令牌验证？
   • 应用是否通过范围过宽的查询或缓存泄露未发布内容？

4. 审查查询和解析器效率

   • N+1 解析器模式
   • 开销过大的元数据查找或无界连接
   • 缺少字段级保护或分页默认值
   • 架构或片段设计导致的数据过度获取

5. 审查缓存和构建失效机制

   • 明确划分源站缓存、应用缓存和 CDN 缓存的边界
   • 重新验证／Webhook 行为具有确定性
   • 构建流水线不应假设每次编辑后都需要手动清除缓存

6. 问题分类

   • **严重：**未发布内容暴露、不安全的预览／身份验证流程，或可能导致数据泄露或生产环境不稳定的无界解析器
   • **警告：**脆弱的架构建模、开销过大的解析器、缺少分页、失效规则薄弱，或前端与不稳定的字段结构紧密耦合
   • **信息：**可改进命名、片段、架构文档、持久化查询规范或构建可观测性

特定文件类型检查

WPGraphQL 架构扩展

• 严重：架构在没有明确权限检查的情况下暴露私有／元数据
• 警告：解析器针对每个节点重复执行 get_post_meta() / WP_Query，且没有批处理或缓存
• 警告：字段名或返回类型与领域模型不匹配，迫使前端采取变通做法
• 信息：可将相关字段归入对象类型或连接，而不是零散地添加单独的标量字段

前端查询层

• 警告：路由／页面查询获取了庞大的数据树，但实际只渲染少数几个字段
• 警告：不同模板／路由中的片段重复且不一致
• 警告：预览模式和生产模式不安全地共用缓存
• 信息：可持久化共享片段，或按内容类型集中管理查询文档

预览和身份验证流程

• CRITICAL：预览端点只信任 slug 或文章 ID，不验证 capability/token 的归属
• CRITICAL：草稿/私有内容可能会在 CDN 或应用层被缓存
• WARNING：未区分编辑器预览流量和公开流量
• INFO：可以更清晰地说明预览生命周期、令牌过期时间和缓存绕过规则

构建 / 重新验证 / Webhook

• WARNING：每次内容变更都会触发完整构建，且没有范围限制
• WARNING：Webhook 不会标明哪些路由/内容依赖于此次变更
• WARNING：重新验证事件失败时没有重试/验证流程
• INFO：可以添加事件日志或支持重放的 Webhook 投递机制，以便调试

快速检测的搜索模式（HEADLESS-21）

使用这些 rg 命令快速定位无头架构和 WPGraphQL 相关内容。

Schema 和解析器发现

rg -n "register_graphql_(field|fields|connection|object_type|interface_type|union_type|enum_type)|graphql_register_types" . -g '*.{php}'
rg -n "WPGraphQL|graphql" . -g '*.{php,js,jsx,ts,tsx,md,yml,yaml}'

前端查询发现

rg -n "gql`|graphql`|useQuery\(|ApolloClient|@apollo/client|urql|graphql-request|getStaticProps|getServerSideProps|generateStaticParams" . -g '*.{js,jsx,ts,tsx}'
rg -n "preview|draftMode|draftMode\(|revalidate|revalidatePath|revalidateTag" . -g '*.{js,jsx,ts,tsx}'

高风险数据和缓存模式

rg -n "get_post_meta\(|WP_Query\(|meta_query|posts_per_page\s*=>\s*-1" . -g '*.{php}'
rg -n "webhook|revalidation|x-vercel|x-signature|secret|persisted query|persistedQuery" . -g '*.{php,js,jsx,ts,tsx,yml,yaml}'

参考文件

• references/graphql-schema-and-modeling.md - Schema 边界、CPT/分类法映射、连接设计和解析器模式
• references/auth-preview-and-drafts.md - 预览模式、私有内容、身份验证边界和缓存绕过规则
• references/caching-builds-and-webhooks.md - 持久化查询、缓存层、路由重新验证和 Webhook 投递设计

输出格式（HEADLESS-23）

对于每项发现，请包含：

1. 严重程度：CRITICAL、WARNING 或 INFO
2. 文件和行号
3. 无头架构/WPGraphQL 风险摘要
4. 其对 Schema 设计、前端正确性或生产稳定性的影响
5. 建议采用的更安全模式

如果未发现问题，请明确说明，并指出任何残留风险，例如预览文档不完整、缺少失效可观测性，或随着前端演进可能发生变化的 Schema 区域。