GraphQL
高级通用
GraphQL 是一种让客户端按字段请求数据的 API 查询语言，服务端依据预先定义的类型和字段处理请求。它解决不同页面需要的数据不一样、固定接口可能返回过多或需要多次请求的问题；例如商品页可一次取得商品名称和卖家昵称。
你可能会说：「商品卡片和详情页要的数据不一样，能不能让前端自己指定每次取哪些字段？」
动手看看商品详情的数据查询
商品详情 · API 请求服务端类型：Product、Seller
GraphQL 查询
query ProductDetail {
product(id: "P-204") {
name
price
seller {
nickname
}
}
}
返回数据
{
"product": {
"name": "手冲咖啡壶"
"price": 168
"seller": {
"nickname": "山间器物"
}
}
}
商品字段
卖家字段
切换下方的商品字段和卖家字段，对照左右两栏：查询里写了哪些字段，返回数据就包含哪些字段。
要点GraphQL 怎样让前端按需取数据？
- 1
先约定客户端能取什么
服务端用 Schema 定义类型、字段及其关系。你能在请求里选择已开放的字段，却不能凭空读取数据库里的任意列；这样前后端能对照同一份约定开发。
- 2
请求里写出需要的字段
读取数据通常用 Query，修改数据通常用 Mutation。比如商品卡片只取名称和价格，详情页再取描述和卖家信息；响应会按请求的字段结构组织。
- 3
字段仍要由服务端实现
客户端选了字段，服务端还得负责取数、鉴权和处理错误。一次请求选中很多关联字段，也可能触发大量数据库查询，所以 GraphQL 不会自动让接口变快。
容易混淆的地方
GraphQL 和 REST API 都能给前端提供数据，区别主要在请求方式：REST 通常围绕资源端点设计响应，GraphQL 让客户端从 Schema 开放的字段中组合所需数据。它也不是 SQL：客户端描述想拿到什么，至于查数据库、调用其他服务，还是组合缓存，由服务端决定。
什么时候用
适合用
- 同一套商品数据要供卡片、详情页和后台使用，各处需要的字段不同，想减少重复接口。
- 一个页面要展示订单、商品和卖家信息，希望客户端在一次请求中明确写出所需字段。
- 网站和 App 共用后端，但展示内容持续变化，想让两端按各自需求选择已开放的数据。
不适合用
- 只有一个简单表单提交，输入和返回内容都固定，用普通 HTTP 接口通常更省事。
- 现有 REST API 已满足少量固定页面，而且没有取数或维护问题，为换技术而迁移并不划算。
- 只是想让用户实时收到订单状态变化，先考虑 WebSocket 或服务端事件；GraphQL 本身不是实时传输协议。
练一练选一个答案，看看解释
你在做商城网站和 App。商品卡片只需名称与价格，详情页还要卖家和库存。团队想减少为不同页面维护的取数接口，哪种方案最符合 GraphQL 的用法？
让 AI 帮你做复制给 AI Agent 直接用
请为商品卡片和详情页设计 GraphQL API：先列出两处各需哪些字段，再设计商品、卖家相关类型及 Query。说明字段如何取数、如何校验访问权限，并检查关联数据是否可能造成重复查询；暂不生成无关字段。