Files
clean-architecture-backend-…/docs/web-superpowers-package/docs/superpowers/specs/2026-08-13-web-inbound-http-api-execution-platform-design.md
T

31 KiB

인바운드 HTTP API 실행 플랫폼 web 설계서

기준일: 2026-08-13 기준 기술선: Java 21, Spring Boot 4.1 BOM, Spring Framework 7.0.x 대상: Backend Skeleton의 인바운드 HTTP 실행 계층 원본 요구사항: 인바운드 HTTP API 실행 플랫폼 web 심층 리서치


0. 확정 경계 요약

이번 web은 Spring MVC 설정, 공통 ControllerAdvice, Swagger UI를 한데 묶은 편의 라이브러리가 아니다.

HTTP 요청 수신
→ 신뢰 프록시 정규화
→ CORS·Trace·Authentication
→ Global Budget·Admission
→ Route·API Version 선택
→ Route Policy
→ Decode·Binding·Transport Validation
→ Controller Adapter
→ Application Use Case
→ Application Commit Evidence
→ Response Mapping
→ Cache·Conditional Response
→ Problem Details 또는 Streaming Terminal
→ Metric·Access Log·Audit

플랫폼의 핵심 산출물은 “Controller가 호출됐다”가 아니라 다음 세 축의 증거다.

Request Evidence
Application Evidence
Response Evidence
HTTP response write 완료
≠ client가 response를 관찰함

Application method 반환
≠ database transaction commit

HTTP 5xx·connection reset
≠ mutation이 실행되지 않음

상태 변경 재호출의 안전성은 HTTP status가 아니라 Idempotency Scope + Semantic Fingerprint + Authoritative Commit Evidence에서 확보한다.


1. 문서 목적

이 설계서는 구현 중 다시 결정해서는 안 되는 다음 항목을 고정한다.

  • web과 Security·JPA·MongoDB·Redis·Messaging·Fileserver의 책임 경계
  • Stable·Advanced·Experimental 기능 등급
  • MVC·WebFlux 실행 profile
  • HTTP method·status·header·media type 계약
  • DTO·JSON·Validation 정책
  • RFC 9457 Problem Details wire contract
  • Path major API version과 deprecation
  • Cursor·filter·sort·projection 계약
  • ETag·If-Match·If-None-Match
  • Idempotency·Application Commit·Response Loss 복구
  • Durable Operation과 202 Accepted
  • Cache·CORS·CSRF·Forwarded Header·Nginx
  • Request budget·rate limit·admission
  • OpenAPI·Route Inventory·Observability
  • 실제 server·proxy·fault·performance release gate

이 설계서는 도메인 URI, 실제 DTO field, 구체 업무 권한, 업무별 TTL을 정의하지 않는다. 해당 값은 각 애플리케이션 모듈이 본 플랫폼의 catalog와 SPI에 등록한다.


2. 플랫폼 핵심 불변식

2.1 일곱 가지 불변식

  1. HTTP status는 업무 결과를 숨기지 않는다.
  2. Controller는 Application Use Case Adapter다.
  3. Application Commit과 HTTP Response Delivery는 다른 증거다.
  4. Mutation retry는 status가 아니라 idempotency evidence로 판단한다.
  5. ETag/If-Match와 Idempotency는 서로 다른 문제를 해결한다.
  6. Response commit 이후에는 Problem Details로 status를 다시 바꿀 수 없다.
  7. Cache·Proxy·Security·OpenAPI·Observability는 공개 HTTP 계약의 일부다.

2.2 금지되는 설계

Controller → JpaRepository
Controller → EntityManager
Controller → MongoTemplate
Controller → WebClient/RestClient retry
Controller → Kafka/Rabbit ACK
Controller → MinIO SDK
Controller @Transactional
Entity/Document request binding
Entity/Document response serialization
전역 ApiResponse<T>
무제한 Map<String,Object>

3. 기술 기준선

영역 Stable 기준 정책
Java 21 플랫폼 최소선
Spring Boot 4.1 BOM 모든 Spring·Server 버전 Source of Truth
Spring Framework Boot 관리 7.0.x 직접 override 금지
MVC Stable 기본 일반 업무 API
MVC server Tomcat 기본 실제 server release gate
Jetty Stable compatibility 동일 wire contract
WebFlux Stable 선택 profile 완전 reactive chain
WebFlux server Reactor Netty 실제 server gate
Virtual Thread MVC Advanced 별도 부하·pinning 검증
Problem RFC 9457 application/problem+json
HTTP RFC 9110·9111 method/status/cache/conditional
OpenAPI 3.1.2 Stable 3.2는 Experimental
Test mock + actual server + Nginx mock-only Stable 금지

