[작성자:] [email protected]

1. GraphQL 스키마는 명시적으로 제공

GraphQL 서버는 스키마를 명시적으로 정의합니다. 이 스키마는 클라이언트가 어떤 데이터 타입과 필드를 요청할 수 있는지를 서버에서 정의하는 설계도입니다. 그렇기 때문에 클라이언트가 요청할 수 있는 데이터 구조를 미리 알기 위해서는 서버에서 스키마를 확인해야 합니다.

2. 스키마를 확인하는 방법

클라이언트는 여러 가지 방법을 통해 서버의 스키마 정보를 확인할 수 있습니다.

1) GraphiQL 인터페이스를 통해 스키마 탐색

GraphiQL 같은 개발 도구를 사용하면, 서버의 스키마를 시각적으로 탐색할 수 있습니다.

• GraphiQL은 보통 http://localhost:4000/graphql과 같은 주소로 제공되며, 서버에서 graphiql: true로 활성화되었을 때 사용할 수 있습니다.
• 이 인터페이스에서 제공하는 “Docs” 탭을 열면, 서버가 제공하는 스키마 정보(쿼리와 뮤테이션의 구조, 필드 타입 등)를 탐색할 수 있습니다.

이 툴을 통해 클라이언트는 서버가 제공하는 모든 쿼리와 뮤테이션, 그리고 각 필드의 타입, 인자 등을 쉽게 알 수 있습니다.

2) Introspection 쿼리를 사용하여 스키마 가져오기

GraphQL은 Introspection이라는 메커니즘을 통해 클라이언트가 서버의 스키마를 쿼리로 요청할 수 있게 해줍니다. Introspection 쿼리를 사용하면 서버가 제공하는 전체 스키마 정보를 JSON 형식으로 받아올 수 있습니다.

다음은 Introspection 쿼리 예시입니다:

{
  __schema {
    types {
      name
      fields {
        name
      }
    }
  }
}

이 쿼리는 서버가 제공하는 모든 타입과 각 타입의 필드를 반환해줍니다. 클라이언트는 이 쿼리를 통해 서버에서 어떤 데이터 구조를 제공하는지 알 수 있습니다.

서버는 일반적으로 Introspection 기능을 기본적으로 활성화해 두지만, 보안이나 성능상의 이유로 일부 서버에서는 비활성화할 수 있습니다. 이를 통해 클라이언트는 어떤 쿼리나 뮤테이션을 보낼 수 있는지 파악할 수 있습니다.

3) GraphQL SDL 문서 제공

서버는 **GraphQL SDL (Schema Definition Language)**로 스키마를 정의합니다. 이 SDL은 주로 개발자가 서버에서 작성하며, 서버가 제공하는 API 문서에 포함되어 있을 수 있습니다. 서버 측에서 API 문서를 통해 스키마를 명시적으로 제공할 수도 있습니다.

예를 들어, 문서로 제공된 스키마가 다음과 같이 생겼을 수 있습니다:

graphql코드 복사type Query {
  user(id: ID!): User
  users: [User]
}

type User {
  id: ID!
  name: String!
  email: String!
}

type Mutation {
  addUser(name: String!, email: String!): User
}

이 문서를 보면 클라이언트는 어떤 쿼리와 뮤테이션이 가능한지, 어떤 필드가 있는지 쉽게 파악할 수 있습니다.

3. 클라이언트에서 Apollo Client로 스키마 읽어오기

Apollo Client와 같은 고급 클라이언트 라이브러리는 Introspection을 자동으로 실행해 스키마를 미리 가져와 사용하기도 합니다. 이를 통해 개발자가 어떤 쿼리를 보낼 수 있는지 쉽게 파악할 수 있고, 클라이언트 측에서 스키마에 대한 자동 완성 기능까지 사용할 수 있습니다.

import { ApolloClient, InMemoryCache, gql } from '@apollo/client';

const client = new ApolloClient({
  uri: 'http://localhost:4000/graphql',
  cache: new InMemoryCache(),
  introspection: true, // Introspection 쿼리를 자동으로 실행
});

client
  .query({
    query: gql`
      query {
        __schema {
          types {
            name
            fields {
              name
            }
          }
        }
      }
    `,
  })
  .then(result => console.log(result));

이처럼 클라이언트는 Introspection을 통해 서버에서 제공하는 스키마를 받아올 수 있고, 이를 통해 서버의 모든 쿼리와 뮤테이션, 데이터 구조를 파악할 수 있습니다.

결론

