텍스트로 JSON 을 diff 중지하도록 가르쳐 준 버그는 주말의 대부분을 소비했습니다. 내가 실행하는 Laravel SaaS 의 지불 웹 후크는 공급자 "non-breaking" API 업데이트 - 변경 로그에서 그들의 단어. 나는 업데이트 이전의 페이로드를 로그에서 꺼내 신선한 하나를 잡고 일반 텍스트 diff 에 둘 다 던졌습니다. 모든 라인이 켜졌습니다. 공급자는 모든 키를 알파벳 순서로 재정렬하고 들여쓰기를 네 칸에서 두 칸으로 변경한 직렬 변환기를 전환했습니다. 6 백 개의 라인이 변경되었으며,그 어딘가에서 하나의 실제 차이점이 발견되었습니다: 전에 두 번 위에서 아래로 그 diff 를 읽었습니다 amount 번호에서 변경되었습니다 1099 문자열에 "1099". 화면에 같은 문자. 다른 유형. 우리의 엄격한 비교는 그것을 거부,대기열은 땅에 다시 시도,텍스트 diff 는 599 화장품 아래에 하나의 의미있는 변화를 묻었다.
That's 근본적인 문제: JSON 은 데이터 형식이지만 텍스트 diff 는 산문으로 취급합니다. 키 순서,공백, 들여쓰기,후행 개행 - JSON 파서에는 아무 의미도 없으며 모든 것이 줄 기반 비교의 변경 사항으로 표시됩니다. 당 RFC 8259, JSON 객체는 입니다 주문되지 않은 이름/값 쌍의 모음. 두 문서는 바이트 대 바이트로 다를 수 있으며 의미 적으로 동일 할 수 있습니다. JSON 을 한 줄씩 비교하는 도구는 잘못된 질문에 답하는 것입니다.
A JSON 차이 도구 올바른 것에 답합니다. 두 문서를 모두 트리로 구문 분석하고 비교합니다 값: 이 키가 추가되었고, 해당 키가 제거되었으며, 이 값이 X에서 Y로 변경되었습니다. 그리고 - 내 주말을 저장한 값이 내 브라우저 탭에 존재했다면 - 이 값이 변경되었습니다 유형. 내가 Toolz.dev 를 위한 diff 검사기를 만들었을 때,type-change 감지는 리스트의 첫 번째 기능이었는데,그 이유는 it's 텍스트 diffs 가 구조적으로 서페이싱을 할 수 없고 실제 시스템을 가장 자주 깨뜨리는 변화의 클래스이기 때문이다.
이 가이드는 구조적 비교가 작동하는 방식, 배열 순서가 중요해야 하는 경우와 그래야 하는 경우't 문제, 디버깅 워크플로우 - API 회귀, 구성 드리프트, 패키지 매니페스트 감사 - JSON diff가 매주 비용을 지불하는 경우를 다룹니다.
TL;DR: 두 개의 JSON 문서를 붙여넣습니다 Toolz.dev JSON 차이점 검사기 그리고 구조적 비교를 얻으십시오: 다음과 같은 정확한 경로로 키를 추가, 제거 및 변경했습니다
features.rateLimit또는users[3].email- 값이 변경될 때 별도의 플래그를 지정합니다 유형 (그3000→"3000"버그). 키 순서와 서식은 절대 오탐지를 생성하지 않습니다. 모든 것이 브라우저에서 실행됩니다; 아무것도 업로드되지 않습니다. 와 페어링하십시오 JSON 포맷터 먼저 문서를 정리하려면 텍스트 차이 도구 라인이 실제로 중요한 콘텐츠의 경우.
JSON을 구조적으로 차이한다는 것은 무엇을 의미합니까?
구조적 diff 는 두 문서를 실제 데이터 트리로 구문 분석하고 키별로,요소별로 함께 걸어갑니다. 모든 노드에서 묻습니다: 이 키가 양쪽에 존재합니까? 값이 동일한 유형입니까? 동일합니까? 출력 isn't "line 14 changed" - it's a list of facts about your data:
version에서 변경되었습니다"1.4.0"에"1.5.0"features.metrics가치를 더했다trueport번호에서 문자열로 유형 변경tags[2]가치를 더했다"monitored"
각 차이점에는 전체 JSON 경로가 포함되므로 깊이 중첩된 문서에서 볼 위치를 정확히 알 수 있습니다. users[12].address.postalCode 어떤 사용자, 어떤 필드를 알려주고 스크롤이 필요하지 않습니다.
텍스트 diff 와의 대비는 실제 문서에서 가장 극명합니다. Take a package.json 다른 npm 버전에 의해 재생성되거나 백엔드 팀이 직렬화기를 업그레이드한 후의 API 응답 또는 포맷터를 통해 실행되는 config 파일. 텍스트 diff: 수백 개의 변경된 줄. 구조적 diff: 실제로 일어난 세 가지 변경 사항 또는 없다는 정직한 답변 - "structurally idential" - 그 자체로 가치있는 위험한 리팩터가 생성되었음을 확인합니다 영 데이터 변경은 내가이 도구에 도달 한 이유의 절반입니다.
There's 선 diffs 를 위한 장소,명확하게 하기 위하여. 산문,코드, HTML,물리적 레이아웃이 의미를 전달하는 모든 것 - that's 텍스트 차이 영토. 그러나 JSON's 레이아웃은 사양에 의해 아무런 의미를 지니지 않으며,그렇지 않은 척하는 비교는 노이즈를 생성 한 다음 눈으로 필터링해야합니다.
유형 변경이 고유한 범주에 적합한 이유는 무엇입니까?
왜냐하면 그들은'데이터의 다른 모든 보기에서는 보이지 않으며,디버그하기 비참한 방식으로 물건을 깨뜨리기 때문입니다.
1099 그리고 "1099" 로그 파일,터미널, 대부분의 텍스트 diff 에서 동일하게 렌더링 - 따옴표는 오전 2 시에 놓치기 쉽습니다. 그러나 입력된 모든 소비자에게는 다른 값입니다. JavaScript's === 비교를 거부합니다. A JSON Schema declaring "type": "integer" 유효성 검사에 실패합니다. a Go 서비스는 an으로 마샬링 해제됩니다 int64 오류를 반환합니다; 자바의 엄격한 잭슨 역직렬화 장치가 던집니다. PHP는 느슨한 비교를 통해 용서하는 것으로 유명하지만 모든 최신 Laravel 코드베이스가 수행해야 하는 엄격한 유형을 활성화하는 순간입니다 "1099" 돈이 되는 것을 멈추고 예외가 되기 시작합니다.
가장 고약한 부분은 어디 이러한 변화는 에서 비롯됩니다. 개발자가 의도적으로 값을 편집하는 경우는 거의 없습니다. serializer swaps,ORM upgrade,migrating from 데이터베이스 열에서 비롯됩니다 INT 에 VARCHAR, 숫자를 문자열화하는 캐싱 레이어 또는 선의의 API 게이트웨이 "normalizing" 페이로드. 아무도 그들이 일어난 것을 모르기 때문에 아무도 그들을 위해 changelog 항목을 작성하지 않습니다.
그래서 the JSON 디프체커 보고서 유형 변경은 자체 카테고리로 표시됩니다 ! 복사 가능한 보고서에서,평범한 값 변화와 구별 - 이전 및 새 유형이 철자되어 있습니다. when you're staring at a summary that says 0 added, 0 removed, 0 changed, 1 type changed, 당신은 정확히 어떤 종류의 버그 you're 사냥 전에 you've 읽기 단일 경로.
두 개의 JSON 파일을 도구와 어떻게 비교합니까?
1 단계: 두 문서를 모두 붙여 넣기
원본 (또는 알려진-좋은) JSON 왼쪽 패널에가 서 업데이트 (또는 의심 스러운) JSON 오른쪽. 규칙은 출력을 읽기 위한 경우에만 중요 합니다: & quot;added" 오른쪽에 존재 하지만 왼쪽을 의미 하지, & quot;removed" 반대로 의미 합니다. 만약 you're 작업 환경을 깨진 하나에 비교 하면 왼쪽에 작업을 넣어 diff & quot;what broke changed."로 읽습니다
There's는 모든 차이 유형, 즉 값 변경, 추가, 유형 변경, 배열 증가를 실행하는 작은 서비스 구성으로 두 패널을 채우는 로드 샘플 버튼으로, 출력이 어떻게 읽히는지 배우는 가장 빠른 방법입니다.
2 단계: 배열 순서가 중요한지 결정
이것은 당신이 생각해야 할 하나의 옵션이며, 올바른 대답은 배열에 달려 있습니다 의미- 아래에 더 많은 것. 기본값은 JSON 사양과 일치하는 순서에 민감합니다. 틱 " 배열 order" 무시; 배열이 의미론적으로 설정되어 있을 때.
3 단계: 비교하기
두 문서 모두 어떤 것이 비교되기 전에 유효성이 검사됩니다. 만약 어느 쪽이든 구문 오류가 있다면 - 뒤의 쉼표,작은 따옴표,인용되지 않은 키,일반적인 용의자 - 당신은 파서's 정확한 메시지를 얻고,결정적으로 어느 쪽 에서 왔다. 침묵하는 실패 없음,반으로 분석된 쓰레기를 비교하는 없음. you're 가 당신의 JSON 가 유효하기 조차 확실하지 않은 경우에,그것을 통해서 실행하십시오 JSON 포맷터 첫째; 한 단계로 검증하고 예쁜 인쇄를 합니다.
4단계: 요약을 읽은 다음 표를 읽습니다
요약 줄은 카테고리별로 카운트를 제공합니다. 추가, 제거, 변경, 유형 변경 - 이는 종종 필요한 전부입니다. "47 추가, 0 제거, 0 변경" API 버전 범프 후에는 새 필드만 의미합니다: 안전. "0 추가, 3 제거" 소비자가 의존할 수 있는 필드를 의미합니다. 방금 사라진: 안전하지 않음. 아래 표에는 긴 값에 대한 가독성을 위해 잘린 경로, 이전 값 및 새 값과의 모든 차이점이 나열되어 있습니다.
5 단계: 보고서 복사
보고서 복사 버튼은 일반 텍스트 요약을 생성합니다 + / - / ~ / ! 마커 및 전체 경로 - 풀 요청 주석, Slack 사건 스레드 또는 티켓에 직접 붙여넣도록 설계되었습니다. "Here's staging과 production config" 사이에 정확히 무엇이 변경되었는지; 영수증과 함께, 한 번의 클릭으로.
언제 배열 순서를 무시해야 합니까?
JSON 배열은 사양에 따라 정렬됩니다 [1, 2] 그리고 [2, 1] 는 다른 문서이고,기본 비교는 그것을 존중합니다. 그러나 사양은 당신의 의도가 아닌 컨테이너를 설명하고,실제로 배열은 두 가지 다른 방법으로 사용됩니다:
시퀀스로 배열합니다는, 위치는 의미 있는 곳에: 순서대로 실행하는 미들웨어 사슬, 마이그레이션 목록, 분류된 리더보드, 페이지 매겨진 결과. 이들을 재정렬하는 것은 진짜 변화이다 - 달리는 미들웨어 스택 auth 이후 handle 는 다른 (그리고 아마 깨진) 응용 프로그램입니다. 주문 민감도를 유지하십시오.
집합으로 배열위치가 사고인 경우: 태그 목록, 역할 할당, 기능 플래그, 데이터베이스 쿼리에서 반환된 ID가 없습니다 ORDER BY. Postgres 는 다른 실행에 다른 순서로 같은 행을 반환 할 수있는 권리 내에서 전적으로이며,때문에 diff 가 점등되는 경우 that's 노이즈. 이것은 무엇 "배열 order" 무시; 옵션은에 대한 것입니다 - 요소는 위치에 관계없이 일치,그래서 ["admin", "editor"] 같음 ["editor", "admin"].
API 페이로드를 비교한 수년간의 경험 법칙: 백엔드가 명시적인 정렬을 적용하면 배열을 시퀀스로 처리합니다; if it does't, it's a set whether the authors realized it or not, and order-insensitive comparation tells you the truth about the data.
구조적 차이 대 텍스트 차이 대 수동 검사
| 구조적 JSON 차이 | 텍스트/라인 차이 | 그것을 눈알로 | |
|---|---|---|---|
| 재정렬된 키 | 보고된 차이는 없습니다 | 모든 이동된 라인에 플래그가 지정되었습니다 | 변화를 놓치기 쉽다 |
| 공백을 다시 포맷했습니다 | 보고된 차이는 없습니다 | 모든 것이 신고되었습니다 | N/A |
유형 변경(1 → "1") |
유형 변경으로 플래그가 지정되었습니다 | 선의 바다에서 두 캐릭터 | 거의 보이지 않습니다 |
| 중첩된 변경 위치 | 정확한 경로: a.b[2].c |
라인 번호 포맷된 텍스트 | 수동 횡단 |
| 배열 재정렬 (의도적) | 플래그가 지정됨(또는 무시됨, 선택) | 플래그가 지정되었습니다 | 배열 크기에 따라 다릅니다 |
| 위한 최고의 | JSON, API 페이로드, 구성 | 코드, 산문, 마크업 | 두 줄짜리 문서 |
| 실패 모드 | 유효한 JSON 에 없음 | 거짓 긍정은 실제 변화를 묻어 버립니다 | 인간의 피로 |
정직한 요약: 텍스트 diffs aren't 잘못, they're 다른 질문에 대답 - "바이트가 변경 되었습니까?" JSON 에 대 한 당신은 거의 항상 "did the 데이터 change?", 그리고 그 질문들은 의외로 자주 다른 대답을 가지고 있다.
JSON Diff의 실제 워크플로는 무엇입니까?
API 회귀 디버깅
지금 체계화 된 내 웹 훅 이야기의 워크 플로우: 변경하기 전에에서 페이로드 캡처 (로그,기록 된 정착물,당신의 테스트 suite's 스냅 샷) 및 후에서 하나. 왼쪽 패널,오른쪽 패널,비교. diff 는 제공자 's changelog did't - 어떤 필드가 이동했는지,어떤 유형이 변경되었는지,조용히 사라졌는지 초 단위로 알려줍니다. 타사 API 가 버전 범프를 발표 할 때마다이 작업을 수행합니다 전에 이전 버전은 일몰하고 업그레이드 티켓에 보고서를 제출합니다.
구성 드리프트를 잡습니다
준비 작업,생산 doesn't,그리고 둘 다 "deployed from the same config." 그들은 있었습니까? 둘 다 내보내기 - 환경 JSON,a docker inspect 출력, Kubernetes ConfigMap이 덤프되었습니다 -o json- 그리고 차이점을 살펴보겠습니다. 구성 드리프트는 거의 항상 하나 또는 두 개의 키이며 경로 열은 바로 그곳으로 이동합니다. 이 비트 diff <(jq -S . a.json) <(jq -S . b.json) 터미널에서는 유형 변경도 포착하기 때문입니다 jq-정규화된 텍스트 차이는 거의 눈에 띄지 않게 렌더링됩니다.
Lockfile 및 Manifest 변경 사항 검토
A package.json 또는 composer.json 충돌하는 병합으로 인해 엉망이 되었거나 프레임워크 업그레이드 후 생성된 OpenAPI 사양: 구조적 diff는 재생된 포맷의 노이즈 없이 종속성 변경을 보여줍니다. WordPress 플러그인 작업의 경우 - WP JSON으로 선박 설정을 관리합니다. - 리팩터 did't가 수천 개의 설치에 의존하는 키를 삭제하도록 릴리스 간에 내보낸 설정 스키마를 변경합니다. 실수로 제거하면 a로 표시됩니다 - 선; 4,000줄 설정 내보내기의 텍스트 차이에서는 전혀 아무것도 아닌 것으로 표시됩니다.
데이터 마이그레이션 확인
Before: JSON 으로 대표 레코드를 내보냅니다. 마이그레이션 후: 다시 내보냅니다. diff 는 마이그레이션이 의도한 변경 사항을 정확하게 표시해야 합니다 다른 아무것도. "구조적으로 동일" that should't have been touched 레코드에서 가장 저렴한 회귀 테스트 you'll 이제까지 실행됩니다. 이 쌍을 통해 테이블 내보내기 변환과 잘 CSV에서 JSON 데이터가 CSV로 데이터베이스에서 나오는 경우.
환경 반응 비교
두 환경에서 동일한 끝점을 누르면 응답이 다릅니다. dev에 있지만 프로덕션에서 누락된 필드는 일반적으로 기능 플래그, 오래된 배포 또는 설정되지 않은 환경 변수를 의미합니다. 요약 개수만으로 진단하는 경우가 많습니다.
이 도구에 대해 대부분의 것보다 클라이언트 측 처리가 더 중요한 이유는 무엇입니까?
JSON diff 에 붙여넣는 것을 생각해 보세요: 고객 이메일이 포함된 API 응답,내부 호스트 이름이 포함된 구성 파일,결제 메타데이터가 포함된 웹훅 페이로드,데이터베이스 내보내기 등이 바로 유출되어서는 안 되는 데이터이며,아무도 방금 어떤 온라인 도구를 감사하지 않는 바로 그 순간 - 사건 중간 - 에 붙여넣어져야 합니다.
X-1000 X 1000 X 1000 X 1000 X 1000 X 1000 X 1000 X 1000 X 1000 X 1000 X 1000 X 1000 X 1000 X 1000 X 1000 X 1000 X 1000 X 1000 X 1000 X 1000 X 1000 X 1000 X 1000 X 1000 X 1000 X 1000 X 1000 X 1000 X 1000 X 1000 X 1000 X 1000 X 1000 X 1000 X Toolz.dev 차이점 검사기 브라우저에서 완전히 구문 분석하고 비교합니다. 어떤 요청도 문서를 어디로든 전달하지 않습니다; 이 도구는 페이지가 로드되면 오프라인으로 작동하며 네트워크를 잘라내고 다시 비교하여 확인할 수 있습니다. 이것은 프리미엄 기능 또는 변경할 수 있는 정책 약속인 isn't - it's 아키텍처입니다. 비교 로직은 메모리의 두 구문 분석된 트리에서 작동하는 순수 JavaScript 로 데이터를 보낼 서버 구성 요소가 없습니다.
동일한 개인 정보 보호 주장이 전체 도구 상자에 적용됩니다. it's the reason the Toolz.dev 에 개발자 툴킷 브라우저 우선으로 구축되었지만 비교하기 때문에 diff 도구는 it's가 가장 심각한 곳입니다 둘 생산 문서는 붙여넣기 노출을 두 배로 늘립니다.
얼마나 큰 문서를 비교할 수 있습니까?
비교는 두 트리의 모든 노드를 한 번 방문하므로 작업은 문서 크기에 따라 선형적으로 확장됩니다. 실제로: 수백 킬로바이트의 문서는 즉시 비교; 최신 노트북과 유사한 모든 항목에서 1초 이내에 낮은 한 자리 메가바이트가 완료됩니다; 수십 메가바이트가 작동하지만 브라우저가 두 문서를 모두 구문 분석하고 두 트리를 동시에 메모리에 보관해야 하기 때문에 you'll이 느낄 것입니다.
매우 큰 페이로드에 대한 두 가지 실용적인 팁. 먼저 문서의 일부만 신경 쓰면 해당 하위 트리 만 비교하십시오 - 붙여 넣기 response.data.items 전체 봉투가 아닌 양쪽에서. 둘째,diff 가 수천 개의 항목을 생성하는 경우 that's 는 일반적으로 한쪽의 부호가 다릅니다 모양 (객체에 싸인 배열, 추가 중첩 수준) - 스크롤하기 전에 처음 몇 경로를 확인하십시오; they'll은 you're가 계단식으로 이어지는 하나의 구조적 변화 또는 수천 개의 정품 변화를 보고 있는지 알려줍니다.
자주 묻는 질문
두 개의 JSON 파일을 온라인으로 비교하려면 어떻게 해야 합니까?
열다 JSON 디프체커를 누르고,한 문서를 왼쪽 패널에 붙여넣고 다른 문서를 오른쪽에 붙여넣은 다음 비교를 클릭합니다. 정확한 JSON 경로로 추가,제거, 변경 및 유형 변경한 모든 값의 분류된 목록을 얻습니다. 두 문서 모두 브라우저에서 완전히 처리됩니다. - 어떤 서버에도 업로드되지 않습니다.
JSON 데이터가 동일할 때 텍스트 차이가 왜 그렇게 많은 변경 사항을 표시합니까?
텍스트 diffs 는 선을 비교하고 JSON 은 동일한 데이터를 여러 가지 방법으로 쓸 수 있기 때문에 재정렬 된 키,다른 들여 쓰기 및 공백은 모두 데이터를 변경하지 않고 텍스트를 변경합니다. 구조적 diff 는 두 문서를 먼저 구문 분석하고 실제 값을 비교하므로 서식 차이는보고 된 변경 사항이 0 이됩니다.
JSON 객체의 키 순서가 중요합니까?
RFC 8259에서는 JSON 개체를 이름/값 쌍의 정렬되지 않은 모음으로 정의합니다 {"a":1,"b":2} 그리고 {"b":2,"a":1} 는 같은 객체입니다. diff 검사기는 키 이름으로 객체를 비교하고 변경으로 재정렬을 보고하지 않습니다. 이와 대조적으로 배열 요소 순서는 기본적으로 중요합니다. 배열은 사양에서 정렬됩니다.
언제 "Ignore array order" 옵션을 사용해야 하나요?
배열이 시퀀스가 아닌 의미론적으로 설정되어 있을 때 사용합니다 - 태그 목록,역할 모음,정렬되지 않은 데이터베이스 쿼리의 ID. With the option on, [1,2,3] 그리고 [3,1,2] 동등한 것으로 비교하십시오. 순서가 지정된 미들웨어 체인,순위 결과 또는 페이지가 매겨진 목록과 같이 위치가 의미를 전달할 때 그것을 남겨 두십시오.
유형 변경이란 무엇이며 별도로 플래그가 지정되는 이유는 무엇입니까?
유형 변경은 value's JSON 유형이 비슷해 보여도 문서 간에 다른 경우 - 숫자 3000 끈이 되는 것 "3000" 고전적인 경우입니다. It's 는 텍스트 diffs 및 로그에서 거의 보이지 않으면서 엄격한 형식의 소비자,스키마 유효성 검사 및 엄격한 동등성 검사를 중단하기 때문에 별도로 플래그가 지정됩니다. It's 는 API 통합 회귀의 가장 일반적인 원인 중 하나입니다.
비교 결과를 팀과 공유할 수 있나요?
예. 보고서 복사 버튼은 일반 텍스트 diff 보고서를 생성합니다 + (추가), - (제거됨), ~ (변경), 그리고 ! (유형 변경) 모든 차이에 대한 마커 및 전체 JSON 경로. It's는 풀 요청 주석, 느슨한 스레드 및 문제 추적기에 깔끔하게 붙여넣기 위해 포맷되었습니다.
프로덕션 API 응답을 도구에 붙여넣는 것이 안전한가요?
예. 구문 분석 및 비교는 브라우저의 JavaScript에서 완전히 실행됩니다. 데이터로 네트워크 요청이 이루어지지 않고, 아무것도 기록되거나 저장되지 않으며, 도구가 오프라인으로 계속 작동합니다. 이를 통해 고객 데이터, 내부 호스트 이름 또는 자격 증명이 포함된 페이로드에 안전하지만 공유하기 전에 비밀을 수정할 수 있습니다 보고서 는 여전히 당신 위에 있습니다.
내 문서 중 하나가 isn't 유효한 JSON 인 경우 어떻게됩니까?
이 도구는 비교하기 전에 양쪽의 유효성을 검사하고 parser's 정확한 오류 메시지를 왼쪽 또는 오른쪽에서 온 쪽과 함께 보고합니다. 일반적인 범인은 후행 쉼표,이중 대신 작은 따옴표,따옴표가 없는 키로 보고된 문제를 수정하거나 문서를 실행합니다 JSON 포맷터 문제를 찾으려면 다시 비교하세요.
구조적 비교는 버그를 변경할 수 있는 도구 중 하나입니다 보다. Text diffs 대답 "바이트가 변경 되었습니까?"; JSON 의 경우 중요한 질문은 "데이터가 변경 되었습니까?" - 및 시스템을 실행하는 API 페이로드,구성 및 매니페스트의 경우 JSON 디프체커 몇 초 만에 응답, 브라우저에서, 당신의 데이터는 기계를 떠나지 않고. 더 많은 JSON 워크 플로우 - 서식, 유효성 검사, 변환 - 에 살고 코딩 도구 가이드.