3.1 실행 Profile

PLATFORM_THREAD_MVC
→ Stable default

VIRTUAL_THREAD_MVC
→ Advanced opt-in

REACTIVE_WEBFLUX
→ Stable separate profile

WEBFLUX_BLOCKING_BRIDGE
→ Advanced, bounded and registered

3.2 Starter 선택

web-spring-boot-starter-mvc
XOR
web-spring-boot-starter-webflux

둘 다 classpath에 있으면 startup을 실패시킨다. Spring Boot가 암묵적으로 MVC를 선택하게 두지 않는다.


4. 책임 경계

연계 모듈 web 소유 상대 모듈 소유
Security HTTP authentication context, CORS·CSRF integration token/session 검증, actor·permission 원천
HTTP Client inbound HTTP outbound HTTP, retry, TLS
GraphQL endpoint edge integration schema·resolver·GraphQL error
gRPC 일반 HTTP resource API Protobuf RPC
WebSocket upgrade auth/context bidirectional connection protocol
Fileserver metadata·ticket DTO binary upload/download·Range
JPA·MongoDB Use Case 호출 transaction·query·lock
Redis HTTP rate/idempotency SPI 호출 atomic counter·TTL
Messaging 202·operation representation durable publish·ACK·DLQ
Notification notification request representation provider delivery lifecycle

4.1 허용 호출 구조

HTTP
→ Web Edge Policy
→ Controller Adapter
→ Request DTO
→ Application Command / Query
→ Application Use Case
→ Persistence / Integration
→ Application Result + Commit Evidence
→ Response DTO / Operation Resource
→ HTTP Status + Header + Representation

5. 공개 계층

계층 이름 범위
W1 Standard HTTP API Controller, DTO, validation, Problem, version, pagination, OpenAPI
W2 Advanced HTTP API idempotency, precondition, durable operation, admission
W3 Transport Extension WebFlux, virtual threads, functional endpoint, streaming
W4 Contract/Admin Plane route inventory, OpenAPI publish/diff, usage, audit

5.1 Stable 범위

MVC Controller/DTO
Tomcat
Jetty compatibility
WebFlux separate profile
Validation
RFC 9457
Path major version
Slice·Keyset cursor
ETag·Conditional GET
If-Match mutation
OpenAPI 3.1.2
Registered mutation idempotency
Durable 202 operation

5.2 Advanced

Virtual Thread MVC
Controlled blocking bridge
JSON Merge Patch
JSON Patch
SSE
NDJSON
JSON Sequence
Functional WebFlux
CBOR/XML

5.3 Experimental

OpenAPI 3.2
RateLimit draft headers

5.4 비지원

Raw ServletRequest / ServerWebExchange in domain
Controller transaction
Entity/Document wire model
WebFlux event-loop blocking JPA
Web-owned durable SSE history
Large binary transfer
Bidirectional messaging
Global ApiResponse<T>

6. 모듈 구조

6.1 Stable

modules/web/
├── web-core-api
├── web-contract
├── web-validation
├── web-error
├── web-pagination
├── web-idempotency
├── web-idempotency-jpa
├── web-idempotency-redis
├── web-versioning
├── web-security-integration
├── web-observability
├── web-openapi
├── web-mvc
├── web-webflux
├── web-admin
├── web-operation-jpa
├── web-operation-messaging
├── web-spring-boot-starter-mvc
├── web-spring-boot-starter-webflux
├── web-testkit-core
├── web-testkit-mvc
├── web-testkit-webflux
└── web-testkit-contract

6.2 Advanced

modules/web-advanced/
├── web-advanced-bootstrap
├── web-streaming-core
├── web-streaming-mvc
├── web-streaming-webflux
├── web-patch
├── web-functional-webflux
├── web-codec-cbor
├── web-codec-xml
├── web-openapi-32-experimental
├── web-ratelimit-draft-experimental
└── web-advanced-testkit

6.3 의존 방향

web-core-api
      ↑
contract / validation / error / pagination / idempotency / versioning
      ↑
mvc / webflux / openapi / admin
      ↑
starter-mvc OR starter-webflux

