Drupal 作为后端：GraphQL、JSON:API、RESTful，以及隐藏在 API 选择中的昂贵错误

有一次，在一次关于解耦 Drupal 的规划会议进行到一半时，一位 CTO 问我：“所以，我们应该使用哪个 API？”

房间里安静了一秒。前端想要 GraphQL。后端想要 JSON:API。一家集成供应商已经默认会使用 REST。产品负责人只是希望移动应用不要再等待网站发布。

这个小问题通常听起来像是技术问题。其实不是。它是治理问题，是预算问题，有时还是一个披着开发者连帽衫的招聘问题。

Drupal 可以成为解耦产品中非常强大的后端。它已经具备结构化内容、角色、权限、工作流、修订、翻译、媒体处理、分类法以及成熟的模块生态系统。尴尬的部分在于决定这些内容如何离开 Drupal。Drupal 核心原生支持 JSON:API，GraphQL 可通过贡献模块使用，而 Drupal 的 RESTful Web Services 模块仍然是自定义资源式 endpoint 的一个选择。Drupal 自己的解耦文档把这种划分说得很清楚：JSON:API 在核心中，GraphQL 是贡献模块，Drupal 可以通过 API 向外部前端暴露内容。

然而，团队仍然会做出糟糕的选择。

他们选择 GraphQL，因为它听起来现代。他们选择 REST，因为所有人都用过。他们选择 JSON:API，因为它已经存在。这些都不是战略。

更直接地说：对于大多数以 Drupal 为后端的内容平台，JSON:API 应该是默认起点。GraphQL 应该是被证明值得之后才使用。REST 应该保留给另外两者过于宽泛或过于固执的场景。

这会惹恼一些人。很好。

从那个无聊的赢家开始：JSON:API

JSON:API 是以最好的方式显得无聊。

Drupal 核心的 JSON:API 模块为 Drupal 实体实现了 JSON:API 规范。它提供了一种零配置、带有明确约定的方式，用于暴露站点内容的 CRUD 操作，并且与 Drupal 的 Entity API、Field API、缓存、认证和授权系统相连接。

这句话里包含了高管应该关心的部分：核心模块。

核心很重要。核心通常意味着更少的供应商意外、更容易规划维护、更清晰的安全姿态，以及更少出现“我们需要那个唯一懂自定义 API 层的承包商”的风险。Drupal 的 JSON:API 文档说明，该模块围绕实体类型和 bundle 暴露 API，支持过滤、includes、分页、排序、修订、翻译、GET、POST、PATCH、DELETE、文件上传，以及通过事件进行资源定制。

一个实际例子：想象一家媒体公司，有文章、作者、主题、落地页 teaser 和图片。前端团队需要用 Next.js 构建文章页面。移动应用需要同样的文章正文、hero 图片、作者姓名和相关主题。JSON:API 可以暴露这些 Drupal 实体，而不需要后端团队从零开始发明一种 API 语言。相关资源可以通过 includes 嵌入，集合也可以被过滤或分页。

payload 漂亮吗？有时候。也有时候看起来像是一个委员会在漫长午餐后设计出来的。

但这也正是重点。JSON:API 是一种规范，不是某个开发者的个人审美。JSON:API 官方网站将其描述为一种用于构建 JSON API 的规范，带有共享约定，可以减少围绕响应形状的争论，并帮助团队使用通用工具。它的媒体类型是 application/vnd.api+json，版本 1.1 于 2022 年 9 月 30 日最终确定。

这里还有一个隐藏的管理收益。标准化的响应格式意味着新人入职不那么依赖部落知识。新的前端开发者可能仍然会咒骂嵌套的 data、attributes 和 relationships 结构。没关系。至少他们咒骂的是有文档记录的东西。

没人愿意提起的陷阱

JSON:API 会相当直接地暴露 Drupal 的内容模型。这可以是一种优势，尤其是当 Drupal 是编辑层面的事实来源时。但它也可能把 Drupal 的内部结构过多地泄漏到前端。

如果你的内容模型很干净，JSON:API 会显得高效。如果你的内容模型是一座旧妥协的博物馆，JSON:API 会让混乱变得可见。

