Spring for GraphQL

Spring for GraphQL 把 Schema 与 Java Bean 绑定：用 @QueryMapping、@MutationMapping、@SchemaMapping 实现 Resolver，与现有 spring-boot-essentials 项目共存。

学习目标

• 添加 spring-boot-starter-graphql 依赖
• 放置 schema.graphqls 并映射 Query
• 启用 GraphiQL 做本地调试（实验路由，非生产主 API）

核心内容

依赖与配置

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-graphql</artifactId>
</dependency>

# application.yml（实验 profile）
spring:
  graphql:
    graphiql:
      enabled: true
    schema:
      locations: classpath:graphql/

重要：CodeRoadMap 对外 主 API 仍是 REST /tracks。GraphQL 建议挂在 /graphql 或 lab profile，避免与现有 TrackController 路由混淆。

QueryMapping 示例

src/main/resources/graphql/track.graphqls：

type Query {
  tracks: [Track!]!
  track(slug: String!): Track
}

@Controller
public class TrackGraphqlController {

    private final TrackService trackService;

    @QueryMapping
    public List<Track> tracks() {
        return trackService.findAll();
    }

    @QueryMapping
    public Track track(@Argument String slug) {
        return trackService.findBySlug(slug).orElse(null);
    }

    @SchemaMapping
    public List<Lesson> lessons(Track track) {
        return lessonService.findByTrackSlug(track.getSlug());
    }
}

复用现有 TrackService / JPA 实体，与 REST 共享事务边界（sb-transaction）。

开发环境访问 /graphiql 验证 Schema；生产关闭 GraphiQL（gql-security）。nextjs-essentials 主站继续 fetch REST /tracks；实验页可 POST /graphql 对比。

练习

• 在 lab profile 启动 GraphiQL，查询全部 track 的 slug、title
• 为 lesson Query 增加 @QueryMapping 方法
• 确认 REST GET /tracks 与 GraphQL tracks 返回数据一致

小结

Spring GraphQL = 注解 + schema 文件 + 复用 Service 层。 下一课 N+1 与 DataLoader 性能。