web-core-api에는 다음 type을 넣지 않는다.

HttpServletRequest
HttpServletResponse
ServerWebExchange
Mono
Flux
DataBuffer
ProblemDetail

7. 인바운드 실행 파이프라인

7.1 의미 단계

EDGE
  forwarded normalization
  CORS
  request-id / trace
  authentication
  global budget / admission

ROUTING
  route mapping
  API version

HANDLER POLICY
  route auth
  route rate/admission
  idempotency requirement
  precondition policy

BINDING
  decode
  bind
  transport validation

APPLICATION
  controller adapter
  application use case
  object/tenant authorization
  transaction

OUTBOUND
  response mapping
  cache / ETag
  Problem if uncommitted
  metric / access log / audit

7.2 실행 증거

public enum WebRequestPhase {
    HTTP_RECEIVED,
    REQUEST_NORMALIZED,
    ROUTE_SELECTED,
    REQUEST_BOUND,
    REQUEST_VALIDATED,
    REQUEST_ADMITTED
}

public enum WebApplicationEvidence {
    NOT_STARTED,
    APPLICATION_STARTED,
    APPLICATION_ROLLED_BACK,
    APPLICATION_COMMITTED,
    APPLICATION_UNKNOWN
}

public enum WebResponseEvidence {
    NOT_COMMITTED,
    RESPONSE_HEADERS_COMMITTED,
    RESPONSE_PARTIALLY_WRITTEN,
    RESPONSE_WRITE_COMPLETED_LOCALLY,
    CLIENT_OBSERVATION_UNKNOWN
}

public record WebExecutionEvidence(
        WebRequestPhase requestPhase,
        WebApplicationEvidence applicationEvidence,
        WebResponseEvidence responseEvidence) {
}

7.3 해석

Evidence Application Commit 재호출
request rejected 미진입 없음 수정 후 가능
application started 진입 불명 mutation 자동 재호출 금지
rolled back 진입 없음 profile에 따라 가능
committed 진입 있음 replay/reconcile
headers committed 가능 별도 evidence status만으로 판정 금지
partial response 가능 별도 evidence resume contract 필요
local write complete 가능 별도 evidence client observation 아님

8. Core 공개 타입

public record WebOperationName(String value) {
    public WebOperationName {
        if (value == null || !value.matches("[a-z][a-z0-9.-]{2,127}")) {
            throw new IllegalArgumentException("invalid web operation name");
        }
    }
}

public record WebRouteId(String value) {}
public record WebRequestId(String value) {}
public record WebTraceId(String value) {}
public record ApiMajorVersion(int value) {}
public record WebRequestContext(
        WebRequestId requestId,
        WebTraceId traceId,
        WebOperationName operationName,
        ApiMajorVersion apiVersion,
        ActorContext actor,
        TenantContext tenant,
        Locale locale,
        Instant receivedAt,
        Instant deadline,
        ExternalRequestContext externalRequest) {
}
public enum MutationKind {
    READ_ONLY,
    CREATE,
    REPLACE,
    PARTIAL_UPDATE,
    DELETE,
    COMMAND,
    DURABLE_ASYNC
}
public record WebOperationProfile(
        WebOperationName operationName,
        HttpMethodSemantic method,
        MutationKind mutationKind,
        WebBudgetProfileName requestBudget,
        AuthorizationProfileName authorization,
        IdempotencyPolicy idempotency,
        PreconditionPolicy precondition,
        CachePolicyName cachePolicy,
        AdmissionProfileName admission,
        ResponseProfileName responseProfile) {
}

모든 공개 route는 하나의 등록된 WebOperationProfile을 가져야 한다.


9. URI·Method 계약

9.1 URI

/api/v1/documents/{documentId}

정책:

항목 정책
case sensitive
trailing slash canonical form 하나
duplicate slash reject/edge normalize
encoded slash 기본 reject
matrix parameter 비지원
ID opaque string
DB column 노출 금지
user redirect target raw 사용 금지

9.2 Method

Method 용도 등급
GET query/resource Stable
HEAD GET metadata Stable
POST create/command Stable
PUT replace/create-known-URI Stable
PATCH partial update Stable typed DTO
DELETE deletion Stable
OPTIONS CORS·Allow Stable
TRACE blocked Unsupported
CONNECT blocked Unsupported

9.3 PATCH

방식 등급
typed DTO Stable 기본
JSON Merge Patch RFC 7396 Advanced
JSON Patch RFC 6902 Advanced
Map<String,Object> Unsupported

