Buf v2 기반 Proto 관리 및 코드 자동 생성

Buf를 쓰는 이유

protoc 단독 사용의 반복 문제를 Buf가 정리해 줍니다.

• 의존성 관리
• 린트 규칙 통일
• breaking change 검증
• 플러그인 기반 코드 생성

기본 파일

• buf.yaml: 모듈/의존성/린트/브레이킹 규칙
• buf.gen.yaml: 생성 플러그인 설정
• buf.lock: 의존성 잠금

추천 구조

proto/
  v1/
    service.proto
buf.yaml
buf.gen.yaml

핵심 명령

buf lint
buf breaking --against '.git#branch=main'
buf generate

CI 최소 기준:

1. buf lint
2. buf breaking
3. buf generate 후 diff 없음 확인

운영 규칙

• package와 파일 경로를 버전(v1, v1beta1) 기준으로 고정
• field 번호 재사용 금지, 삭제 시 reserved 선언
• 호환성 깨는 변경은 새 버전 패키지로 분리

코드 생성 팁

• Go/gRPC/gateway/OpenAPI 생성 경로를 명확히 분리
• 생성 산출물 커밋 여부를 팀 규칙으로 고정
• 로컬과 CI에서 같은 플러그인 버전 사용

자주 하는 실수

• lint 통과만 보고 의미 호환성 검토 누락
• breaking 기준 브랜치 설정 오류
• 옵션 파일/외부 proto 의존성 버전 불일치

요약

Buf 도입의 핵심 가치는 "생성 편의"보다 "계약 품질 관리"입니다. proto를 API 계약으로 운영하려면 lint + breaking + generate를 CI 필수 단계로 묶어야 합니다.