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 듀얼 프로토콜 지원

관련