10. Status·Header 계약

10.1 성공

상황 Status 필수
조회 200 representation
생성 201 Location
durable async 202 operation Location
body 없음 204 body 금지
partial content 206 Fileserver 중심
not modified 304 body 금지

10.2 오류

상황 Status
malformed JSON·conversion 400
unauthenticated 401
unauthorized 403
not found·existence hidden 404
method not allowed 405
not acceptable 406
gone 410
payload too large 413
unsupported media 415
business conflict 409
precondition failed 412
transport semantic validation 422
rate limit 429
admission/capacity 503
upstream bad response 502
upstream timeout 504
internal 500

10.3 Header Catalog

Location
Content-Location
ETag
Last-Modified
If-Match
If-None-Match
If-Modified-Since
If-Unmodified-Since
Cache-Control
Vary
Retry-After
Deprecation
Sunset
Link
Allow
Content-Type
Content-Language

11. JSON·Binding·Validation

11.1 Stable JSON Profile

public record WebJsonProfile(
        boolean rejectUnknownProperties,
        boolean rejectDuplicateKeys,
        boolean rejectTrailingTokens,
        boolean caseSensitiveEnums,
        boolean rejectScalarCoercion,
        int maxDepth,
        int maxArrayElements,
        int maxStringBytes) {
}

기본:

unknown mutation field reject
duplicate key reject
trailing token reject
unknown enum reject
enum case-sensitive
empty string → null disabled
number ↔ string disabled
polymorphism allowlist only

11.2 Validation 계층

Parsing
→ JSON/URI/header syntax

Transport Validation
→ length/range/format/count/cross-field

Application Validation
→ existence/state/permission/domain invariant

Transport validator는 DB·HTTP·Messaging에 접근하지 않는다.

11.3 Wire Manifest

Java JSON
Instant UTC RFC 3339
OffsetDateTime offset ISO
LocalDate YYYY-MM-DD
Duration ISO-8601
UUID canonical
BigDecimal precision·scale contract
long optional string profile
Enum stable wire value
URI normalized
Locale BCP 47

12. Controller Adapter

@RestController
@RequestMapping("/api/v1/documents")
final class DocumentHttpController {
    private final CreateDocumentUseCase createDocument;

    @PostMapping
    ResponseEntity<DocumentResponse> create(
            @Valid @RequestBody CreateDocumentRequest request,
            WebRequestContext context) {

        var result = createDocument.execute(
            request.toCommand(context.actor(), context.tenant())
        );

        return ResponseEntity
            .created(URI.create("/api/v1/documents/" + result.documentId()))
            .body(DocumentResponse.from(result));
    }
}

Controller 허용:

transport input
DTO mapping
context
use case invocation
response mapping

Controller 금지:

transaction
repository composition
retry
broker settlement
binary storage
business state machine

13. RFC 9457 Problem Details

public record WebProblem(
        URI type,
        String title,
        int status,
        String detail,
        URI instance,
        ProblemCode code,
        String traceId,
        List<ValidationIssue> errors) {
}

13.1 Problem Code

MALFORMED_REQUEST                 400
BINDING_FAILED                    400
VALIDATION_FAILED                 422
AUTHENTICATION_REQUIRED           401
ACCESS_DENIED                     403
RESOURCE_NOT_FOUND                404
METHOD_NOT_ALLOWED                405
NOT_ACCEPTABLE                    406
RESOURCE_GONE                     410
RESOURCE_CONFLICT                 409
PRECONDITION_FAILED               412
REQUEST_TOO_LARGE                 413
UNSUPPORTED_MEDIA_TYPE            415
IDEMPOTENCY_KEY_REQUIRED          400
IDEMPOTENCY_KEY_REUSED            422
IDEMPOTENCY_REQUEST_IN_PROGRESS   409
RATE_LIMITED                      429
ADMISSION_REJECTED                503
DEPENDENCY_FAILURE                502/503 profile
DEPENDENCY_TIMEOUT                504
RESPONSE_TOO_LARGE                500/stream termination profile
INTERNAL_ERROR                    500

금지 정보:

stack trace
exception class
SQL/JPQL/Mongo query
internal host
access token/cookie
provider raw body
PII

Factory만 Problem을 만들고 body status와 실제 response status를 검증한다.


14. API Versioning·Deprecation

14.1 Version

