GraphQL vs REST 选型

没有银弹：GraphQL 解决字段组合与多端差异；REST 在资源稳定、缓存简单、团队熟悉时往往更优。 CodeRoadMap deliberately 选择 REST 作为主 API。

学习目标

• 列出 GraphQL 优势与代价
• 理解 BFF 层使用 GraphQL 的典型场景
• 能向团队解释本站为何保持 /tracks REST

核心内容

对比矩阵

维度	REST（本站）	GraphQL
学习曲线	低，HTTP 动词 + JSON	中，Schema + Resolver + 客户端
过度获取	靠 DTO 分层	客户端选字段
欠获取 / 往返	多次 GET 或聚合接口	单次嵌套 Query
CDN/HTTP 缓存	GET /tracks 易缓存	POST 为主，缓存靠客户端
文件上传	multipart 成熟	常仍走 REST 侧车
监控	路径即指标	需解析 operationName
安全面	端点固定	深度/复杂度攻击面

CodeRoadMap 选 REST 的理由

1. 资源清晰：track、lesson 与 URL /tracks/{slug}/lessons/{lessonSlug} 一一对应，SEO 与 nextjs-essentials RSC 友好
2. 只读为主：课程站点写操作少，Mutation 优势不明显
3. 栈统一：spring-boot-essentials 团队已有 @RestController、OpenAPI、JWT 模式
4. 运维简单：网关限流按路径；GraphQL 需额外复杂度预算（gql-security）
5. 数据在 MySQL：关系明确，JOIN 可预测；mongodb-essentials 文档库为可选扩展，非 GraphQL 前提

何时引入 GraphQL

• 移动 App + Web + 合作伙伴 API 字段差异大
• 微服务聚合层（BFF）减少客户端编排
• 内部 Admin 控制台动态表单、报表

可 REST + GraphQL 并存：公开读 /tracks，内部 Admin 用 /graphql——但需双倍维护 Schema 与 DTO 一致性。

与 React 数据获取

react-essentials 中 useLesson 绑 REST URL 即可；换 GraphQL 是 客户端 transport 替换，不是业务模型革命。

练习

• 为你熟悉的一个项目写 3 条「选 REST」和 2 条「可考虑 GraphQL」的理由