【免费下载链接】howtographqlThe Fullstack Tutorial for GraphQL项目地址https://gitcode.com/gh_mirrors/ho/howtographql点击查看免费下载本文是 howtographql 仓库中 GraphQL Java 后端教程总结篇 的收官解读。该教程用 Java 生态最主流的graphql-java系列库从零搭建了一个完整的 Hackernews 风格 GraphQL 服务覆盖 schema-first 开发、查询/变更解析器、MongoDB 连接器、认证、错误处理、过滤与分页并介绍了graphql-spqr的 code-first 备选方案。读完本文你将获得整条教程的路线图、核心代码要点与可验证的源码依据同时了解动态数据结构、恶意查询防护、缓存等值得继续深入的方向。GraphQL 的三项核心承诺总结篇开宗明义地指出GraphQL 承诺一种清晰而简洁的方式来描述和操作数据describe and manipulate data通过类型系统与 schema 精确刻画数据形状只获取恰好且必需的数据fetch exactly and only the data that is required客户端决定取哪些字段杜绝过度获取获得可预测的结果receive a predictable result响应结构固定错误与数据分离。整个 Java 教程正是围绕这三项承诺展开的先用 SDL 定义Link类型与allLinks查询再通过解析器把 schema 与 Java 代码接起来最终让客户端能以{allLinks{url}}这样的查询精确拿到所需字段。教程开篇还解释了为何 schema-first契约优先在 GraphQL 中天然可行schema 是客户端与服务端之间的中央契约且得益于 introspection内省查询schema 具有自描述能力。教程路线图从零到可用的 GraphQL 服务下面按章节顺序回顾整条教程的技术脉络每部分都指向仓库中对应的章节文件与核心代码。1. 项目初始化Maven 骨架与 SDL 起步教程使用 Maven 的 webapp 骨架初始化项目详见 1-getting-started.mdmvn archetype:generate -DarchetypeArtifactIdmaven-archetype-webapp -DgroupIdcom.howtographql.sample -DartifactIdhackernews-graphql-java -Dversion1.0-SNAPSHOT随后在src/main/resources/schema.graphqls中定义第一个 schematype Link { url: String! description: String! } type Query { allLinks: [Link] } schema { query: Query }在pom.xml中声明四个依赖graphql-javaGraphQL 实现本身、graphql-java-tools灵感来自 Apollographql-tools的动态解析器装配库、graphql-java-servlet开箱即用的 Servlet以及javax.servlet-api。章节中给出的版本如graphql-java3.0.0、graphql-java-tools3.2.0、graphql-java-servlet4.0.0写作时是最新版本但库的迭代很快动手前务必检查更新。同时配置jetty-maven-plugin与maven-compiler-pluginJava 1.8、Servlet 3.1之后只需mvn jetty:run即可在 8080 端口启动 Jetty。服务端入口是继承SimpleGraphQLServlet的GraphQLEndpoint通过SchemaParser解析 schema 文件并生成可执行 schemaWebServlet(urlPatterns /graphql) public class GraphQLEndpoint extends SimpleGraphQLServlet { public GraphQLEndpoint() { super(SchemaParser.newParser() .file(schema.graphqls) .build() .makeExecutableSchema()); } }此时访问http://localhost:8080/graphql仍会报错——因为还没有任何解析器被接入allLinks无从执行。2. 查询解析器data class 与 resolver 的分工graphql-java-tools把 Java 类分成两类详见 2-queries.md数据类data classes建模领域、通常是纯 POJO与解析器resolvers建模查询与变更、包含解析函数。一个 GraphQL 类型常常需要两者共同建模public class Link { private final String url; private final String description; // 构造器与 getter }public class Query implements GraphQLRootResolver { private final LinkRepository linkRepository; public ListLink allLinks() { return linkRepository.getAllLinks(); } }LinkRepository把链接的存取逻辑隔离起来初期用内存ArrayList存储。更新GraphQLEndpoint后访问http://localhost:8080/graphql?query{allLinks{url}}就能看到首个查询结果{ data: { allLinks: [ { url: http://howtographql.com }, { url: http://graphql.org/learn/ } ] } }随后教程引入 GraphiQL 浏览器 IDE把index.html中graphiql.css/graphiql.js的引用改为 CDN 地址存到src/main/webapp/index.html并重启 Jetty即可在http://localhost:8080/获得带自动补全的交互式测试环境。3. 变更解析器带参数的 mutation定义变更与定义查询同样直接详见 3-mutations.md。先在 SDL 中描述createLink变更并把mutation根类型挂到 schema 上type Mutation { createLink(url: String!, description: String!): Link } schema { query: Query mutation: Mutation }再创建根变更解析器Mutation implements GraphQLRootResolver其方法签名与 schema 中变更的参数名、类型一一对应public Link createLink(String url, String description) { Link newLink new Link(url, description); linkRepository.saveLink(newLink); return newLink; }最后在GraphQLEndpoint#buildSchema中通过.resolvers(new Query(linkRepository), new Mutation(linkRepository))注册即可。重启 Jetty 后用 GraphiQL 执行变更并重跑allLinks即可验证新链接已持久化。4. 数据连接器接入 MongoDB纯内存存储无法持久化教程选择 MongoDB 作为存储详见 4-connectors.md并借此强调 GraphQL 架构的一个优点引入第三方连接器对开发者很轻量对客户端完全透明——同一查询响应中的不同字段可以来自多个存储或第三方 API。步骤包括给Link类型补充id: ID!字段并同步改造Link类在pom.xml加入mongodb-driver依赖把LinkRepository从内存列表重构为基于MongoCollectionDocument的实现findById按_id查询、saveLink用Document追加字段后insertOne最后在GraphQLEndpoint的静态块中连接本地 MongoDB 的hackernews库并取出links集合。若 Mongo 不在本地 27017 端口把new MongoClient()改为new MongoClient(host:port)即可。重启后一切照旧只是数据不再因断电而丢失。章节末尾还点出了 N1 问题若description存于另一数据库每解析一个链接的description字段都会触发一次额外查询。解决办法是批量解析如 SQL 的SELECT * FROM Descriptions WHERE link_id IN (1,2,3)Java 侧可参考graphql-java的BatchedExecutionStrategy配合Batched注解的DataFetcher接收源对象列表、返回结果列表或使用 Java 版的 DataLoader 工具。5. 认证从 signinUser 到 AuthContext没有用户追踪就谈不上互动教程实现了注册与登录详见 5-authentication.md。先扩展 schema新增createUser(name: String!, authProvider: AuthData!): User变更、User类型与AuthData输入类型type User { id: ID! name: String! email: String password: String } input AuthData { email: String! password: String! }配套创建User、AuthData两个数据类与UserRepository按email/_id查询、保存用户。教程特意注明永远不要明文存储密码这里仅为简化示例。登录侧则定义signinUser(auth: AuthData): SigninPayload变更SigninPayload包含token与user由于SigninPayload内含非标量对象User还需要配套的SigninResolver implements GraphQLResolverSigninPayload。登录解析器校验密码失败时抛出GraphQLException(Invalid credentials)成功则返回 token——本示例中 token 就是用户 id生产环境应替换为 JWT 或类似方案。随后处理请求认证约定客户端在每次请求的Authorization头中带回 token如Authorization: Bearer token。由于 GraphiQL 不便发送该头教程让读者在index.html中硬编码测试。服务端侧的关键是context 对象——它是执行期间传递给所有解析器的数据载体。教程创建AuthContext extends GraphQLContext携带User并覆写GraphQLEndpoint#createContext从请求头解析用户Override protected GraphQLContext createContext(OptionalHttpServletRequest request, OptionalHttpServletResponse response) { User user request .map(req - req.getHeader(Authorization)) .filter(id - !id.isEmpty()) .map(id - id.replace(Bearer , )) .map(userRepository::findById) .orElse(null); return new AuthContext(user, request, response); }有了用户身份后教程给Link增加postedBy: User字段用LinkResolver implements GraphQLResolverLink提供postedBy(Link link)解析按link.getUserId()反查用户并在createLink解析器中通过DataFetchingEnvironment env注入 context把当前登录用户记为链接作者。6. 投票功能与自定义 DateTime 标量认证之后教程引入投票特性详见 6-more-mutations.md定义createVote(linkId: ID, userId: ID): Vote变更与Vote类型其中createdAt: DateTime!需要一个自定义标量type Vote { id: ID! createdAt: DateTime! user: User! link: Link! } scalar DateTime自定义标量通过GraphQLScalarType实现负责三类转换serialize输出时把ZonedDateTime格式化为 ISO 字符串、parseValue输入值解析与parseLiteral字面量解析public class Scalars { public static GraphQLScalarType dateTime new GraphQLScalarType(DateTime, DataTime scalar, new Coercing() { Override public String serialize(Object input) { return ((ZonedDateTime)input).format(DateTimeFormatter.ISO_OFFSET_DATE_TIME); } // parseValue / parseLiteral 相应实现 }); }配套创建Vote数据类、VoteResolver解析user与link字段与VoteRepository按userId/linkId查询、保存投票最后在GraphQLEndpoint#buildSchema中同时注册新解析器与标量.resolvers(... new VoteResolver(linkRepository, userRepository)).scalars(Scalars.dateTime)。createVote解析器用Instant.now().atZone(ZoneOffset.UTC)生成 UTC 时间戳后入库。7. 错误处理可预测的响应结构与错误脱敏GraphQL 服务端的响应结构始终可预测详见 7-error-handling.md由三部分组成data字段操作结果errors字段执行过程中累积的所有错误可选的extensions字段任意内容通常是响应元数据。语法错误与校验错误由服务器自动处理并原样告知客户端而解析器中抛出的异常通常需要应用层定制处理。graphql-java-servlet提供了两个定制入口isClientError决定某错误的消息是原样发给客户端还是被掩盖为通用的 server error。默认只放行语法与校验错误这能防止异常消息与堆栈泄露敏感信息。filterGraphQLErrors在错误发送给客户端之前进行脱敏、过滤、包装或转换。教程的典型做法是用SanitizedError extends ExceptionWhileDataFetching包装数据获取异常并用JsonIgnore注解让 Jackson 在序列化时忽略底层异常堆栈不会到达客户端public class SanitizedError extends ExceptionWhileDataFetching { public SanitizedError(ExceptionWhileDataFetching inner) { super(inner.getException()); } Override JsonIgnore public Throwable getException() { return super.getException(); } }再覆写filterGraphQLErrors只放行数据获取异常与客户端错误并把前者包装为SanitizedError。这样signinUser的Invalid credentials这类精确消息能到达客户端而堆栈细节被隐藏。需要更低层控制时还可以自定义ExecutionStrategy覆写handleDataFetchingException把 Java 异常翻译成 GraphQL 错误并在构造函数中传入super(buildSchema(), new CustomExecutionStrategy())。8. 订阅现实限制与演进预期实时推送是 GraphQL 规范的亮点但教程订阅章节如实说明graphql-java虽然能解析订阅请求但当时的支持程度有限不做大量手工工作便难以实用这超出了教程范围。章节承诺一旦生态情况变化会及时更新——这本身也印证了总结篇Java 生态中 GraphQL 仍处于早期、演进很快的判断。9. 过滤参数没有固有语义语义由你定义查询与变更都能通过参数接收输入而参数本身没有固有语义详见 9-filtering.md。教程把这一特性用于过滤给allLinks增加LinkFilter输入参数type Query { allLinks(filter: LinkFilter): [Link] } input LinkFilter { description_contains: String url_contains: String }LinkFilterPOJO 用JsonProperty(description_contains)让 getter 名与 schema 的下划线命名对齐。LinkRepository#getAllLinks(LinkFilter filter)把过滤条件翻译成 MongoDB 查询条件Bson对非空字段构造.*pattern.*的不区分大小写正则两个条件同时存在时用and(...)合并private Bson buildFilter(LinkFilter filter) { // descriptionCondition / urlCondition 分别用 regex(description/url, .* pattern .*, i) 构造 // 两者都有时返回 and(descriptionCondition, urlCondition) }最终Query#allLinks(LinkFilter filter)把参数透传给仓库层。教程特别提醒这只是过滤的一种实现示例完全可以用其他格式实现。10. 分页limit-offset 方案链接增多后需要分页详见 10-pagination.md。教程采用 SQL 风格的 limit-offset 分页在 schema 中为allLinks增加带默认值的参数type Query { allLinks(filter: LinkFilter, skip: Int 0, first: Int 0): [Link] }仓库层对查询结果链式调用.skip(skip).limit(first)顶层Query方法中参数类型必须声明为Number而非int因为graphql-java-tools会根据上下文有时塞入Integer、有时塞入BigInteger用Number再.intValue()转换最稳妥。章节同时指出这种分页方式与前端 Relay 不兼容——Relay 要求基于 connection 概念的游标分页。若使用 limit-offset跳过大页时存在明显的性能边界。11. 备选开发风格code-first 与 graphql-spqr教程最后一章反思了 schema-first 在 Java 这类强静态类型语言中的痛点Link类型在 SDL 与 Java POJO 中各写一遍信息完全重复改动需同步进行重构风险大对存量项目引入 GraphQL 更是等于重新描述整个模型。code-first风格则从已有模型生成 schema保持 schema 与模型同步、利于重构适合在既有代码库上引入 GraphQL缺点是 schema 在服务端代码写好之前并不存在客户端与服务端工作产生依赖可先用桩代码生成 schema 再并行开发。教程用graphql-spqr演示 code-first在pom.xml加入spqr依赖并开启maven-compiler-plugin的-parametersjavac 选项保留方法参数名schema 才能使用参数名之后必须重新构建项目如mvn clean package再重启 Jetty。改造方式是给已有业务方法加注解public class Query { GraphQLQuery public ListLink allLinks(LinkFilter filter, GraphQLArgument(name skip, defaultValue 0) Number skip, GraphQLArgument(name first, defaultValue 0) Number first) { return linkRepository.getAllLinks(filter, skip.intValue(), first.intValue()); } }要点实现GraphQLRootResolver/GraphQLResolver不再是必需GraphQLQuery、GraphQLMutation等注解完全可选但默认配置会在顶层期望它们GraphQLArgument用于改参数名与设默认值GraphQLContext Link link能把外部方法织入已有类型语义等同于Link类内含postedBy()方法GraphQLRootContext AuthContext可直接注入 context免去对DataFetchingEnvironment的依赖。最后用生成器从单例业务对象生成 schemareturn new GraphQLSchemaGenerator() .withOperationsFromSingletons(query, linkResolver, mutation) .generate();同样的 GraphiQL 结果但再也不用维护显式 schema也不必把链路逻辑拆进顶层查询、嵌套解析器与变更三个位置——遗留代码与既有最佳实践可以原样保留。留给你的探索领域总结篇明确指出教程所覆盖的只是如何利用 GraphQL 优势的基础以下领域留待读者自行探索动态数据结构dynamic data structures如何建模与处理结构不固定的数据恶意查询防护protection against malicious queries深度嵌套、字段爆炸等查询对服务端的资源消耗需要在应用层设计防护策略缓存cachingGraphQL 的按需取数模型让传统 HTTP 缓存不再直接适用如何设计高效缓存是经典难题。建议以教程建立的基础为跳板针对这些问题寻找更深入的答案。生态现状与注意事项总结篇提醒GraphQL 是新生技术在 Java 生态中尤其如此——库在变化思路与最佳实践也在发展与迁移需要持续关注教程的更新它可能随时被修订甚至重写以保持相关性。这一提醒在教程开篇的警告中也能得到印证该 Java 教程写作时间较早且在其上叠加了第三方库如graphql-java-tools并未明确说明这些并非graphql-java本身作者正在推进更新版本。因此在实践中应以graphql-java官方的最新教程与 Spring Boot 集成方案为优先参考把本教程当作理解架构思想与核心 API 的入门路线而非照搬版本号。结语至此你已走完从零到完整 GraphQL 服务的 Java 全流程SDL 定义 schema → 查询/变更解析器 → MongoDB 连接器 → 基于 context 的认证 → 自定义标量 → 错误脱敏 → 过滤与分页 → code-first 备选方案。正如总结篇所言You made it! 带着这份路线图你可以去继续探索动态数据、查询防护与缓存等更深的话题让 GraphQL 的能力真正为己所用。赞分享【免费下载链接】howtographqlThe Fullstack Tutorial for GraphQL项目地址https://gitcode.com/gh_mirrors/ho/howtographql点击查看免费下载相关推荐GraphQL Node.js Prisma 后端教程总结从零构建 Hacker News API 的完整技术栈回顾GraphQL Node.js Prisma 后端教程总结从零构建 Hacker News API 的完整技术栈回顾 本篇文章是对 howtograp使用 graphql-java 在 Java 后端实现 GraphQL Mutation 的完整指南使用 graphql java 在 Java 后端实现 GraphQL Mutation 的完整指南 本篇指南基于开源仓库 howtographql https用 graphql-ruby 与 Ruby 构建 GraphQL 服务端全教程核心知识点总结用 graphql ruby 与 Ruby 构建 GraphQL 服务端全教程核心知识点总结 本篇为 How to GraphQL 开源教程中《Buildin上一篇OpenCore Legacy Patcher终极指南如何让旧Mac免费升级最新macOS系统下一篇攻克AKS中Istio Service Entry的DNS解析难题从故障排查到根治方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考