Major → /api/v1
Minor/Patch → additive compatibility

Unknown major version은 catalog policy에 따라 404 Problem으로 처리한다.

14.2 Deprecation

Deprecation
Sunset
Link rel=deprecation

제거 gate:

OpenAPI breaking diff
+ usage threshold
+ sunset elapsed
+ client owner confirmation
+ consumer contract
+ rollback plan

15. Collection Query

15.1 방식

방식 용도
Page 작은 admin·total count
Slice 일반 목록
Keyset Cursor 대규모·high-write
offset/limit 제한형

15.2 Catalog

public interface SortFieldCatalog {
    SortField resolve(String externalName);
}

public interface FilterFieldCatalog {
    FilterField resolve(String externalName);
}

public interface FilterOperatorCatalog {
    FilterOperator resolve(String externalName);
}

public interface ProjectionProfileCatalog {
    ProjectionProfile resolve(String externalName);
}

15.3 Cursor

public record WebCursorPayload(
        int version,
        String queryProfile,
        Map<String, String> sortValues,
        String uniqueTieBreaker,
        String filterFingerprint,
        Instant issuedAt,
        String keyId) {
}

HMAC으로 인증하며 다음을 거부한다.

tampered MAC
unknown version
wrong query profile
filter mismatch
missing unique tie-breaker
page hard maximum violation

16. Conditional Request

public record EntityTag(String value, boolean weak) {}
GET/HEAD + matching If-None-Match
→ 304

PUT/PATCH/DELETE + mismatching If-Match
→ 412

PUT + If-None-Match: * + exists
→ 412
If-Match
→ 내가 읽은 revision이 최신인가?

Idempotency
→ 같은 command를 이미 실행했는가?

둘은 함께 필요할 수 있다.


17. Idempotency

17.1 Scope

public record IdempotencyScope(
        TenantFingerprint tenant,
        ActorFingerprint actor,
        WebOperationName operationName,
        IdempotencyKey key) {
}

17.2 상태

public enum IdempotencyState {
    PROCESSING,
    APPLICATION_COMMITTED,
    COMPLETED_REPLAYABLE,
    FAILED_RETRYABLE,
    COMPLETION_UNKNOWN,
    EXPIRED
}

17.3 SPI

public interface IdempotencyStore {
    IdempotencyClaim claim(
            IdempotencyScope scope,
            RequestFingerprint fingerprint,
            Instant expiresAt);

    void recordApplicationCommitted(
            IdempotencyScope scope,
            CommitEvidence evidence);

    void complete(
            IdempotencyScope scope,
            ResponseSnapshot snapshot,
            Instant expiresAt);

    Optional<IdempotencyRecord> find(IdempotencyScope scope);
}

17.4 Semantic Fingerprint

operation name
normalized path IDs
semantic command DTO
selected header allowlist

Raw JSON bytes를 hash하지 않는다.

17.5 Adapter

web-idempotency-jpa
→ business mutation + authoritative evidence same DB transaction

web-idempotency-redis
→ concurrent claim + replay cache
→ sole DB commit evidence 금지

17.6 동일 key 처리

same key + same fingerprint + PROCESSING
→ 409

same key + same fingerprint + COMPLETED
→ original response replay

same key + different fingerprint
→ 422

18. Commit 후 Response Loss

필수 fault scenario:

POST
→ Application transaction COMMIT
→ response write 전 TCP reset
→ client IOException
→ same idempotency key retry
→ previous result replay
→ business side effect count = 1

서버가 response를 썼다는 사실로 client 관측을 증명할 수 없다. 따라서 다음 중 하나가 필요하다.

Idempotency
Client-generated resource ID
Conditional create
Durable Operation
Reconciliation GET

19. Durable Operation과 202

public enum OperationStatus {
    PENDING,
    RUNNING,
    SUCCEEDED,
    FAILED,
    CANCELED,
    EXPIRED
}
public record OperationResource(
        OperationId operationId,
        OperationStatus status,
        Instant createdAt,
        Optional<Instant> startedAt,
        Optional<Instant> completedAt,
        Optional<OperationProgress> progress,
        Optional<URI> resultLocation,
        Optional<WebProblem> problem,
        Optional<Duration> retryAfter,
        Instant expiresAt) {
}

19.1 202 조건

durable operation row commit
OR
business DB transaction + outbox commit

THEN
202 Accepted

금지:

Controller → @Async → 202

19.2 HTTP