我见过一些 “Article” 内容类型，里面有 field_new_body_2021、field_mobile_summary、field_legacy_related 和 field_do_not_use 这样的字段。JSON:API 不会神奇地把它变成优雅的产品 API。它暴露的是你实际拥有的模型。也许有点残酷。但很有用。

Drupal 的文档也明确划出了一条边界：JSON:API 处理面向实体的 CRUD，但登录、密码重置和账号创建等业务规则不属于 JSON:API 的职责范围。如果你的应用需要“批准供应商”“计算续约报价”或“提交索赔”这样的领域动作，不要仅仅因为模块方便，就把它们强行塞进内容实体 endpoint。

那条路很快就会变得难看。

GraphQL 看起来优雅，是因为它转移了痛苦

GraphQL 很诱人。前端可以请求它想要的确切字段。响应具有与查询相同的形状。它有类型化 schema。它感觉像是为基于组件的前端而设计的，因为坦率地说，它确实如此。GraphQL 官方网站将 GraphQL 描述为一种开源查询语言，以及用于 API 的服务器端运行时，具有强类型 schema，并展示了客户端请求所选字段，而不是接收固定服务器响应的方式。

对前端团队来说，这是实实在在的改进。

以一个由组件组成的首页为例：hero、精选文章、活动、赞助位、导航、区域提醒。使用 REST 时，前端可能会调用多个 endpoint。使用 JSON:API 时，它可以请求一个集合并包含相关资源，但结构仍然遵循实体关系。使用 GraphQL 时，查询可以更接近屏幕本身。当团队需要快速交付产品界面时，这很重要。

Drupal 的 GraphQL 模块允许开发者为 Drupal 10 和 11 构建并暴露 GraphQL schema。它基于 webonyx/graphql-php，支持官方 GraphQL 规范，在 /graphql/explorer 提供 GraphiQL，并为开发者提供 data producer plugins 以及用于 schema 工作的自定义代码。

仔细读这句话：“构建并暴露”。

当前的 Drupal GraphQL 模块不是一面魔镜，不会简单地把每个 Drupal 字段反射成一个整洁的 API。Drupal.org 表示，较早的 3.x 版本会根据 Drupal 实体自动生成 schema，并通过 API 暴露 Drupal 细节，而 4.x 则将 schema 设计交给开发者，这样可以隐藏 Drupal 内部实现。同一页面还说，4.x 要求开发者设置并映射 schema。

这不是脚注。这就是账单。

GraphQL 可以在产品和内容存储之间提供一份干净的契约。但必须有人设计这份契约。编辑添加字段时、设计系统变化时、个性化功能到来时、法务要求区域性同意逻辑时、移动团队需要离线同步时，也必须有人维护它。

实际上，这种说法太客气了。必须有人拥有它。所有权是许多 GraphQL 提案中缺失的预算项。

GraphQL 什么时候值得这个成本

当 API 本身就是一个产品时，GraphQL 是有意义的。

一所大型大学拥有数十个 microsite、学生移动应用、数字标牌、教师档案、课程目录和设计系统，可能会从 GraphQL 层中受益。消费者各不相同。内容图谱很深。前端团队需要选择性访问。组织可能希望有一份 API 契约来隐藏 Drupal bundle 的怪异之处。

当 Drupal 只是多个来源之一时，GraphQL 也很适合。也许内容来自 Drupal，价格来自 ERP，可用性来自预订引擎，用户权益来自 CRM。GraphQL 可以向客户端呈现一个一致的 schema，而 resolvers 则从不同系统获取数据。GraphQL 模型围绕强类型 schema 和客户端指定的响应形状构建，这正是它在这种组合层中运行良好的原因。

但对于一个普通的、带 headless 前端的营销网站呢？我会持怀疑态度。甚至会有点恼火。

如果真正的需求是“React 应该从 Drupal 读取文章”，GraphQL 可能只是一次化装舞会。你会花架构预算来避免学习 JSON:API 的 includes 和 filters。更糟的是，你可能会创建一个只有两个开发者理解的定制 API 层。

Drupal GraphQL 项目页面称，稳定版本受 Drupal 安全公告政策覆盖，并列出了 Drupal 10 和 11 的近期版本，包括 2026 年 4 月 29 日发布的 8.x-4.14，以及面向 Drupal 10.4 和 11 的 5.0.0 beta。这是健康的信号。但它并不会消除设计工作。

