使用 Go 与 gqlgen 实现 GraphQL Mutation：createLink 解析器实战-平芜编程栈

【免费下载链接】howtographql

The Fullstack Tutorial for GraphQL

项目地址：https://gitcode.com/gh_mirrors/ho/howtographql

本篇文章以 How to GraphQL 仓库中 GraphQL Go 后端教程的 Mutations 章节为骨架，讲解 GraphQL Mutation 的基本概念，以及如何在 gqlgen 自动生成的schema.resolvers.go中实现createLinkmutation 解析器，并在 GraphQL playground 中完成真实的请求/响应验证。读完你将掌握 Mutation 的 schema 定义方式、gqlgen resolver 的函数签名约定、输入类型到业务对象的映射手法，以及从"内存假实现"演进到"数据库真实写入"的完整路径。

什么是 Mutation

在 GraphQL 中，Mutation（变更）与 Query（查询）在形态上几乎一致：它们都有操作名称、可以接收参数、也可以返回数据。二者唯一的本质区别在于语义约定——Mutation 用于触发数据写入（写操作），而 Query 用于读取数据（读操作）。

值得注意的是，GraphQL 规范层面并没有强制禁止在 Query 中写入数据，技术上完全可以在 Query 的 resolver 里修改数据库。但从工程规范上讲，绝不应该这样做：

客户端可以通过操作名称一眼识别出该请求是否会改变服务端状态，从而决定缓存策略与调用方式；
GraphQL 规范要求 Mutation 根字段的解析必须串行执行，而 Query 字段可以并行解析——把写操作放在 Query 中会破坏这种确定性，导致难以预期的并发副作用；
语义混乱会让 API 契约（schema）失去自解释能力，违背 GraphQL"schema 即约定"的设计初衷。

所以，凡是要新增、修改、删除数据的操作，都应该定义在Mutation类型之下。

Mutation 的 Schema 定义与代码生成

gqlgen 采用schema 驱动开发：先在schema.graphqls中声明类型与操作，再运行代码生成命令自动产出 resolver 骨架，最后开发者只需填充业务实现。在本教程的 Getting Started 章节中，我们定义了如下核心 schema（graph/schema.graphqls）：

