Blog

🚨 도입부

Node.js를 사용하면서 ‘SyntaxError: Unexpected token in JSON’ 에러를 만나면 여러분도 좌절감을 느끼실 것입니다. 이 에러는 JSON 데이터를 다루는 과정에서 자주 발생하며, 많은 개발자들을 혼란에 빠뜨립니다. 예를 들어, 외부 API로부터 JSON 응답을 받을 때, 파일에서 JSON 데이터를 읽을 때, 또는 JSON 데이터를 직접 생성할 때 이 오류가 발생할 수 있습니다. JSON은 웹 개발에서 데이터를 교환하는 표준 형식이기 때문에, 이 에러는 다양한 상황에서 나타날 수 있습니다. 다행히 이 글을 통해 여러분은 이 에러의 발생 원인과 구체적인 해결책을 배우게 될 것입니다. 해결에 드는 시간은 상황에 따라 다르지만, 기본적인 시나리오는 몇 분 이내에 해결 가능하며, 복잡한 경우에도 이 글의 가이드를 따르면 쉽게 해결할 수 있습니다.

🔍 에러 메시지 상세 분석

이 에러의 정확한 메시지는 ‘SyntaxError: Unexpected token in JSON’입니다. 이 오류는 JavaScript 엔진이 JSON 데이터를 파싱할 때 예상치 못한 문자를 만나면 발생합니다. 예를 들어, JSON 데이터의 시작이나 끝에 잘못된 문자나 기호가 포함된 경우입니다. 이 에러는 다음과 같은 다양한 상황에서 발생할 수 있습니다:

• 잘못된 JSON 형식: 키와 값의 쌍이 올바르게 구성되지 않음
• 응답 데이터의 시작이나 끝에 불필요한 문자가 포함됨
• JSON 문자열에 이스케이프되지 않은 특수 문자가 포함됨
• API 호출 시 서버에서 제대로 포맷되지 않은 데이터를 반환함
• 파일 시스템에서 잘못된 형식의 JSON 데이터를 읽어옴

이 에러 메시지를 읽을 때, 초보자들은 ‘Unexpected token’이 무엇을 의미하는지 혼란스러울 수 있습니다. 이는 JSON 파서가 문법적으로 잘못된 지점을 가리키며, 일반적으로 데이터가 잘못 포맷되었음을 의미합니다. 이 에러와 비슷한 오류로는 ‘SyntaxError: Unexpected end of JSON input’, ‘SyntaxError: JSON.parse: unexpected character’ 등이 있습니다. 이런 오류들은 모두 JSON 포맷의 문제에서 기인하므로, JSON 구조를 꼼꼼히 확인하는 것이 중요합니다.

🧐 발생 원인 분석

이 에러의 주요 원인을 5가지만 꼽아보겠습니다:

1. 잘못된 JSON 형식: JSON 데이터가 잘못된 문법으로 구성되어 있을 때 발생합니다. 예를 들어, JSON 키가 따옴표로 감싸져 있지 않거나 콜론(:) 다음에 값이 없을 때입니다.
2. 응답 데이터의 잘못된 포맷: API로부터 받은 JSON 데이터의 시작이나 끝에 잘못된 문자가 포함되어 있을 수 있습니다. 예를 들어, 응답 데이터가 HTML 태그로 감싸여 있을 때입니다.
3. 이스케이프 처리되지 않은 특수 문자: JSON 데이터 내 특수 문자가 이스케이프 처리되지 않으면 파싱 오류가 발생할 수 있습니다. 예를 들어, 문자열 내에 백슬래시가 제대로 이스케이프되지 않은 경우입니다.
4. 잘못된 데이터 타입: JSON 데이터에 숫자 대신 문자열이 포함될 때도 문제가 발생할 수 있습니다. 예를 들어, 숫자 데이터를 따옴표로 감싸 문자열로 처리할 경우입니다.
5. 비동기 요청의 불완전한 처리: 비동기적으로 데이터를 요청할 때, 서버에서 제대로 완료되지 않은 데이터를 받을 수 있습니다.

이런 원인들은 각각의 상황에서 다르게 나타날 수 있으며, 이를 확인하기 위해 JSON 데이터를 직접 검사하거나 JSON 파서 툴을 이용하여 검증하는 방법이 있습니다. 예를 들어, JSON 데이터가 유효한지 확인하려면 온라인 JSON 검사기를 사용할 수 있습니다.

✅ 해결 방법

이제 이 에러를 해결하는 방법을 살펴보겠습니다.

즉시 해결: 1분 내 적용 가능한 빠른 방법

1. JSON Validator 사용: JSONLint와 같은 온라인 JSON 검사기를 사용하여 JSON 형식을 검사하세요. 잘못된 부분을 쉽게 찾을 수 있습니다.
2. JSON 데이터 로그 확인: JSON 데이터를 파싱하기 전에 console.log를 사용하여 데이터를 출력하고, 예상치 못한 문자가 있는지 확인하세요.
3. API 응답 체크: API 응답을 직접 브라우저에서 확인하여 예상치 못한 문자가 있는지 검사하세요.

표준 해결: 일반적이고 안전한 해결법

