应选 graphql-kickstart-spring-boot-starter（适配 graphql-java 19+）；纯 Java/Vert.x 场景用 graphql-java + graphql-java-tools 或 codegen；注意 20.x 起 RuntimeWiring.Builder 链式调用弃用，改用 WiringFactory。
怎么选 graphql-java 的核心依赖版本
graphql-java 本身不绑定运行时或 Web 框架，只提供 GraphQL 执行引擎。你得自己挑配套的“胶水”模块，否则写完 Schema 也跑不起来。
- 用 Spring Boot？优先加
graphql-spring-boot-starter（注意：它已停止维护），现在更稳的是graphql-kickstart-spring-boot-starter（对应graphql-java19+ 版本） - 纯 Java SE 或 Vert.x 场景？直接依赖
graphql-java+graphql-java-tools（用于基于 POJO 自动映射字段）或graphql-java-codegen（适合强类型、多客户端协作） - 别踩坑：
graphql-java20.x 起弃用了graphql.schema.idl.RuntimeWiring.Builder的部分链式调用，改用WiringFactory；如果教程里还写.type("Query", ...)连续调用，大概率是旧版写法，编译会报错
schema.graphql 文件放哪、怎么加载
GraphQL 的 SDL（Schema Definition Language）文件默认不会被 graphql-java 自动扫描。路径和加载方式直接影响启动是否报 SchemaProblem: No type named Query。
- 推荐放
src/main/resources/graphql/下，命名如schema.graphqls（注意后缀是.graphqls，不是.graphql；后者通常用于 query 文件，工具链可能忽略） - 加载代码要手动读取：
String sdl = Resources.toString(Resources.getResource("graphql/schema.graphqls"), StandardCharsets.UTF_8); TypeDefinitionRegistry registry = new SchemaParser().parse(sdl); RuntimeWiring wiring = RuntimeWiring.newRuntimeWiring().build(); GraphQLSchema schema = new SchemaGenerator().makeExecutableSchema(registry, wiring); - 容易漏：没加
Resources依赖（Maven 里是com.google.guava:guava），或路径写成/graphql/schema.graphqls（开头斜杠在 classpath 下反而找不到）
dataFetcher 怎么写才不掉进 N+1 和空指针里
DataFetcher 是 resolver 的实现载体，但直接 new 一个匿名类容易埋下性能和健壮性隐患。
立即学习“Java免费学习笔记（深入）”；
- 避免在
DataFetcher.get()里同步查数据库——尤其当字段是 List 关联时，会触发 N+1 查询。应该用BatchLoader+DataLoader（需搭配graphql-java-dataloader-tools） - 别假设
environment.getSource()一定非空：比如根级Query字段的 source 是 null，直接((User) env.getSource()).getId()必崩。加判空或用env.getArgument("id")取参数更安全 - 示例中常见错误写法：
// ❌ 错误：没处理 source 为 null 的情况 return ((Post) environment.getSource()).getAuthor(); </li></ul><p>// ✅ 正确：按字段层级区分取值来源 if (environment.getSource() instanceof Post post) { return authorService.findById(post.getAuthorId()); } return null;</p>为什么 Int 类型返回了字符串、ID 总是被转成 Long
这是
graphql-java默认标量（Scalar）行为导致的隐式转换，不声明自定义 Scalar 就会走内置逻辑。-
Int在 Java 侧默认映射到Integer，但如果 JSON 输入里传了"123"（字符串数字），graphql-java不会自动 parse，而是抛CoercingParseValueException。解决办法是注册自定义GraphQLInt实现，重写parseValue支持字符串输入 -
ID类型默认用GraphQLId，其coerceInput把任意非 null 输入都转成String，但很多团队习惯用Long当主键，结果前端收到的是字符串 ID，后端又拿它去查 Long 字段，查不到 - 关键点：别只改 schema SDL 里的类型声明，必须同步注册对应的
GraphQLScalarType实例到RuntimeWiring，否则声明无效
复杂点在于，Scalar 行为不报错也不警告，问题往往出现在联调阶段才暴露——比如前端发了个 ID 字符串，后端日志里查不到记录，但控制台没异常。这时候得翻
graphql-java的 scalar 源码，确认你用的版本里GraphQLId到底干了什么。 -
