입력 (JSON)

출력 (.proto 스키마)

이 도구가 하는 일

실제 JSON 페이로드 — 샘플 API 응답, 웹훅 본문, NoSQL 저장소의 한 행 — 가 있고, 이를 Protocol Buffers 메시지로 모델링하고 싶으신가요? 스키마를 손으로 타이핑하는 건 느리고, 특히 중첩 객체와 배열이 있을 때 실수하기 쉽습니다. 이 변환기는 JSON을 순회하며 각 필드의 Protobuf 타입을 추론하고, 프로젝트에 그대로 붙여넣을 수 있는 깔끔한 proto3 스키마를 출력합니다.

타입 추론은 직접 작성하는 방식 그대로 따라갑니다: 문자열은 string, 불리언은 bool, 32비트에 들어가는 정수는 int32, 그 외에는 int64, 정수가 아닌 숫자는 double, 균일한 요소 타입의 배열은 repeated <T> (객체 배열에는 중첩 메시지 하나를 재사용), 중첩 객체에는 중첩 message 블록입니다. JSON은 struct와 map을 구분하지 못하므로 모든 객체는 중첩 메시지로 출력됩니다 — 데이터가 진짜 map이라면 손으로 map<K, V>로 바꿔주세요.

필드 이름은 camelCase나 kebab-case에서 Protobuf 관례인 snake_case로 변환됩니다. 필드 번호는 선언 순서대로 1, 2, 3, … 으로 할당됩니다. 출력은 유효한 proto3입니다 — .proto 파일에 붙여넣고 protoc나 buf를 실행하면 원하는 언어의 코드가 생성됩니다. 변환은 전적으로 브라우저 안에서 실행됩니다 — JSON도, 필드 이름도, 값도 어디로도 전송되지 않습니다.

사용 방법

세 단계. 잘 형성된 JSON 객체라면 무엇이든 동작합니다 — API 응답, 로그 항목, 픽스처 파일, 무엇이든.

JSON 붙여넣기

왼쪽 에디터에 JSON을 넣으세요. 루트는 객체 ({ ... }) 여야 합니다 — 데이터가 배열로 시작한다면 먼저 객체로 감싸세요. 예: { "items": [...] }. 현실적인 데이터를 사용하세요: 샘플이 대표적일수록 추론된 타입이 장기적으로 원하는 것에 잘 맞습니다.

JSON에 따옴표 없는 키, 마지막 쉼표, 기타 변칙이 있다면 먼저 JSON Fixer로 정리하세요 — Protobuf는 깨끗한 객체에서만 동작합니다.

변환 누르기

초록색 변환 버튼을 누르세요. 변환기는 JSON의 모든 키를 순회하며 Protobuf 타입을 고르고, 중첩 객체에는 중첩 message 블록을 만들고, 맨 위에 syntax = "proto3";을 붙여 스키마를 출력합니다. 필드 번호는 소스 순서대로 할당됩니다.

.proto 사용하기

스키마를 리포지토리의 .proto 파일에 복사하세요. 추론된 타입을 검토하세요 — JSON 샘플이 비어 있던 (빈 배열, null) 필드에는 타입이 추측이라는 코멘트가 표시됩니다. 필요한 부분을 조정한 뒤, protoc이나 buf generate를 실행해 원하는 언어의 코드를 생성하세요.

실제로 시간이 절약되는 순간

서드파티 API를 Protobuf로 모델링하기

벤더는 JSON을 반환합니다. 당신의 서비스는 Protobuf로 저장합니다. 실제 응답을 가져와 여기에 붙여 그 타입의 시작 스키마를 받고, 그 위에서 다듬어 가세요. 문서를 읽고 50개 필드를 손으로 타이핑하는 것보다 낫습니다.

JSON 기반 서비스를 gRPC로 마이그레이션하기

HTTP+JSON 마이크로서비스를 gRPC로 옮기는 중입니다. 요청/응답 형태마다 .proto가 필요합니다. 캡처한 페이로드를 각각 Protobuf 스키마로 변환해 한 파일에 모으면 계약의 초안이 잡힙니다.

