DongHyeonka ce83f4d550
pr / ci (pull_request) Successful in 1m9s
docs: 별도 repo 라이브러리로서의 지침·작업 문서·릴리스 절차를 쓴다
옮겨 온 문서는 템플릿 안의 optional build를 전제로 했다(`-p
platforms/optional-build`, 템플릿 registry·workflow 경로, "벤더드 플랫폼").
하네스 뼈대의 루트 지침과 문제 정의는 비어 있었다.

- 루트 AGENTS.md(38줄)·CLAUDE.md: 꼭 지킬 것(core-api 순수성, Stable이
  advanced를 안 씀, 템플릿에 기대지 않음, 배포한 버전 불변, 버전 규칙),
  지도, 맡은 일, 검증 진입점. 비대화형 세션의 플러그인 설치 두 줄.
- README: 무엇인가, 받는 법(exclusiveContent), 지원 표, 구조, 문서 지도,
  서명, 이력(filter-repo, 커밋 SHA·리뷰 ID는 템플릿 기준).
- docs/work/README.md·gates.md·release.md: 고치는 법, 단계와 바꾼 것별
  게이트, 템플릿과 같이 고치기(composite), 릴리스와 소유자가 할 일
  (PACKAGES_TOKEN, SIGNING_KEY·SIGNING_PASSWORD, 첫 태그 v1.0.0).
- CHANGELOG.md(1.0.0 미발행, 옮기는 법), docs/README.md(지도, 머리 블록).
- scripts/verify.sh: unit·pr·main·release 단계. 라이브러리라 app은 없다.
- 살아 있는 문서(grpc·grpc-advanced AGENTS.md, 지원 매트릭스, runbook):
  경로·패키지·optional build 문장을 이 repo 기준으로. ADR·설계서 본문은
  기록이라 고치지 않았다.
- docs/vision.md는 소유자가 쓰는 문서라 비워 두었다.

검증: scripts/verify.sh docs rc=0(AGENTS.md 38줄, 장부 JSON).
2026-11-08 11:22:12 +09:00

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)이 붙는다. 공개 키는 첫 릴리스 때 소유자가 여기에 붙인다(docs/work/release.md 1절).

이력

  • 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로 옮겼다(템플릿 main 22df3525 기준). 옮긴 코드 폴더의 트리 해시는 템플릿 기준 커밋과 같다.
  • filter-repo가 커밋 SHA를 모두 다시 썼다. 코드 주석과 문서가 부르는 커밋 SHA와 리뷰 ID(RR6-…, BUILD-O3-5 등)는 템플릿 repo 기준이다. 그 리뷰 문서는 템플릿 docs/reviews/에 남아 있다.
  • 설계와 결정: design-docs repo-structure/05-library-repos.md(소유자 승인 2026-11-07).
S
Description
clean-architecture-backend-template에서 빼낸 grpc-library (design-docs repo-structure/05-library-repos.md)
Readme
1.7 MiB
Languages
Java 98.3%
Shell 1.5%
Python 0.2%