bufBreaking은 기준(PR이면 merge base, main이면 직전 커밋)과 schema를
비교해 깨짐이면 무조건 실패했다. 그래서 일부러 깨는 변경(바로 앞 커밋의
proto 패키지 이름 바꾸기 같은 것)은 PR도 병합 뒤 main도 빨갛게 만들고,
통과시킬 길이 기준을 손으로 바꾸는 것뿐이었다.
기준과 HEAD 사이 커밋 하나가 `BREAKING CHANGE:` 꼬리말로 선언하면
통과시킨다. 커밋 규칙이 이미 깨지는 변경에 요구하는 표시이고, 그 표시가
MAJOR 버전의 근거다(docs/work/release.md 2절). 선언 없는 깨짐은 전처럼
실패하고, 고치는 길(되돌리기 또는 선언)을 말한다.
버린 대안: 첫 릴리스 전에는 검사를 끄기(태그 뒤의 첫 깨짐을 놓친다),
마지막 릴리스 태그와 비교(한 번 선언한 깨짐 뒤로 다음 릴리스까지 모든
PR이 빨개진다).
검증(desktop): HEAD c8f8721(BREAKING CHANGE 선언)과 기준 bbe49ac — 깨짐을
알리고 rc=0. 같은 트리에 꼬리말 없는 메시지로 바꾼 버리는 사본 — rc=1과
안내. gates.md 4절에 규칙을 적었다.
grpc-library
Spring Boot 앱에 gRPC 서버·클라이언트를 붙이는 플랫폼 라이브러리다. 타입 있는 서비스 adapter, method 정책(deadline·멱등성·크기 한도), 실행 증거와 실패 모델, durable operation 원장, 관측 규칙, 인증 lane(in-process·실제 Netty·fault·performance)을 준다.
앱 소유 port ──> 앱의 inbound adapter ──> grpc-spring-boot-starter (조립)
├─ grpc-runtime (io.grpc 위의 정책·서버·클라이언트)
├─ grpc-core-api (Java 표준 라이브러리만: 식별자·정책·증거·실패 모델)
├─ grpc-observability (metric·trace 규칙)
└─ grpc-operation-ledger-jpa (선택: 멱등성 원장)
받는 법
Maven group은 com.hyeonworks.grpc, artifact는 모듈 이름 그대로다(grpc-core-api, grpc-runtime, grpc-spring-boot-starter, …). 저장소는 소유자 Gitea Packages이고, 공개라 읽을 때 토큰이 필요 없다.
// settings.gradle
dependencyResolutionManagement {
repositories {
exclusiveContent {
forRepository {
maven { url = 'https://git.learn.hyeonworks.com/api/packages/donghyeon.kang/maven' }
}
filter { includeGroupByRegex 'com\\.hyeonworks(\\..*)?' }
}
mavenCentral()
}
}
// build.gradle
dependencies {
implementation 'com.hyeonworks.grpc:grpc-spring-boot-starter:1.0.0'
}
exclusiveContent는 com.hyeonworks group을 이 저장소에서만, 나머지는 Maven Central에서만 찾게 한다. 같은 이름을 공개 저장소에 올리는 공격이 통하지 않고, Gitea가 느려도 다른 의존성 해석에는 영향이 없다.
지원 표
| 라이브러리 | Spring Boot(컴파일·시험한 줄) | io.grpc BOM | Java |
|---|---|---|---|
| 1.0.x | 4.0.x (4.0.9) |
1.75.0 | 21 |
무엇을 인증했고 무엇은 지켜보기만 하는지는 docs/compatibility/grpc-support-matrix.md와 grpc-advanced-support-matrix.md다.
프로젝트 구조
| 폴더 | 무엇 |
|---|---|
grpc/ |
Stable 모듈 7개(Unary, Server Streaming). 규칙은 grpc/AGENTS.md |
grpc-advanced/ |
capability flag 뒤의 고급 능력 2개(client·bidi streaming, xDS, gRPC-Web 등). 규칙은 grpc-advanced/AGENTS.md |
build-logic/ |
백엔드 템플릿에서 복사해 줄인 Gradle convention 플러그인. 출처는 build-logic/UPSTREAM.md |
config/ |
모듈 registry(architecture/modules.json), Checkstyle·SpotBugs 설정, 테스트 컨테이너 이미지 |
scripts/ |
검증 진입점 verify.sh, 고정 도구 tool.sh, Buf buf.sh, 릴리스 보조 release/ |
.gitea/workflows/ |
단계 파일 셋: pr.yml(ci), main.yml(mainCheck), release.yml(releaseCheck release) |
docs/ |
문서. 지도는 docs/README.md |
문서 지도
- 작업 방법:
docs/work/README.md(고치기·리뷰),docs/work/gates.md(게이트),docs/work/release.md(릴리스·버전 규칙·비밀 값) - 결정 기록:
docs/adr/(ADR-GRPC-001~006, ADR-GRPC-ADV-001) - 운영:
docs/runbooks/grpc-platform-operations.md,docs/runbooks/grpc-advanced-capabilities.md - 설계서:
docs/design/2026-08-30-grpc-platform-adaptation-design.md - 바뀐 것:
CHANGELOG.md
서명
배포 파일마다 PGP 서명(.asc)이 붙는다. 서명 키는 RSA 4096, 지문 92646CEAFE816CF8B9C249F0A1C936D7F791F8AB, 2028-11-07에 만료된다. 키를 바꾸는 법은 docs/work/release.md 1절이다.
-----BEGIN PGP PUBLIC KEY BLOCK-----
mQINBGrv1SYBEADGgq8CTE7wdDPIg0zNRXelPvlgyK04tpDTL0b9k1INxDwFEiS0
87bTL22Zjipp+2uDg012TALeLsDV12yh1IToNaYq7zR9bRvEua25+351zw91ojC+
z2/1Y7S98o813hu6qP6EFUHnsWPVLEt40mlGDn3kl8iXMLgjozVYbylomweh/Yvz
HLJd5lQGE76mIejIeGp3m1OA5M2RV4xspA8K8TZkXXSqe3nbfSjPXAOwysPmRRd9
IoLDwakSq4tRI9dlm08bzznsoaaTCRcJ0XAbJK7+ZrQkSwIrsi/gsBkCOJI6Wcs6
+R+9Wy7tYsyd59TdgIdjq3uHadSLWQ3dc0g0ux2krxSL0PHXrT9Upmcorj2+Ltkh
9J1I6hUv1O7e0Y8Es7Ov5WUPfdSdQ5ApwtwFX5aSwYokoW9wXMLg2zdQx0JEx1ix
/qTEvpSKfM0/zVbKJO9RDF/F7HZkDWSOhZe+4x7dak+xN6KOfEQVmcBneaGtPqgJ
eAsIBgRwp42G5llqnTcWAHLAKCDEE9wHK3+gJt5f5rO5e+r1GoYHLn0Iw3iiX6rC
NFot/5my/oePTeRur5tjv14kw1FMXHVNvLOxHeaiZzfVVjO/vbwAtGvZDiRdAgd6
kHyt9Ch/JccIa0ylA9Tttb0A33ZGTQl6sAC6jTSIhfnEAdlCX7MVAE8n4wARAQAB
tCNkb25naHllb24ua2FuZyA8ZG9uZzUxMjlAZ21haWwuY29tPokCVwQTAQoAQRYh
BJJkbOr+gWz4ucJJ8KHJNtf3kfirBQJq79UmAhsDBQkDwmcABQsJCAcCAiICBhUK
CQgLAgQWAgMBAh4HAheAAAoJEKHJNtf3kfir2j8P/RWRT0GTxBNQvm76iO6XnvFD
mDPGq37A5iuD4pJ624/BccKTGe8+WWqtlpAiN6AdHGNi/LGhuYaGL9ce6Gja5tTX
y/ZY8jthbEoi41g6cim8W8knd3v2Ne/qj3dKvphSiVsZBrumEzrZyw2UUD3IRqVx
r2WQZTcSa4UDd7+Qie0h8IrnmfMYIseDCWjDCATNJqr9PBGoKYehv8+Wo3QDVBRd
B0lWepudJjLTsPCXsgFnFJ2HmltRQr1JB+I4CPasfsBp3xqF23hywUuW6fOsHZvv
g5QU7qYfaoxG6E8krGpiibocF5EKXtpEYzDOBFoDS9uNVBAD/LzS7OGtTFr5x3qL
is3eccwNClQS1jeX8Guxam+TlO8XaqnQLCIpdau20/sge6PqXKXauKZiBTGCak1j
zVDQ/sro3VRPePusNHK1CdOi6wiruXw4ZLWO3aEHibi8LbgfwymxXHEtJO5zwFcD
qAnp7KEAkOG8y5LR0FfwWWYnqUZxWJ0ua2Acf8gL8o6DO5pVyJSYrdgCpWjwEWcp
Ms2iit9bCNIMaH6EVgLA2NWCuIL9xAFdXqw/VXrMVK3XXftzNvayvLJCH2eintRg
IKLO/ewISKIFQd3+II3/MM80eUvKGtfi8Y1mj1zyQtcPVykru5DEHjpaLs2SPxdI
Lp+HGQo/NvzwdpIV+8TQ
=eD8w
-----END PGP PUBLIC KEY BLOCK-----
받은 파일을 확인하는 법: 위 키를 gpg --import로 넣고 gpg --verify <파일>.asc <파일>. 배포 토큰 secret 이름은 설계 문서의 PACKAGES_TOKEN이 아니라 등록된 PACKAGE_TOKEN이다.
이력
- 2026-08-31 ~ 2026-11-07: 백엔드 템플릿
clean-architecture-backend-template안에서 만들었다(src/grpc,src/grpc-advanced,src/optional-platforms→ 2026-11-07부터src/platforms/…). - 2026-11-08:
git filter-repo로 그 경로들의 이력을 이 repo로 옮겼다(템플릿 main22df3525기준). 옮긴 코드 폴더의 트리 해시는 템플릿 기준 커밋과 같다. - filter-repo가 커밋 SHA를 모두 다시 썼다. 코드 주석과 문서가 부르는 커밋 SHA와 리뷰 ID(
RR6-…,BUILD-O3-5등)는 템플릿 repo 기준이다. 그 리뷰 문서는 템플릿docs/reviews/에 남아 있다. - 설계와 결정: design-docs
repo-structure/05-library-repos.md(소유자 승인 2026-11-07).