How to GraphQL 实战:使用 graphql-java 从零搭建 Java GraphQL 服务器
How to GraphQL 实战:使用 graphql-java 从零搭建 Java GraphQL 服务器
本篇指南是 How to GraphQL 开源教程中 Java 后端路线的入门章节,完整讲解如何用 Maven 初始化一个 Web 项目、以 Schema Definition Language(SDL)定义 GraphQL schema、引入 graphql-java 系列依赖,并通过 Jetty 插件与一个继承 SimpleGraphQLServlet 的端点类把 GraphQL 服务器跑起来。读完本文,你将能亲手启动一个监听 8080 端口的 GraphQL 服务,并理解"schema 即运行时对象"这一 graphql-java 的核心设计,为后续实现查询解析器(resolver)与变更(mutation)打下基础。
前置准备:Maven 与项目初始化
本教程全程使用 Maven 作为构建工具——它至今仍是 Java 生态中使用最广泛的构建工具。开始之前,请确保本机安装了一个版本足够新的 Maven。
使用 Maven 的 archetype 插件可以快速生成一个最小可用的 Web 应用骨架。在终端中执行以下命令(遇到提示时输入 Y 确认):
mvn archetype:generate -DarchetypeArtifactId=maven-archetype-webapp -DgroupId=com.howtographql.sample -DartifactId=hackernews-graphql-java -Dversion=1.0-SNAPSHOT
几个关键参数的含义:
-DarchetypeArtifactId=maven-archetype-webapp:选用标准的 Maven Web 应用骨架,它会生成pom.xml、src/main/webapp等基本结构;-DgroupId=com.howtographql.sample:项目的组织标识(groupId),后续所有 Java 包的根命名空间都基于它;-DartifactId=hackernews-graphql-java:项目标识(artifactId),同时也是生成目录的名称;-Dversion=1.0-SNAPSHOT:项目版本号,SNAPSHOT表示开发中的快照版本。
搭建项目结构
生成骨架之后,需要立即调整目录结构,为 Servlet 3.x 风格的配置腾出空间:
- 在
src/main下新建一个名为java的目录,所有 Java 源码都将放在这里; - 删除
src/main/webapp下的WEB-INF/web.xml(或者干脆删除整个WEB-INF目录)。
为什么必须删除 web.xml? 因为后续我们会使用 Servlet 3.x 的注解式配置(@WebServlet)来注册端点,不再依赖传统的 XML 描述符。如果 web.xml 仍然存在,容器会优先采用描述符驱动模式,导致注解被忽略,服务器起来后访问 /graphql 只会得到 404。
理解 schema:既是文档,也是运行时对象
在动手写 schema 之前,必须先建立一个重要的认知:在 GraphQL 中,resolver(解析函数)是字段定义不可分割的一部分,因此 schema 并不是一份纯文档,而是一个运行时对象实例——在本教程的语境下,就是一个 Java 对象。它由 graphql-java 在启动时构建,查询执行时所有字段的取值都依赖它。
schema 有两种定义方式:
- 程序化定义(programmatically):在代码中手工组装各个类型定义;
- 使用 Schema Definition Language(SDL)定义:用一段语言无关的文本描述(也就是前几章看到的那些
type、schema写法),schema 从文本生成后,再把 resolver 函数动态地接驳上去。
两种方式各有优劣,最终取决于个人偏好:前者把字段与对应的 resolver 放在一起(代码即 schema),后者则在"数据"与"行为"之间划出清晰界限。本路线大部分章节采用 SDL,因为它能写出更简洁的示例,也更贴合 GraphQL 社区推崇的 schema-first(契约优先) 开发模式。
关于 schema-first 的深层动机,可以回顾本路线开篇章节的论述:GraphQL 把"取哪些数据"的决定权完全交给客户端,配合 introspection(自省查询)机制,schema 天然就是客户端与服务器之间的中心契约,同时它天然地推动开发者把逻辑拆分成更小、更单一职责的函数来充当 resolver——这正是 Java 静态类型系统下一种非常自然的开发风格。
定义 schema:写出第一个 schema.graphqls
本教程示例项目的核心是一个 Hackernews 克隆(即教程仓库 meta/structure/java.md 中描述的 HN 示例),第一个领域类型是"链接"(Link)。
先定义表示一条链接的简单类型:
type Link {
url: String!
description: String!
}
注意 String! 中的感叹号表示非空(non-null):任何返回 Link 的查询,其 url 和 description 字段都必须有值,否则会触发执行错误。
再定义查询根类型,用于获取全部链接:
type Query {
allLinks: [Link]
}
[Link] 表示一个 Link 列表。最后把这些串起来,定义 schema 入口:
schema {
query: Query
}
将以上三段定义保存到 src/main/resources/schema.graphqls 文件中。graphql-java-tools 的 SchemaParser 会在运行时读取这个文件并据此构建可执行的 schema。
安装依赖:pom.xml 中的四个关键库
构建一个 GraphQL 应用,严格来说只需要 graphql-java(GraphQL 实现本身)。但为了让动态 resolver 接驳更省力、并把 API 暴露到 Web 上,教程还引入了另外三个库。把它们全部添加到 pom.xml 的 <dependencies> 节点下:
<dependency>
<groupId>com.graphql-java</groupId>
<artifactId>graphql-java</artifactId>
<version>3.0.0</version>
</dependency>
<dependency>
<groupId>com.graphql-java</groupId>
<artifactId>graphql-java-tools</artifactId>
<version>3.2.0</version>
</dependency>
<dependency>
<groupId>com.graphql-java</groupId>
<artifactId>graphql-java-servlet</artifactId>
<version>4.0.0</version>
</dependency>
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>javax.servlet-api</artifactId>
<version>3.0.1</version>
<scope>provided</scope>
</dependency>
四个依赖各司其职:
graphql-java:GraphQL 规范在 Java 上的核心实现,负责 schema 的解析、校验与查询执行;graphql-java-tools:灵感来自 Apollo 的graphql-tools,它基于 SDL 文件 + 普通 Java 类自动"接驳"resolver,免去大量样板代码;graphql-java-servlet:一个开箱即用的辅助库,内含现成的 Servlet(SimpleGraphQLServlet),用来接收 HTTP 上的 GraphQL 查询请求;javax.servlet-api:Servlet 规范实现,<scope>provided</scope>表示它由运行时的 Servlet 容器提供,不打包进最终产物。
版本提醒:以上版本是撰写教程时各库的最新版本,但 Java 生态的库更新非常快(bug 修复、新特性不断发布),后续章节使用的 API 可能随版本演进而变化。动手前务必到各库的发布页确认是否有更新的稳定版本,并以实际引入的版本为准。
配置服务器:Jetty 插件与编译选项
任何 Servlet 容器都能胜任运行这个应用,开发期最简单的做法是通过 Maven 插件内嵌一个容器。这里选用 Jetty,在 pom.xml 的 <build> 节点下添加:
<build>
<finalName>hackernews</finalName>
<plugins>
<plugin>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-maven-plugin</artifactId>
<version>9.4.6.v20170531</version>
</plugin>
</plugins>
</build>
<finalName>hackernews</finalName> 决定最终构建产物的名字(war 包将叫 hackernews.war)。
趁此机会一并配置两个基础项(放在 Jetty 插件下方):把 Java 编译级别设为 8,并把 Servlet 规范版本对齐到 3.1:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.5.1</version>
<configuration>
<source>1.8</source>
<target>1.8</target>
</configuration>
</plugin>
<plugin>
<artifactId>maven-war-plugin</artifactId>
<version>3.1.0</version>
</plugin>
maven-compiler-plugin的<source>/<target>均设为1.8,确保代码以 Java 8 语法编译并产出兼容 Java 8 的字节码(注意graphql-java 3.x系列对 JDK 版本有要求,此处按教程原配置执行即可);maven-war-plugin负责把 Web 应用打成 war 包,版本3.1.0与 Servlet 3.1 配置相匹配。
配置完成后,在 pom.xml 所在目录执行一条命令即可启动应用:
mvn jetty:run
Jetty 会默认监听 8080 端口。
创建端点:GraphQLEndpoint Servlet
此时打开 http://localhost:8080 还看不到任何东西——服务器还没有被配置成"做"任何事。要补救这一点,需要创建一个名为 GraphQLEndpoint 的类,它将作为暴露 API 的 Servlet。
教程示例项目的所有类都放在 com.howtographql.hackernews 包下,建议在 src/main/java 下同步创建这个包。GraphQLEndpoint 的代码如下:
import com.coxautodev.graphql.tools.SchemaParser;
import javax.servlet.annotation.WebServlet;
import graphql.servlet.SimpleGraphQLServlet;
@WebServlet(urlPatterns = "/graphql")
public class GraphQLEndpoint extends SimpleGraphQLServlet {
public GraphQLEndpoint() {
super(SchemaParser.newParser()
.file("schema.graphqls") //parse the schema file created earlier
.build()
.makeExecutableSchema());
}
}
逐行拆解这个类的职责:
@WebServlet(urlPatterns = "/graphql"):Servlet 3.x 注解,把该 Servlet 注册到/graphql路径,这正是之前删除web.xml的原因所在;extends SimpleGraphQLServlet:复用graphql-java-servlet提供的现成 Servlet,它已经处理好了 HTTP 请求到 GraphQL 执行的转换;- 构造函数中,
SchemaParser.newParser().file("schema.graphqls")读取前面创建的 schema 文件,.build().makeExecutableSchema()将其编译成可执行的GraphQLSchema并传给父类。
此刻的预期状态:还没有 resolver
启动服务器后访问 http://localhost:8080/graphql,仍然会得到一个错误——因为到目前为止还没有任何 resolver 函数被接驳进来,schema 里定义的 allLinks 查询无从执行。
这其实是本教程刻意设计的节奏:schema 只描述了"有什么数据、长什么样",而"数据从哪来"由下一章的 resolver 负责。接下来你将按照 2-queries.md 的指引:
- 创建
LinkPOJO(纯数据类)与LinkRepository(内存仓储); - 创建实现
GraphQLRootResolver的Query类,提供allLinks()方法; - 在
GraphQLEndpoint.buildSchema()中通过.resolvers(new Query(linkRepository))把 resolver 注册进 schema。
完成注册后,打开 http://localhost:8080/graphql?query={allLinks{url}} 就能看到第一批真实的查询结果,之后还可以在 3-mutations.md 中给 schema 增加 mutation 根类型,通过 createLink 实现写操作。
小结
至此,你已经完成了 graphql-java 服务器的全部"脚手架"工作,回顾一下本阶段的关键产出:
- 用
maven-archetype-webapp初始化了hackernews-graphql-java项目,并调整了src/main/java与src/main/webapp的结构; - 理解并实践了 SDL 方式的 schema 定义(
Link、Query、schema三段式),明确 schema 是运行时对象而非纯文档; - 在
pom.xml中引入了graphql-java、graphql-java-tools、graphql-java-servlet与javax.servlet-api四个依赖,并配置了 Jetty、编译器与 war 插件; - 通过
@WebServlet注解 +SimpleGraphQLServlet子类创建了GraphQLEndpoint,mvn jetty:run即可在 8080 端口启动服务。
这个最小骨架正是 12-summary.md 中回顾的"Schema、Resolvers、Models、Connectors"四大组成部分的前两环。下一章补齐 resolver 后,你的 Java GraphQL 服务器就能真正响应查询了。