• 명시적 스키마 제공: 서버는 반드시 스키마를 명시적으로 정의하고 클라이언트에 제공해야 합니다. 그래야 클라이언트가 어떤 데이터를 요청할 수 있는지 알 수 있습니다.
• Introspection 쿼리: 클라이언트는 Introspection 쿼리를 통해 서버의 스키마를 요청할 수 있습니다.
• GraphiQL: GraphiQL 같은 개발 도구를 사용하면 스키마를 쉽게 탐색할 수 있습니다.

서버 측에서 Introspection을 제공하는지 여부에 따라 클라이언트는 해당 메커니즘을 사용하여 스키마를 동적으로 파악할 수 있습니다. 스키마를 미리 문서화해 제공하거나, GraphiQL 같은 도구를 통해 탐색할 수도 있습니다.

파이썬에서는 requests 라이브러리를 사용하여 GraphQL 서버에 HTTP 요청을 보내고, 데이터를 가져올 수 있습니다. 또한 **gql**이라는 라이브러리를 사용하면 좀 더 직관적인 방식으로 GraphQL 쿼리와 뮤테이션을 작성할 수 있습니다. 두 가지 방식 모두 예제로 보여드릴게요.

1. requests 라이브러리를 사용한 예제

먼저 requests 라이브러리를 이용한 기본적인 GraphQL 클라이언트 예제입니다.

설치:

pip install requests

GraphQL 쿼리 예제:

import requests

# GraphQL 엔드포인트 설정
url = 'http://localhost:4000/graphql'

# GraphQL 쿼리 작성
query = """
{
  user(id: 1) {
    name
    email
  }
}
"""

# 요청 보내기
response = requests.post(url, json={'query': query})

# 응답 결과 출력
print(response.json())

이 코드는 파이썬의 requests 라이브러리를 사용하여 GraphQL 서버에 쿼리를 보내는 예제입니다. 이때 쿼리를 JSON 형식으로 서버에 전송하고, 서버의 응답을 JSON으로 출력합니다.

결과:

{
  "data": {
    "user": {
      "name": "John",
      "email": "[email protected]"
    }
  }
}

GraphQL 뮤테이션 예제:

이번에는 사용자를 추가하는 뮤테이션 예제를 살펴보겠습니다.

import requests

# GraphQL 엔드포인트 설정
url = 'http://localhost:4000/graphql'

# GraphQL 뮤테이션 작성
mutation = """
mutation {
  addUser(name: "Alice", email: "[email protected]") {
    id
    name
    email
  }
}
"""

# 요청 보내기
response = requests.post(url, json={'query': mutation})

# 응답 결과 출력
print(response.json())

이 코드 역시 requests 라이브러리를 사용하여, 새로운 사용자를 추가하는 뮤테이션을 서버에 보내고 결과를 출력합니다.

2. gql 라이브러리를 사용한 예제

**gql**은 GraphQL 쿼리 및 뮤테이션을 좀 더 Pythonic하게 작성할 수 있는 라이브러리입니다.

설치:

pip install gql requests

GraphQL 쿼리 예제:

from gql import gql, Client
from gql.transport.requests import RequestsHTTPTransport

# GraphQL 엔드포인트 설정
transport = RequestsHTTPTransport(
    url='http://localhost:4000/graphql',
    use_json=True
)

client = Client(transport=transport, fetch_schema_from_transport=True)

# GraphQL 쿼리 작성
query = gql("""
{
  user(id: 1) {
    name
    email
  }
}
""")

# 쿼리 실행
response = client.execute(query)

# 응답 결과 출력
print(response)

gql 라이브러리를 사용하면 GraphQL 쿼리를 쉽게 실행할 수 있으며, 쿼리 문법도 보다 직관적입니다.

결과:

{
  "user": {
    "name": "John",
    "email": "[email protected]"
  }
}

GraphQL 뮤테이션 예제:

from gql import gql, Client
from gql.transport.requests import RequestsHTTPTransport

# GraphQL 엔드포인트 설정
transport = RequestsHTTPTransport(
    url='http://localhost:4000/graphql',
    use_json=True
)

client = Client(transport=transport, fetch_schema_from_transport=True)

# GraphQL 뮤테이션 작성
mutation = gql("""
mutation {
  addUser(name: "Alice", email: "[email protected]") {
    id
    name
    email
  }
}
""")

# 뮤테이션 실행
response = client.execute(mutation)

# 응답 결과 출력
print(response)

이 예제에서는 gql 라이브러리를 사용하여 새로운 사용자를 추가하는 뮤테이션을 실행합니다.

결론

1. requests 라이브러리는 HTTP 요청을 쉽게 처리할 수 있으며, GraphQL 요청도 단순하게 보낼 수 있습니다.
2. gql 라이브러리는 GraphQL 쿼리와 뮤테이션을 조금 더 직관적이고 간결하게 작성할 수 있습니다.