一个贡献模块可以很成熟，同时仍然是错误的默认选择。

RESTful Web Services：老旧、有用，并且通常被过度使用

REST 已经变成了那种说话者想让它表示什么，它就表示什么的词。有时它指干净的、面向资源的 HTTP。有时它指“我们从 controller 返回 JSON”。有时它指“供应商给了我们一个 endpoint 和一份 PDF”。

Roy Fielding 的论文将 REST 引入为一种用于分布式超媒体系统的架构风格，带有客户端-服务器分离、无状态通信、缓存、统一接口、分层系统以及可选的按需代码等约束。这个原始概念比很多项目计划中所谓的 REST 要严格得多。

Drupal 的 RESTful Web Services 模块很有用，因为它可以用特定方法、序列化格式和认证方式暴露资源。Drupal 学习材料描述了用于实体的 REST 资源，支持 GET、POST、PATCH 和 DELETE 等方法，支持 JSON 或 XML 序列化，并支持通过 Basic Auth、cookie 或 OAuth 等其他模块进行认证。它还指出，不安全的方法需要 X-CSRF-Token 请求头。

这使 REST 很适合范围较窄的集成工作。

支付提供商向 Drupal 发布交易状态。仓库系统拉取更新后的产品手册列表。合作伙伴门户需要一个为已批准资产精心设计的 endpoint。一个旧版移动应用已经期望 /api/v1/articles/{id}，并且本季度无法重写。

REST 给你控制权。它也给你空白页综合征。

与 JSON:API 不同，后者已经选好了约定；自定义 REST endpoint 需要做很多决定：URL 形状、响应格式、错误格式、分页风格、过滤语法、版本控制、认证、缓存头、文档、弃用策略。OpenAPI 可以帮助记录这个表面，而 OpenAPI Specification 是一种标准的、语言无关的方式，用于描述 HTTP API，使人类和计算机无需阅读源代码即可理解它们。

不过，你仍然必须做出选择。

而这些选择会留下来。第二周设计的一个草率 endpoint 可能会困扰产品多年，因为某个仍在外部使用的应用版本依然依赖它。

决策不是“哪个 API 最好？”

这种提问方式很懒。抱歉，但确实如此。

更好的问题是：你的组织能够承受哪种类型的耦合？

JSON:API 将消费者耦合到 Drupal 的实体模型。当 Drupal 是主要内容系统，而前端只是替代展示层时，这通常是可以接受的。回报是速度，以及更少的后端发明。

GraphQL 将消费者耦合到你的团队设计的 schema。如果做得好，这个 schema 会隐藏 Drupal，并表达产品领域。如果做得不好，它会变成第二套在代码中维护的 CMS 模型。

REST 将消费者耦合到自定义 endpoint。这对于特定集成非常出色，但对于广泛内容交付则很危险，因为每个 endpoint 都会变成一个带有自己维护尾巴的微型产品。

下面是我会放到高管指导小组面前的版本。

表格有点无趣，但这张表能节省会议。

项目经理应该关注什么

API 选择对项目计划的影响，比人们承认的要大。

使用 JSON:API 时，关键路径是内容建模。如果内容模型经过深思熟虑，API 工作可以快速推进。如果内容模型混乱，前端开发会变慢，因为每次查询都会暴露另一个编辑层面的妥协。在前端团队开始连接页面之前，应让资深人员关注字段命名、可复用 paragraph 模式、媒体关系、分类法和权限。

使用 GraphQL 时，关键路径是 schema 所有权。谁设计 schema？谁审查破坏性变更？谁编写 resolvers？谁处理嵌套查询触发过多后端加载等性能问题？Drupal GraphQL 模块提供工具和扩展点，包括 data producer plugins 和 GraphiQL，但它并不会消除对后端工程纪律的需求。

使用 REST 时，关键路径是契约纪律。每个 endpoint 都需要文档、测试、认证规则、错误语义和版本控制方案。REST 在第一个 endpoint 建成时看起来很便宜。第五个 endpoint 会说出真相。

还有一件事。认证经常被低估。Drupal JSON:API 与 Drupal 的认证和授权系统绑定，REST 可以使用 Basic Auth 和 cookie 等认证提供者，而 OAuth 通常通过贡献模块添加。Lupus Decoupled Drupal 文档指出，Simple OAuth 是在解耦设置中通过 token 认证 API 请求的一种方式。

