Go 1.27, 새로운 JSON API 'v2' 정식 공개

핵심 요약

• Go 표준 라이브러리의 encoding/json이 15년 만에 메이저 업데이트 되어, encoding/json/v2와 encoding/json/jsontext 패키지가 Go 1.27에서 정식 공개되었다.
• 기존 v1의 문제점으로는 무효한 UTF-8 허용, JSON 객체의 중복 키 허용, nil 슬라이스/맵을 JSON null로 변환, 대소문자 무시 언마샬링, MarshalJSON 메서드 비일관적 호출 등이 있다.
• v1 API는 옵션을 Encoder/Decoder에만 적용 가능하고 Marshal/Unmarshal 함수에는 적용 불가, io.Reader에서 올바르게 언마샬링하기 어려움, 메모리 전체 버퍼링 등의 제약이 있었다.
• v2는 문법 처리(syntactic)와 의미 처리(semantic)를 분리하여, encoding/json/jsontext 패키지로 순수 스트리밍 처리를 지원한다.
• 새로운 MarshalerTo와 UnmarshalerFrom 인터페이스는 Encoder/Decoder에서 작동하여 옵션을 호출 스택 전체에 전달할 수 있고, 재할당을 피할 수 있다.
• v2 API는 Marshal/Unmarshal 함수에 옵션을 첫 번째 인자로 받으며, MarshalWrite/UnmarshalRead로 io.Writer/Reader를 직접 처리하고, MarshalEncode/UnmarshalDecode로 Encoder/Decoder를 직접 작동시킨다.
• v2는 호출자가 WithMarshalers/WithUnmarshalers 옵션으로 임의의 타입에 대한 커스텀 JSON 표현을 지정할 수 있다.
• v2 동작 변경사항으로는 무효한 UTF-8에 오류 반환, 중복 키에 오류 반환, nil 슬라이스/맵을 빈 배열/객체로 변환, 대소문자 민감 언마샬링, omitempty 정의 변경, time.Duration 직렬화 오류 반환이 있다.
• Unmarshal 성능은 v1 대비 최대 10배 향상되었으며, Marshal은 비슷하거나 약간 빠르다. MarshalerTo/UnmarshalerFrom으로 마이그레이션하면 추가 성능 향상을 얻을 수 있다.
• v1과 v2는 상호 호환되도록 설계되어, v1이 내부적으로 v2로 구현되고 v1 호환성 옵션을 통해 구현된다.
• 각 동작 차이는 옵션으로 제어되어, DefaultOptionsV2()나 기존 v1 옵션에서 특정 동작만 변경 가능하다.
• 이 작업은 2020년 말에 시작되어 약 6년에 걸쳐 진행되었으며, Google 외 개발자들이 주도적으로 기여했고, 2025년 초 공식 제안 후 Go 1.25에서 실험 패키지로 시작해 Go 1.27에서 정식 공개되었다.