GraphQL自发布以来，已经成为前端与后端数据交互的一种重要选择。它的核心思想是允许客户端精确指定需要的字段，服务端只返回这些字段，不再出现REST接口常见的过度获取或获取不足的问题。Spring Boot从2.7版本开始提供了spring-boot-starter-graphql依赖，让Java开发者无需手动拼接大量GraphQL Java代码就能快速集成。本文将通过一个完整的示例，演示从零开始搭建Spring Boot GraphQL服务。
一、创建项目并添加GraphQL依赖
要使用GraphQL，首先需要在Spring Boot项目中引入对应的starter依赖。如果使用Maven构建，可以在pom.xml中加入以下内容。这里除了GraphQL的starter外，还需要保留Spring Web依赖，因为GraphQL端点默认通过HTTP暴露。
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-graphql</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
如果使用Gradle，可以在build.gradle中添加implementation 'org.springframework.boot:spring-boot-starter-graphql'以及对应的Web依赖。Spring Boot的GraphQL自动配置会扫描classpath下的schema文件，并注册默认的GraphQlSource和GraphQlService，因此只要依赖到位，基础环境就已经就绪。
需要注意的是，spring-boot-starter-graphql本身基于GraphQL Java引擎，它并不绑定特定的传输层。当项目中同时存在spring-boot-starter-web时，Spring Boot会自动暴露/graphql端点，接收POST请求。后续章节会演示如何通过该端点进行查询。
二、编写GraphQL Schema文件
GraphQL强依赖于类型系统，服务端的Schema是前后端之间的契约。Spring Boot默认会从classpath:graphql/目录下加载扩展名为.graphqls或.gql的文件。我们可以在该目录下创建一个schema.graphqls文件，定义数据模型和操作类型。
type Book {
id: ID!
title: String!
author: String!
price: Float
}
type Query {
bookById(id: ID!): Book
allBooks: [Book]
}
type Mutation {
addBook(title: String!, author: String!, price: Float): Book
}
上面的Schema定义了一个Book对象类型，其中ID!表示非空标识，String!表示非空字符串，Float表示可选的浮点数。在GraphQL中，字段后面的感叹号表示该字段不能为null。查询类型Query包含两个操作：根据ID查找书籍和获取全部书籍。修改类型Mutation定义了一个新增书籍的操作，它接收三个参数并返回新创建的Book对象。
GraphQL Schema中的类型名称和字段名称会与Java类及方法进行映射。Spring GraphQL默认使用基于名称的匹配规则，如果Java类的属性名与Schema字段相同，就可以自动完成映射，无需额外的注解。这种约定大于配置的方式可以显著减少样板代码。
三、创建数据模型与Controller
接下来创建Java数据模型。为了简化示例，这里使用一个普通的POJO类来表示Book，并生成对应的构造方法、getter和setter。
public class Book {
private Long id;
private String title;
private String author;
private Double price;
public Book(Long id, String title, String author, Double price) {
this.id = id;
this.title = title;
this.author = author;
this.price = price;
}
// 省略getter和setter方法
}
Spring GraphQL的控制器并不需要实现特定接口，只需要在类上标注@Controller，然后在方法上使用@QueryMapping或@MutationMapping即可。方法名需要与Schema中定义的字段名保持一致，参数通过@Argument注解绑定。
import org.springframework.graphql.data.method.annotation.Argument;
import org.springframework.graphql.data.method.annotation.MutationMapping;
import org.springframework.graphql.data.method.annotation.QueryMapping;
import org.springframework.stereotype.Controller;
import java.util.ArrayList;
import java.util.List;
@Controller
public class BookController {
private final List<Book> books = new ArrayList<>();
@QueryMapping
public Book bookById(@Argument Long id) {
return books.stream()
.filter(book -> book.getId().equals(id))
.findFirst()
.orElse(null);
}
@QueryMapping
public List<Book> allBooks() {
return books;
}
@MutationMapping
public Book addBook(@Argument String title, @Argument String author, @Argument Double price) {
Book book = new Book((long) (books.size() + 1), title, author, price);
books.add(book);
return book;
}
}
在上面的控制器中，@QueryMapping标记的方法会处理GraphQL的查询操作，@MutationMapping则处理修改操作。当GraphQL请求包含allBooks字段时，框架会自动调用allBooks()方法并返回书籍列表。参数id通过@Argument Long id从GraphQL请求的变量中提取，类型转换由Spring完成。
这种编程模型让熟悉Spring MVC的开发者可以快速上手。相比REST控制器中需要自己解析请求参数、处理响应状态码，GraphQL控制器只需关注业务数据本身的返回，序列化与字段过滤都交给框架处理。
四、启动应用并测试GraphQL接口
启动Spring Boot应用后，默认的GraphQL端点位于http://localhost:8080/graphql。可以通过GraphiQL可视化界面进行调试，也可以在application.yml中开启GraphiQL。
spring:
graphql:
graphiql:
enabled: true
开启后，访问http://localhost:8080/graphiql即可在浏览器中编写并执行GraphQL查询。如果想要使用命令行测试，可以发送如下curl请求进行查询。
curl -X POST http://localhost:8080/graphql \
-H "Content-Type: application/json" \
-d '{"query":"{ allBooks { id title author } }"}'
对于新增操作，可以发送包含Mutation的请求。下面的curl命令演示了如何新增一本书，并指定返回新书的id和title字段。
curl -X POST http://localhost:8080/graphql \
-H "Content-Type: application/json" \
-d '{"query":"mutation { addBook(title: \"GraphQL入门\", author: \"李四\", price: 59.9) { id title } }"}'
在GraphQL中，客户端可以精确指定返回的字段。上面新增操作只返回id和title，即使Book对象还包含author和price，服务端也不会将它们放入响应。这种按需取用的能力可以降低网络传输量，提升移动端等弱网环境下的体验。
五、与REST对比及常见问题处理
与REST相比，GraphQL最大的优势在于前端可以一次请求获取多个资源。例如一个页面需要展示书籍列表以及每本书的作者详情，在REST下通常需要先调用书籍接口，再根据返回的ID逐个请求作者接口。而GraphQL可以直接在一个查询中嵌套作者字段，服务端通过数据加载器一次性或批量完成数据获取。
不过GraphQL也带来了新的复杂性。最常见的挑战是N+1查询问题：当Schema中存在嵌套关联时，如果简单地在Controller中逐条访问数据库，就会产生大量SQL查询。Spring GraphQL通过DataLoader机制提供批处理支持，开发者可以自定义BatchLoader将多次加载合并为一次批量查询，从而显著降低数据库压力。
另一个需要注意的细节是异常处理。GraphQL默认会将未捕获异常包装为通用错误信息返回给客户端，可能丢失具体堆栈信息。在生产环境中建议实现GraphQLError或使用DataFetcherExceptionHandler定制错误结构，避免暴露内部实现细节。同时，对于分页查询，可以在Schema中定义连接类型或使用Page对象映射，让客户端通过first和after参数控制数据量。
通过本文的示例可以看到，Spring Boot整合GraphQL并不复杂。只要添加依赖、编写Schema文件、创建控制器，就能搭建一个可运行的GraphQL服务。后续可以根据实际项目需求逐步引入权限控制、缓存、批量加载等高级特性，让接口层更加灵活高效。
Spring BootGraphQLSpring Boot GraphQL修改时间：2026-08-26 20:19:25