01
루트는 첫 메시지에서 시작
파일 이름이나 서비스가 아닌 첫 message 선언을 기본 루트로 사용합니다. 옵션에서 전체 타입 이름으로 다른 메시지를 선택할 수 있습니다. 소스를 수정하면 선택이 초기화되어 삭제하거나 이름을 바꾼 타입을 계속 가리키지 않습니다.
Protocol Buffers 정의
Protobuf Formatter
외부 의존성이 없는 proto3 정의를 구조 트리, 정리된 코드, JSON 형태로 확인하세요. 필드 번호는 바뀌지 않습니다.
Protobuf Formatter
Proto3 소스
결과
소스는 브라우저 안에서 처리됩니다. import 파일을 가져오거나 네트워크 요청을 보내지 않습니다.
옵션
단일 파일 proto3 하위 집합을 지원합니다. import, 사용자 정의 옵션, 컴파일 및 호환성 검사는 지원하지 않습니다. 소스를 바꾸면 루트 선택이 초기화됩니다.
한도: UTF-16 문자 100,000개, 토큰 20,000개, 선언 2,000개, 중첩 32단계. 제한 시간 8초.
결과가 오래되었습니다. 복사와 다운로드가 비활성화됩니다.
Protobuf Formatter는 팀원이 작성한 스키마를 검토할 때 유용합니다. 들여쓰기가 정돈되어 있어도 예약 번호를 다시 사용했거나 타입 이름을 잘못 적었을 수 있습니다. 이 도구는 지원하는 선언을 검사한 다음에 결과를 내보낼 수 있도록 합니다.
트리는 소스에 적힌 필드 이름과 wire 번호, 참조가 가리키는 전체 타입 경로를 보여 줍니다. JSON Schema는 선택한 메시지의 데이터 형태를 나타냅니다. 서비스 정의와 이전 버전의 번호 사용 이력처럼 투영에서 빠지는 정보는 원래 계약으로 확인해야 합니다.
Protobuf Formatter로 검토하는 이유
같은 이름을 가진 타입 구별
Protobuf Formatter는 중첩 선언과 필드 순서를 유지합니다. OuterA.Item과 OuterB.Item은 끝 이름이 같아도 서로 다른 타입으로 표시됩니다. 재귀 참조는 경로로 보여 주므로 같은 메시지 구조가 끝없이 펼쳐지지 않습니다.
필요한 메시지부터 JSON 형태 확인
한 파일에 여러 메시지가 있다면 루트를 선택하세요. 결과의 $ref는 선택한 메시지를 가리키고 공통 정의는 $defs에 남습니다. 배열, map, 상호 배타적인 연락처 필드를 비교하며 실제 소비자가 기대하는 구조인지 확인할 수 있습니다.
검토할 때 알아 둘 세 가지
02
트리 탐색과 데이터 내보내기 구분
선언을 접거나 펼치고 행 번호로 소스 위치를 찾을 수 있습니다. 긴 트리는 보이는 항목을 50개씩 표시합니다. 구조 복사와 다운로드에는 접힌 항목과 아직 표시하지 않은 항목까지 전체 선언이 포함됩니다.
03
자동 검사와 수동 실행 전환
입력 후 350ms 동안 변경이 없으면 검사합니다. 자동 검사를 끄면 실행 버튼과 Ctrl/Cmd + Enter를 사용할 수 있습니다. 입력이나 옵션을 바꾸는 즉시 이전 결과의 내보내기를 막습니다. 예제와 비우기는 교체 미리보기를 거치며 실행 취소는 소스와 결과를 함께 복원합니다.
소스 정리부터 데이터 구조 확인까지
번호를 유지하는 proto 파일 포맷
공백 2개 또는 4개로 들여쓰기를 맞춥니다. 문자열 안의 중괄호나 세미콜론을 구조로 오해하지 않으며 주석 내용도 유지합니다. 이름, 번호, 선언 순서는 바꾸지 않습니다. 별도의 출력 코드를 다시 파싱하여 원래 정의와 같은 구조인지 확인한 뒤 내보냅니다.
스키마 검증에서 번호와 예약 확인
필드 번호는 양수이며 메시지 안에서 고유해야 합니다. 19000–19999는 사용하지 못합니다. 필드 뒤에 선언한 reserved도 검사합니다. proto3 enum의 첫 값은 0이어야 하고 숫자 별칭에는 allow_alias가 필요합니다. 이는 현재 파일 검사이며 과거 버전의 계약 이력을 추정하지 않습니다.
현재 파일의 타입 참조 해결
트리에 package, message, enum, oneof, service, RPC를 표시합니다. 뒤에서 선언한 타입, 중첩 타입, 재귀 메시지 참조를 같은 파일에서 찾습니다. 타입을 찾지 못하면 임의의 객체로 대신하지 않고 생성을 중단합니다. 트리는 JSON 이름과 구분해 원래 snake_case 필드 이름을 유지합니다.
Protobuf JSON 형태의 제한된 투영
JSON Schema 2020-12 문서가 전체 이름을 $defs에 사용합니다. repeated는 배열, map은 객체, int64는 문자열입니다. oneof에서는 아무 멤버도 없거나 하나만 존재할 수 있습니다. 일반 단일 필드와 optional 필드 모두 생략 가능하며 required를 임의로 추가하지 않습니다.
지원하는 범위와 변환의 한계
- 명시적인 proto3 단일 파일
- 첫 선언은 syntax = "proto3";이어야 합니다. proto2, Editions, required, group, extensions는 지원하지 않습니다. Timestamp와 Any를 포함한 모든 import를 거부합니다. 의존성이 있는 정의는 파일과 검색 경로를 갖춘 프로젝트 도구로 검사하세요.
- 알려진 표준 옵션만 허용
- 일반적인 파일 수준 코드 생성 옵션과 올바른 위치의 json_name, packed, deprecated, allow_alias를 처리합니다. 사용자 정의 옵션, 집합 형태 옵션, 검증 주석, CEL은 거부합니다. 생성 설정을 소스에 보존한다고 해서 JSON Schema에 업무 규칙이 생기지는 않습니다.
- 런타임 ProtoJSON 검증과 다름
- 주로 생성되는 JSON 형태를 표현하며 모든 허용 입력을 재현하지 않습니다. null을 미설정으로 처리하는 동작, 숫자 enum, 느슨한 숫자 문자열 입력은 범위 밖입니다. 정수 문자열 패턴은 전체 64비트 범위를 검사하지 않고 base64 contentEncoding은 주석입니다. 실제 데이터용 제약은 추가해야 합니다.
- 프로토콜 계약 자동 수정 없음
- 번호를 다시 매기거나 예약을 삭제하거나 정리한 코드로 입력을 덮어쓰지 않습니다. 현재 파일만으로 과거에 사용한 태그를 알 수 없습니다. protoc 컴파일, Buf lint, 호환성을 깨는 변경 탐지, 클라이언트 생성, OpenAPI 출력은 프로젝트 도구가 맡아야 합니다.
- 한도를 넘으면 오류로 종료
- 실행마다 UTF-16 문자 100,000개, 토큰 20,000개, 선언 2,000개, 중첩 32단계까지 처리합니다. 출력 한도는 1,000,000자이며 워커는 8초 뒤 중단됩니다. 입력을 몰래 잘라 일부 결과만 성공으로 보여 주지 않습니다.
- 입력은 데이터가 아닌 선언
- 이 도구는 .proto 정의를 받습니다. 바이너리, Base64, TextFormat 메시지를 디코딩하지 않습니다. 결과는 소스, 구조 보고서 또는 스키마입니다. JSON Schema 역변환, 여러 파일 처리, 원격 가져오기, 소스를 포함한 공유 링크는 제공하지 않습니다.
Protobuf Formatter 자주 묻는 질문
필드 번호를 0부터 시작할 수 있나요?
메시지 태그는 1부터 536870911까지이며 구현용으로 예약된 19000–19999도 제외됩니다. 반면 proto3 enum의 첫 선언 값은 0이어야 합니다. 두 숫자는 역할이 다르므로 서로 다른 규칙으로 검사합니다. 잘못된 필드 태그를 유효한 enum의 0과 혼동하지 마세요.
필드 번호 사이를 비워 두어도 되나요?
네. 번호는 연속될 필요가 없습니다. 필드 1 다음에 20이 있어도 중복이나 예약 충돌이 없으면 유효합니다. 정리 과정에서 빈 번호를 채우거나 순서를 바꾸지 않습니다. 삭제한 번호를 재사용하지 못하게 하려면 reserved로 남기세요. 빈 간격만으로는 사용 이력이 기록되지 않습니다.
proto3에서 optional 필드는 어떻게 선언하나요?
타입 앞에 optional을 쓰면 생성 코드에서 명시적인 존재 여부를 추적할 수 있습니다. 트리에서도 이 선언을 확인할 수 있습니다. 하지만 JSON Schema에서는 일반 단일 필드와 optional 필드 모두 생략할 수 있습니다. 생성된 has 메서드나 미설정 상태와 기본 반환값의 차이까지 표현하지는 않습니다.
int64가 JSON에서 문자열인 이유는 무엇인가요?
JavaScript 숫자는 모든 64비트 정수를 정확히 표현할 수 없습니다. 일반적인 ProtoJSON 출력은 값을 십진 문자열로 보존하므로 이 투영도 같은 형태를 사용합니다. Number로 변환하지 않아 정밀도를 잃지 않습니다. 다만 패턴은 표기 형태를 검사하므로 정확한 부호별 범위는 따로 검증해야 합니다.
import 경로가 맞는데 왜 실패하나요?
컴파일러는 설정된 import 루트 디렉터리에서 의존 파일을 찾습니다. 이 화면에는 파일 트리나 의존성 해결 환경이 없으므로 모든 import를 명시적으로 거부합니다. 전체 파일과 경로를 설정한 protoc 또는 Buf로 검사하세요. 경로를 내려받거나 선언을 건너뛰어 성공으로 표시하지 않습니다.
지원해야 할 정의에서 문제가 생겼나요?
다음 스키마 변경 검토하기
Protobuf Formatter에서 지원하는 선언을 확인하고 소스와 검토한 JSON 형태를 프로젝트로 가져가세요. 최종 컴파일에는 전체 의존성이 필요합니다.