Spring GraphQL多Schema文件Query重复定义问题咨询

为什么会出现「Query类型重复定义」错误 #

GraphQL 规范要求全局根类型（Query、Mutation、Subscription）只能有一个基础定义。Spring GraphQL 会自动扫描resources/graphql目录下所有.graphql/.graphqls文件，并将它们合并为一个完整的 Schema。如果多个文件各自定义完整的type Query { ... }，就会触发重复定义冲突，导致启动失败。

正确的多Schema文件处理方式 #

要在多个文件中拆分根类型字段，必须使用 GraphQL 的类型扩展语法：在一个主文件中定义根类型的基础结构，其他文件通过extend type Query（或extend type Mutation）来添加新字段。

示例：

• 主文件base.graphql：

# 定义基础Query根类型
type Query {
    healthCheck: String
}

• 用户模块user.graphql：

# 扩展Query根类型，添加用户相关字段
extend type Query {
    getUser(id: ID!): User
    listUsers: [User]
}

type User {
    id: ID!
    name: String
    email: String
}

• 订单模块order.graphql：

# 扩展Query根类型，添加订单相关字段
extend type Query {
    getOrder(id: ID!): Order
    listOrders(userId: ID!): [Order]
}

type Order {
    id: ID!
    amount: Float
    status: String
}

这样 Spring GraphQL 合并 Schema 时，会将所有extend type Query的字段整合到同一个Query根类型中，不会出现冲突。

Spring GraphQL 的 Schema 合并核心规则 #

1. 根类型处理：Query/Mutation/Subscription只能有一个基础type定义，其他文件必须用extend扩展，不能重复定义完整根类型。
2. 普通类型处理：如果多个文件定义了同名的自定义类型（如User、Order），所有定义必须完全一致（字段名、参数、返回类型均匹配），否则会触发类型不一致错误。
3. 扫描范围：默认扫描resources/graphql及其子目录下的所有 GraphQL 文件，可通过配置spring.graphql.schema.locations或spring.graphql.schema.files调整扫描路径或指定具体文件。
4. 合并顺序：文件的加载顺序不影响最终 Schema 结构，所有合法的扩展都会被整合到对应类型中。

额外说明 #

即使拆分到多个文件，根字段对应的@SchemaMapping（或@QueryMapping）数据获取器依然可以正常工作，只要字段名与映射注解的名称匹配即可，无需关心字段定义在哪个 Schema 文件中。

内容的提问来源于stack exchange，提问作者Tomas Kloucek