企业官网建设流程全解析

本篇指南基于 HowToGraphQL 开源仓库中的 graphql-java 教程 · 连接器章节 展开，讲解如何为基于graphql-java+graphql-java-tools+ Jetty 的 Java GraphQL 服务器接入 MongoDB 作为持久化存储，并深入剖析由此引出的 N+1 查询问题及DataLoader/BatchedExecutionStrategy等批处理解决方案。读完本文，你将掌握：为现有 GraphQL 类型平滑扩展字段、用 MongoDB Java Driver 重写仓储层、在 Servlet 端点中装配数据库连接，以及识别与规避 resolver 级联查询的性能陷阱。

无论你的 GraphQL API 设计得多么精妙，只要它无法与其他系统（数据库、第三方 API 等）对话，其价值就十分有限。Connectors（连接器）解决的就是这个"对外连接"问题——它既包括持久化存储，也包括任何第三方数据源。GraphQL 架构的巧妙之处在于，引入连接器对开发者来说轻而易举，而对客户端完全透明：因为 resolver 负责解析单个字段的值，一次查询响应中的不同字段，完全可以同时来自多个存储系统和第三方 API，客户端对此毫无感知。

下面我们沿着教程原文的步骤，把 Hackernews 示例项目从"内存存储"迁移到 MongoDB。

为 Link 类型补上 id 字段

开始接入数据库之前，先做一次顺手的小重构。后续功能（投票、关联用户等）都需要唯一标识，因此要给Link类型增加id字段。

首先更新 SDL 模式文件（示例项目中的src/main/resources/schema.graphqls），让id作为非空 ID 类型出现在最前面：

type Link { id: ID! url: String! description: String }

接着同步重构 Java 数据类Link，新增id字段。这里采用两个构造函数的写法：Link(String url, String description)委托给全参构造函数并传入null作为 id，这样在插入新数据（id 由数据库生成）时依然可以沿用旧的两参写法：

