本文详解如何在 spring boot graphql 应用中正确使用 @mockbean 模拟业务服务，并通过 httpgraphqltester 验证 graphql 查询行为，避免因测试配置不当导致真实服务被调用。
本文详解如何在 spring boot graphql 应用中正确使用 @mockbean 模拟业务服务，并通过 httpgraphqltester 验证 graphql 查询行为，避免因测试配置不当导致真实服务被调用。
在 Spring Boot + GraphQL（基于 Spring for GraphQL）项目中，对 GraphQL 端点进行集成测试时，一个常见误区是：误以为只要声明 @MockBean 就能自动拦截所有 GraphQL 请求路径下的服务调用。实际上，Mock 的生效前提是——GraphQL 执行引擎（如 GraphQLController 或 GraphQlHttpHandler）所依赖的 Bean 确实被替换为 Mock 实例，且测试上下文完整加载了 GraphQL 基础设施。
你提供的测试代码中，@MockBean private UserData userData; 语法本身正确，但问题往往出在以下关键环节：
✅ 正确配置测试类注解
确保测试类启用完整的 Spring Boot 上下文和 GraphQL 支持：
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@ActiveProfiles("test") // 推荐使用独立测试 profile，避免污染 local/dev 配置
@AutoConfigureHttpGraphQlTester // 必须！用于自动配置 HttpGraphQlTester Bean
@ExtendWith(MockitoExtension.class) // 仅当混合使用 Mockito 原生 API（如 given()）时需要；Spring Test 已内置 Mock 支持
class UserTests {
@Autowired
private HttpGraphQlTester graphQlTester; // 优先使用 @Autowired 注入，而非手动构建
@MockBean
private UserData userData; // 此处会替换容器中同类型的单例 Bean
}
⚠️ 注意：@SpringBootTest 默认启动完整上下文；若使用 webEnvironment = MOCK，需额外确认 GraphQL WebMvc/WebFlux 自动配置是否激活（推荐 RANDOM_PORT 或 DEFINED_PORT 以保障端到端行为）。
✅ 正确编写 Mock 行为（适配响应式类型）
你的 getUsers() 方法返回 Mono
@Test
void testGetUsers() {
// 构造预期数据
List<user> mockUsers = List.of(
User.builder().name("Test User").build(),
User.builder().name("Test User 2").build()
);
PageInfo pageInfo = new PageInfo(1, 2, 1, 2, 2, false, false);
UserPage expectedPage = new UserPage(mockUsers, pageInfo);
// 正确 Mock：返回 Mono.just(...)，而非 Flux.collectList().flatMap(...)
when(userData.getUsers(any(), any(), any()))
.thenReturn(Mono.just(expectedPage));
// 执行 GraphQL 查询（假设 schema 中有字段 userPage）
graphQlTester
.documentName("top5users") // 对应 src/test/resources/graphql/top5users.graphql
.execute()
.path("userPage") // 对应查询返回的字段名
.entity(UserPage.class)
.matches(actual -> {
assertThat(actual.users()).hasSize(2);
assertThat(actual.pageInfo().totalElements()).isEqualTo(2);
});
}</user>
? 关键修正点：
- 使用 when(...).thenReturn(...)（Mockito 4+ 推荐）替代过时的 given(...).willReturn(...)；
- 直接 Mono.just(expectedPage) 替代冗余的 Flux.fromIterable(...).collectList().flatMap(...)；
- 利用 matches() 进行断言，语义清晰且与 GraphQL 响应结构强绑定。
✅ GraphQL 查询文件（.graphql）必须匹配服务契约
确保 src/test/resources/graphql/top5users.graphql 内容与后端 resolver 返回结构一致，例如：
query GetUsers($filter: NameFilter!, $pageable: PageableInput!) {
userPage(filter: $filter, pageable: $pageable) {
users { name }
pageInfo { totalElements hasNext hasPrevious }
}
}
若查询中未请求 users 字段，则 actual.users() 将为 null —— 断言失败并非 Mock 失效，而是 GraphQL 投影不完整。
⚠️ 常见陷阱与排查建议
- Mock 未生效？检查 Bean 名称冲突：确认 UserData 类上只有 @Service（无 @Primary 或条件化 @ConditionalOn...），且没有其他同类型 Bean 干扰；
- 仍调用数据库？验证 Profile 和配置：检查 application-test.yml 是否禁用了 spring.datasource 或启用了内存数据库（H2）；
- WebTestClient 构建方式错误：不要手动创建 WebTestClient.bindToServer() —— 它绕过了 Spring 管理的 HttpGraphQlTester，导致 Mock Bean 不参与请求链路；
- 依赖版本兼容性：确保 spring-boot-starter-graphql 与 Spring Boot 版本匹配（如 Spring Boot 3.2+ 对应 Spring for GraphQL 1.2+）。
✅ 总结：可靠 GraphQL 集成测试三要素
| 要素 | 要求 | 验证方式 |
|---|---|---|
| 上下文配置 | @SpringBootTest + @AutoConfigureHttpGraphQlTester | 启动日志含 GraphQlHttpHandler 初始化信息 |
| Mock 注入 | @MockBean 作用于 GraphQL Resolver 依赖的服务层 | 在 UserData 方法内加 log.info("Called!")，确认测试运行时无日志输出 |
| 查询验证 | 使用 graphQlTester.execute().path(...).entity(...) 链式断言 | 响应体 JSON 包含预期字段，且值与 Mock 一致 |
遵循以上实践，即可精准隔离外部依赖，在 GraphQL 层面实现可预测、可重复、高覆盖率的集成测试。
