본문으로 건너뛰기
· backend · 2분 읽기

GraphQL 입력 확장에서 누락과 null을 구분하기

일괄 API에 항목별 옵션을 추가할 때 기존 공통 옵션을 그대로 두면 입력이 겹친다. 항목별 값이 없을 때 공통 값을 쓰면 되지만, 명시적으로 null을 보냈을 때도 같은 의미인지 결정해야 한다.

nullable 필드를 추가한 뒤에는 기존 요청의 처리 결과도 비교한다. 옵션의 기본값이나 우선순위가 바뀌면 같은 요청의 결과가 달라질 수 있다.

공통 옵션과 항목별 옵션

graphql
input BatchInput {
  requestKey: ID!
  commonNote: String
  items: [ItemInput!]!
}

input ItemInput {
  id: ID!
  note: String
}

예제는 메모 필드 하나다. 정책은 항목별 note가 누락되면 공통 메모를 상속하고, null이면 메모를 명시적으로 비우고, 문자열이면 그 값을 사용한다. 빈 문자열은 유효한 별도 값으로 둔다.

항목 note공통 commonNote최종 값
누락문자열공통 문자열
null문자열null
빈 문자열문자열빈 문자열
다른 문자열문자열항목 문자열
누락누락 또는 null기존 기본 동작인 null

이 표는 GraphQL 자체의 업무 정책이 아니라 예제 API가 선택한 우선순위다. GraphQL 입력 강제 변환 규칙은 누락과 명시적 null을 구분한다.

resolver까지 presence를 유지한다

Go에서 필드를 단순 *string으로 받으면 생성기와 설정에 따라 누락과 null이 모두 nil로 표현될 수 있다. presence를 보존하는 wrapper나 입력 map을 사용해야 한다.

go
type OptionalString struct {
    Present bool
    Value   *string
}

func effectiveNote(item, common OptionalString) *string {
    if item.Present {
        return item.Value
    }
    return common.Value
}

이 코드는 선택 규칙만 보여 준다. GraphQL 입력을 OptionalString으로 변환하는 부분은 사용하는 생성기의 기능에 맞춰 구현한다. 함수 단위 테스트만으로 wire의 누락과 null이 보존되는지 확인할 수는 없다.

여러 옵션을 객체로 받는다면 객체 전체를 교체할지 필드별로 병합할지도 정해야 한다. 객체가 존재한다고 그 안의 누락 필드까지 명시적으로 지운 것으로 처리하면 예상과 달라질 수 있다.

기본값의 적용 위치

스키마에 기본값을 넣으면 입력 강제 변환 단계에서 누락 값이 채워질 수 있다. resolver에서 “사용자가 보내지 않았음”을 알아야 한다면 기본값을 어디서 적용할지 먼저 정한다.

기존 공통 옵션의 의미를 유지하면서 새 항목 옵션을 추가하는 것이 첫 단계다. 기존 필드를 바로 필수로 만들거나 삭제하지 않고, 구클라이언트가 보낸 변수와 mutation 문서를 그대로 실행해 본다.

클라이언트 생성 코드도 확인한다. 어떤 직렬화 코드는 undefined를 생략하고 어떤 코드는 null을 넣는다. 스키마에 대한 설명만 바꿨는데 기존 클라이언트가 다른 의미의 요청을 보낼 수 있다.

재시도 계약에 새 옵션 포함하기

요청키 기반 멱등 처리가 있다면 입력 서명에도 옵션을 반영한다. 같은 요청키로 첫 요청은 메모 A, 두 번째 요청은 메모 B인데 ID 목록만 해시하면 다른 요청을 같은 것으로 취급한다.

예제에서는 정규화한 최종 옵션과 계약 버전을 서명에 넣는다. 단, 누락과 null이 감사 기록이나 업무상 의미에서 다르면 그 차이도 보존한다. “결과가 비슷하다”는 이유로 모든 입력을 합치지 않는다.

서버 기본값이 배포 후 바뀔 수 있다면 진행 중 요청의 해석도 고정해야 한다. 동일 요청키의 재시도에서 저장된 계약 버전으로 입력을 검증하고 기존 결과를 반환하는 방식으로, 현재 기본값이 과거 작업을 재해석하지 않게 한다.

검증할 요청 조합

다음은 미실행 테스트 항목이다. 표의 입력 조합을 mutation과 variables JSON으로 요청해 확인한다.

  • 구클라이언트의 항목 옵션 없는 요청이 기존 결과를 유지한다.
  • note 누락, null, 빈 문자열이 resolver에서 구분된다.
  • 입력 객체의 누락과 객체 내부 필드의 누락을 다르게 처리한다.
  • 같은 요청키에 옵션만 바꾸면 정의한 충돌 응답이 나온다.
  • 기본값 변경 전 요청의 재시도가 동일 작업으로 처리된다.
공유하기 X LinkedIn

관련 글