Spring Boot GraphQL仅含Mutation时Schema报错及解决方案咨询

错误信息 #

Caused by: graphql.schema.idl.errors.SchemaProblem: errors=[A schema MUST have a 'query' operation defined]

为什么必须定义Query？ #

GraphQL官方规范明确要求：一个合法的Schema必须包含至少一个根操作类型，而Query是默认的必填根类型。这是因为Query是GraphQL的核心操作范式之一，规范以此保证Schema的结构完整性——哪怕你当前业务完全不需要查询功能，Schema层面也得满足这个语法要求，否则会被校验器判定为不合法。

推荐解决方案 #

方案一：定义空Query类型 #

这是最简单直接的方式，只需要在Schema中添加一个没有任何字段的Query类型，就能通过合法性校验，后续需要查询功能时再补充字段即可。

修改后的完整Schema：

type Query {
  # 空Query，仅满足Schema合法性要求
}

type Mutation {
 sendMessage(message: String!, routingKey: String!): String!
 sendMessageWithDTO(msgDTO: MsgDTOInput!, routingKey: String!): String!
 sendMessageWithTTL(msgDTO: MsgDTOInput!, routingKey: String!, expire: Int!): String!
 sendToNormalExchange(msgDTO: MsgDTOInput!, routingKey: String!): String!
 sendWithDelay(msgDTO: MsgDTOInput!, routingKey: String!, delay: Int!): String!
}

input MsgDTOInput {
  message: String!
}

方案二：添加占位字段的Query类型 #

如果觉得空Query不够直观，可以加一个无业务意义的占位字段，比如简单的健康检查字段，实际业务中无需调用它，后续扩展查询功能时直接在Query类型下添加新字段即可。

示例：

type Query {
  healthCheck: Boolean! # 占位字段，仅用于通过Schema校验
}

type Mutation {
 sendMessage(message: String!, routingKey: String!): String!
 sendMessageWithDTO(msgDTO: MsgDTOInput!, routingKey: String!): String!
 sendMessageWithTTL(msgDTO: MsgDTOInput!, routingKey: String!, expire: Int!): String!
 sendToNormalExchange(msgDTO: MsgDTOInput!, routingKey: String!): String!
 sendWithDelay(msgDTO: MsgDTOInput!, routingKey: String!, delay: Int!): String!
}

input MsgDTOInput {
  message: String!
}

方案三：自定义Schema构建逻辑（不推荐） #

如果使用Spring Boot GraphQL Starter，也可以通过自定义配置类绕过默认的Query校验，但这种方式会破坏规范的一致性，增加后续维护成本，仅适合有特殊需求的场景，一般前两种方案完全够用。

内容的提问来源于stack exchange，提问作者Thilak Sparrow