POST /api/v1/exports
→ 202 + Location: /api/v1/operations/{id}

GET /api/v1/operations/{id}
DELETE /api/v1/operations/{id}

20. HTTP Cache

Profile Header
sensitive private, no-store
public immutable public, max-age, immutable
public mutable ETag + revalidation
browser private private, max-age
authenticated shared explicit review only
no-cache
→ store 가능, reuse 전 validation

no-store
→ 저장 금지

Vary에는 실제 representation을 바꾸는 bounded header만 넣는다.


21. MVC·WebFlux

21.1 MVC

blocking stack
JPA/blocking Mongo/blocking SDK
dedicated async/streaming executor
actual Tomcat gate
Jetty compatibility

21.2 WebFlux

reactive stack
Reactor Context
event-loop blocking prohibited
actual Reactor Netty gate

21.3 Blocking bridge

Stable에서는 금지한다. Advanced에서 registered operation, bounded concurrency, queue timeout, cancellation을 가진 bridge만 허용한다.


22. Streaming

22.1 범위

SSE
NDJSON
JSON Sequence
Async single response

범위 밖:

WebSocket bidirectional
Messaging durability
Fileserver binary

22.2 Commit 이후 오류

uncommitted
→ Problem Details + 4xx/5xx

committed
→ terminal stream error record if possible
→ otherwise abrupt close evidence

22.3 Policy

heartbeat
idle timeout
max age
max buffered items
slow consumer close
cancellation
shutdown drain

Durable replay는 Messaging/Event Log에 위임한다.


23. Security

23.1 CORS

exact origin allowlist
allowed methods
allowed headers
exposed headers
credential mode
preflight max age

금지:

origin reflection
* + credentials
production all-path unrestricted CORS

23.2 CSRF

Credential CSRF
Session/BFF cookie required
cookie+bearer cookie mutation protected
Authorization header only explicit threat review
service-to-service bearer normally not browser CSRF

23.3 Authorization

Authentication
→ Route/Function permission
→ Use Case permission
→ Object authorization
→ Property authorization
→ Tenant isolation

Route role check가 object authorization을 대신하지 않는다.


24. Proxy·Forwarded Header

24.1 Trusted Nginx

Internet
→ Nginx removes incoming Forwarded/X-Forwarded-*
→ Nginx sets authoritative values
→ internal trusted connection
→ Spring normalization

24.2 External Context

public record ExternalRequestContext(
        String scheme,
        String host,
        int port,
        String prefix,
        String clientAddress) {
}

Raw Host/X-Forwarded-Host로 absolute URI를 만들지 않는다.

24.3 Prefix

production /api
development /dev-api

Prefix는 한 번만 적용한다.


25. Request Budget·Rate Limit·Admission

25.1 Budget

public record WebRequestBudget(
        int maxUriBytes,
        int maxHeaderBytes,
        int maxQueryParameters,
        long maxBodyBytes,
        int maxJsonDepth,
        int maxArrayElements,
        int maxMultipartParts,
        Duration maxExecutionTime,
        long maxResponseBytes) {
}

Standard initial profile:

URI                8 KiB
headers           16 KiB
query params      100
JSON body          1 MiB
large JSON         ≤8 MiB opt-in
JSON depth        64
array elements  1000
multipart parts   20
sync hard time    ≤30s

25.2 Rate Limit

actor/IP/tenant/route quota
→ 429
→ Retry-After

25.3 Admission

global writes
expensive query concurrency
bounded queue timeout
→ 503

Rate limit과 admission은 별도다.


26. Filter·Interceptor 순서

26.1 MVC

Servlet Filter
→ Security Filter Chain
→ Handler Mapping
→ HandlerInterceptor
→ ArgumentResolver
→ Controller
→ ResponseBodyAdvice
→ ExceptionHandler

26.2 WebFlux

WebFilter
→ Security WebFilter
→ Handler Mapping
→ ArgumentResolver
→ Handler
→ Result Handler
→ Error WebExceptionHandler

26.3 Body 처리

금지:

Filter reads entire body
→ String
→ hash/log
→ controller

권장:

bounded decode
→ typed DTO
→ deterministic semantic fingerprint
→ idempotency
→ use case

27. OpenAPI·Route Inventory

27.1 Stable artifact

OpenAPI 3.1.2

27.2 Route

