Files
clean-architecture-backend-…/docs/web/runbook.md
T
DongHyeonka 9d6c67c14e docs(web): web 운영 문서를 한국어로 옮기고 코드와 맞춘다
문제: docs/web 아래 살아 있는 문서 7개가 영어였다(language 예외). http-contract.md는
짝 프론트 repo의 문서를 이 repo 경로처럼 인라인 코드로 적었다(reference 예외).
repository-adaptation.md는 번역하며 보니 지금 코드와 여러 곳이 달랐다.
- 1절 표: 설계 모듈 대부분을 「planned」로 적었지만 `core`·`mvc`는 web leaf에,
  `contract`·`versioning`·`admin`·`openapi`·`idempotency`는 web-advanced leaf에 이미 있다.
  `fileserver.*`·`notification.*`는 web leaf가 아니라 web-fileserver·web-notification leaf다.
- Advanced 절: Advanced가 「이 leaf」의 package이고 `WebArchitectureRules.stableDoesNotDependOnAdvanced()`
  (`WEB-ARCH-ADV`)가 방향을 막는다고 했다. 그런 규칙은 없고, Advanced는 따로 된 leaf
  `adapter:inbound:web-advanced`이며 registry가 web-advanced → web 방향만 허락한다.
- 4절: Spring Boot 기준을 4.0.8로 옮겨 적고 없는 `.vscode/settings.json`을 근거로 들었다.
- 6절: 다시 보내기 JSON 인코딩이 web leaf에 남는다고 했지만 web-advanced에 있다.
- 7절: web leaf가 의존할 수 있는 leaf에서 `adapter-outbound-support`가 빠졌다.

고친 방법: 뜻을 그대로 옮기고 식별자·명령·경로·설정 key·오류 코드·표 구조는 원문으로
둔다. 위 불일치는 registry와 트리에 맞춰 고쳤다. 다른 repo 문서는 경로 대신 repo 이름과
문서 이름을 문장으로 쓴다. 버전은 src/gradle/libs.versions.toml을 가리킨다.

버린 대안: 1절 표를 지우고 registry만 가리키기. 설계와 트리를 대조하는 사람에게 필요한
대응이 사라진다.

위험·한계: 내용 감사는 하지 않았다. 번역하며 본 불일치만 고쳤다.

검증: python3 scripts/check-docs.py에서 이 폴더 예외 줄 0. docs/web을 읽는 테스트는
주석뿐이다(`grep -rn 'docs/web' src --include=*.java`: EnvelopeWireShapeTest 등 주석).
2026-11-07 17:29:57 +09:00

6.0 KiB

Web 플랫폼 runbook

HTTP 경계가 이상할 때 운영자에게 필요한 것이다. 어느 모듈이 가졌는지가 아니라 무엇을 보았는지로 나눴다. 새벽 3시에 손에 있는 것이 그것이기 때문이다.

429 읽기

RateLimitInterceptor는 edge 속도 제한이 호출자를 거부하면 Retry-After와 함께 429 RATE_LIMIT_EXCEEDED로 답한다. RATE_LIMIT_UNAVAILABLE은 호출자가 무언가를 넘었다는 뜻이 아니라 속도 제한 저장소에 닿지 못했다는 뜻이다. 호출자가 아니라 저장소를 본다.

Envelope가 아닌 오류

애플리케이션이 쓰는 모든 HTTP 오류는 GlobalExceptionHandler가 쓰는 Envelope이고 (spring.mvc.problemdetails.enabled=false), client가 분기하는 error.code를 가진다.

  • 빨리 확인하는 법: 검증에 실패해야 하는 요청을 보내고 본문에 error.code가 있는지 본다. 없으면(Spring의 ProblemDetail이나 container의 오류 쪽) handler가 설치되지 않았거나 응답이 edge에서 왔다.

응답이 잘리거나 문서 중간에 connection이 끊긴다

원인은 둘이고, client가 받은 상태로 구분한다.

  • client가 상태를 받고 그다음 아무것도 없다 — 응답이 commit 뒤에 실패했다. 상태는 되돌릴 수 없으므로 문서 중간에 connection이 끝난다.
  • client가 애플리케이션에서 아무것도 받지 못했다 — proxy가 거부했다. nginx의 client_max_body_size는 Envelope가 아니라 자기 HTML로 답한다. repository-adaptation.md §8을 본다.

재시도한 쓰기가 두 번 일어났다

