문제: `docs/adr/`의 결정 기록 26개는 머리 블록만 한국어이고 본문이 영어다. 소유자는 2026-11-07에 결정 기록도 본문까지 한국어로 쓰기로 정했다(design-docs `repo-structure/README.md` 3.2절). 방법: 결정의 뜻을 바꾸지 않고 옮긴다. 머리 블록(상태·작성일·요약· 현재 정본·대체됨)은 한 글자도 바꾸지 않는다. 본문의 상태·날짜·범위 줄, 나중에 붙인 보완·대체 메모, 따져 본 대안도 함께 옮긴다. 코드· 명령·경로·식별자·설정 키·SQL·표 구조는 원문으로 둔다. 본문이 인용한 영어 원문(루트 CLAUDE.md의 한 문장, 플러그인 주석)은 원문을 두고 뜻을 괄호로 붙인다. 결정 기록은 본문을 고치지 않는 문서라서, 번역하며 본 지금 코드와 다른 점(예: ADR-MONGO-ADV-001은 지웠다고 적은 `scripts/verify-mongodb-advanced.sh`가 지금 있다)은 고치지 않고 보고에 남긴다. 위험: 머리 블록 둘째 줄 「본문은 결정한 때의 원문이다」는 번역한 뒤 문자 그대로는 맞지 않는다. 문구를 고칠지는 통합 단계에서 정한다. 검증: python3 scripts/check-docs.py rc=0(language 줄 26개 지움, head 실패 0), 머리 블록이 HEAD와 같은지 26개 모두 diff로 대조, check-work-docs.py --links(gates.md 범위) 깨진 링크 0.
73 lines
5.2 KiB
Markdown
73 lines
5.2 KiB
Markdown
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
|
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
|
|
|
- 상태: 대체됨
|
|
- 작성일: 2026-08-30
|
|
- 요약: protoc와 Buf CLI 없이 스키마를 관리하려던 결정이다. 2026-09-28 Gradle protobuf plugin과 buf로 바뀌었다.
|
|
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
|
|
- 대체됨: `docs/capability-status.md`
|
|
<!-- 머리 블록 끝 -->
|
|
|
|
# ADR-GRPC-002: schema 관리는 protoc 없이, Buf CLI 없이 돈다
|
|
|
|
- 상태: **대체됨(2026-09-28)** — 2026-09-25 리뷰 후속의 소유자 결정 18
|
|
- 날짜: 2026-08-30
|
|
- 범위: `:grpc:grpc-proto-contract`, `:grpc:grpc-codegen`(둘 다 지움)
|
|
|
|
> **대체됨.** 정규식 `.proto` 검증기와 Buf 규칙의 Java 재구현은 지웠다. schema는 이제 `:grpc:grpc-contract`
|
|
> (`src/grpc/grpc-contract/src/main/proto`)에 있고 Gradle protobuf 플러그인(`com.google.protobuf`, 버전은
|
|
> `src/gradle/libs.versions.toml`에 고정. protoc와 protobuf-java runtime은 둘 다 `protobufGrpc`)이 컴파일한다. 생성된
|
|
> 소스는 그 leaf에서만 Spotless, Checkstyle, Error Prone에서 뺀다. `buf lint`와 `buf breaking`
|
|
> (`src/grpc/grpc-contract/buf.yaml`, STANDARD lint, FILE breaking)은 CI의 `.github/workflows/ci-quality-gates.yml`
|
|
> job `grpc-proto-buf`에서 돈다. proto organization은 `caskeleton`이다(예전에는 `hyeonworks`). 아래 글은 원래 결정의
|
|
> 기록으로 남긴다.
|
|
|
|
## 배경
|
|
|
|
Stable Task 8부터 11은 proto 문체 규칙, Buf format·lint·breaking 관리, Java codegen 소유자 하나, 그리고 쓰는 쪽
|
|
컴파일 결과가 릴리스를 막는 descriptor artifact를 요구한다.
|
|
|
|
그 Task가 이름을 대는 도구 중 둘이 이 toolchain에 없다. Buf CLI는 설치돼 있지 않다. 그리고 `protoc`는 Gradle
|
|
protobuf 플러그인으로 쓸 수 있지만, 이 저장소의 모든 leaf는 google-java-format을 쓴 spotless, checkstyle, HIGH
|
|
confidence의 SpotBugs, Error Prone, `-Werror`를 통과하는데 — 생성된 protobuf 소스는 그중 어느 것도 통과하지 못한다.
|
|
codegen을 켜면 source set 하나를 품질 게이트 다섯에서 빼야 한다.
|
|
|
|
그런 예외에는 선례가 있다: `jmh` source set은 `spotbugsJmh`와 `checkstyleJmh`를 끄고 Error Prone도 끈다. 그러니 빼는
|
|
길은 있다. 하지만 그것은 Task 하나를 위해 leaf의 품질 기준선에 대해 내리는 결정이고, 이 일이 바꾸라고 받은 범위
|
|
밖이다.
|
|
|
|
`adapter:inbound:grpc`에도 반대 방향으로 기록된 결정이 있다: 그 `CLAUDE.md`는 쓰는 기능 모듈이 자기 schema를 가져야
|
|
한다는 이유로 그 leaf에서 protobuf 플러그인과 `.proto`를 금지한다.
|
|
|
|
## 결정
|
|
|
|
`.proto` 소스를 커밋하고, Task가 요구하는 모든 규칙을 protoc 실행도 Buf CLI 호출도 없이 실행되는 Java로 구현한다.
|
|
|
|
`GrpcProtoContractValidator`는 `.proto` 글을 읽고 다음을 강제한다: proto3 문법, `{organization}.{domain}.v{major}`
|
|
패키지 규칙, `java_multiple_files`, 손으로 쓴 것과 겹치지 않는 생성 Java 패키지, `_UNSPECIFIED` enum 0값, 받은 삭제
|
|
이력과 대조한 `reserved` 선언, well-known type 허용 목록, map 필드 허용 목록. 자기 시험에서 커밋한 schema에 대고
|
|
돌므로, 출하하는 `.proto` 파일은 장식이 아니라 살아 있다.
|
|
|
|
`GrpcBufPolicy`는 breaking gate를 Buf의 `FILE` category로 고정하고, 규칙을 따르는 pipeline이 등록하는 lifecycle 단계
|
|
넷을 이름으로 댄다. `GrpcCodegenManifest`는 codegen 소유자를 하나로 고정하고 리터럴 생성기 버전을 거절한다.
|
|
`GrpcDescriptorArtifact`, `GrpcConsumerFixture`, `GrpcSchemaArtifactPublisher`는 schema hash, descriptor digest, 쓰는
|
|
쪽별 소스 깨짐 보고를 싣고, 쓰는 쪽을 깨뜨리는 게시나 이미 릴리스한 버전을 다른 바이트로 다시 게시하는 것을
|
|
거절한다.
|
|
|
|
커밋한 `buf.yaml`도 같은 규칙을 적으므로, CLI가 있는 환경에서 돌리면 같은 판정에 닿는다.
|
|
|
|
## 결과
|
|
|
|
**불변식은 강제하고, 과정은 돌리지 않는다.** Task 8부터 11이 다루는 모든 것 — 어떤 schema 변경을 거절하는지, 어떤
|
|
쓰는 쪽 깨짐이 릴리스를 막는지, 생성을 누가 가지는지 — 이 여기서는 빌드로 검사하는 규칙이다. 빠진 것은 protoc
|
|
호출과 Buf 바이너리다.
|
|
|
|
**codegen을 켜는 것은 한계 있는 변경이다.** `GrpcCodegenManifest.caSkeleton()`이 이미 실제 플러그인 설정이 만족해야
|
|
할 소유자, 관리되는 버전 출처, 빌드 디렉터리 출력 경로, 겹치지 않는 패키지 정책을 이름으로 댄다. 할 일은 source set
|
|
예외와 플러그인 블록이지 재설계가 아니다.
|
|
|
|
**fixture는 텍스트 codec을 쓴다.** `GrpcTextCodec`이 testkit에 UTF-8 marshaller를 줘서, 프로세스 안 lane과 Netty
|
|
lane이 생성된 stub 없이 interceptor, status 대응, metadata 한계, stream 순서를 시험할 수 있다. 그 계약은 메시지
|
|
모양이 아니라 플랫폼과 전송의 성질이므로 바꿔 넣어도 잃는 것이 없다 — 그리고 lane이 codegen이 들어온 뒤가 아니라
|
|
오늘 돈다.
|