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 일곱 가지 불변식
- HTTP status는 업무 결과를 숨기지 않는다.
- Controller는 Application Use Case Adapter다.
- Application Commit과 HTTP Response Delivery는 다른 증거다.
- Mutation retry는 status가 아니라 idempotency evidence로 판단한다.
- ETag/If-Match와 Idempotency는 서로 다른 문제를 해결한다.
- Response commit 이후에는 Problem Details로 status를 다시 바꿀 수 없다.
- 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 |