웹 개발을 하면서 JSON을 안 만져본 사람은 거의 없을 겁니다. REST API 응답, 설정 파일, 데이터 저장 포맷 등 JSON은 사실상 현대 개발의 공용어라고 해도 과언이 아니에요. 그런데 막상 실무에서 JSON을 다루다 보면 예상보다 자잘한 문제가 많이 생기더라고요. 이 글에서는 그동안 겪었던 JSON 관련 삽질과 해결법을 정리해봤습니다.
API 응답 디버깅, 가독성이 먼저다
백엔드 API를 개발하거나, 외부 API를 연동할 때 가장 먼저 하는 일이 응답 데이터를 확인하는 겁니다. 문제는 실제 API 응답이 한 줄로 압축되어 오는 경우가 대부분이라는 거예요.
{"users":[{"id":1,"name":"Kim","roles":["admin"]},{"id":2,"name":"Lee","roles":["user"]}],"total":2}
이걸 눈으로 파싱하려면 머리가 아프죠. JSON 포맷터를 사용하면 들여쓰기가 적용되어 구조를 한눈에 파악할 수 있습니다. 특히 중첩이 깊은 데이터일수록 포매팅의 효과가 큽니다.
개발하면서 느낀 건, API 응답을 제대로 들여다보는 습관이 디버깅 시간을 확실히 줄여준다는 겁니다. 에러가 발생했을 때 응답 전체를 포매팅해서 보면, 어디서 null이 들어오는지, 어떤 필드가 빠져있는지 금방 찾을 수 있어요.
JSON 문법 오류, 이것만 알면 된다
JSON 유효성 검사에서 빈번하게 걸리는 패턴이 있습니다. 코드 리뷰하면서 가장 많이 봤던 실수들이에요.
1. 후행 쉼표 (Trailing Comma)
JavaScript에서는 배열이나 객체 마지막에 쉼표를 넣어도 되지만, JSON에서는 문법 오류입니다. IDE 자동완성에 의존하다 보면 자주 생기는 실수예요.
{"name": "홍길동", "age": 30,} // 오류!
{"name": "홍길동", "age": 30} // 올바른 형태
2. 작은따옴표 사용
Python 딕셔너리를 그대로 JSON으로 가져오면 이런 실수를 하게 됩니다. JSON은 반드시 큰따옴표만 허용해요.
3. 주석 사용
JSON에는 주석이 없습니다. 설정 파일 용도로 주석이 필요하면 JSONC나 JSON5 같은 확장 포맷을 고려하거나, 아예 YAML로 전환하는 게 나을 수 있어요.
4. 숫자 앞의 0
JSON에서 숫자 앞에 0을 붙이면 (예: 007) 파서에 따라 오류가 발생합니다. 8진수로 해석하는 파서도 있어서 혼란을 일으킬 수 있으니 주의하세요.
CSV 변환: 엑셀 팀과 소통하기
개발자와 비개발자 사이에서 가장 자주 일어나는 데이터 교환 상황이 바로 JSON과 CSV 간의 변환입니다. 기획팀이나 마케팅팀에서 "이 데이터 엑셀로 주세요"라고 하면, 결국 JSON을 CSV로 변환해야 하는 거죠.
평탄한 구조의 JSON이면 변환이 간단하지만, 중첩 객체가 있으면 어떤 레벨까지 펼칠지 결정해야 합니다. 배열이 포함된 경우에는 한 셀에 여러 값을 넣을지, 행을 나눌지도 고민이 필요해요.
실무 팁을 하나 드리자면, 변환 전에 데이터 구조를 먼저 확인하고, 중첩이 깊으면 필요한 필드만 추출해서 변환하는 편이 깔끔합니다. 전체를 한 번에 변환하려다 컬럼이 수십 개가 되어버린 경험이 있거든요.
XML/YAML과 JSON 간 변환
레거시 시스템과 연동하다 보면 XML을 JSON으로 변환해야 하는 상황이 꽤 있습니다. 특히 SOAP API나 오래된 엔터프라이즈 시스템에서 데이터를 받아올 때 그렇죠.
XML에서 JSON으로 변환할 때 주의할 점은 XML 속성(attribute)의 처리입니다. XML의 속성과 자식 요소가 JSON에서 어떻게 매핑되는지 미리 파악해두면 삽질을 줄일 수 있어요. 네임스페이스가 있는 XML은 더 복잡해지니, 필요 없는 네임스페이스는 변환 전에 제거하는 것도 방법입니다.
YAML의 경우, Kubernetes 설정이나 CI/CD 파이프라인 파일을 다루면서 JSON 변환이 필요한 경우가 많습니다. YAML은 들여쓰기에 민감하기 때문에, JSON으로 변환해서 구조를 확인한 다음 다시 YAML로 돌리는 방법도 유용해요.
대용량 JSON 처리 노하우
수 MB 이상의 JSON 파일을 다뤄야 할 때가 있습니다. 데이터 마이그레이션이나 로그 분석이 대표적인 상황이죠. 이럴 때 브라우저 기반 도구가 뻗어버리거나, 에디터가 멈추는 경험을 한 번쯤 해보셨을 겁니다.
몇 가지 대처 방법이 있어요. 첫째, 스트리밍 파서를 사용하는 겁니다. 전체를 메모리에 올리지 않고 한 줄씩 처리하면 기가 단위 파일도 문제없습니다. Node.js에서는 JSONStream, Python에서는 ijson 같은 라이브러리가 있어요.
둘째, 데이터를 분할하는 방법입니다. jq 같은 커맨드라인 도구로 필요한 부분만 추출하면 작은 단위로 나눠서 처리할 수 있습니다. jq는 JSON 처리의 스위스 아미 나이프라고 불릴 만큼 강력해요.
셋째, 포매팅은 필요한 부분만 하세요. 전체를 예쁘게 출력하려면 메모리를 많이 잡아먹으니, 특정 키나 경로에 해당하는 데이터만 뽑아서 확인하는 습관을 들이면 좋습니다.
JSON 스키마로 데이터 검증하기
API를 설계하다 보면 "이 필드는 문자열이어야 하고, 최소 1글자 이상이어야 합니다" 같은 제약 조건이 생깁니다. 이런 규칙을 코드에 하나씩 적는 대신, JSON Schema를 사용하면 선언적으로 데이터 구조를 정의할 수 있어요.
JSON Schema를 도입한 뒤 가장 좋았던 점은, 프론트엔드와 백엔드 사이에서 "이 필드 타입이 뭐였죠?" 같은 대화가 줄었다는 겁니다. 스키마 파일 하나가 곧 문서 역할을 해주니까요. TypeScript를 쓰고 있다면 json-schema-to-typescript 같은 도구로 타입을 자동 생성할 수도 있습니다.
실무에서 자주 쓰는 팁 모음
- API 응답이 이상할 때는 먼저 JSON 유효성 검사부터 돌려보세요. 파서 에러 메시지보다 검증 도구의 메시지가 친절합니다.
- 환경 변수나 비밀 키가 포함된 JSON은 포매팅할 때 주의하세요. 온라인 도구에 민감한 데이터를 붙여넣는 건 위험합니다.
- 여러 JSON 파일의 diff를 볼 때는 먼저 키 순서를 정렬한 다음 비교하면 변경 사항을 파악하기 쉽습니다.
- JSON Lines(JSONL) 포맷은 로그 데이터나 스트리밍 데이터에 유용합니다. 한 줄에 하나의 JSON 객체를 넣는 방식이에요.
정리하며
JSON은 단순한 포맷이지만, 실무에서는 생각보다 많은 곳에서 발목을 잡습니다. 문법 오류 하나 때문에 30분을 허비하는 일이 없도록, 좋은 도구를 곁에 두는 것만으로도 효율이 크게 달라집니다. 특히 여러 포맷 간 변환 작업은 수작업 대신 자동화 도구를 활용하는 게 실수를 줄이는 가장 확실한 방법이에요.