입력 (.proto 스키마)

출력 (검증 보고서)

이 도구가 하는 일

Protocol Buffers 파일을 저장하고 protoc 또는 buf를 돌렸는데, 알아보기 힘든 라인/컬럼 오류로 빌드가 죽는 상황. 이 검증기는 엄격한 컴파일러와 동일한 규칙으로 .proto를 파싱해서, 무엇이 잘못됐는지 평이한 언어로 알려줍니다. 커밋해서 CI가 잡아내기 전에 미리 정리할 수 있습니다.

"파싱은 됐는가" 외에도, spec이 실제로 요구하는 검사들을 lint 패스로 함께 돌립니다. 필드 번호는 1..536870911 범위 안에 있어야 하고, 19000..19999 구간은 Google이 내부 용도로 예약해두었으며, 메시지 안의 필드 번호는 모두 고유해야 하고 필드 이름도 중복되면 안 됩니다. 이런 위반들이 실제 빌드 실패를 만들고, 검증기는 컴파일러처럼 한 번에 하나씩이 아니라 한꺼번에 모두 보여줍니다.

모든 동작은 브라우저 안에서 이루어집니다. .proto, 메시지 이름, 패키지 경로가 사용자의 머신을 떠나지 않습니다. 파서는 syntax/package/import 지시문, 라인 및 블록 주석, 중첩된 message와 enum 블록, oneof, map<K, V>, repeated, optional, 서비스(스킵), 필드 옵션을 처리합니다. 공식 proto3 언어 가이드와 동일한 워크플로를 위해 설계됐습니다.

사용 방법

세 단계, 입력 중에 동작합니다. 출력 에디터는 입력을 멈추고 약 300 ms 뒤에 갱신됩니다.

.proto 스키마 붙여넣기

왼쪽 에디터에 스키마를 떨어뜨리세요 — 길이 상관없이 단일 파일이면 됩니다. 맨 위의 syntax = "proto3";는 있어도 좋지만 선택입니다. import 문은 인식되지만 건너뜁니다(파일 간 해석은 여기 범위 밖이며, 임포트된 메시지를 함께 검증하려면 입력에 인라인으로 붙여넣으세요). 모든 주석은 파싱 전에 제거됩니다.

에디터가 붙여넣기 시 스마트 따옴표를 추가하면 검증기가 토큰화 오류를 낼 수 있습니다. 제거하거나 평문 텍스트 소스에서 다시 붙여넣으세요.

보고서 읽기

오른쪽: 스키마가 깨끗하면 녹색 체크, 그렇지 않으면 문제 목록이 나옵니다. 각 문제는 정확한 메시지와 필드를 가리키므로 grep 없이 에디터에서 바로 고칠 수 있습니다. 보고서에는 메시지 수, enum 수, 전체 필드 수 요약도 포함됩니다.

수정 후 다시 붙여넣기

에디터에서 수정한 뒤 갱신된 스키마를 붙여넣으면 출력이 1초 이내에 재검증됩니다. 새로고침도, 리빌드도, CI가 빨갛게 돌아오는 것을 기다릴 필요도 없습니다. 스키마가 깨끗해지면 검증 기록을 남기고 싶을 때 보고서를 PR 코멘트에 복사해 두세요.

실제로 시간이 절약되는 경우

CI에 푸시하기 전에 오류 잡기

팀이 CI에서 buf lint를 돌리고 있다면, 로컬에서 먼저 검증해 두는 것만으로 푸시-대기-빨강-수정-푸시의 사이클이 브라우저 탭 하나로 압축됩니다.

동료의 Protobuf PR 리뷰

동료의 스키마 변경을 리뷰해야 하는데 로컬에 protoc 툴체인이 깔려 있지 않다면, 새 .proto를 여기 붙여 구조적으로 깨끗한지 확인하고 "괜찮아 보임, 머지"가 아닌 초점 있는 리뷰를 남기세요.

proto2 → proto3 마이그레이션

오래된 스키마는 required(proto3에서는 없어진)가 그대로거나, 확인하기 전까지 멀쩡해 보이는 필드 번호가 섞여 있곤 합니다. 검증기는 중복과 범위 외 번호를 한 번에 짚어주므로, 800줄짜리 .proto를 손으로 읽는 것보다 훨씬 빠릅니다.

코드 생성 도구가 만든 .proto 검증

제너레이터(예: JSON Schema → Protobuf, OpenAPI → Protobuf)는 가끔 엣지 케이스 오류를 만들어냅니다 — 중복 필드 번호, 예약 범위 충돌. 출력을 신뢰하기 전에 검증기를 통과시키세요.

자주 묻는 질문

.proto 스키마가 서버로 전송되나요?

아닙니다. 파서와 lint 검사는 모두 브라우저 안에서 JavaScript로 동작합니다. DevTools를 열고 붙여넣는 동안 Network 탭을 보세요 — 요청은 0건입니다. 내부 타입 이름, 패키지 경로, 외부 검증기로 보내고 싶지 않은 어떤 것이 들어 있는 스키마에도 안전합니다.

lint 패스가 정확히 무엇을 검사하나요?

필드 번호는 1..536870911 범위(Google 예약 19000..19999 제외) 안이어야 하고, 메시지 안의 필드 번호는 모두 고유, 필드 이름도 모두 고유해야 합니다. 이 중 하나라도 어기면 정확한 message.field 경로와 함께 보고됩니다. 파싱 단계에서도 세미콜론 누락, 중괄호 불일치, 예상치 못한 토큰 등에서 실패합니다.

proto3 스펙 기준인가요, proto2 기준인가요?

두 문법 모두 받습니다(proto3 default-zero, proto2 required/optional 한정자 등). lint 검사는 스펙으로 정해진 것이라 양쪽에 동일하게 적용됩니다. "proto3에서 required 금지" 같은 가장 엄격한 검사는 여기서는 강제하지 않습니다 — protoc 자체가 잡아냅니다.

왜 필드 번호 19000이 지적되나요?

19000..19999 구간은 Google이 Protocol Buffers 구현 용도로 내부 예약해둔 범위입니다. 이 범위에 필드 번호를 할당하면 실제 protoc가 스키마를 거부합니다. 검증기는 이를 미리 잡아주어 혼란스러운 빌드 오류 대신 이 도구에서 먼저 알 수 있게 해줍니다.

import를 따라가나요?

아닙니다. import 문은 인식되지만 건너뛰며, 다른 파일의 메시지 타입은 "unknown"으로 처리되고 검증되지 않습니다. 임포트된 타입에 의존하는 메시지를 검증해야 한다면, 임포트된 메시지를 같은 입력에 함께 붙여넣으세요.

스키마 크기는 어디까지 처리되나요?

수만 줄도 무리 없습니다. 검증은 로컬, 업로드 없음, 레이트 리밋 없음, 네트워크 왕복 없음 — 원한다면 리포 전체를 붙여넣어도 됩니다. 한계는 브라우저 메모리입니다.

Protobuf 검증기