type Link { id: ID! title: String! address: String! user: User! } type User { id: ID! name: String! } type Query { links: [Link!]! } input NewLink { title: String! address: String! } input RefreshTokenInput{ token: String! } input NewUser { username: String! password: String! } input Login { username: String! password: String! } type Mutation { createLink(input: NewLink!): Link! createUser(input: NewUser!): String! login(input: Login!): String! # we'll talk about this in authentication section refreshToken(input: RefreshTokenInput!): String! }

其中与本文直接相关的是两个声明：

input NewLink：一个输入类型，包含title与address两个必填String!字段，是客户端提交创建链接数据时使用的参数容器；
createLink(input: NewLink!): Link!：Mutation 根字段，接收一个必填的NewLink输入对象，返回一个非空Link对象。

完成 schema 定义后，运行以下命令让 gqlgen 重新生成模型与执行器代码：

go run github.com/99designs/gqlgen generate

生成的关键文件（依据 gqlgen 官方说明与本教程结构）包括：

graph/generated/generated.go—— GraphQL 执行运行时，生成代码的主体；
graph/model/models_gen.go—— 根据 schema 生成的模型，其中就包含NewLink、Link、User等类型；
graph/schema.graphqls—— schema 定义文件；
graph/schema.resolvers.go—— 应用代码所在位置，generated.go会调用这里的函数来获取客户端请求的数据；
server.go—— 最小入口，将生成的 GraphQL 服务器挂载到http.Handler上。

提示：若生成时报validation failed: packages.Load错误，通常是 gqlgen 使用了 todo 项目作为起始模板所致。可编辑graph/schema.resolvers.go，删除模板自带的CreateTodo与Todos函数后再重新运行生成命令。

实现 createLink 解析器

第一步：查看生成的函数签名

打开graph/schema.resolvers.go，找到 gqlgen 为createLink生成的 resolver 骨架：

func (r *mutationResolver) CreateLink(ctx context.Context, input model.NewLink) (*model.Link, error) {

逐项拆解这个签名：

r *mutationResolver：mutation 解析器的接收者，generated.go会把所有 Mutation 字段解析器聚合在该结构体上；
ctx context.Context：携带请求上下文（如认证后的用户信息、链路追踪数据等），后续实现鉴权时正是从这里取出当前用户；
input model.NewLink：由 schema 中input NewLink生成的输入类型，input.Title、input.Address即为客户端提交的字段值；
(*model.Link, error)：返回值约定。第一个值是对应 schema 返回类型Link!的模型对象，第二个值是错误信息，供 GraphQL 执行引擎处理错误路径。

第二步：构造 Link 对象并返回

由于本阶段尚未接入数据库（数据库将在下一节配置），我们暂时只接收NewLink数据、在内存中构造一个Link对象作为响应返回。在函数体内填入：

func (r *mutationResolver) CreateLink(ctx context.Context, input model.NewLink) (*model.Link, error) { var link model.Link var user model.User link.Address = input.Address link.Title = input.Title user.Name = "test" link.User = &user return &link, nil }

这段代码完成了两个关键动作：

输入映射：把input.NewLink中的Title、Address逐字段复制到model.Link上。schema 中Link.title与Link.address均为非空字段，因此必须先赋值才能满足返回类型约束；
关联对象构造：由于Link.user: User!也是非空字段，必须同时构造一个model.User并赋值给link.User。这里为了演示先用user.Name = "test"写死一个测试用户名——它将在后续章节被替换为从数据库查询或从认证上下文解析出的真实用户。

return &link, nil表示解析成功且无错误，gqlgen 执行引擎会按照客户端请求的字段选择集序列化该对象。

教程正文中的<Instruction>步骤块是 How to GraphQL 站点的交互式提示组件，由 Markdown.tsx 中的JsxParser将INSTRUCTION映射到 Instruction.tsx 渲染，阅读时可将其中内容视为"动手操作指令"。

运行服务器并验证 Mutation

启动服务器：

go run server.go

浏览器打开 gqlgen 自带的 GraphQL playground（默认访问http://localhost:8080/，具体端口由server.go中defaultPort决定），发送如下 mutation 请求：

mutation { createLink(input: {title: "new link", address:"http://address.org"}){ title, user{ name } address } }

观察返回结果：

{ "data": { "createLink": { "title": "new link", "user": { "name": "test" }, "address": "http://address.org" } } }

值得注意的细节：

响应中的title、address与请求输入一致，说明输入类型到Link对象的字段映射正确；
user.name返回"test"，正是 resolver 中写死的测试用户；
响应字段完全由客户端的选择集决定：即使Link类型还包含id字段，只要请求中没有选择它，响应就不会包含它——这是 GraphQL 按需取数的核心特性，也是 Mutation 与 Query 共有的行为。

从"内存假实现"到"数据库真实写入"

以上实现每次都会丢弃输入数据，仅返回一个全新构造的对象，属于典型的"假实现"。为了让createLink具备真实持久化能力，教程在数据库章节配置 MySQL 之后，于 Create and Retrieve Links 章节给出了完整演进：

第一步，在internal/links/links.go中定义数据访问层结构体与方法：

package links type Link struct { ID string Title string Address string User *users.User } func (link Link) Save() int64 { stmt, err := database.Db.Prepare("INSERT INTO Links(Title,Address) VALUES(?,?)") if err != nil { log.Fatal(err) } res, err := stmt.Exec(link.Title, link.Address) if err != nil { log.Fatal(err) } id, err := res.LastInsertId() if err != nil { log.Fatal("Error:", err.Error()) } log.Print("Row inserted!") return id }

这里Save()使用Prepare+Exec的方式插入记录：预编译语句（prepared statement）既能防御 SQL 注入，又能在多次执行相同语句时获得性能收益；LastInsertId()则返回自增主键。

第二步，改写schema.resolvers.go中的CreateLink，把内存构造替换为数据库写入：

func (r *mutationResolver) CreateLink(ctx context.Context, input model.NewLink) (*model.Link, error) { var link links.Link link.Title = input.Title link.Address = input.Address linkID := link.Save() return &model.Link{ID: strconv.FormatInt(linkID, 10), Title:link.Title, Address:link.Address}, nil }

这一步揭示了本项目的双 Link 结构体设计：links.Link是面向数据库持久化的内部模型，model.Link是 gqlgen 根据 schema 生成、面向 GraphQL 客户端的模型，二者之间通过 resolver 手动转换（数据库自增 ID 需用strconv.FormatInt(linkID, 10)转成 schema 要求的ID!字符串类型）。同理，上一章的 Links 查询从"写死的 dummy link"演进为通过links.GetAll()从数据库读取记录后逐条转换为model.Link。

此时再发送同样的 mutation，返回结果中的id将是数据库真实生成的自增主键：

{ "data": { "createLink": { "title": "something", "address": "somewhere", "id": "1" } } }

小结与下一步

通过本篇文章，我们完成了从概念到代码的完整闭环：

知识点	要点
Mutation 语义	与 Query 形态一致（有名字、有参数、有返回值），但专用于写操作
Schema 声明	在`graph/schema.graphqls`中定义`Mutation`根类型与`input`输入类型，再运行`gqlgen generate`
Resolver 签名	`CreateLink(ctx context.Context, input model.NewLink) (*model.Link, error)`，ctx 携带请求上下文
字段映射	从`input`复制数据构造`model.Link`，非空关联字段需一并构造
验证方式	`go run server.go`后在 playground 发送 mutation，响应字段由选择集决定
持久化演进	通过`internal/links/links.go`的`Save()`/`GetAll()`配合 MySQL 与 golang-migrate 实现真实读写

现在你已经掌握 Mutation 的实现套路。接下来可以继续阅读数据库配置章节了解 MySQL 与迁移脚本的搭建，再回到 Create and Retrieve Links 章节完善真实持久化，最终在认证章节中将写死的"test"用户替换为登录后的真实用户——届时ctx context.Context中携带的认证信息将派上用场。