Protobuf를 쓰는 서비스에서 .proto 파일은 코드 생성 입력이 아니라 서비스 사이의 계약서다. 계약이 깨지지 않게 지키는 일은 Buf가, 같은 계약을 HTTP/JSON으로도 내보내는 일은 gRPC-Gateway가 맡는다. 결과적으로 비즈니스 로직은 한 번만 구현하고 프로토콜은 둘을 제공한다.
핵심
- 계약 품질은 CI에서 강제한다. 린트, 기준 브랜치 대비 breaking change 검사, 생성 후 diff 없음 확인을 필수 단계로 두고, 로컬과 CI가 같은 플러그인 버전을 쓰게 한다. Buf는
protoc만 쓸 때의 의존성 관리, 린트 통일, breaking change 검증, 플러그인 코드 생성을 한데 묶는다. 설정은buf.yaml(모듈, 의존성, 린트, breaking 규칙),buf.gen.yaml(생성 플러그인),buf.lock(의존성 잠금)이고, CI는buf lint,buf breaking --against '.git#branch=main',buf generate뒤 diff 없음 확인 순이다. 린트 통과만 보고 의미 호환성 검토를 빠뜨리거나 breaking 기준 브랜치를 잘못 잡는 실수가 흔하다. - 호환성은 번호와 버전으로 지킨다. field 번호는 재사용하지 않고 지울 때
reserved로 막으며, 호환을 깨야 하면v1을 고치지 않고 새 버전 패키지를 만든다.package와 파일 경로는v1,v1beta1같은 버전으로 고정하고, Go·gRPC·gateway·OpenAPI 생성 경로를 나누며, 생성물 커밋 여부를 팀 규칙으로 정한다. - gRPC-Gateway는 Proto에 HTTP 매핑을 붙여 내부는 gRPC, 외부는 HTTP/JSON으로 연다. 가능하면 같은 프로세스에 등록하고, 두 프로토콜의 에러를 같은 도메인 코드로 매핑하며, 인증 정책도 공통 미들웨어로 맞춘다. gRPC-Gateway로 단일 API 듀얼 프로토콜 지원
- HTTP 계층이 하나 더 생기므로 지연은 늘 수 있고, 스트리밍 RPC는 변환 제약이 크다. 경로별 지연을 gRPC와 HTTP로 나눠 관측하고, 클라이언트 계약 테스트로 매핑 회귀를 막는다. gRPC-Gateway로 단일 API 듀얼 프로토콜 지원