통제 수단은 멱등 key이고, 그것이 적용되지 않는 길은 정확히 셋이다.

  1. client가 key를 보내지 않았다. endpoint가 key를 요구하지 않으니 보호 없이 돌았다. 중복을 받아들일 수 없으면 key를 요구한다.
  2. client가 다른 본문을 보냈다. 422 IDEMPOTENT_REQUEST_MISMATCH로 답하고 절대 다시 보내지 않는다. 다시 보내면 호출자가 한 적 없는 요청의 영수증을 돌려주게 된다.
  3. 기록이 만료됐다. TTL은 연산마다 정하고 상한은 72h다. 만료 뒤의 재시도는 정의상 새 요청이다.

409 IDEMPOTENT_IN_FLIGHT(retryable=true, Retry-After: 2)는 실패가 아니다. 앞 시도가 아직 돌고 있고 그 결과를 모른다. 호출자는 Retry-After 뒤에 같은 Idempotency-Key로 다시 보낸다. 새 key는 새 요청이고, 쓰기가 두 번 적용되는 길이 그것이다. 멱등성 답 넷은 http-contract.md §2에 있다.

rolling 배포가 인스턴스를 반쯤 비운 채 멈춘다

shutDownGracefully는 진행 중인 일을 기다리고, 열려 있지만 노는 keep-alive connection이 진행 중으로 셀 수 있다. 그 기다림 중에 stop()을 부르면 멈춘다.

  • 증상: 요청을 받지도 않고 끝나지도 않는 인스턴스. 로그에 오류가 없다.
  • 원인: 상한 없는 graceful 기다림. GracefulShutdownProbe는 정한 유예 시간으로 그것을 제한하고, 시간이 지나면 어쨌든 서버를 멈춘다. 배포도 같게 해야 한다.
  • 설정: spring.lifecycle.timeout-per-shutdown-phase. 상한이 없으면 배포는 영영 놀지 않을 수도 있는 connection을 기다린다.

metric이 오지 않거나 청구액이 뛰었다

거의 늘 가짓수가 많은 tag다. 흔히 풀린 경로를 담은 routeTemplate이고, 자원마다 시계열 하나가 된다.

  • 확인: metric 저장소에서 routeTemplate의 tag 값을 본다. 중괄호가 있으면 template이고, 식별자가 있으면 풀린 경로가 새어 나갔다.
  • 절대 tag로 쓰지 않는 것: URL, query string, 식별자, tenant, key, token, cookie, 본문. tag 값은 가려지지 않은 채 metric 저장소에 닿고, 보통 그와 함께 외부 SaaS에도 닿는다.

브라우저에서만 cross-origin 요청이 실패한다

API는 맞게 답하는데 브라우저가 응답을 거부한다. CORS는 SecurityConfig가 적용하는 CorsSettings(app.cors.*)다. 시작 단계는 두 설정을 거부한다.

  • origin 없이 APP_SECURITY_CORS_ENABLED=true.
  • APP_SECURITY_CORS_ALLOW_CREDENTIALS=true와 함께 APP_SECURITY_CORS_ORIGINS의 * — 어떤 브라우저도 받아들이지 않는다.

다음 둘은 시작은 되지만 브라우저에서 여전히 실패한다.

  • origin 목록의 https://*.example.com — 글자 그대로 비교하므로 아무것에도 맞지 않는다.
  • 경로가 있는 origin(https://app.example.com/ui) — origin은 scheme, host, port뿐이다.

응답은 오는데 브라우저 코드에서 헤더가 null로 읽힌다(Retry-After, X-Request-Id, Location, tus Upload-Offset): 그 헤더가 Access-Control-Expose-Headers에 없다. 노출 목록은 CorsExposedHeaders.PLATFORM과 모듈마다의 CorsExposedHeaders bean이다(docs/web/http-contract.md §3). 서비스가 더한 헤더에는 자기 bean이 필요하다. Access-Control-Expose-Headers를 지우거나 고쳐 쓰는 proxy도 같은 증상을 낸다.

preflight가 401로 답하면 CORS가 인증 뒤에 돈 것이다. preflight는 설계상 credential을 싣지 않는다. 순서는 WebPipelineOrderContract가 단언한다.

요청 하나에 접근 로그 줄이 둘

async 요청은 servlet filter chain을 두 번 지난다. 처음 요청 때 한 번, ASYNC 재전달 때 또 한 번이다. isAsyncStarted()를 확인하지 않고 기록한 완료는 두 번 쓰이고, 그 데이터로 계산한 모든 지연 백분위수는 그럴듯해 보이면서 틀린다. WebPipelineOrderContract가 모든 container에서 논리 요청마다 관측이 정확히 하나임을 단언한다.

확인 명령

cd src
./gradlew :adapter:inbound:web:test                          # 단위, 경계, 아키텍처
./gradlew :adapter:inbound:web:systemTest                    # Tomcat, 실제 socket
./gradlew :adapter:inbound:web:webJettyCompatTest            # 두 번째 servlet container