일반적인 JSON 오류를 해결하는 방법: 개발자를 위한 생존 가이드

Source: Dev.to

죄송합니다. 번역할 텍스트가 제공되지 않았습니다. 번역이 필요한 본문을 알려주시면 바로 도와드리겠습니다.

Introduction

혹시 밤늦게까지 “Unexpected token” 라는 빨간 오류 메시지를 보며 앉아본 적 있나요? JSON (JavaScript Object Notation)은 데이터 교환의 공통 언어이지만, 한 번의 실수인 쉼표 하나나 잘못된 따옴표만으로도 모든 것이 깨질 수 있습니다. 빠른 sanity check가 필요하다면 디버깅을 시작하기 전에 JSON 포매터로 페이로드를 한 번 검증해 보세요.

이 가이드에서는 제가 수년간 마주한 가장 흔한 JSON 오류들을 하나씩 풀어보고, 정확히 어떻게 식별할 수 있는지 보여드리며, 즉시 적용할 수 있는 실용적인 해결책을 제시합니다. API를 처음 접하든, 수년간 서비스를 통합해 오든, 이러한 오류를 읽고 고치는 방법을 알면 큰 좌절을 피할 수 있습니다.

1. 뒤에 오는 쉼표

문제 – 객체나 배열의 마지막 항목 뒤에 쉼표를 남겨두는 것. JavaScript와 달리 JSON은 뒤에 오는 쉼표를 허용하지 않으므로 파서가 *“Unexpected token ‘}’”*와 같은 오류를 발생시킵니다.

잘못된 JSON (뒤에 오는 쉼표)

{
  "name": "John Doe",
  "age": 30,
  "city": "New York",
}

해결 방법

마지막 쉼표를 제거합니다.

{
  "name": "John Doe",
  "age": 30,
  "city": "New York"
}

이를 방지하는 방법

• 편집기에 통합된 JSON 검증기나 린터를 사용하세요; 대부분 자동으로 뒤에 오는 쉼표를 강조 표시합니다.
• 포매터(Prettier, ESLint 등)를 저장 시 뒤에 오는 쉼표를 제거하도록 설정하세요.
• JavaScript에서 객체를 복사할 때는 구성 파일이나 API 호출에 사용하기 전에 검증기(예: CodeItBro의 JSON 검증기)를 통해 검증하세요.

2. 잘못된 인용 부호

Problem – JSON은 모든 문자열과 속성 이름에 큰따옴표를 요구합니다. 작은따옴표는 JavaScript에서는 합법이지만 JSON에서는 “예기치 않은 문자” 오류를 일으킵니다.

Invalid JSON (single quotes)

{
  'name': 'John Doe',
  'active': true
}

Fix

모든 단일 따옴표를 큰따옴표로 교체합니다.

{
  "name": "John Doe",
  "active": true
}

Why this matters

• 일관된 큰따옴표 사용은 다양한 언어와 플랫폼에서 JSON을 유효하게 유지합니다.
• 서로 다른 파서가 단일 따옴표를 다르게 해석할 때 발생할 수 있는 미묘한 버그를 방지합니다.

3. 따옴표 없는 속성 이름

문제 – JavaScript 객체 리터럴에서는 키 주변의 따옴표를 생략할 수 있지만, JSON 절대 허용하지 않습니다.

따옴표 없는 키가 있는 잘못된 JSON

{
  name: "John Doe",
  age: 30
}

해결 방법

모든 속성 이름을 큰따옴표로 감싸세요.

{
  "name": "John Doe",
  "age": 30
}

팁

• 최신 편집기에서는 JSON 구문 모드를 활성화하면 따옴표 없는 키를 보통 강조 표시합니다.
• JSON 린팅을 켜서 이러한 실수를 초기에 잡아내세요.

4. 항목 사이에 누락된 쉼표

Problem – 속성(또는 배열 요소) 사이에 쉼표를 빼먹으면 *“Unexpected string”*와 같은 오류가 발생합니다.

Invalid JSON (missing comma)

{
  "firstName": "John"
  "lastName": "Doe"
}