public class Link { private final String id; //the new field private final String url; private final String description; public Link(String url, String description) { this(null, url, description); } public Link(String id, String url, String description) { this.id = id; this.url = url; this.description = description; } public String getId() { return id; } public String getUrl() { return url; } public String getDescription() { return description; } }

回顾 本教程前序章节 的内容，Link属于data class（纯 POJO，只承载数据、不含行为），而查询与变更的 resolver 则放在Query/Mutation类中；当类型包含非标量（对象）字段时，还需要配套的GraphQLResolver<T>实现类（后续 认证章节 中的LinkResolver、SigninResolver就是例证）。这种"数据与行为分离"的建模方式是graphql-java-tools的核心约定。

安装 MongoDB 并声明 Java Driver 依赖

本项目选用 MongoDB 作为持久化存储，但教程原文明确指出：采用完全相同的方法，你可以把任何第三方系统接入到 resolver 底层。MongoDB 只是第一个示范。

操作分三步：

1. 安装并启动 MongoDB：按照 MongoDB 官方文档中对应你所在平台的Install Community Edition指引完成安装，并确保服务已启动。
2. 在pom.xml中声明 MongoDB Java Driver 依赖（教程写作时的版本为3.4.2，建议动手前检查是否有更新版本）：

<dependency> <groupId>org.mongodb</groupId> <artifactId>mongodb-driver</artifactId> <version>3.4.2</version> </dependency>

3. 利用已有的仓储抽象：得益于前序章节中把"链接的保存与加载"抽取到LinkRepository类的决策，MongoDB 的引入对代码的冲击面被压缩到极小——只需要重写这一个类，上层 resolver 与 Schema 解析逻辑几乎不动。

关于项目本身的搭建方式，可以回看 Getting Started 章节：使用mvn archetype:generate生成 Web 应用骨架，引入graphql-java、graphql-java-tools、graphql-java-servlet与javax.servlet-api依赖，并配置jetty-maven-plugin通过mvn jetty:run在 8080 端口启动服务。

重构 LinkRepository：从内存列表到 MongoDB

教程原文强调，重构的收益在于"影响局部化"。改造后的LinkRepository不再持有List<Link>，而是持有MongoCollection<Document>，通过 MongoDB Java Driver 的同步 API 完成增查：

public class LinkRepository { private final MongoCollection<Document> links; public LinkRepository(MongoCollection<Document> links) { this.links = links; } public Link findById(String id) { Document doc = links.find(eq("_id", new ObjectId(id))).first(); return link(doc); } public List<Link> getAllLinks() { List<Link> allLinks = new ArrayList<>(); for (Document doc : links.find()) { allLinks.add(link(doc)); } return allLinks; } public void saveLink(Link link) { Document doc = new Document(); doc.append("url", link.getUrl()); doc.append("description", link.getDescription()); links.insertOne(doc); } private Link link(Document doc) { return new Link( doc.get("_id").toString(), doc.getString("url"), doc.getString("description")); } }

几个值得展开的实现细节：

• findById：用eq("_id", new ObjectId(id))构造查询条件。MongoDB 的主键_id是ObjectId类型，查询时必须先用ObjectId包装字符串 id，再通过.first()取回单个文档。
• getAllLinks：links.find()返回游标，遍历每个Document并映射为Link；link(doc)私有方法统一完成Document → Link的转换，其中doc.get("_id").toString()把数据库主键序列化成字符串填入Link.id。
• saveLink：用new Document()组装 BSON 文档，insertOne落库。注意：插入时没有显式设置_id，由 MongoDB 自动生成，因此插入完成后Link对象本身仍无 id——这一点在后续 认证章节 的UserRepository.saveUser中做了改进（插入后立即从doc.get("_id")取回并返回带 id 的新对象），可作为你阅读时的对照。

底层逻辑与 前一章的 Query / Mutation 实现 完全兼容：Query.allLinks()返回List<Link>，Mutation.createLink(url, description)调用saveLink。仓储层替换后，resolver 无需任何改动。

更新 Query 与 GraphQLEndpoint：装配数据库连接

重构仓储层后，还有两处收尾工作。

第一处：更新Query类中的allLinks方法，让它调用linkRepository.getAllLinks()（教程原文此处提醒核对方法名，避免仍指向旧的内存版 API）。

第二处：更新GraphQLEndpoint，在 Servlet 初始化时建立 MongoDB 连接，并把links集合交给LinkRepository。GraphQLEndpoint继承自SimpleGraphQLServlet，用@WebServlet(urlPatterns = "/graphql")暴露/graphql端点：

@WebServlet(urlPatterns = "/graphql") public class GraphQLEndpoint extends SimpleGraphQLServlet { private static final LinkRepository linkRepository; static { //Change to `new MongoClient("<host>:<port>")` //if you don't have Mongo running locally on port 27017 MongoDatabase mongo = new MongoClient().getDatabase("hackernews"); linkRepository = new LinkRepository(mongo.getCollection("links")); } public GraphQLEndpoint() { super(buildSchema()); } private static GraphQLSchema buildSchema() { return SchemaParser.newParser() .file("schema.graphqls") .resolvers(new Query(linkRepository), new Mutation(linkRepository)) .build() .makeExecutableSchema(); } }

这段代码的要点：

• 静态初始化块：MongoClient默认连接localhost:27017；若 Mongo 不在本机默认端口，按注释改为new MongoClient("<host>:<port>")。
• 数据库与集合：数据库名为hackernews，集合名为links。后续 认证章节 会在同一数据库上继续添加users、votes集合，并沿用"static块初始化仓储 +buildSchema()装配 resolver"的模式，因此这里的结构值得牢牢记住。
• Schema 装配：SchemaParser.newParser().file("schema.graphqls").resolvers(...).build().makeExecutableSchema()是贯穿整个 Java 教程的标准装配流程——从 SDL 文件解析模式，再把 Java resolver 对象动态绑定到字段上（与 Getting Started 章节 介绍的 schema-first 开发方式一脉相承）。

到这里就全部完成了！重启 Jetty，打开 GraphiQL 试一下：先创建几条链接，再查询allLinks。一切行为与之前完全相同，唯一的不同是——即使断电，保存的链接也不会丢失了。

性能陷阱：N+1 问题与批处理策略

教程原文在这一章末尾提出了一个值得深思的性能问题：目前这种"每个字段独立解析"的执行策略是相当朴素的。

设想链接描述（description）存放在另一个独立的数据库里。对于下面这条查询：

query links { allLinks { description } }

description字段的 resolver 会为结果中的每一条链接各执行一次对另一个数据库的查询——结果里有 N 条链接，就产生 N 次额外查询，加上最初获取链接列表的 1 次，这就是经典的N+1 问题。解决思路是把多次请求合并成一次批处理。以 SQL 数据库为例，理想的 resolver 应当生成这样的语句：

SELECT * FROM Descriptions WHERE link_id IN (1,2,3) -- fetch descriptions for 3 links at once

一次IN查询把 3 条链接的描述一次性取回，而不是逐条查询。

围绕这一策略，教程给出了两条技术路线：

• DataLoader：在 JavaScript 及部分其他语言中，最流行的实现是 Facebook 开源的DataLoader工具，它通过"按请求收集 key → 合并加载 → 缓存结果"的机制消灭 N+1；Java 生态也有对应的移植实现。
• BatchedExecutionStrategy：作为替代方案，graphql-java本身提供了BatchedExecutionStrategy执行策略。它专门寻找被@Batched注解标注的 resolver（在graphql-java术语中，resolver 即DataFetcher）。这类 resolver 的签名与普通 resolver 不同——接收源对象列表，返回结果列表。就上面的例子而言，即接收List<Link>，返回List<String>描述列表，从而让引擎在单次执行中完成整批解析。教程原文还补充了一条更新信息：graphql-java-tools自某次提交起也已支持 batched data fetchers。

这条优化路径与后续章节中 "每新增一个对象字段就配套一个GraphQLResolver" 的模式形成了鲜明对照：关系型/文档型数据库的关联字段天然容易触发 N+1，而批处理、DataLoader 正是把关联查询收敛为常数次数据库往返的关键手段。

与后续章节的衔接：连接器模式的复现

连接器章节确立的"仓储类 + 静态初始化 + resolver 装配"模式，是整个 Java 教程后续所有功能的地基：

• 认证章节 按同样方式新增UserRepository（依赖users集合），并扩展GraphQLEndpoint的静态块与buildSchema()；
• 更多变更章节 继续新增VoteRepository、自定义DateTime标量，并注册VoteResolver，buildSchema()中的 resolver 列表随之不断增长；
• 教程末尾的 总结章节 则指出，本教程之外还有动态数据结构、恶意查询防护、缓存等大量主题留待读者自行探索。

注意事项与学习建议

最后，结合本仓库的实际情况给你三点提醒：

1. 本教程已被标记为过时：仓库 README.md 明确将graphql-java教程列为 "Out of date"，教程开篇的 Introduction 章节 也给出了同样的警告，指出原教程在graphql-java之上叠加了部分第三方库且未作清晰说明。因此本文涉及的依赖版本（graphql-java 3.0.0、graphql-java-tools 3.2.0、mongodb-driver 3.4.2等）均以教程写作时间为准，实际项目中务必核对最新版本。
2. 示例工程源码不在本仓库内：教程代码块中标注的hackernews-graphql-java示例工程路径指向教程配套的独立示例仓库；本仓库 content/backend/graphql-java/ 目录下存放的是全部章节的 Markdown 教学文档，你可以按章节顺序（0-introduction→12-summary）完整跟进。
3. 动手验证：MongoDB 的安装请遵循官方社区版安装指引（按平台选择 Install Community Edition 部分）；启动服务后，用mvn jetty:run起 Jetty，在http://localhost:8080/graphql的 GraphiQL 中先执行createLink变更再执行allLinks查询，即可完整验证本章改造效果。