如何在Spring Web项目中使用Spring GraphQL Starter而不依赖WebFlux？

能否保留starter并替换为同步HTTP客户端？ #

当然可以。spring-boot-starter-graphql本身没有强制依赖WebFlux，只是默认用WebClient作为响应式客户端实现。你完全可以在保留starter的前提下，自定义基于同步HTTP客户端的GraphQL调用逻辑，和Spring Web（Servlet栈）完美兼容。

具体操作步骤： #

1. 确保WebFlux不被引入（可选）

如果你的依赖树里不小心引入了spring-boot-starter-webflux（比如某些依赖传递引入），可以直接在spring-boot-starter-graphql依赖中排除它：

Maven 配置：

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

Gradle 配置：

implementation('org.springframework.boot:spring-boot-starter-graphql') {
    exclude group: 'org.springframework.boot', module: 'spring-boot-starter-webflux'
}

如果你的项目本来就没引入WebFlux，这一步可以跳过。

2. 基于RestTemplate实现同步GraphQL客户端

RestTemplate是Spring Servlet栈原生的同步HTTP客户端，用它封装GraphQL调用非常方便：

首先配置RestTemplate Bean：

@Configuration
public class RestTemplateConfig {
    @Bean
    public RestTemplate restTemplate() {
        return new RestTemplate();
    }
}

然后封装一个可复用的同步GraphQL客户端组件：

@Component
public class SyncGraphQlClient {
    private final RestTemplate restTemplate;
    private final String graphqlApiUrl;

    // 从配置文件读取GraphQL API地址
    public SyncGraphQlClient(RestTemplate restTemplate, @Value("${graphql.api.endpoint}") String graphqlApiUrl) {
        this.restTemplate = restTemplate;
        this.graphqlApiUrl = graphqlApiUrl;
    }

    // 通用执行方法，支持带变量的查询
    public <T> T execute(String graphqlQuery, Class<T> responseClass, Map<String, Object> variables) {
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);

        // 构造GraphQL标准请求体
        Map<String, Object> requestBody = new HashMap<>();
        requestBody.put("query", graphqlQuery);
        if (variables != null && !variables.isEmpty()) {
            requestBody.put("variables", variables);
        }

        HttpEntity<Map<String, Object>> request = new HttpEntity<>(requestBody, headers);
        return restTemplate.postForObject(graphqlApiUrl, request, responseClass);
    }

    // 重载方法，支持无变量的查询
    public <T> T execute(String graphqlQuery, Class<T> responseClass) {
        return execute(graphqlQuery, responseClass, null);
    }
}

3. 在业务代码中使用同步客户端

比如在你的@RestController里调用：

@RestController
@RequestMapping("/app")
public class BusinessController {
    private final SyncGraphQlClient syncGraphQlClient;

    public BusinessController(SyncGraphQlClient syncGraphQlClient) {
        this.syncGraphQlClient = syncGraphQlClient;
    }

    @GetMapping("/user/{userId}")
    public ResponseEntity<User> getUser(@PathVariable String userId) {
        // 定义GraphQL查询语句
        String query = """
            query GetUser($id: ID!) {
                user(id: $id) {
                    id
                    username
                    email
                    createdAt
                }
            }
        """;
        // 构造查询变量
        Map<String, Object> variables = Map.of("id", userId);
        // 执行查询并解析响应
        UserGraphQlResponse response = syncGraphQlClient.execute(query, UserGraphQlResponse.class, variables);
        return ResponseEntity.ok(response.getData().getUser());
    }

    // 定义对应的响应实体类（和GraphQL返回结构匹配）
    private static class UserGraphQlResponse {
        private UserData data;

        // getter & setter
        public UserData getData() { return data; }
        public void setData(UserData data) { this.data = data; }

        private static class UserData {
            private User user;

            // getter & setter
            public User getUser() { return user; }
            public void setUser(User user) { this.user = user; }
        }
    }

    // 业务用的User实体
    public static class User {
        private String id;
        private String username;
        private String email;
        private LocalDateTime createdAt;

        // getter & setter
        // 省略具体实现
    }
}

替代方案：如果不想自己封装 #

如果觉得手动封装麻烦，可以直接使用成熟的同步GraphQL客户端库：

• GraphQL Java Client：GraphQL官方的Java客户端，原生支持同步调用，无需依赖WebFlux，可直接集成到Spring Boot Web项目。
• graphql-request + OkHttp：轻量级的GraphQL请求库，配合OkHttp作为同步HTTP客户端，配置简单、体积小。
• Apache HttpClient：直接用Apache HttpClient构造POST请求，手动封装GraphQL的JSON请求体和响应解析，灵活性最高。

这些方案都完全适配Spring Servlet栈，不会和你的@RestController产生任何冲突或性能问题。

内容的提问来源于stack exchange，提问作者Stan Ostrovskii