1. JSON.stringify 사용: 데이터를 JSON 형식으로 변환할 때 JSON.stringify()를 사용하여 정확한 형식으로 변환하세요.

   const obj = { name: "John", age: 30 };
   const jsonString = JSON.stringify(obj);
   console.log(jsonString); // "{"name":"John","age":30}"
   

   이 코드는 객체를 JSON 문자열로 변환하여 파싱 오류를 방지합니다.

2. JSON.parse 예외 처리: JSON.parse()를 사용할 때 try-catch 블록을 사용하여 예외를 처리하세요.

   const jsonString = '{ "name": "John", "age": 30 }';
   try {
     const obj = JSON.parse(jsonString);
     console.log(obj);
   } catch (error) {
     console.error('Invalid JSON:', error);
   }
   

   이 코드는 JSON 파싱 중 오류가 발생하면 에러를 콘솔에 출력합니다.

3. API 호출 후 데이터 검사: API 호출 후 응답 데이터를 검사하여 JSON이 유효한지 확인하세요.

   fetch('https://api.example.com/data')
     .then(response => response.json())
     .then(data => {
       console.log(data);
     })
     .catch(error => {
       console.error('Error fetching data:', error);
     });
   

   이 코드는 API로부터 데이터를 받아 JSON으로 변환하고, 오류가 발생할 경우 콘솔에 출력합니다.

4. JSON 데이터 파일 검사: 파일 시스템에서 읽어온 JSON 데이터가 유효한지 확인하세요.

   const fs = require('fs');
   
   fs.readFile('data.json', 'utf8', (err, data) => {
     if (err) {
       console.error('Error reading file:', err);
       return;
     }
     try {
       const obj = JSON.parse(data);
       console.log(obj);
     } catch (error) {
       console.error('Invalid JSON in file:', error);
     }
   });
   

   이 코드는 파일에서 JSON 데이터를 읽고, 파싱 중 오류가 발생하면 에러를 출력합니다.

5. JSON 데이터의 특수 문자 이스케이프: JSON 문자열에 포함된 특수 문자를 이스케이프 처리하세요.

   const jsonString = '{ "text": "This is a string with a \"quote\"." }';
   const obj = JSON.parse(jsonString);
   console.log(obj);
   

   이 코드는 JSON 문자열 내의 특수 문자를 이스케이프 처리하여 파싱 오류를 방지합니다.

고급 해결: 복잡한 상황을 위한 해결법

1. 데이터 유효성 검사 라이브러리 사용: JSON Schema Validator를 사용하여 데이터를 검증하고, JSON 형식이 유효한지 확인하세요.
2. API 응답의 데이터 형식 지정: 서버 측에서 데이터 응답 형식을 명시적으로 지정하여 클라이언트에서 파싱에 문제가 없도록 하세요.
3. 데이터 전환 로직 개선: 복잡한 데이터 구조를 다룰 때, 데이터 전환 로직을 개선하여 JSON 포맷의 일관성을 유지하세요.

각 방법의 장단점과 사용 상황은 다음과 같습니다. JSON Validator는 빠르고 간단하지만, 직접적인 문제 해결에는 한계가 있습니다. JSON.stringify와 예외 처리는 간단한 에러를 해결하는데 유용하지만, 복잡한 데이터 구조에는 적합하지 않을 수 있습니다. 고급 해결책은 복잡한 상황에 적합하지만, 구현에 시간이 걸릴 수 있습니다.

🛡️ 예방법 및 베스트 프랙티스

이 에러가 재발하지 않도록 하기 위해 몇 가지 예방 방법을 제안합니다:

• 항상 JSON.stringify와 JSON.parse를 사용할 때 예외 처리를 포함하세요.
• JSON Schema를 사용하여 데이터의 유효성을 지속적으로 검사하세요.
• API 응답 데이터를 받을 때, 항상 JSON 형식을 명시적으로 선언하세요.
• 모든 JSON 데이터는 올바른 형식으로 이스케이프 처리된 상태로 유지하세요.
• 코드 리뷰를 통해 JSON 데이터 처리 로직을 검증하세요.

팀 개발 시에는 공통의 JSON 데이터 처리 가이드라인을 마련하여 모든 팀원이 일관된 방식으로 데이터를 처리하도록 하세요. 또한, 린터와 같은 도구를 사용하여 코드 품질을 유지하고, JSON 포맷 오류를 사전에 방지할 수 있습니다.

🎯 마무리 및 추가 팁

이 글에서는 ‘SyntaxError: Unexpected token in JSON’ 에러의 원인과 해결책을 다루었습니다. 주요 내용을 요약하자면, 첫째, JSON 데이터의 형식을 올바르게 유지해야 합니다. 둘째, JSON.stringify와 JSON.parse를 사용할 때 항상 예외 처리를 포함해야 합니다. 셋째, JSON Schema를 사용하여 데이터 유효성을 지속적으로 검사하는 것이 좋습니다. 이와 유사한 에러에 대해 더 알고 싶다면 JSON 관련 오류를 다룬 다른 FixLog 노트를 참조하세요. 추가 학습을 위해 JSON과 관련된 공식 문서를 확인하거나, JSON 유효성 검사기 및 파서 관련 라이브러리를 활용해 보세요. 여러분이 이 에러를 해결하는 데 성공할 수 있도록 응원합니다!