GraphQL Java怎么集成？

本文目录导读：

1. Spring Boot 集成（最常用）
2. 非 Spring 环境集成
3. 客户端集成
4. 完整项目结构建议
5. 注意事项
6. 快速启动示例（全部代码）

GraphQL Java 的集成主要分为：Spring Boot 集成、非 Spring 环境集成 和 客户端集成 三种场景,以下是常用的集成方式和步骤：

---

Spring Boot 集成（最常用）

使用 graphql-spring-boot-starter 可以快速在 Spring Boot 中搭建 GraphQL 服务。

引入依赖

<!-- Maven -->
<dependency>
    <groupId>com.graphql-java</groupId>
    <artifactId>graphql-spring-boot-starter</artifactId>
    <version>5.0.2</version>
</dependency>
<!-- 或者使用最新版 graphql-java-kickstart -->
<dependency>
    <groupId>com.graphql-java-kickstart</groupId>
    <artifactId>graphql-spring-boot-starter</artifactId>
    <version>15.0.0</version>
</dependency>

编写 Schema 文件

在 src/main/resources/ 下创建 schema.graphqls：

type Query {
    hello(name: String): String
    user(id: ID): User
}
type User {
    id: ID
    name: String
    age: Int
}

实现数据获取逻辑（DataFetcher 或 Resolver）

@Component
public class GraphQLDataFetchers {
    public DataFetcher<String> hello() {
        return environment -> {
            String name = environment.getArgument("name");
            return "Hello, " + (name != null ? name : "World");
        };
    }
    public DataFetcher<User> user() {
        return environment -> {
            String id = environment.getArgument("id");
            // 模拟从数据库查询
            return new User(id, "张三", 25);
        };
    }
}

配置 GraphQL Bean

@Configuration
public class GraphQLConfig {
    @Autowired
    GraphQLDataFetchers fetchers;
    @Bean
    public GraphQL graphQL() throws IOException {
        // 加载 schema 文件
        Resource schemaResource = new ClassPathResource("schema.graphqls");
        String sdl = IOUtils.toString(schemaResource.getInputStream(), StandardCharsets.UTF_8);
        // 解析 schema
        TypeDefinitionRegistry typeRegistry = new SchemaParser().parse(sdl);
        // 注册 DataFetcher
        RuntimeWiring wiring = RuntimeWiring.newRuntimeWiring()
            .type("Query", typeWiring -> typeWiring
                .dataFetcher("hello", fetchers.hello())
                .dataFetcher("user", fetchers.user()))
            .build();
        // 生成可执行的 Schema
        SchemaGenerator generator = new SchemaGenerator();
        GraphQLSchema graphQLSchema = generator.makeExecutableSchema(typeRegistry, wiring);
        return GraphQL.newGraphQL(graphQLSchema).build();
    }
}

编写 Controller（可选，starter 会自动生成端点）

默认端点：POST /graphql

@RestController
public class GraphQLController {
    @Autowired
    private GraphQL graphQL;
    @PostMapping("/graphql")
    public ResponseEntity<Object> query(@RequestBody String query) {
        ExecutionResult result = graphQL.execute(query);
        return ResponseEntity.ok(result.getData());
    }
}

---

非 Spring 环境集成

如果不用 Spring,可以手动构建：

public class GraphQLServer {
    public static void main(String[] args) throws Exception {
        // 1. 加载 schema
        String schema = "type Query { hello: String }";
        // 2. 解析
        SchemaParser parser = new SchemaParser();
        TypeDefinitionRegistry typeRegistry = parser.parse(schema);
        // 3. 绑定 DataFetcher
        RuntimeWiring wiring = RuntimeWiring.newRuntimeWiring()
            .type("Query", builder -> builder
                .dataFetcher("hello", env -> "Hello, world!"))
            .build();
        // 4. 生成可执行 schema
        SchemaGenerator generator = new SchemaGenerator();
        GraphQLSchema graphQLSchema = generator.makeExecutableSchema(typeRegistry, wiring);
        // 5. 创建 GraphQL 实例
        GraphQL graphQL = GraphQL.newGraphQL(graphQLSchema).build();
        // 6. 执行查询
        String query = "{ hello }";
        ExecutionResult result = graphQL.execute(query);
        System.out.println(result.getData().toString());
    }
}

---

客户端集成

调用 GraphQL API（类似 HTTP 请求）：

// 使用 RestTemplate 或 WebClient
String query = "{\"query\":\"{ hello(name: \\\"Tom\\\") }\"}";
RestTemplate restTemplate = new RestTemplate();
String response = restTemplate.postForObject(
    "http://localhost:8080/graphql",
    query,
    String.class
);
System.out.println(response);

如果需要更完善的客户端，可以使用 graphql-java-kickstart 提供的 GraphQLClient：

// 需要额外引入
<dependency>
    <groupId>com.graphql-java-kickstart</groupId>
    <artifactId>graphql-java-client</artifactId>
    <version>15.0.0</version>
</dependency>

---

完整项目结构建议

src/main/java/com/example/
├── config/
│   └── GraphQLConfig.java       # GraphQL Bean 配置
├── resolver/
│   ├── QueryResolver.java       # Query 类型的 DataFetcher
│   └── MutationResolver.java    # Mutation 类型的 DataFetcher
├── model/
│   └── User.java                # POJO 对象
├── service/
│   └── UserService.java         # 业务逻辑层
└── controller/
    └── GraphQLController.java   # API 端点（非必需）
src/main/resources/
└── schema.graphqls              # Schema 定义

---

注意事项

1. 多 Schema 文件：使用 SchemaParser 的 parse 方法合并多个文件
2. 错误处理：实现 DataFetcherExceptionHandler 处理异常
3. 性能优化：
   • 使用 BatchLoader 或 DataLoader 解决 N+1 查询问题
   • 开启 graphql.servlet.cors-enabled 配置跨域
4. 版本兼容：Spring Boot 2.x 建议使用 graphql-kickstart-spring-boot-starter，Spring Boot 3.x 需要适配

---

快速启动示例（全部代码）

// 1. pom.xml 引入 spring-boot-starter-web 和 graphql-spring-boot-starter
// 2. 创建 schema.graphqls
// 3. 启动类
@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}
// 4. 启动后访问 http://localhost:8080/graphiql 可以看到可视化工具（默认集成）

这样即可完成 GraphQL Java 的基本集成，如果需要更复杂的场景（订阅、联邦、安全拦截等），可进一步使用 GraphQL-Java 的高级特性。