PHP Academy · 강의

GraphQL과 REST 비교

언제 GraphQL이 REST보다 뛰어난지, 그 이유는 무엇인지 이해합니다.

GraphQL과 REST 비교은(는) CoddyKit의 무료 PHP Academy 강의입니다. 이것은 4개 중 1번째 강의입니다. 아래에서 전체 강의를 무료로 읽을 수 있으며, 내장 코드 에디터와 24/7 AI 튜터와 함께 브라우저에서 직접 실습할 수 있습니다. 이 강의는 PHP Academy 학습 경로의 일부이며, 진행 상황이 웹과 CoddyKit 앱에 동기화됩니다. PHP Academy 강의에는 총 4개의 강의가 포함되어 있습니다.

GraphQL을 사용하는 이유

PHP로 REST API를 배포하는 방법은 이미 알고 계실 것입니다. GraphQL은 HTTP를 대체하거나 모든 문제를 해결하는 만능 도구가 아닙니다. 클라이언트가 정확히 필요한 것을 설명하고, 한 번의 왕복으로 정확히 그 결과를 받게 해 주는 쿼리 언어이자 타입 시스템입니다.

이 레슨에서는 두 방식을 솔직하게 비교합니다. GraphQL이 실제로 더 나은 경우, REST를 선택해야 하는 경우, 그리고 GraphQL이 운영 측면에서 초래하는 비용을 살펴봅니다.

과다 조회와 과소 조회

REST의 대표적인 문제점은 다음과 같습니다.

과다 조회: GET /users/1이 40개의 필드를 반환하지만 사용자 인터페이스에는 3개만 필요합니다.
과소 조회: 사용자의 게시물과 각 게시물의 댓글 수를 표시하려면 /users/1을 호출한 다음 /users/1/posts를 호출하고, 이어서 N개의 댓글 엔드포인트를 호출해야 합니다.

GraphQL은 이를 하나의 선언적 요청으로 통합합니다.

query {
  user(id: 1) {
    name
    posts {
      title
      commentCount
    }
  }
}

단일 엔드포인트와 타입이 지정된 스키마

REST는 여러 URL을 노출하지만 GraphQL은 강한 타입의 스키마를 기반으로 하는 하나의 엔드포인트(일반적으로 POST /graphql)를 노출합니다. 스키마는 계약이며 introspection을 지원하므로 도구(자동 완성, 문서, 코드 생성)를 별도 비용 없이 사용할 수 있습니다.

아래는 SDL로 작성한 최소한의 스키마입니다. 가능한 모든 응답의 형태를 미리 알 수 있습니다.

type User {
  id: ID!
  name: String!
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  commentCount: Int!
}

type Query {
  user(id: ID!): User
}

쿼리를 그대로 반영하는 응답

핵심적인 특성은 JSON 응답의 형태를 쿼리에서 예측할 수 있다는 점입니다. 클라이언트는 필드 이름을 추측할 필요가 없습니다. 따라서 버전 관리에 따른 변경 부담이 크게 줄어듭니다. 기존 클라이언트를 깨뜨리지 않고 필드를 추가할 수 있으며, @deprecated를 사용해 필드를 사용 중단 처리할 수 있으므로 /v2 URL을 새로 만들 필요가 없습니다.

{
  "data": {
    "user": {
      "name": "Ada",
      "posts": [
        { "title": "On Engines", "commentCount": 12 }
      ]
    }
  }
}

GraphQL이 REST보다 나은 경우

다음과 같은 경우에는 GraphQL이 더 적합합니다.

서로 다른 데이터 요구 사항을 가진 다양한 클라이언트(웹, iOS, Android)를 지원합니다.
클라이언트가 동적으로 탐색하는 깊은 관계를 가진 그래프 형태의 데이터입니다.
하나의 타입이 지정된 게이트웨이 뒤에서 여러 백엔드를 집계하려고 합니다.
프런트엔드의 빠른 반복 개발이 중요하고, 백엔드 엔드포인트를 끊임없이 변경하는 일을 피하고 싶습니다.

REST가 여전히 앞서는 경우

무조건 GraphQL을 선택하지는 마십시오. 다음과 같은 경우에는 REST가 더 단순하고 더 나은 선택인 경우가 많습니다:

HTTP 캐싱이 필요할 때 — CDN/엣지 캐시는 URL과 메서드를 기준으로 키를 생성하므로, 단일 POST /graphql은 캐시에서 식별할 수 없습니다.
API가 리소스 중심이고 안정적일 때(몇 가지 엔터티에 대한 생성·조회·수정·삭제).
파일 업로드/다운로드나 스트리밍에 의존할 때. REST에서는 멀티파트와 바이트 범위가 기본 기능으로 지원됩니다.
일반적인 REST 의미 체계를 기대하는 서드 파티 소비자가 있을 때.

간단한 PHP 비교

다음은 PHP에서 REST 방식으로 같은 데이터를 조합한 예입니다 — 클라이언트는 여전히 여러 번 호출하거나 삽입 매개변수를 직접 만들어야 한다는 점에 주목하십시오. 반면 GraphQL은 이러한 선택 로직을 클라이언트로 옮깁니다.

<?php
// REST: server decides the payload shape
function userResource(int $id): array {
    return [
        'id' => $id,
        'name' => 'Ada',
        'email' => 'ada@example.com',   // over-fetched by mobile
        'createdAt' => '1815-12-10',
        'posts' => [                       // pre-embedded, all-or-nothing
            ['title' => 'On Engines', 'commentCount' => 12],
        ],
    ];
}

header('Content-Type: application/json');
echo json_encode(userResource(1), JSON_PRETTY_PRINT);

