GraphQL 响应中避免字符串字段的意外转义：正确建模嵌套 JSON 数据

先聊聊一个挺常见的问题：当你在GraphQL里把一个字段声明为String，但实际想返回的是一个结构化的JSON对象时，会发生什么？大概率，你会收到一串带着反斜杠和额外引号的字符串——“双倍转义”的尴尬场景就这么出现了。

说白了，问题的症结其实很简单：类型语义对不上。你在Schema里写的是 payload: String，这在GraphQL看来就是个纯文本。所以哪怕后端Ja va代码传过来的是合法JSON字符串，比如 {"logo": "https://..."}，GraphQL执行器也只会把它当成一个普通的字符串来处理——怎么处理呢？把里面的双引号、换行符全部做JSON转义，然后外层再套一对双引号。于是前端收到的，就变成了 "{ \"logo\": \"...\" }"，一个被双重编码、没法直接点属性访问的字符串。

正确做法：让类型系统匹配数据结构

解决方案说起来也直截了当：别再用String这个模糊类型去掩盖真实的JSON结构。你应该在Schema里把数据的形状明确定义出来。比如下面这样：

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

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

相应地，你的 StringApiResponse 定义也要更新，把 payload 从String换成真正的对象类型：

type StringApiResponse {
  statusCode: String!
  message: String!
  timestamp: String!
  payload: Payload  # ← 不再是 String！
}

后端这边，Ja va代码同样需要跟上。用强类型对象来替代那个字符串payload：

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

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

// 在 Resolver 中：
@QueryMapping
public StringApiResponse getValue() {
    String rawJson = ValueService.getValue(); // 假设返回原始 JSON 字符串
    // ✅ 关键：解析为 Ja va 对象，而非保留为 String
    Payload payload = new ObjectMapper().readValue(rawJson, Payload.class);
    return StringApiResponse.builder()
        .statusCode("S0000")
        .message("Success")
        .timestamp(Instant.now().toString())
        .payload(payload) // ← 传递对象，非字符串
        .build();
}

经过这一层调整，GraphQL执行器会递归地序列化 Payload 及其嵌套结构，最终生成的是纯正的JSON对象响应。那些让人头疼的转义符，再也不会出现了：

{
  "data": {
    "getValue": {
      "payload": {
        "logo": "https://www.php.cn/link/bb859699a1e4fc28c59162684235a28c",
        "name": { "en": "AAA", "ja": "aaa" },
        "copyrightText": { "en": "AAA", "ja": "aaa" },
        "help": "http://help",
        "termsAndCondition": "http://terms"
      }
    }
  }
}

几点提醒

• 别把“字符串即JSON”当成习惯。String类型字段天生无法表达结构，如果前端每次都要先 JSON.parse() 才能用，那只不过是在用临时补丁掩盖设计缺陷，类型安全和IDE的智能提示也被一并牺牲了。
• 前端查询时，显式地选择你需要的字段。比如上面示例中的 name { en, ja }，这样做既能按需获取数据、提升性能，也让接口契约变得更加清晰、可验证。
• 如果后端数据源实在变幻莫测（比如任意JSON Schema），可以考虑自定义一个 GraphQLScalarType 来处理JSON标量。但对于大多数相对稳定的结构，强类型对象依然是更优的选择——它更安全、可验证，也更易于长期维护。

总的来说，通过精准的Schema设计与后端Ja va对象的映射，你不仅能彻底摆脱那些恼人的转义字符，还能真正构建出一套类型驱动、符合GraphQL精神的API体系。这才是正确的打开方式。