JSON.stringify 순환 참조(Circular Reference) 오류 해결
JavaScript에서 객체를 JSON 문자열로 변환할 때 JSON.stringify() 함수를 자주 사용합니다. 하지만 객체 내부에 자기 자신 또는 다른 객체를 통해 다시 자신을 참조하는 **순환 구조(Circular Reference)**가 있을 경우, 이 함수는 TypeError: Converting circular structure to JSON 오류를 발생시키며 실패합니다.
1) 순환 참조란?
객체 A가 B를 참조하고, B가 다시 A를 참조하는 것처럼 객체들 사이에 끝없이 이어지는 참조 고리가 생기는 경우를 말합니다. 대표적인 예시는 DOM 객체, 이벤트 객체, 부모-자식 관계의 데이터 모델 등에서 자주 발생합니다.
const a = {};
const b = {};
a.b = b;
b.a = a; // B가 A를 참조 -> 순환 참조 발생
// JSON.stringify(a); // TypeError: Converting circular structure to JSON
2) 오류가 발생하는 이유
JSON.stringify()는 객체의 모든 속성을 재귀적으로 탐색하며 문자열로 변환합니다. 순환 참조가 있으면 이 탐색 과정이 무한히 반복되어 스택 오버플로우를 일으키거나, JSON 표준에 맞지 않는 무한한 구조가 생성되려 하기 때문에 JavaScript 엔진이 의도적으로 오류를 발생시킵니다.
3) 순환 참조 해결 방법
3.1) replacer 함수 사용 (수동 필터링)
JSON.stringify()의 두 번째 인자인 replacer 함수를 사용하여 순환 참조가 있는 속성을 수동으로 제거하거나 다른 값으로 대체할 수 있습니다. 가장 기본적인 해결책입니다.
const a = {};
const b = {};
a.b = b;
b.a = a;
const cache = new Set();
const jsonString = JSON.stringify(a, (key, value) => {
if (typeof value === 'object' && value !== null) {
if (cache.has(value)) {
// 순환 참조가 발견되면 undefined를 반환하여 해당 속성을 제거
return undefined;
}
// 새로운 객체는 cache에 추가
cache.add(value);
}
return value;
});
console.log(jsonString); // {"b":{}}
3.2) 외부 라이브러리 사용
replacer 함수를 직접 구현하는 것이 번거롭거나 더 복잡한 제어가 필요할 때는 flatted, json-stringify-safe 같은 전문 라이브러리를 사용할 수 있습니다. 이 라이브러리들은 순환 참조를 감지하여 안전하게 문자열로 변환해 줍니다.
flatted: 순환 참조를~문자를 이용해 다시 참조 가능한 형태로 변환합니다. (압축에도 용이)json-stringify-safe: 순환 참조 부분을[Circular]같은 플레이스홀더로 대체합니다.
3.3) 데이터 구조 변경 (가장 좋은 방법)
가장 근본적인 해결책은 애초에 데이터 모델을 설계할 때 순환 참조가 발생하지 않도록 하는 것입니다. 필요하다면 관련 객체를 참조하는 대신 해당 객체의 ID만을 저장하는 식으로 관계를 역참조하게 만듭니다.
4) 체크리스트
-
JSON.stringify오류가TypeError: Converting circular structure to JSON인가? - 객체 내부에 부모-자식 또는 상호 참조 관계가 있는가?
-
replacer함수를 사용하여 순환 참조 부분을 제거하거나 대체해 보았는가? - 필요하다면
flatted등의 라이브러리 사용을 고려해 보았는가?
JSON 데이터의 유효성을 확인하고 싶다면 JSON Formatter 도구를 사용해 보세요.