JSON 포맷팅 모범 사례: 읽기 쉽고, 유효하고, 효율적인
빠른 답변
사람이 읽을 수 있는 JSON, 후행 쉼표 없음, 큰따옴표 키 및 일관된 키 순서(알파벳순 또는 도메인 의미)를 위해 2칸 들여쓰기를 사용합니다. 프로덕션 전송을 위해 JSON을 축소하고 개발을 위해 예쁜 인쇄를 수행합니다. 무료 JSON 포맷터를 사용하면 둘 사이를 즉시 전환할 수 있습니다.
소개
JSON 형식 선택은 가독성, 파일 크기 및 디버깅 속도에 영향을 미칩니다. JSON 구문은 RFC 8259에 의해 엄격하게 정의되어 있지만 들여쓰기, 키 순서 지정 및 공백 처리 방법은 관례의 문제입니다. 이 가이드에서는 JSON이 팀 전체에서 일관성을 유지하고 디버그하기 쉽고 효율적으로 작동할 수 있도록 널리 채택된 모범 사례를 설명합니다.
단계별
-
들여쓰기 너비 선택
공백 2개가 가장 일반적인 규칙입니다(Prettier, ESLint, Google JSON 스타일 가이드). 깊게 중첩된 구성에는 공백 4개가 허용됩니다. 렌더링은 편집기마다 다르기 때문에 탭을 사용하지 않는 것이 좋습니다. 하나를 선택하고 프로젝트 전체에 적용하세요.
-
키를 일관되게 주문하세요
결정적 출력(캐싱 및 차이점에 유용함)을 위해 키를 알파벳순으로 정렬하거나 도메인 의미(ID 먼저, 속성, 관계 순)별로 그룹화합니다. 무작위 키 순서를 피하세요. 그러면 diff에 잡음이 생기고 스냅샷 테스트가 중단됩니다.
-
생산 운송을 위한 축소
축소된 JSON는 불필요한 공백을 모두 제거하여 페이로드 크기를 10~0% 줄입니다. 프로덕션 환경에서는 APIs의 축소된 JSON을 제공하고 로컬 개발 및 디버깅용으로만 보기 좋게 인쇄된 JSON을 유지합니다.
-
보내기 전에 확인하세요
API로 보내거나 구성 파일에 쓰기 전에 항상 유효성 검사기를 통해 JSON을 실행하세요. 단일 후행 쉼표 또는 따옴표가 없는 키로 인해 JSON.parse()가 소비자를 던지고 중단하게 됩니다.
-
포맷터를 사용하여 모드 전환
JSON을(를) JSON 포맷터에 붙여넣어 읽기에 편리하게 하거나 이동하기 위해 축소하세요. 이 도구는 구문을 검증하고 오류의 정확한 위치를 보고하므로 디버깅 시간이 절약됩니다.
예
예쁘게 인쇄됨(2칸 들여쓰기)
입력: {"id":1,"name":"Alice","active":true}
산출: {
"id": 1,
"name": "Alice",
"active": true
}
생산을 위해 최소화됨
입력: {
"id": 1,
"name": "Alice"
}
산출: {"id":1,"name":"Alice"}
알파벳순으로 정렬된 키
입력: {"zebra":1,"apple":2,"mango":3}
산출: {"apple":2,"mango":3,"zebra":1}
일반적인 문제
- 후행 쉼표: {"a":1,}은 유효하지 않습니다. JSON. 대부분의 포맷터는 이를 제거하지만 JSON.parse()와 같은 엄격한 파서는 입력을 거부합니다.
- 작은따옴표와 따옴표가 없는 키: {'a':1} 및 {a:1}은 유효한 JavaScript이지만 JSON은 유효하지 않습니다. 키와 문자열 값에는 항상 큰따옴표를 사용하세요.
- JSON의 주석: 표준 JSON에서는 // 또는 /* */ 주석을 허용하지 않습니다. 인라인 문서가 필요한 경우 JSONC, JSON5 또는 별도의 스키마 파일을 사용하세요.
- 혼합 들여쓰기: 탭과 공백을 혼합하면 diff 도구가 손상되고 "일관되지 않은 들여쓰기" 보푸라기 오류가 발생할 수 있습니다. 커밋하기 전에 포맷터로 정규화하세요.
팁
- 저장 시 2칸 들여쓰기로 JSON 형식을 지정하도록 편집기를 구성하세요. 이렇게 하면 코드 검토 시 스타일 논쟁을 방지할 수 있습니다.
- API 응답의 경우 Content-Type: application/json을 설정합니다. charset=utf-8이며 최대 효율성을 위해 gzip/Brotli 압축으로 축소된 JSON을 제공합니다.
- 스냅샷 테스트에서 JSON을 해시하거나 비교할 때 결정적 키 순서(예: 알파벳순)를 사용합니다. 무작위 순서로 인해 거짓양성 오류가 발생합니다.
- 대규모 JSON 페이로드를 디버깅할 때 먼저 이를 예쁘게 인쇄한 다음 육안으로 스캔하는 대신 regex 또는 jq를 사용하여 관련 하위 트리를 추출합니다.