[Spring Boot 번역] Spring for GraphQL

출처: https://docs.spring.io/spring-boot/4.0-SNAPSHOT/reference/web/spring-graphql.html

중요: 이 버전은 아직 개발 중이며 안정적인 것으로 간주되지 않습니다. 최신 안정 버전은 Spring Boot 3.5.6을 사용하세요!

GraphQL 애플리케이션을 구축하려는 경우 Spring Boot의 Spring for GraphQL 자동 구성을 활용할 수 있습니다.
Spring for GraphQL 프로젝트는 GraphQL Java를 기반으로 합니다.
최소한 spring-boot-starter-graphql starter가 필요합니다.
GraphQL은 전송 방식에 구애받지 않기 때문에 웹을 통해 GraphQL API를 노출하려면 애플리케이션에 하나 이상의 추가 starter가 필요합니다:

Starter	Transport	Implementation
`spring-boot-starter-web`	HTTP	Spring MVC
`spring-boot-starter-websocket`	WebSocket	WebSocket for Servlet apps
`spring-boot-starter-webflux`	HTTP, WebSocket	Spring WebFlux
`spring-boot-starter-rsocket`	TCP, WebSocket	Spring WebFlux on Reactor Netty

GraphQL Schema

Spring GraphQL 애플리케이션은 시작 시 정의된 스키마가 필요합니다.
기본적으로 src/main/resources/graphql/** 아래에 ".graphqls" 또는 ".gqls" 스키마 파일을 작성할 수 있으며 Spring Boot가 자동으로 이를 선택합니다.
spring.graphql.schema.locations로 위치를 사용자 정의하고 spring.graphql.schema.file-extensions로 파일 확장자를 사용자 정의할 수 있습니다.

참고: Spring Boot가 모든 애플리케이션 모듈 및 해당 위치의 종속성에서 스키마 파일을 감지하도록 하려면 spring.graphql.schema.locations를 "classpath*:graphql/**/"로 설정할 수 있습니다(classpath*: 접두사에 유의하세요).

다음 섹션에서는 두 가지 타입과 두 가지 쿼리를 정의하는 이 샘플 GraphQL 스키마를 고려할 것입니다:

type Query {
    greeting(name: String! = "Spring"): String!
    project(slug: ID!): Project
}

""" A Project in the Spring portfolio """
type Project {
    """ Unique string id used in URLs """
    slug: ID!
    """ Project name """
    name: String!
    """ URL of the git repository """
    repositoryUrl: String!
    """ Current support status """
    status: ProjectStatus!
}

enum ProjectStatus {
    """ Actively supported by the Spring team """
    ACTIVE
    """ Supported by the community """
    COMMUNITY
    """ Prototype, not officially supported yet  """
    INCUBATING
    """ Project being retired, in maintenance mode """
    ATTIC
    """ End-Of-Lifed """
    EOL
}

참고: 기본적으로 field introspection은 GraphiQL과 같은 도구에 필요하므로 스키마에서 허용됩니다. 스키마에 대한 정보를 노출하지 않으려면 spring.graphql.schema.introspection.enabled를 false로 설정하여 introspection을 비활성화할 수 있습니다.

GraphQL RuntimeWiring

GraphQL Java RuntimeWiring.Builder는 사용자 정의 scalar 타입, directives, type resolvers, DataFetcher 등을 등록하는 데 사용할 수 있습니다.
Spring 구성에서 RuntimeWiringConfigurer 빈을 선언하여 RuntimeWiring.Builder에 액세스할 수 있습니다.
Spring Boot는 이러한 빈을 감지하고 GraphQlSource builder에 추가합니다.

그러나 일반적으로 애플리케이션은 DataFetcher를 직접 구현하지 않고 대신 annotated controllers를 생성합니다.
Spring Boot는 annotated handler 메서드가 있는 @Controller 클래스를 자동으로 감지하고 이를 DataFetcher로 등록합니다.
다음은 @Controller 클래스를 사용한 greeting 쿼리의 샘플 구현입니다:

Java:

import org.springframework.graphql.data.method.annotation.Argument;
import org.springframework.graphql.data.method.annotation.QueryMapping;
import org.springframework.stereotype.Controller;

@Controller
public class GreetingController {

    @QueryMapping
    public String greeting(@Argument String name) {
        return "Hello, " + name + "!";
    }

}

Kotlin:

import org.springframework.graphql.data.method.annotation.Argument
import org.springframework.graphql.data.method.annotation.QueryMapping
import org.springframework.stereotype.Controller

@Controller
class GreetingController {

    @QueryMapping
    fun greeting(@Argument name: String): String {
        return "Hello, $name!"
    }

}

Querydsl and QueryByExample Repositories Support

Spring Data는 Querydsl과 QueryByExample repositories 모두를 지원합니다.
Spring GraphQL은 Querydsl과 QueryByExample repositories를 DataFetcher로 구성할 수 있습니다.

@GraphQlRepository로 annotated되고 다음 중 하나를 확장하는 Spring Data repositories:

