GraphQL不是REST升级版，而是声明式数据获取新范式，通过强类型Schema和单端点查询解决过度获取、请求爆炸等问题，适合多资源聚合、字段差异大等场景，但文件上传、强缓存等仍宜用REST。
GraphQL 不是 REST 的“升级版”，而是另一种数据获取范式。它不靠替换 HTTP 方法或资源路径来工作，而是用声明式查询取代固定端点，让前端真正掌控要什么、要多少、要多深。
明确替代边界：不是全量替换，而是按需切入
GraphQL 适合替代那些存在明显痛点的 REST 场景，而不是一刀切地重写所有接口。重点关注以下几类：
- 页面需要聚合多个资源（如用户 + 订单 + 收货地址 + 最近评论），当前靠 3–5 次 REST 请求拼装
- 移动端频繁因字段冗余导致加载慢、流量高，尤其在弱网环境下
- 同一资源在不同端（H5/小程序/App）需求差异大，后端被迫维护多套相似接口
- 前端迭代快，但每次加字段都要等后端排期、发版、改文档、联调
服务端接入：从 Schema 定义开始
核心是定义强类型 Schema，它既是接口契约，也是自文档和类型校验基础。以用户+文章为例：
Schema 示例（SDL 格式）：
type User {
id: ID!
name: String!
email: String
posts(first: Int = 10): [Post!]!
}
type Post {
id: ID!
title: String!
createdAt: String!
}
type Query {
user(id: ID!): User
users: [User!]!
}
只需实现对应解析器（resolver），把字段映射到实际数据源（数据库、其他服务、缓存），无需暴露 URL 路由逻辑。
客户端迁移：用查询语句代替接口调用
不再写 GET /api/users/123 或 GET /api/users/123/posts，而是发送一个 GraphQL 请求体到统一端点（如 /graphql）：
查询示例：
query GetUserWithLatestPost($userId: ID!) {
user(id: $userId) {
name
email
posts(first: 1) {
id
title
createdAt
}
}
}
返回结果严格匹配结构，无多余字段，一次请求完成嵌套数据获取。前端可自由调整查询，无需后端配合发版。
注意保留 REST 的优势场景
GraphQL 并非万能。以下情况仍建议保留或优先使用 REST：
- 纯资源型操作（如上传文件、触发导出任务、发送短信验证码），更适合用 POST/PUT 等语义化方法
- 需要强 HTTP 缓存（CDN、浏览器缓存）的公开只读资源（如商品目录、静态配置），REST 的 URL 可缓存性更直接
- 第三方系统集成，对方只支持 REST 或 Webhook 回调机制
- 团队尚未熟悉 GraphQL 生态，或项目处于快速 MVP 阶段，REST 的简单性仍是效率保障
实践中，混合架构很常见：主业务走 GraphQL，文件上传、通知推送、支付回调等仍用 REST 接口。
