GraphQL 入门与实践

目标：看懂 GraphQL 的 Schema、查询和响应，理解它适合解决什么问题，以及接入 Go 服务时需要考虑的成本。

1. GraphQL 是什么

GraphQL 是面向 API 的查询语言和执行规范。服务端先定义可访问的数据类型及字段，客户端再声明本次需要哪些字段，服务端按 Schema 验证并执行请求。

它不限定数据库类型，也不让客户端直接执行数据库查询。字段的数据仍由服务端代码获取，既可以来自数据库，也可以来自其他服务。GraphQL 通常通过 HTTP 提供服务，但“所有操作必须共用一个 URL”并非语言本身的要求。

一句话理解：Schema 规定能取什么，查询声明这次取什么，Resolver 决定如何取。

2. 从一个例子看懂请求

下面是用于说明语法的示例 Schema，并非现有项目接口：

type Product {
id: ID!
name: String!
reports(first: Int = 20): [Report!]!
}

type Report {
id: ID!
fileName: String!
conclusion: String
}

type Query {
product(id: ID!): Product
}

ID! 表示该字段不能返回 null；[Report!]! 表示列表本身不能为 null，列表中的元素也不能为 null。conclusion: String 则允许没有结论时返回 null。first 是这个示例自行定义的参数，不是 GraphQL 自动提供的分页能力。

客户端可以只要商品名和前两份报告的文件名：

query ProductReports($productId: ID!) {
product(id: $productId) {
id
name
reports(first: 2) {
id
fileName
}
}
}

变量与查询分开传递：

{
"productId": "123"
}

可能得到这样的响应：

{
"data": {
"product": {
"id": "123",
"name": "示例商品",
"reports": [
{ "id": "r1", "fileName": "检测报告一.pdf" },
{ "id": "r2", "fileName": "检测报告二.pdf" }
]
}
}
}

响应的 data 形状与查询的字段选择基本对应。动态值应使用变量传递，避免把用户输入拼进查询字符串。

3. 几个核心概念

概念作用

Schema	定义类型、字段、参数和返回值，是客户端与服务端的契约。
Query	读取数据；客户端明确选择需要返回的字段。
Mutation	执行写入或其他有副作用的操作；具体写入能力仍须由服务端定义。
Subscription	订阅数据变化；实时传输方式和连接管理取决于具体实现。
Resolver	服务端为字段提供数据的逻辑，可调用现有业务服务或数据源。
Variable	在操作之外提供动态参数，便于复用、校验和记录操作。

例如，服务端定义 renameProduct(id: ID!, name: String!): Product! 后，客户端才能发起相应的 Mutation。GraphQL 不会凭空生成任意数据库写操作。

4. 与 REST 的区别

维度REST 常见做法GraphQL 常见做法

数据入口	按资源设计多个 URL，例如商品、报告各一个接口。	从 Schema 的字段进入，可在一次操作中选择关联数据。
返回字段	服务端为每个接口确定响应结构。	客户端从服务端允许的字段中选择本次响应结构。
页面数据组合	页面可能请求多个接口，也可以由专门的聚合接口返回。	一次查询可以描述页面所需的多个对象及字段。
缓存	HTTP URL 与方法通常更便于直接使用通用缓存。	需要结合查询、变量及身份设计缓存；GET 查询或持久化查询可帮助利用 HTTP 缓存。
演进	可调整资源接口或增加版本。	通常通过新增字段、标记废弃字段逐步演进 Schema。

两者可以共存。GraphQL 对多端页面的数据组合很方便，但减少 HTTP 往返不等于减少数据库查询；服务端仍要处理聚合成本、权限和缓存。

5. 一次请求怎样执行

客户端提交操作和变量
→ 解析、校验 Schema 与参数
→ 鉴权并执行字段 Resolver
→ 读取业务数据或调用其他服务
→ 组装 data，必要时附带 errors

通过 HTTP 发送时，常见形式是 POST /graphql，JSON 请求体包含 query、variables，有多个操作时还需 operationName。支持 GET 的服务只能用 GET 执行 Query，不能用它执行 Mutation。

执行期间某个字段出错时，响应可能同时含有部分 data 和 errors。因此客户端不能只看 HTTP 状态码或只判断 data 是否存在，还需要按业务要求处理 errors。

6. 主要收益与代价

适合考虑的场景：多个客户端需要同一批实体的不同字段；页面要组合多个关联对象；接口字段变化频繁，希望有统一、可发现的类型契约。

要付出的成本：

N+1 查询：列表中每个对象的子字段都单独查库，容易把一次页面请求放大成很多次数据库访问；需批量加载或在业务层集中查询。
查询成本控制：限制列表长度、嵌套深度、字段数量和请求频率；复杂查询可能给数据库或下游服务带来高负载。
字段级权限：既要确认用户能访问对象，也要确认能访问选中的敏感字段；不能只在 GraphQL 入口鉴权一次。
缓存和观测：按操作名、变量、身份与字段统计耗时和错误，并明确缓存键、过期策略及失效时机。

GraphQL 本身不会自动解决这些问题；是否采用，应比较它带来的页面组合收益与服务端治理成本。

7. 放到 Go 服务中如何评估

如果未来在 Go 服务中引入 GraphQL，可以先选一个只读、数据来源明确的页面验证价值：

列出页面实际需要的字段、身份范围和数据新鲜度，先确定 Schema 契约。

让 Resolver 调用现有 Service / Domain 能力；数据访问仍由既有 Store 负责，避免在 Resolver 里直接拼接跨库查询。

用真实页面请求测量 HTTP 次数、数据库查询次数、总耗时和响应大小，对比现有 REST 方案。

在开放列表和嵌套字段前，落实分页、权限、复杂度限制、超时及日志追踪。

这是一种选型验证路径，不表示当前项目已经接入 GraphQL。单个固定页面若已有清晰、稳定的 REST 聚合接口，未必需要额外引入 GraphQL。

8. 参考资料

GraphQL 官方简介
Schema 与类型
查询、变量与片段
GraphQL over HTTP
性能建议与安全建议
GraphQL 规范

GraphQL 入门与实践