Spring Boot 3.4.2에서 GraphQL 도입 시 호환성 이슈

Spring Boot 3.4.2에서 GraphQL 도입 시 호환성 이슈

---

UTM 0.1.0을 Spring Boot 3.4.2 버전에서 개발 중
기존의 REST API 대신 GraphQL을 도입하는 과정에서 호환성 이슈가 발생.

---

문제

GraphQL 사용 시, resource/schema.graphqls에 등록된 type, query, mutation을 올바른 경로에서 찾을 수 있어야 함.
그러나 GraphQlAutoConfigurator가 이를 제대로 매핑하지 못해 Spring Boot 애플리케이션 실행 시 첫 로그에 Unmapped fields로 Query, Mutation들이 나타나는 이슈.
이로 인해 정상적인 매핑이 불가한 상태

---

원인

• GraphQLQueryResolver와 GraphQLMutationResolver 인터페이스를 통해 리졸버를 구현하고자 했으나, 이는 graphql-java-kickstart 라이브러리에서 제공됨.
• Spring Boot 3.x 버전과는 호환성이 좋지 않음.

---

기존 사용 lib(호환성 문제)

implementation 'com.graphql-java-kickstart:graphql-spring-boot-starter:11.0.0'
implementation 'com.graphql-java-kickstart:graphiql-spring-boot-starter:11.0.0'
implementation 'com.graphql-java-kickstart:playground-spring-boot-starter:7.1.0'

---

대체 가능한 의존성 lib (호환성 문제 해결)

implementation 'org.springframework.boot:spring-boot-starter-graphql:3.4.2'

• graphql-java-kickstart 대신 spring-boot-starter-graphql을 사용

---

해결

1. 어노테이션 변경

• 기존의 GraphQLQueryResolver, GraphQLMutationResolver 인터페이스 대신,
  spring-boot-starter-graphql에서 제공하는 @SchemaMapping, @QueryMapping, @MutationMapping을 사용해야 함.
• 이로 인해 스키마와 메서드 간의 매핑 문제가 해결됨.

---

Exmample: 어노테이션 변경 후

@Controller
public class UserResolver {

    @MutationMapping
    public User createUser(@Argument String username, @Argument String email) {
        User user = new User();
        user.setUsername(username);
        user.setEmail(email);
        return userService.createUser(user);
    }

    @QueryMapping
    public List<User> getAllUsers() {
        return userService.getAllUsers();
    }
}

---

2. @Controller 사용

• @Component 또는 @Service 대신 @Controller를 사용해야 함.
• 이유: @Controller는 HandlerMapping에 등록되어 DispatcherServlet이 해당 Bean을 찾아서 매핑해 줌.
• 반면, @Component나 @Service는 단순히 Bean으로만 등록될 뿐, HTTP 요청 매핑 불가.
• 결국, GraphQL 요청도 HTTP POST 요청이므로 @Controller가 필요함.

---

3. 최종 dependency 설정

build.gradle에서 다음과 같이 설정해야 함.

implementation 'org.springframework.boot:spring-boot-starter-graphql:3.4.2'

• 기존 kickstart 관련 의존성은 모두 제거해야 함.

---

결론

• graphql-java-kickstart 라이브러리는 Spring Boot 3.x와 호환성이 좋지 않음.
• spring-boot-starter-graphql을 사용하고, @Controller와 @SchemaMapping 계열의 어노테이션을 활용해 해결 가능.
• 이를 통해 GraphQL 스키마와 리졸버 간의 매핑 문제를 해결