Buf 모듈 부트스트랩

새 Buf 모듈을 세팅하면서 시작점이 될 현실적인 스키마가 필요한가요? 기존 JSON 픽스처를 변환해 그 출력을 .proto 파일의 씨앗으로 사용하세요 — 처음부터 타이핑하는 것보다 훨씬 빠릅니다.

Protobuf 코드용 테스트 픽스처 작성

팀에는 JSON 테스트 데이터가 있습니다. 새 코드는 Protobuf를 소비합니다. JSON에서 <code>.proto</code>를 생성하고, codegen이 타입을 만들게 하면 픽스처와 코드가 동기화된 상태로 유지됩니다.

자주 묻는 질문

제 JSON이 어디로 전송되나요?

아닙니다. 변환기는 브라우저 안에서 전적으로 JavaScript로 실행됩니다. JSON — 키, 값, 민감한 정보 — 가 절대 기기를 떠나지 않습니다. DevTools를 열고 변환을 클릭하면서 Network 탭을 확인하세요. 요청 0건입니다.

int32, int64, double을 어떻게 고르나요?

정수 값에 대해서는 부호 있는 32비트 범위 (-2^31 ~ 2^31-1) 안에 들어가는지 확인합니다. 들어가면 int32, 아니면 int64입니다. 정수가 아닌 숫자는 항상 double이 됩니다. 데이터가 부호 없음임을 알고 있거나 fixed32 같은 특정 폭이 필요하다면 출력을 직접 편집하세요 — 사용 가능한 모든 숫자 타입과 와이어 인코딩 트레이드오프는 스칼라 타입 표를 참고하세요.

객체는 언제 중첩 메시지가 되고 언제 map이 되나요?

항상 중첩 메시지입니다 — map은 절대 아닙니다. JSON은 struct와 map을 구분하지 못하므로 둘 중 하나로 추측하면 절반 정도는 틀립니다. 데이터가 실제로 키-값 map (메타데이터, 헤더, 피처 플래그 등) 이라면 출력을 열어 message Foo { ... }를 map<string, V> foo = N;으로 손수 바꾸세요. 데이터를 보면 수정은 기계적이고 자명합니다.

null과 빈 배열은 어떻게 처리되나요?

둘 다 출력에 "퇴화한 샘플에서 타입을 추측했다"는 코멘트를 남깁니다. null은 "nullable" 주석이 달린 string으로, 빈 배열은 "empty array" 주석이 달린 repeated string으로 기본값이 설정됩니다. 그 타입들을 실제로 기대하는 것으로 교체하세요.

왜 혼합 타입 배열은 repeated string으로 표시되나요?

Protobuf는 이종 리스트를 직접 지원하지 않습니다. JSON 배열에 혼합 타입 (문자열 일부, 숫자 일부) 이 있다면 깔끔한 Protobuf 등가물이 없습니다 — google.protobuf.Value나 oneof가 필요하거나 데이터 형태를 다시 짜야 합니다. 변환기는 코멘트로 표시해 직접 결정할 수 있게 합니다.

깊게 중첩된 JSON도 처리하나요?

예. 각 중첩 객체는 파생된 PascalCase 이름의 중첩 message가 됩니다. 중첩 깊이는 변환기가 아니라 스택 깊이로만 제한됩니다 — 매우 깊게 중첩된 API 응답도 깔끔하게 변환됩니다.

이 두 도구로 JSON ↔ Protobuf 라운드트립이 가능한가요?

대체로 그렇습니다. JSON to Protobuf는 스키마를 주고, Protobuf to JSON은 샘플을 줍니다. JSON 샘플에 대표 값이 있던 필드는 형태가 일치합니다. JSON이 null이거나 빈 배열이었던 곳은 추론된 Protobuf 타입이 추측이므로, 타입을 고친 뒤에야 라운드트립이 정확하게 맞습니다.

JSON to Protobuf 변환기