GraphQL Mutation 설계하기

Apollo 공식 블로그 원문을 번역·정리한 글로, 좋은 GraphQL Mutation API를 설계할 때 반드시 고려해야 할 5가지 원칙을 코드 예시와 함께 구체적으로 다룬다. API의 장기적 확장성과 사용성을 동시에 확보하는 실용적 가이드다.

핵심 포인트 - 작명 원칙: 동사 먼저, 목적어는 선택. createUser, likePost, updateComment (O) — userCreate, postLike (X). 일부 팀은 알파벳 정렬·CRUD 패턴 이유로 역순 선호 (Shopify 등) - 명확성 원칙: 범용 mutation 지양. sendEmail(type: PASSWORD_RESET) 보다 sendPasswordResetEmail이 타입 강제·GraphiQL 가독성·미래 인자 추가 측면에서 훨씬 우수 - 단일 input 객체: mutation은 input이라는 이름의 하나의 nullable이 아닌 고유 InputType을 받아야 함. updatePost(input: {id, newText}) (O) — updatePost(id:4, newText:"...") (X) - 고유 Payload 타입: 각 mutation마다 고유한 반환 타입 사용. MutationNamePayload 패턴. mutation 결과에 추후 필드 추가가 용이하고 클라이언트 타입 안전성 확보 - 중첩 활용: 연관된 반환값을 payload 안에 중첩 구조로 배치. 예: UpdatePostPayload { post { ... }, errors { ... } } 형태

상세 정리 - 단일 input 사용 이유 1: 클라이언트에서 변수 하나(input 객체)만 관리하면 됨 — 인자마다 별개 변수 선언 불필요 - 단일 input 사용 이유 2: 추후 필드 추가 시 기존 클라이언트 코드 변경 없이 input 타입에만 새 필드 추가 가능 - 고유 payload 이유: 여러 mutation이 같은 반환 타입 공유하면 한 mutation을 위한 필드 추가가 다른 mutation에 영향. 각 mutation 전용 타입으로 독립적 진화 가능 - 범용 mutation의 실패: sendEmail(type: PASSWORD_RESET)처럼 열거형 타입으로 분기하면 → 특정 이메일 타입에만 필요한 추가 인자를 모든 타입에 공개하는 문제 발생 - 의미 있는 mutation: UI가 만들 수 있는 사용자 행동과 1:1 대응. 백엔드 최적화·보안 측면에서도 유리 - camelCase 명명: GraphQL 컨벤션. createUser, updateUserProfile 형태 - 중첩 payload의 에러 처리: errors 필드를 payload 내부에 포함해 HTTP 상태코드와 별도로 비즈니스 오류를 표현 가능

왜 읽나: GraphQL Mutation 설계의 5가지 핵심 원칙(작명·명확성·단일 input·고유 payload·중첩)을 실제 코드 예시와 함께 익혀 장기적으로 유지보수하기 쉬운 API를 설계할 수 있다.