Fix

누락된 쉼표를 추가합니다.

{
  "firstName": "John",
  "lastName": "Doe"
}

Quick check

오류가 정상적으로 보이는 라인을 가리킬 때, 이전 라인에 쉼표가 누락되었는지 확인하세요.

5. 불일치하는 괄호

Problem – 모든 {는 대응되는 }가 있어야 하고, 모든 [는 대응되는 ]가 있어야 합니다. 길거나 깊게 중첩된 JSON에서는 닫히지 않은 괄호를 놓치기 쉬워서 “Unexpected end of JSON input” 오류가 발생합니다.

Invalid JSON (닫히지 않은 중괄호)

{
  "users": [
    {"name": "Alice"},
    {"name": "Bob"}
  ],
  "total": 2

Fix

모든 구조를 올바르게 닫아 주세요.

{
  "users": [
    {"name": "Alice"},
    {"name": "Bob"}
  ],
  "total": 2
}

Tips

• 대부분의 편집기는 매칭되는 괄호를 강조 표시합니다.
• JSON 포매터/프리티프린터를 사용해 중첩 레벨을 들여쓰기 하면 불일치가 쉽게 드러납니다.

6. 잘못된 숫자 형식

문제 – JSON은 표준 십진수만 지원합니다. 앞에 0이 붙은 숫자, 16진수 표기법, NaN이나 Infinity와 같은 특수 값은 허용되지 않습니다.

잘못된 JSON (잘못된 숫자)

{
  "quantity": 007,
  "price": 0xFF,
  "discount": NaN
}

해결 방법

올바른 십진수를 사용하고, 지원되지 않는 값은 null(또는 유효한 숫자)로 교체합니다.

{
  "quantity": 7,
  "price": 255,
  "discount": null
}

참고

과학적 표기법(예: 1.5e10) 은 유효한 JSON입니다.

7. 지원되지 않는 데이터 유형

문제 – JSON은 여섯 가지 데이터 유형만 지원합니다: string, number, boolean, null, array, object. undefined, 함수, Date 객체, 정규식, 주석 등은 허용되지 않습니다.

Invalid JSON (unsupported types)

{
  "name": "John",
  "age": undefined,
  "callback": function() { return true; },
  "created": new Date()
}

Fix

{
  "name": "John",
  "age": null,
  "callback": null,
  "created": "2025-01-30T10:30:00Z"
}

Conversion checklist

• undefined를 null로 교체합니다.
• 함수를 문자열로 변환하거나 제거합니다.
• 날짜를 ISO‑8601 문자열로 표현합니다.
• 정규식을 일반 문자열로 변환합니다.
• 사용자 정의 객체에 toJSON()을 사용해 직렬화합니다.

8. JSON에서 주석

Problem – JSON은 주석을 허용하지 않습니다. /* … */ 또는 // 를 추가하면 파서가 파일을 거부합니다.

Invalid JSON (with comments)

{
  "name": "John Doe",

  /* Age in years */
  "age": 30
}

메모를 포함하는 옵션

1. 전용 주석 필드(예: _comment)를 추가하여 문자열을 저장합니다.
2. 문서를 별도로 유지합니다(README, docs 폴더 등).
3. JSONC(주석이 포함된 JSON)를 도구가 명시적으로 지원하는 경우에만 사용합니다.

9. 문자열의 이스케이프 시퀀스

JSON 문자열에는 이스케이프 시퀀스(예: \n, \t, \\, \")를 포함할 수 있습니다.
역슬래시가 올바르게 이스케이프되었는지 확인하십시오; 그렇지 않으면 파서가 이를 잘못된 문자로 처리합니다.

최종 팁

• 초기에 검증 – 커밋하기 전에 모든 JSON 페이로드를 검증기나 린터로 실행하세요.
• 편집기 지원 활성화 – 대부분의 최신 IDE는 JSON 구문 강조, 괄호 매칭 및 린팅을 기본 제공합니다.
• 포맷 자동화 – 포맷터(Prettier, jq 등)를 설정하여 저장 시 또는 CI 파이프라인의 일부로 실행되게 하세요.

이러한 일반적인 함정을 염두에 두면, 암호 같은 “Unexpected token” 오류를 추적하는 데 드는 시간을 크게 줄이고 훌륭한 애플리케이션을 만드는 데 더 많은 시간을 할애할 수 있습니다. 즐거운 코딩 되세요!

Source:

Common JSON Errors and How to Fix Them

JSON을 다룰 때, 작은 오타 하나가 몇 시간씩 디버깅을 하게 만들 수 있습니다. 아래는 가장 흔히 마주치는 함정들, 발생 원인, 그리고 이를 피하거나 해결하는 실용적인 방법들입니다.

1. Invalid Escape Sequences

JSON 문자열에서는 특정 이스케이프 시퀀스만 허용됩니다(예: 개행을 위한 \n, 탭을 위한 \t, 유니코드 이스케이프 \u00A9 등). 인식되지 않는 이스케이프가 있으면 파싱 오류가 발생합니다.

Invalid JSON with bad escape sequences

{
  "path": "C:\\new\\folder",
  "message": "Line 1\\xLine 2"
}

Valid JSON using correct escapes

{
  "path": "C\\\\new\\\\folder",
  "message": "Line 1\\nLine 2"
}

Tip: 유효한 이스케이프 시퀀스 목록을 손에 넣어 두거나, 편집기의 구문 강조 기능을 활용해 잘못된 시퀀스를 찾아보세요.

2. Duplicate Property Names

일부 파서가 중복 키를 허용하긴 하지만, JSON 사양에서는 중복 키를 어떻게 처리해야 하는지 정의하지 않습니다. 구현마다 첫 번째 값을 유지하거나, 마지막 값을 사용하거나, 오류를 발생시켜 예측 불가능한 결과를 초래합니다.

Problematic JSON with duplicate keys

{
  "name": "John Doe",
  "age": 30,
  "name": "Jane Doe"
}

Corrected JSON – each key appears only once

{
  "firstName": "John",
  "lastName": "Doe",
  "age": 30
}

Advice: 의미 있는 고유한 속성 이름을 사용해 데이터를 플랫폼 간에 일관되게 유지하세요.

3. Debugging Large JSON Files

JSON 파일이 크고 오류 원인이 명확하지 않을 때는 체계적인 접근이 큰 도움이 됩니다.

Techniques

• Use a JSON validator – 온라인 도구는 오류를 강조 표시하고 라인 번호를 보여줍니다.
• Format the file first – 적절한 들여쓰기는 괄호 불일치와 같은 구조적 문제를 드러냅니다.
• Binary search your JSON – 내용의 절반을 주석 처리(또는 임시 삭제)하고 남은 절반을 검증한 뒤, 문제를 찾을 때까지 반복합니다.
• Check the encoding – 파일이 UTF‑8인지 확인하세요; 숨겨진 BOM이나 특수 문자가 모호한 오류를 일으킬 수 있습니다.
• Validate programmatically – 파싱을 try/catch 블록으로 감싸고 오류 메시지와 위치를 로그에 남깁니다.

4. Preventing Errors – Best Practices

Closing Thoughts

JSON을 올바르게 다루는 일은 화려하지 않지만 필수적입니다. 핵심 규칙—끝에 쉼표 금지, 문자열과 키는 반드시 이중 따옴표, 올바른 숫자 형식, 유효한 이스케이프 시퀀스, 중복 키 금지—을 기억하면 프로덕션에 도달하기 전에 대부분의 구문 오류를 제거할 수 있습니다. 문제가 발생하더라도 체계적인 디버깅과 좋은 도구를 활용하면 빠르게 원인을 찾고 해결할 수 있습니다.

최근에 이러한 오류와 싸워본 적이 있나요?
어떤 도구나 기법이 여러분을 구해줬나요? 댓글로 이야기를 공유하고, 서로가 늦은 밤에 겪는 JSON 골칫거리를 피하도록 도와요.

이 가이드가 도움이 되었다면 북마크하거나 팀과 공유해 주세요. 즐거운 코딩 되세요!