本文详解如何通过 GraphQL Mutation 向后端安全、准确地传递 JSON 类型数据，重点解决 attributes: JSON 字段传空或解析失败的问题，涵盖 Schema 定义、客户端调用规范及常见误区。
本文详解如何通过 graphql mutation 向后端安全、准确地传递 json 类型数据，重点解决 `attributes: json` 字段传空或解析失败的问题，涵盖 schema 定义、客户端调用规范及常见误区。
在 GraphQL 中使用自定义标量（如 JSON）接收动态结构化数据（如 Map<String, String>）是常见需求，但直接在内联查询中书写嵌套对象常导致解析失败——正如问题中所示：attributes:{ Key: "Value" } 被后端识别为 null。根本原因在于 GraphQL 查询字符串本身不支持原生 JSON 对象字面量；内联写法中的 { Key: "Value" } 并非合法 GraphQL 输入值，而会被解析器忽略或报错。
✅ 正确做法是：始终通过变量（variables）传递 JSON 数据，并确保服务端 JSON 标量已正确定义与序列化逻辑。
以下为完整实践流程：
1. Schema 保持不变（前提：JSON 标量已注册）
scalar JSON
type Mutation {
createProduct(ProductRequest: ProductInput!): Product
}
input ProductInput {
id: Int
name: String
attributes: JSON # ← 依赖后端实现的 JSON 解析器
}⚠️ 注意：JSON 不是 GraphQL 内置类型，需在服务端（如 Java 的 GraphQL Java、Node.js 的 graphql-scalars）显式注册 JSON 标量，并实现 coerceInput（解析入参）和 coerceOutput（序列化返回）逻辑。
2. 客户端调用必须使用变量（推荐 Apollo Client 示例）
import { gql } from '@apollo/client';
const CREATE_PRODUCT_MUTATION = gql`
mutation CreateProduct($productRequest: ProductInput!) {
createProduct(ProductRequest: $productRequest) {
id
name
attributes
}
}
`;
// ✅ 正确：JavaScript 对象直接作为变量传入（Apollo 自动序列化为 JSON）
const productRequest = {
id: 1,
name: "ABC",
attributes: {
brand: "Nike",
color: "Black",
tags: ["sport", "casual"]
}
};
client.mutate({
mutation: CREATE_PRODUCT_MUTATION,
variables: { productRequest } // ← 关键：JSON 数据走 variables
}).then(result => {
console.log("创建成功:", result.data.createProduct);
}).catch(error => {
console.error("请求失败:", error.message);
});3. ❌ 错误示范（避免内联 JSON）
# 错误！GraphQL 规范不支持在 query 字符串中直接写 { key: "value" }
mutation {
createProduct(ProductRequest: {
id: 1,
name: "ABC",
attributes: { brand: "Nike" } # ← 解析失败，attributes 为 null
}) { ... }
}即使某些客户端（如 GraphiQL）看似“能运行”，实际发送的仍是非法 AST，服务端无法可靠解析。
4. 后端关键检查点（以 Java Spring GraphQL 为例）
- 确保 GraphQLScalarType 的 coerceInput(Object input) 方法能处理 LinkedHashMap 或 JsonNode；
- 若使用 graphql-java，推荐集成 graphql-java-extended-scalars 并注册 ExtendedScalars.Json；
- 数据库存储时，将 attributes 字段映射为 String（JSON 字符串）或数据库原生 JSON 类型（如 PostgreSQL jsonb）。
总结
| 场景 | 是否可行 | 说明 |
|---|---|---|
| 使用 variables 传 JS 对象 | ✅ 推荐 | Apollo/Relay 等客户端自动序列化为标准 JSON 字符串 |
| 内联写 { key: "val" } | ❌ 禁止 | 违反 GraphQL 语法，解析器无法识别为有效值 |
| 传 JSON 字符串（如 '{"key":"val"}'） | ⚠️ 可行但冗余 | 需手动 JSON.parse()，易出错，不推荐 |
只要坚持「标量声明 + 变量传参」模式，并验证后端标量解析逻辑，JSON 字段即可稳定传递至数据库。
