本文详解 GraphQL Mutation 中常见的变量传递错误——将输入对象的字段直接作为顶层变量传入，导致 NonNull 类型校验失败；重点说明如何根据 Schema 正确构造嵌套输入对象，并提供可运行的测试代码示例与关键注意事项。
本文详解 graphql mutation 中常见的变量传递错误——将输入对象的字段直接作为顶层变量传入，导致 `nonnull` 类型校验失败；重点说明如何根据 schema 正确构造嵌套输入对象，并提供可运行的测试代码示例与关键注意事项。
在使用 GraphQL 进行 Mutation 测试时，一个高频却隐蔽的错误是：误将输入类型（Input Type）的内部字段当作独立变量传入，而未按 Schema 要求封装为结构化对象。你的报错信息明确指出：
Variable 'documentInput' has an invalid value: ... coerced Null value for NonNull type 'DocumentInput!'
这并非服务端解析失败或 DTO 构造函数问题，而是客户端根本没有向变量 documentInput 赋值——你调用 .variable("id", 0L) 等操作，实际声明了三个无关变量 id、name、desc，但 GraphQL 执行器仍在等待名为 documentInput 的非空对象，自然返回 null。
✅ 正确做法：按 Schema 定义构造 DocumentInput 对象
首先，需查阅服务端 Schema 中 DocumentInput 的定义，典型如下：
input DocumentInput {
id: Long
name: String!
desc: String
}
这意味着 documentInput 必须是一个 JSON 对象，而非三个独立字段。因此，测试代码中应将字段嵌套进 documentInput 变量：
@Test
public void shouldCreateDocument_andReturnIt() {
// ✅ 正确：将字段封装为 documentInput 对象
Map<string object> documentInput = Map.of(
"id", 0L,
"name", "named",
"desc", "descd"
);
DocumentDto result = httpGraphQlTester.document("""
mutation createDocument($documentInput: DocumentInput!) {
createDocument(documentInput: $documentInput) {
id
name
desc
}
}
""")
.variable("documentInput", documentInput) // ← 关键：变量名必须匹配 schema 中的参数名
.execute()
.path("data.createDocument") // ← 推荐精确到字段路径，避免 data 为空时异常
.entity(DocumentDto.class)
.get();
System.out.println(result);
}</string>
? 验证技巧：在 GraphiQL 中手动测试时，也需在 Query Variables 面板输入：
{ "documentInput": { "id": 0, "name": "named", "desc": "descd" } }
⚠️ 注意事项与最佳实践
-
变量名必须严格一致：
$documentInput中的documentInput是变量标识符，.variable("documentInput", ...)的键必须完全匹配，大小写敏感； -
避免字段扁平化陷阱：GraphQL 输入类型（
input）不是“自动解包”的——它不会像 REST 的@RequestBody那样将 JSON 属性映射到参数字段，而是要求显式对象结构； - 利用 IDE 或工具生成变量模板：多数 GraphQL IDE（如 GraphQL Playground、Apollo Studio）支持从 Schema 自动补全变量结构，减少手误；
-
服务端日志辅助定位：若仍报错，开启 Spring GraphQL 的
DEBUG日志（logging.level.org.springframework.graphql=DEBUG），可查看实际接收到的variables值； -
测试健壮性建议：对
DocumentInput字段做空值/边界值测试，尤其注意String!（非空）字段缺失时会触发同类型校验错误。
掌握这一原则后，所有类似 createXxx(input: XxxInput!) 的 Mutation 测试都将清晰可控——变量名即契约，对象结构即约定，二者缺一不可。