不要把它留到发布前的那个 sprint。那个 sprint 已经被诅咒了。

性能：所有人都会简化的争论

GraphQL 粉丝说它避免 over-fetching。没错。JSON:API 粉丝说 includes 减少往返请求。也没错。REST 粉丝说 HTTP 缓存很直接。还是没错。

现在是不愉快的部分：三者都可以很快，三者也都可以很慢。

GraphQL 可以减少 payload 大小，但如果 resolvers 粗心，复杂的嵌套查询会惩罚后端。JSON:API 可以使用 Drupal 的响应缓存和 includes，但 payload 可能很冗长。REST 可以很好地映射到 HTTP 缓存，但自定义 endpoint 通常会在性能测试开始前忘记 cacheability。Fielding 的 REST 约束包含缓存，因为缓存可以减少网络流量和延迟，但陈旧数据和缓存失效仍然是真实的权衡。Drupal 的 JSON:API 文档明确将该模块与 Drupal 响应缓存联系起来，而 GraphQL 模块在 Drupal.org 上被归类为 Decoupled、Developer tools 和 Performance。

所以，不，GraphQL 并不自动是“性能选项”。

第一个性能收益通常是更好的内容建模。第二个是缓存策略。第三个是避免愚蠢的客户端行为，比如因为没人写数据访问层，就把同一个 endpoint 调用十二次。

光鲜吗？不。有效吗？是的。

一个直白的选择框架

如果我要给 founder 或 CTO 提建议，我会从这个顺序开始。

第一，除非你有解耦的理由，否则使用 Drupal 正常渲染的页面。解耦会增加托管、预览、路由、缓存、部署、认证和调试复杂度。Drupal 自己的解耦文档通过指出 layout 转移到前端、后端通过 API 暴露内容，将标准 Drupal 与解耦 Drupal 区分开来。这个转变并不是免费的。

第二，如果你主要是为了现代前端而解耦，就从 JSON:API 开始。构建一个真实页面，而不是 demo。包括媒体、菜单或导航、相关内容、预览需求、必要时的认证，以及缓存行为。你从一个丑陋的真实页面中学到的东西，会比从六张架构图中学到的更多。

第三，只有当消费者体验能够证明 schema 工作是值得的时，才转向 GraphQL。好的理由包括多个前端消费者、需要隐藏 Drupal 内部实现、复杂内容图谱，或跨系统聚合。糟糕的理由包括“我们的前端开发者喜欢 Apollo”和“投资人演示文稿里写着 GraphQL”。

第四，将 REST 用于需要清晰边界的集成。为合作伙伴导出设计一个自定义 endpoint 可以很干净。由手写 endpoint 组成的整个内容平台，则可能变成一个装满未贴标签钥匙的抽屉。

还有，清理 Drupal 模型。拜托。没有任何 API 层能完全拯救一个没人负责的内容模型。

“future-proof”的政治

高管喜欢“future-proof”这个词。我理解原因。没人想批准一次后端重建，却在十八个月后听到所选 API 把公司逼进了角落。

但所谓面向未来，通常与其说是选择最花哨的 API，不如说是决定变化被允许发生在哪里。

JSON:API 说：“Drupal 的模型就是契约。”这很诚实，也很快。

GraphQL 说：“我们的产品 schema 才是契约。”这很强大，也很昂贵。

REST 说：“这个 endpoint 就是契约。”这很精确，也很容易倍增成维护问题。

没有普遍赢家。只有适配。

我的偏见很简单：从能够支撑产品的最少自定义方案开始。在 Drupal 中，这通常意味着 JSON:API。当你能说出负责人和预算时，再加入 GraphQL。当集成足够具体、值得拥有自己的入口时，再加入 REST。

最糟糕的选择是为了时髦而做出的选择，因为时髦从不会出现在维护现场。

正在寻找市场上排名第一的 Drupal 开发公司？你已经找到了。

我们是最优秀的 Drupal 专注型数字 agency，致力于交付快速、安全、可扩展的平台，而且绝不妥协。从新建项目和重新设计，到迁移和长期支持，我们的 Drupal 专家以精品 agency 级别的关注度交付企业级成果。

立即预约通话，让我们把你的 Drupal roadmap 转化为高性能的现实。