GraphQL 中正确处理嵌套 JSON 字段

在 GraphQL 中，将本应结构化的嵌套 JSON 数据错误地定义为 String 类型，会导致数据被双重转义、变成难以直接使用的字符串；本文直击这一常见痛点，揭示通过语义化建模——将 payload 等字段升级为自定义对象类型（如 Payload、LanguageSpecificContent），配合后端强类型解析与精准客户端查询——即可让 GraphQL 原生输出纯净、可解构、类型安全的嵌套 JSON 对象，彻底告别手动 parse 和转义陷阱，大幅提升 API 的健壮性、可维护性与前后端协作效率。

当 GraphQL 字段类型为 String 但实际需返回结构化 JSON 数据时，GraphQL 会将整个对象序列化为带转义的字符串；解决方法是将该字段改为自定义对象类型，让 GraphQL 引擎原生处理嵌套结构，从而输出纯净、可直接使用的 JSON 对象。

当 GraphQL 字段类型为 `String` 但实际需返回结构化 JSON 数据时，GraphQL 会将整个对象序列化为带转义的字符串；解决方法是将该字段改为自定义对象类型，让 GraphQL 引擎原生处理嵌套结构，从而输出纯净、可直接使用的 JSON 对象。

在 GraphQL 中，字段类型决定其序列化行为。你当前的 schema 将 payload 定义为 String：

type StringApiResponse {
  statusCode: String!
  message: String!
  timestamp: String!
  payload: String  # ← 关键问题：String 类型强制整个值作为字符串字面量输出
}

当你在 Java 端传入一个已格式化的 JSON 字符串（如 "{\"logo\":\"http://logo\",...}"），GraphQL 执行器会将其视为纯文本——为确保 JSON 合法性，它会对内部引号、反斜杠等进行二次转义，最终返回一个被双引号包裹、所有特殊字符均已转义的字符串。这正是你看到 \"logo\": \"http://logo\" 的根本原因。

✅ 正确做法是语义化建模：将 payload 从 String 升级为结构化对象类型，使 GraphQL 知道它应是一个复合数据节点，而非原始字符串。

以下是推荐的 schema 改写方案：

type Query {
  getValue: StringApiResponse
}

type StringApiResponse {
  statusCode: String!
  message: String!
  timestamp: String!
  payload: Payload  # ← 改为自定义对象类型
}

type Payload {
  logo: String!
  name: LanguageSpecificContent!
  copyrightText: LanguageSpecificContent!
  help: String!
  termsAndCondition: String!
}

type LanguageSpecificContent {
  en: String!
  ja: String!
}

对应 Java 端，需定义强类型的响应类（以 Spring for GraphQL 为例）：

public record Payload(
    String logo,
    LanguageSpecificContent name,
    LanguageSpecificContent copyrightText,
    String help,
    String termsAndCondition
) {}

public record LanguageSpecificContent(String en, String ja) {}

public record StringApiResponse(
    String statusCode,
    String message,
    String timestamp,
    Payload payload  // ← 不再是 String，而是 Payload 对象
) {}

@QueryMapping
public StringApiResponse getValue() {
    String rawJson = ValueService.getValue(); // 假设返回的是原始 JSON 字符串
    // ✅ 关键：解析为 Java 对象，而非透传字符串
    Payload payload = JsonMapper.builder().build()
        .readValue(rawJson, Payload.class);

    return new StringApiResponse(
        "S0000",
        "Success",
        Instant.now().toString(),
        payload
    );
}

这样，客户端发起精准查询时：

{
  getValue {
    payload {
      logo
      name { en ja }
      copyrightText { en ja }
      help
      termsAndCondition
    }
  }
}

将获得无转义、可直接解构的原生 JSON 对象：

{
  "data": {
    "getValue": {
      "payload": {
        "logo": "http://logo",
        "name": { "en": "AAA", "ja": "aaa" },
        "copyrightText": { "en": "AAA", "ja": "aaa" },
        "help": "http://help",
        "termsAndCondition": "http://terms"
      }
    }
  }
}

⚠️ 注意事项：

• ❌ 避免“字符串透传 + 前端 JSON.parse()”的反模式：既破坏类型安全，又增加前端解析负担与错误风险；
• ✅ 若后端无法预知 payload 结构（动态 Schema），可考虑使用 GraphQLScalarType 自定义 JSON 标量（如 graphql-java 的 GraphQLJSON），但需配套序列化逻辑；
• ? 所有字段建议标注 !（非空）以强化契约，避免运行时 null 值引发意外转义或解析失败。

通过类型驱动的设计，你不仅消除了恼人的转义字符，更提升了 API 的可读性、可测试性与前端开发体验。

以上就是本文的全部内容了，是否有顺利帮助你解决问题？若是能给你带来学习上的帮助，请大家多多支持golang学习网！更多关于文章的相关知识，也可关注golang学习网公众号。