JSON 핵심 문법 오류 패턴과 실전 디버깅 완벽 가이드

RFC 8259 및 ECMA-404 표준으로 정의된 JSON(JavaScript Object Notation)은 현대 웹 API의 사실상 표준 데이터 직렬화 형식입니다. 겉보기에는 자바스크립트 객체 리터럴과 매우 유사해 보이지만, JSON 규격은 자바스크립트보다 훨씬 엄격합니다.

불필요한 쉼표 하나, 작은따옴표 사용, 문자열 내부의 이스케이프되지 않은 제어 문자만으로도 JSON.parse()는 즉시 SyntaxError 예외를 발생시키고 실행을 중단합니다. 프로덕션 환경에서 처리되지 않은 JSON 파싱 에러는 프론트엔드 하이드레이션 오류나 백엔드 500 내부 서버 오류를 유발할 수 있습니다.

RFC 8259 규격을 위반하여 파서가 입력을 거부하는 대표적인 5가지 사례입니다:

1. 마지막 쉼표(Trailing Comma): 자바스크립트와 달리 JSON 표준은 객체나 배열의 마지막 요소 뒤에 오는 쉼표({"a": 1,})를 명시적으로 금지합니다.
2. 작은따옴표('') 사용: JSON의 모든 문자열과 객체 키는 반드시 큰따옴표("key": "value")로 감싸야 합니다. 작은따옴표나 템플릿 리터럴(백틱)은 허용되지 않습니다.
3. 따옴표가 생략된 객체 키: 자바스크립트에서는 { id: 1 }이 허용되지만, JSON에서는 반드시 {"id": 1}이어야 합니다.
4. 이스케이프되지 않은 제어 문자: 문자열 값 내부의 개행, 탭 등은 반드시 \n, \t와 같이 역슬래시로 이스케이프해야 합니다.
5. 잘못된 숫자 형식: 선행 0(0123), 16진수(0x10), NaN 또는 Infinity는 JSON 표준 숫자가 아닙니다.

// ❌ 잘못된 JSON (SyntaxError 발생)
{
  'name': 'DevUtils',
  "version": 2.0,
  "features": [
    "formatter",
    "validator",
  ]
}

// ✅ 올바른 RFC 8259 준수 JSON
{
  "name": "DevUtils",
  "version": 2.0,
  "features": [
    "formatter",
    "validator"
  ]
}

파싱(Parsing) 에러와 달리, 객체를 문자열로 직렬화(Serialization)할 때 발생하는 대표적인 문제가 바로 순환 참조입니다.

객체가 자기 자신을 참조하고 있을 때 JSON.stringify()를 호출하면 TypeError: Converting circular structure to JSON 예외가 발생합니다. JSON은 트리 구조만을 표현할 수 있고 순환 그래프 구조를 지원하지 않으므로, 직렬화 전에 순환 참조 필드를 제거하거나 커스텀 replacer 함수를 사용해야 합니다.

자바스크립트의 기본 숫자는 IEEE 754 배정밀도 64비트 부동소수점 형식을 사용합니다. 이로 인해 자바스크립트에서 안전하게 다룰 수 있는 최대 정수는 Number.MAX_SAFE_INTEGER(2^53 - 1, 즉 9,007,199,254,740,991)까지입니다.

PostgreSQL의 BIGINT나 트위터 Snowflake ID, 분산 시스템의 64비트 ID를 순수 숫자 형태로 JSON에 담아 전송하면, 브라우저의 JSON.parse() 과정에서 하위 비트가 잘려 나가는 정밀도 손실이 발생합니다. 예를 들어 9007199254740993은 자동으로 9007199254740992로 변환됩니다. 따라서 대형 정수 ID는 API 설계 시 항상 문자열(String)로 감싸서 주고받아야 합니다.

// 자바스크립트 숫자 정밀도 손실 예시
const raw = '{"userId": 9007199254740993}';
const parsed = JSON.parse(raw);
console.log(parsed.userId); // 출력: 9007199254740992 (데이터 왜곡 발생!)

// 해결책: 64비트 정수는 문자열로 전송
const safeRaw = '{"userId": "9007199254740993"}';
const safeParsed = JSON.parse(safeRaw);
const bigId = BigInt(safeParsed.userId); // 정확한 값 보존

• 반드시 try-catch 블록으로 파싱 감싸기: 외부 웹훅이나 서드파티 API 응답이 항상 올바른 JSON일 것이라고 가정해서는 안 됩니다.
• 스키마 런타임 검증 도입: 파싱 후 Zod, Yup, Ajv(JSON Schema) 등을 활용하여 객체 형태와 필수 필드를 런타임에 보증하세요.
• Content-Type 헤더 검증: 요청 및 응답 시 Content-Type: application/json을 반드시 설정하고, 본문 디시리얼라이즈 전에 헤더를 확인하세요.
• 온라인 포맷터로 사전 검증: 복잡한 설정 파일이나 모의 데이터(Mock data)를 코드에 커밋하기 전에 DevUtils JSON Formatter로 유효성을 사전 점검하세요.