GraphQL이 추가하는 비용

GraphQL은 복잡성을 서버로 옮깁니다. 이제 직접 책임져야 하는 새로운 문제는 다음과 같습니다:

N+1 쿼리 — 일괄 처리하지 않으면 중첩된 해결기가 각 노드마다 데이터베이스 쿼리를 하나씩 실행합니다(DataLoader).
쿼리 비용/깊이 제한 — 악의적으로 깊게 중첩된 쿼리로 서비스 거부 공격을 받을 수 있습니다.
캐싱이 더 어려워집니다. 일반적으로 HTTP 계층이 아니라 해결기/데이터 계층에서 캐시합니다.
오류 처리 방식이 다릅니다 — 200 OK 응답에도 errors 배열이 포함될 수 있습니다.

오류: 오류 배열이 포함된 200 응답

REST 상태 코드와 달리 GraphQL은 관례적으로 HTTP 200을 반환하고 본문 안에 부분적인 실패를 보고합니다. data에는 일부만 값이 채워질 수 있으며 errors에는 실패한 항목이 나열됩니다. 클라이언트는 두 항목을 모두 검사해야 합니다.

{
  "data": { "user": null },
  "errors": [
    {
      "message": "User not found",
      "path": ["user"],
      "extensions": { "code": "NOT_FOUND" }
    }
  ]
}

선택 기준

실용적인 경험칙은 다음과 같습니다:

공개 API이며 캐시 사용이 많고 리소스 생성·조회·수정·삭제 중심인 경우 → REST.
연결된 데이터를 다양한 고기능 클라이언트에 제공하는 내부/제품 API인 경우 → GraphQL.
여러 백엔드를 하나의 타입이 지정된 계약으로 통합해야 하는 경우 → GraphQL 게이트웨이.

둘 다 운영하는 것은 흔하고 바람직합니다. 웹훅/업로드에는 REST를, 앱의 읽기 그래프에는 GraphQL을 사용할 수 있습니다.

PHP에서 HTTP를 통해 GraphQL 제공하기

운영 측면에서 PHP의 GraphQL 엔드포인트는 JSON 본문을 읽고, query와 variables를 꺼내 스키마에 대해 실행한 뒤 { data, errors }를 반환하는 하나의 경로입니다. REST의 여러 경로와 비교하면 전송 방식은 일관되며, 모든 변형은 클라이언트가 보내는 쿼리 문자열에 들어 있습니다.

<?php
// Minimal GraphQL-over-HTTP entry point
$input = json_decode(file_get_contents('php://input'), true) ?? [];
$query = $input['query'] ?? '';
$variables = $input['variables'] ?? null;

// $result = GraphQL::executeQuery($schema, $query, null, $ctx, $variables);
// header('Content-Type: application/json');
// echo json_encode($result->toArray());
var_dump(['query' => $query, 'variables' => $variables]);

간단 확인

REST가 GraphQL보다 확실히 유리한 경우는 언제입니까?

복습

GraphQL과 REST를 핵심 측면에서 비교했습니다:

GraphQL은 타입이 지정된 단일 엔드포인트와 클라이언트 주도 선택으로 과다 조회와 과소 조회 문제를 해결합니다.
다수의 클라이언트, 그래프 형태의 데이터, 백엔드 통합에 강합니다.
REST는 캐시 가능한 공개 API, 단순한 생성·조회·수정·삭제, 업로드, 일반적인 소비자에 적합합니다.
GraphQL은 비용을 서버로 옮깁니다. N+1, 쿼리 비용 제한, 캐싱, 오류가 포함된 200 응답의 의미 체계를 서버가 처리해야 합니다.

다음: webonyx/graphql-php로 실제 스키마를 구축합니다.

자주 묻는 질문

“GraphQL과 REST 비교” 강의는 무료인가요?

네 — “GraphQL과 REST 비교” 전체 내용을 이 웹사이트에서 무료로 읽을 수 있습니다. 인터랙티브하게 실습하려면(내장 코드 에디터와 24/7 AI 튜터), CoddyKit PRO로 업그레이드하면 PHP Academy 강의 전체를 잠금 해제할 수 있습니다. PHP Academy 강의에는 총 4개의 강의가 포함되어 있습니다.

“GraphQL과 REST 비교”에서 뭘 배우나요?

언제 GraphQL이 REST보다 뛰어난지, 그 이유는 무엇인지 이해합니다. 브라우저에서 직접 실행하는 실습 코드로 PHP Academy을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.

PHP Academy을(를) 시작하는 데 경험이 필요한가요?

사전 경험은 필요하지 않습니다. CoddyKit의 PHP Academy은(는) 초급자부터 고급 학습자까지를 위해 구성되어 있으므로, 여기서 시작하거나 처음부터 시작할 수 있으며 자신의 속도대로 진행할 수 있습니다. 이것은 4개 중 1번째 강의입니다.

“GraphQL과 REST 비교” 강의는 얼마나 걸리나요?

대부분의 CoddyKit 강의는 약 5~10분이 소요됩니다. 각 강의는 간결하고 인터랙티브하여 꾸준한 진행이 가능하며, 웹과 앱에서 중단한 부분부터 바로 시작할 수 있습니다.

이 PHP Academy 강의에서 코드를 작성하고 실행할 수 있나요?

네. 모든 PHP Academy 강의에는 내장 코드 에디터가 포함되어 있으므로, 브라우저에서 바로 실제 코드를 작성하고 실행한 후 즉시 AI 피드백을 받을 수 있습니다 — 로컬 설정이 필요 없습니다.

이 강의의 모든 강의

← PHP Academy(으)로 돌아가기