백엔드
GraphQL Mutation 설계하기
두줄요약
GraphQL mutation을 사용자 행동 중심으로 명명하고 단일 input·전용 payload 구조를 권장했습니다. 중첩을 활용해 버전 없는 API의 확장성과 메타데이터 추가 여지를 확보합니다.
구조와 흐름
- 동사 우선 camelCase와 사용자 행동 중심의 명시적 mutation 명명
- mutation마다
input이라는 단일 non-null 입력 객체와 고유 payload 타입 정의 - 입력과 반환값의 중첩 구조로 필드·메타데이터 확장 여지 확보
선택 이유
- 범용 mutation보다 UI의 의미 있는 동작에 대응하는 명시적 mutation의 높은 활용성
- 단일 입력 변수 사용에 따른 클라이언트 호출과 GraphQL 문서 단순화
- 각 payload에
userErrors,clientMutationId, 추가 반환값을 수용할 수 있는 구조
주의할 점
sendEmail(type: PASSWORD_RESET)같은 범용 API의 입력 검증 및 탐색성 저하- 단일 객체 직접 반환 시 추가 반환 타입·메타데이터 도입의 어려움
- 상태 전환 mutation에서 클라이언트가 불필요한 상태값을 직접 지정하는 엣지 케이스
적용해볼 점
- Todo 예제처럼
createTodo,toggleTodoCompleted,updateTodoText를 분리한 스키마 설계 - 현재 입력이 비어 있어도 미래 확장을 위한 빈 input 객체와 전용 payload 유지
