Files
clean-architecture-backend-…/docs/web/advanced-capabilities.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.3 KiB

Web Advanced: 지원 매트릭스

Advanced capability는 따로 된 leaf adapter:inbound:web-advanced(src/adapter/inbound/web-advanced, package dev.caskeleton.adapter.inbound.web.advanced)에 있다. 이 leaf를 가진 기본 조립은 없다. app-bootstrap은 이 leaf에 의존하지 않는다. 이 capability 중 하나가 필요한 서비스는 자기 어댑터 leaf에 이 leaf를 implementation으로 더하고 타입을 직접 부른다.

실행 중 스위치가 있는 capability는 셋이고, leaf 자신의 META-INF/spring/...AutoConfiguration.imports로 등록한다. 나머지는 모두 라이브러리다. 속성도 bean도 없고, 서비스 코드가 부르기 전에는 아무 일도 일어나지 않는다.

Capability 켜는 법 더하는 것 테스트
MVC virtual thread app.web.advanced.mvc-virtual-threads.enabled=true(+ 허가 상한과 예산) 모든 요청에 대한 다른 스케줄링 모델 MvcAdvancedConfigurationTest, VirtualThreadAdmissionTest
NDJSON 스트리밍 app.web.advanced.ndjson.enabled=true 오래 사는 connection MvcStreamingWiringTest, WebStreamCoreTest, WebStreamDrainTest, WebStreamingSoakIT
JSON text sequence(RFC 7464) app.web.advanced.json-sequence.enabled=true 오래 사는 connection NDJSON과 같다
JSON Merge Patch(RFC 7396) 라이브러리 — JsonMergePatchApplier 부분 문서 JsonMergePatchApplierTest
JSON Patch(RFC 6902) 라이브러리 — JsonPatchApplier 임의의 pointer JsonPatchApplierTest
CBOR / XML codec 라이브러리 — WebCborMapperFactory, WebXmlMapperFactory. backend jar는 서비스가 고른다 두 번째 decoder WebCodecMapperTest, WebCodecSecurityTest
OpenAPI 3.2 라이브러리 — WebOpenApi32Generator 나란히 만드는 설명 산출물 WebOpenApi32GeneratorTest
messaging에서 stream 다시 보내기 라이브러리 — MessagingReplayBridge 다시 연결한 뒤 이어 받기 MessagingReplayBridgeTest

같은 leaf에 servlet 운영 경로가 닿지 않는 web 라이브러리 package도 있다: http(URI와 method 정책), versioning, operation, budget, contract, security(security context 다리), idempotency(JsonIdempotentResponseCodec), admin/route.

./gradlew :adapter:inbound:web-advanced:test가 전부 돌린다. webAdvancedTest는 tag를 단 부분집합이고, tag가 아무 것도 고르지 않으면 실패한다.

2026-09-25에 지운 것

  • 승격/릴리스 게이트(WebAdvancedPromotionGate, WebAdvancedReleaseManifest, WebAdvancedFeature)와 OpenAPI 3.2 승격 보고서(OpenApi32CompatibilityReport, OpenApiToolchainMatrix). 이 저장소의 릴리스 절차를 검사하는 것이 production 코드에 있었고, 자기 테스트만 그것을 불렀다. 기능 목록은 어떤 코드도 읽지 않는 flag(…json-merge-patch.enabled, …sse.enabled, …cbor.enabled 등)도 적었다.
  • advanced.blockingbridge: WebFlux blocking 다리의 회계 쪽 절반. 어댑터 쪽은 WebFlux 쌍과 함께 사라졌다.
  • functional(FunctionalRouteRegistry, WebFunctionalHandlerAdapter): WebFlux RouterFunction을 만들었는데, servlet만 쓰는 템플릿(D4)에서는 아무것도 그것을 내보내지 않는다. spring-webflux도 함께 leaf를 떠났다.
  • 운영 web 경로가 이미 다른 방식으로 하는 일을 다시 구현한 package들, 그리고 그중 하나만 인증하던 webNginxProxyTest lane:
    • proxy + http.External* — 운영은 server.forward-headers-strategy를 쓴다 (app-bootstrap/src/main/resources/config/server.yml).
    • security CORS/CSRF profile — 운영은 CorsSettings와 SecurityConfig를 쓴다.
    • cache — 운영은 CacheControlFilter를 쓴다.
    • json(WebObjectMapperFactory) — 운영은 Boot의 JsonMapper를 쓴다. 스트리밍 encoder도 이제 그 bean으로 쓴다.
    • openapi.WebOpenApiCustomizer(+ WebOpenApiProfile, CursorSchemaContributor) — 운영은 OpenApiContractConfig로 springdoc을 손본다.

되살리는 길은 docs/capability-status.md(제거된 코드 표)에 있다.

거부하는 것과 그 행이 여기 있는 이유

거부 이유
허가 상한 없는 virtual thread pool 크기가 곧 허가 정책이었다. 그것을 없애면 오는 요청을 다 받고, 늘지 않은 하류 예산에 줄 세운다.
필드 허용 목록 밖의 merge patch merge patch는 부분이라, 어떤 DTO의 빠진 필드도 「허락 안 함」을 뜻하지 않는다. 허용 목록이 없으면 누가 필드를 더할 때마다 쓸 수 있는 집합이 커진다.
허락한 접두사보다 위의 JSON Patch pointer 부모를 바꾸면 모든 형제가 지워진다. 그래서 자식에 대한 권한이 부모 권한을 줄 수 없다.
출처가 허락되지 않은 move 목적지만 검사하면 호출자가 건드릴 수 없는 필드의 데이터를 옮겨 낼 수 있다.
DTD나 외부 entity가 있는 XML Billion-laughs와 XXE. 둘 다 터져도 오류가 나지 않는다. 파싱은 성공하고 문서에 있으면 안 되는 것이 들어 있다.
세 관문을 다 지나지 않은 JSON 아닌 표현 서비스가 RepresentationNegotiationPolicy에 넘기는 켜진 집합, route의 produces, client 허용 목록. Accept 헤더는 그 route가 그 codec으로 시험됐다는 증거가 아니다.
406에서 압축처럼 조용히 물러서기 CBOR만 요청한 client가 JSON을 받으면 그 바이트를 CBOR로 파싱하다 먼 곳에서 실패한다.
commit 뒤 HTTP 상태 바꾸기 본문이 반은 stream, 반은 JSON이 되고, 200이 cache된다.
느린 소비자를 위한 상한 없는 버퍼링 client의 느림을 서버의 heap으로 옮긴다.

끄기

의존성을 빼면 capability가 사라진다. 의존성이 있어도 스위치 셋은 기본으로 꺼져 있다. WebAdvancedRollbackIT가 flag를 하나도 주지 않았을 때와 각 flag를 명시적으로 false로 줬을 때 Advanced bean이 하나도 없음을 단언한다.

docs/adr/ADR-WEB-ADV-001-streaming-is-live-delivery.md, ADR-WEB-ADV-002-virtual-threads-do-not-remove-admission.md, ADR-WEB-ADV-003-openapi-32-remains-experimental.md를 본다.