SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场wp-headless-and-wpgraphql

wp-headless-and-wpgraphql

前端与建站

查看项目

更新于 10-16 09:13

技能介绍

用途

本技能用于对通过 WPGraphQL 或相邻 API 暴露内容的无头 WordPress 项目进行系统性审查。其核心原则是：schema 应反映持久的内容边界和可预测的前端需求，而认证、预览、缓存和构建流水线必须对信任边界与失效规则保持明确。

适用场景

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

不适用场景

  • 仅使用经典 REST、无 GraphQL 表面的 WordPress 集成（应使用 wp-rest-api-development）
  • 不涉及无头前端问题的 ACF 字段组设计（应使用 wp-acf-and-content-modeling）
  • 无解耦前端的通用插件架构审查（应使用 wp-plugin-development）
  • 纯 Playground 演示环境（应使用 wp-playground-development）

代码审查工作流

  1. 识别集成表面：WPGraphQL 插件使用与版本假设；自定义 schema 注册（register_graphql_field、register_graphql_connection、register_graphql_object_type）；前端查询、片段和路由/数据加载器；预览、认证、webhook 和缓存失效流程。
  2. 优先检查数据模型边界：GraphQL 形状是否镜像实际内容模型；分类法/自定义文章类型/选项是有意暴露还是偶然暴露；前端需求是否通过持久 schema 设计而非临时解析器逻辑解决。
  3. 审查认证与预览行为：谁可以读取草稿、修订、私有内容或预览令牌；前端预览端点是否明确进行能力检查和令牌验证；应用是否通过过宽查询或缓存泄露未发布内容。
  4. 审查查询与解析器效率：N+1 解析器模式；昂贵的 meta 查询或无界连接；缺少字段级防护或分页默认值；由 schema 或片段设计导致的过度获取。
  5. 审查缓存与构建失效：源缓存、应用缓存和 CDN 缓存之间的清晰边界；确定性的重新验证/webhook 行为；构建流水线不应假设每次编辑后都需要手动清除缓存。
  6. 分类发现：CRITICAL（未发布内容暴露、不安全的预览/认证流程、无界解析器导致数据泄露或生产不稳定）；WARNING（脆弱的 schema 建模、昂贵解析器、缺少分页、失效规则薄弱、前端与不稳定字段形状紧耦合）；INFO（命名、片段、schema 文档、持久化查询纪律或构建可观测性可改进）。

文件类型特定检查

WPGraphQL Schema 扩展

  • CRITICAL：schema 在无显式权限检查的情况下暴露私有/meta 数据
  • WARNING：解析器对每个节点重复执行 get_post_meta() / WP_Query 工作，无批处理或缓存
  • WARNING：字段名或返回类型与领域模型不匹配，迫使前端采用变通方案
  • INFO：可将相关字段分组为对象类型或连接，而非一次性标量蔓延

前端查询层

  • WARNING：路由/页面查询获取大型树，而实际仅渲染少量字段
  • WARNING：片段在模板/路由间重复且不一致
  • WARNING：预览模式和生产模式不安全地共享缓存
  • INFO：可按内容类型持久化共享片段或集中查询文档

预览与认证流程

  • CRITICAL：预览端点仅信任 slug 或文章 ID，未验证能力/令牌所有权
  • 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）

每个发现应包含：严重性（CRITICAL、WARNING 或 INFO）；文件和行号；无头/WPGraphQL 风险摘要；为何对 schema 设计、前端正确性或生产稳定性重要；推荐的安全模式。

如果未发现问题，应明确说明，并提及任何残余风险，例如预览文档不完整、缺少失效可观测性，或随着前端演进可能漂移的 schema 区域。