public record WebRouteContract(
        WebRouteId routeId,
        WebOperationName operationName,
        ApiMajorVersion apiVersion,
        String method,
        String pathTemplate,
        Set<String> consumes,
        Set<String> produces,
        boolean deprecated,
        Optional<Instant> sunsetAt) {
}

27.3 Release Gate

OpenAPI lint
schema validation
breaking diff
generated client compile
route inventory match
problem catalog match
deprecation usage
consumer contract

Swagger UI:

Local allow
Dev authenticated
Staging admin
Prod off/admin

28. Observability

28.1 Metrics

http.server.requests
active requests
queued/rejected
request/response bytes
validation failures
problem code
rate/admission reject
idempotency replay
operation state
stream duration
disconnect

허용 tags:

routeTemplate
method
status
outcome
apiVersion
operationName
problemCode
clientProfile

금지:

full URL
query string
user/tenant/resource ID
idempotency key
token
cookie
body

28.2 Access Log

requestId
traceId
method
route template
status
duration
bytes
actor fingerprint
normalized client address

28.3 Audit

admin endpoint
force delete
redrive
permission change
sunset change
idempotency override

29. Startup Validation

다음은 startup failure다.

MVC+WebFlux starter simultaneous
Production unbounded budget
Production Swagger/GraphiQL public
Production trust-all forwarded mode
missing cursor HMAC key
unknown operation profile
duplicate route contract
idempotency required without authoritative adapter
Redis marked as sole DB commit evidence
durable async without durable store/outbox
WebFlux blocking dependency without Advanced bridge

30. 테스트 전략

30.1 Contract

method
content type / accept
binding / validation
status / headers / body
Problem
HEAD
201/202/204/304
pagination/cursor
conditional
cache

30.2 Idempotency

same key concurrent
same key same payload
same key different payload
processing crash
commit response loss
replay
TTL expiry
completion unknown

30.3 Security·Proxy

CORS
CSRF
object/property auth
host injection
forwarded spoof
prefix duplicate
open redirect
body/header/path limits

30.4 Abuse

header/URI/body limit
deep JSON
huge arrays
decompression bomb
slow request
slow response consumer
connection flood
request/write/query flood

30.5 Server Matrix

Stack Gate
MVC + Tomcat Stable
MVC + Jetty compatibility
WebFlux + Reactor Netty Stable profile
Nginx + selected server production topology
MVC Virtual Thread Advanced performance

31. Release 단계

Phase A — HTTP Contract Foundation

modules
DTO/controller boundary
strict JSON
status/header
RFC 9457
MVC Tomcat
WebFlux Reactor Netty

Phase B — Contract Evolution

version
deprecation
route inventory
OpenAPI snapshot/diff
query catalog
signed cursor

Phase C — Mutation Safety

ETag
If-Match
idempotency core
JPA evidence
Redis gate
response-loss fault

Phase D — Durable Operation

operation store
lease
outbox
202 resource
restart/cancel/expire

Phase E — Security·Proxy·Budget

actor/tenant
CORS/CSRF
trusted forwarded
Nginx
rate limit/admission
abuse

Phase F — Operations

metrics
access log
audit
admin snapshot
performance
graceful shutdown

Phase G — Advanced

virtual threads
patch
streaming
optional codecs
experimental contract lanes

32. 완료 정의

Stable 완료는 다음을 모두 증명해야 한다.

Controller가 Use Case만 호출
Entity/Document wire 노출 없음
HTTP status/header 의미 일치
Problem status/body 일치
400/422·409/412 구분
cursor tamper 차단
If-Match lost-update 방지
same-key request dedupe
DB mutation + idempotency evidence atomic
commit response-loss side effect 1회
durable acceptance 뒤에만 202
trusted proxy only
CORS/CSRF policy
bounded budget/admission
OpenAPI and route inventory match
low-cardinality observability
actual Tomcat/Jetty/Reactor Netty/Nginx pass
abuse/performance/shutdown pass

33. 요구사항 추적

리서치 요구 설계 위치
기술선·MVC/WebFlux 3, 21
책임 경계 4
W1~W4 5
모듈 6
실행 증거 7, 18
URI·method 9
status·header 10
binding·validation 11
controller 경계 12
RFC 9457 13
version/deprecation 14
pagination/filter/sort 15
conditional 16
idempotency 17
response loss 18
202 operation 19
cache 20
streaming 22
security 23
proxy 24
budget/rate/admission 25
execution order 26
OpenAPI 27
observability 28
tests/release 30~32