QuerydslPredicateExecutor
ReactiveQuerydslPredicateExecutor
QueryByExampleExecutor
ReactiveQueryByExampleExecutor

는 Spring Boot에 의해 감지되고 최상위 쿼리와 일치하는 DataFetcher의 후보로 간주됩니다.

Transports

HTTP and WebSocket

GraphQL HTTP 엔드포인트는 기본적으로 HTTP POST /graphql에 있습니다.
또한 구독(subscriptions)에만 Server Sent Events를 통한 "text/event-stream" 미디어 타입을 지원합니다.
경로는 spring.graphql.http.path로 사용자 정의할 수 있습니다.

팁: Spring MVC와 Spring WebFlux 모두에 대한 HTTP 엔드포인트는 @Order가 0인 RouterFunction 빈에 의해 제공됩니다. 자체 RouterFunction 빈을 정의하는 경우 올바르게 정렬되도록 적절한 @Order annotation을 추가할 수 있습니다.

GraphQL WebSocket 엔드포인트는 기본적으로 꺼져 있습니다. 이를 활성화하려면:

Servlet 애플리케이션의 경우 WebSocket starter spring-boot-starter-websocket을 추가합니다
WebFlux 애플리케이션의 경우 추가 종속성이 필요하지 않습니다
둘 다 spring.graphql.websocket.path 애플리케이션 속성을 설정해야 합니다

Spring GraphQL은 Web Interception 모델을 제공합니다.
이는 HTTP 요청 헤더에서 정보를 검색하여 GraphQL 컨텍스트에 설정하거나 동일한 컨텍스트에서 정보를 가져와 응답 헤더에 작성하는 데 매우 유용합니다.
Spring Boot를 사용하면 WebGraphQlInterceptor 빈을 선언하여 웹 전송에 등록할 수 있습니다.

Spring MVC와 Spring WebFlux는 CORS(Cross-Origin Resource Sharing) 요청을 지원합니다.
CORS는 다른 도메인을 사용하는 브라우저에서 액세스하는 GraphQL 애플리케이션의 웹 구성에서 중요한 부분입니다.

Spring Boot는 spring.graphql.cors.* 네임스페이스 아래에서 많은 구성 속성을 지원합니다. 다음은 간단한 구성 샘플입니다:

Properties:

spring.graphql.cors.allowed-origins=https://example.org
spring.graphql.cors.allowed-methods=GET,POST
spring.graphql.cors.max-age=1800s

YAML:

spring:
  graphql:
    cors:
      allowed-origins: "https://example.org"
      allowed-methods: GET,POST
      max-age: 1800s

RSocket

RSocket도 WebSocket 또는 TCP 위에서 전송으로 지원됩니다.
RSocket 서버가 구성되면 spring.graphql.rsocket.mapping을 사용하여 특정 경로에서 GraphQL 핸들러를 구성할 수 있습니다.
예를 들어, 해당 매핑을 "graphql"로 구성하면 RSocketGraphQlClient로 요청을 보낼 때 이를 경로로 사용할 수 있습니다.

Spring Boot는 컴포넌트에 주입할 수 있는 RSocketGraphQlClient.Builder<?> 빈을 자동 구성합니다:

Java:

@Component
public class RSocketGraphQlClientExample {

    private final RSocketGraphQlClient graphQlClient;

    public RSocketGraphQlClientExample(RSocketGraphQlClient.Builder<?> builder) {
        this.graphQlClient = builder.tcp("example.spring.io", 8181).route("graphql").build();
    }

Kotlin:

@Component
class RSocketGraphQlClientExample(private val builder: RSocketGraphQlClient.Builder<*>) {

그런 다음 요청을 보냅니다:
include-code::RSocketGraphQlClientExample[tag=request]

Exception Handling

Spring GraphQL을 사용하면 애플리케이션이 순차적으로 호출되는 하나 이상의 Spring DataFetcherExceptionResolver 컴포넌트를 등록할 수 있습니다.
Exception은 GraphQLError 객체 목록으로 resolve되어야 합니다. Spring GraphQL exception handling documentation을 참조하세요.
Spring Boot는 DataFetcherExceptionResolver 빈을 자동으로 감지하고 GraphQlSource.Builder에 등록합니다.

GraphiQL and Schema Printer

Spring GraphQL은 GraphQL API를 사용하거나 개발할 때 개발자를 돕기 위한 인프라를 제공합니다.

Spring GraphQL은 기본적으로 "/graphiql"에 노출되는 기본 GraphiQL 페이지와 함께 제공됩니다.
이 페이지는 기본적으로 비활성화되어 있으며 spring.graphql.graphiql.enabled 속성으로 켤 수 있습니다.
이러한 페이지를 노출하는 많은 애플리케이션은 사용자 정의 빌드를 선호할 것입니다.
기본 구현은 개발 중에 매우 유용하므로 개발 중에 spring-boot-devtools와 함께 자동으로 노출됩니다.

spring.graphql.schema.printer.enabled 속성이 활성화되면 /graphql/schema에서 텍스트 형식으로 GraphQL 스키마를 노출하도록 선택할 수도 있습니다.