GraphQL

一、什么是GraphQL

GraphQL 是由 Facebook 于 2015 年开源的 API 查询语言与运行时，强调「客户端精确描述所需字段」——客户端通过单个请求按需获取多个资源的精确字段，避免 REST 中常见的「过度获取」与「请求瀑布」问题。GraphQL 把 API 控制权交给前端，是前端驱动的现代 API 范式，被 GitHub、Shopify、Meta 等众多大型互联网公司广泛采用。

二、原理

1. Schema 定义：用 SDL（Schema Definition Language）定义强类型数据图谱 → 2. 查询 Query：客户端按需声明字段，单次请求获取精确数据 → 3. 变更 Mutation：服务端写操作通过 Mutation 表达 → 4. 订阅 Subscription：基于 WebSocket 的实时数据推送 → 5. 解析器 Resolver：每个字段对应一个解析函数，由服务端实现数据组装 → 6. 联邦 Federation：多服务 GraphQL 联邦（Apollo Federation）

三、信息卡片

四、历史时间线

• 2012 年：Facebook 内部为解决移动端 API 痛点启动 GraphQL
• 2015 年：GraphQL 开源，规范发布
• 2018 年：GraphQL Foundation 成立，独立治理
• 2019 年：Apollo Federation 推动多服务联邦
• 2021 年：GraphQL 与 Edge 计算融合，CDN 边缘 GraphQL
• 2024-2025 年：GraphQL 在前端复杂应用场景广泛使用，与 REST、gRPC 形成互补

五、分类

按架构：单服务 GraphQL vs 多服务 Federation vs GraphQL Gateway

• 按实现：Apollo Server vs Mercurius vs Hasura vs GraphQL Yoga
• 按订阅：基于 WebSocket vs 基于 SSE vs 基于消息队列
• 按 Schema 优先：Schema-First vs Code-First（TypeGraphQL、TypeGraphQL）
• 按持久化：PostGraphile（数据库直出）vs Resolver 自定义

六、应用场景

• 前端复杂应用：多组件、多端统一接口
• 移动端 API：减少网络请求次数与流量
• API 联邦：多微服务 GraphQL 联邦
• CMS 与内容 API：Strapi、Contentful 等支持 GraphQL
• BFF（Backend for Frontend）：为不同端定制 GraphQL 接口

七、优缺点

优点：减少网络请求：单次请求获取多数据，典型场景请求次数减少 50% 以上；避免过度获取：精确字段减少数据流量；提升前端开发效率：前端自主决定数据结构；强类型契约：Schema 即文档，降低协作成本；支撑多端协同：Web、APP、IoT 多端统一接口

• 缺点：查询复杂度难控：深度嵌套查询可能拖垮后端；缓存复杂度提升：相比 REST，HTTP 缓存策略更难；学习曲线：Schema 设计、Resolver、N+1 查询问题需专门治理；运维挑战：错误监控、限流、授权需重新设计

八、常见误区

GraphQL 取代 REST（错：二者解决不同问题，常以 REST 公开 API + GraphQL 内部 BFF 协同）

• GraphQL 一定更快（部分对：减少请求数，但单请求复杂度可能更高）
• GraphQL 不需要文档（错：Schema 即文档，但业务文档仍需补充）
• GraphQL = 数据库（错：GraphQL 是 API 层，背后仍是数据库）

九、关联概念

• 父概念：API · 应用程序接口、RESTful API
• 子概念：Apollo Federation、Schema、Resolver
• 兄弟概念：RESTful API、gRPC、tRPC
• 对比概念：GraphQL vs REST、GraphQL vs gRPC、GraphQL vs BFF
• 应用相关：API 网关、Microservices · 微服务、前端开发（业内默认搭配）