From d9c2c9fcaa024ead664fa3aea089b54def0d203c Mon Sep 17 00:00:00 2001 From: forge-bot Date: Tue, 14 Jul 2026 06:31:51 +0000 Subject: [PATCH] =?UTF-8?q?TA=20=EC=97=AD=ED=95=A0=20Spring=20=EA=B2=BD?= =?UTF-8?q?=EA=B3=84=20smoke=20(role-ta-live-1522-001)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../ADR-001-spring-architecture-boundaries.md | 126 ++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 docs/adr/ADR-001-spring-architecture-boundaries.md diff --git a/docs/adr/ADR-001-spring-architecture-boundaries.md b/docs/adr/ADR-001-spring-architecture-boundaries.md new file mode 100644 index 0000000..2d57bf9 --- /dev/null +++ b/docs/adr/ADR-001-spring-architecture-boundaries.md @@ -0,0 +1,126 @@ +# ADR-001: Spring MVC 경계, 오류 계약 및 트랜잭션 경계 + +## 상태 +**수용됨** — 2026-07-14 + +## 컨텍스트 + +본 프로젝트는 역할 기반 접근 제어(RBAC) 매트릭스를 런타임에 관리하는 Spring Boot 애플리케이션이다. +복잡한 도메인 로직과 다중 데이터 소스를 다루며, 명확한 계층 경계와 일관된 오류 처리가 필수적이다. + +### 현재 문제점 +- Controller에서 직접 Repository 호출 → 테스트 불가능한 구조 +- 예외 처리가 각 계층에 산재 → 일관된 API 응답 불가 +- 트랜잭션 경계가 불명확 → 데이터 불일치 위험 + +## 결정 + +### 1. Controller-Service-Repository 경계 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Controller Layer │ +│ • HTTP 요청/응답 변환 │ +│ • 입력 검증 (Bean Validation) │ +│ • HTTP 상태 코드 결정 │ +│ • DTO 변환 (Request → Command, Response ← Result) │ +│ ❌ 비즈니스 로직 금지 │ +└─────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Service Layer │ +│ • 비즈니스 로직 수행 │ +│ • 도메인 객체 조작 │ +│ • @Transactional 경계 관리 │ +│ • 도메인 예외 발생 (DomainException) │ +│ ❌ HTTP/프레젠테션 concerns 금지 │ +└─────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Repository Layer │ +│ • 데이터 접근 추상화 (JPA Repository) │ +│ • 엔티티 ↔ 도메인 객체 변환 │ +│ • 쿼리 메서드 정의 │ +│ ❌ 비즈니스 로직 금지 │ +└─────────────────────────────────────────────────────────────┘ +``` + +**경계 규칙:** +- Controller → Service: Command/DTO 전달, Result/DTO 수신 +- Service → Repository: 도메인 객체 또는 ID 전달, 도메인 객체 수신 +- 하위 계층이 상위 계층을 직접 참조 금지 (의존성 역전) + +### 2. 오류 계약 (Error Contract) + +#### 2.1 표준 오류 응답 형식 + +```json +{ + "timestamp": "2026-07-14T15:22:00Z", + "status": 400, + "error": "Bad Request", + "code": "ROLE_MATRIX_001", + "message": "역할 매트릭스 이름은 필수입니다", + "path": "/api/v1/role-matrices", + "traceId": "abc123" +} +``` + +#### 2.2 예외 계층 구조 + +``` +Throwable +└── RuntimeException + └── GlobalException (공통 기반 예외) + ├── DomainException (도메인业务 예외) + │ ├── RoleMatrixNotFoundException + │ ├── RoleNotFoundException + │ └── DuplicateRoleMatrixException + ├── ValidationException (검증 예외) + └── InfrastructureException (인프라 예외) + ├── DataAccessException + └── ExternalServiceException +``` + +#### 2.3 예외-상태코드 매핑 + +| 예외 클래스 | HTTP 상태 | 오류 코드 접두사 | +|------------|-----------|------------------| +| ValidationException | 400 | VAL_ | +| DomainException | 400/409 | DOM_ | +| RoleMatrixNotFoundException | 404 | NOT_FOUND_ | +| DuplicateRoleMatrixException | 409 | CONFLICT_ | +| InfrastructureException | 500/503 | SYS_ | + +### 3. 트랜잭션 경계 + +| 작업 유형 | 트랜잭션 전파 | 격리 수준 | 읽기 전용 | +|----------|-------------|----------|----------| +| 조회 (SELECT) | REQUIRED | READ_COMMITTED | true | +| 단일 생성/수정/삭제 | REQUIRED | READ_COMMITTED | false | +| 다중 변경 (배치) | REQUIRED_NEW | READ_COMMITTED | false | + +**롤백 규칙:** +- RuntimeException → 자동 롤백 +- Checked Exception → 명시적 rollbackFor 필요 +- DomainException (RuntimeException 하위) → 자동 롤백 + +## 대안들 + +### 대안 1: 트랜잭션 스크립트 패턴 +- 모든 로직을 Controller에서 처리 +- **단점:** 테스트 불가능, 결합도 높음 +- **기각 이유:** 본 프로젝트 복잡도에서 유지보수 불가 + +## 결과 + +### 긍정적 결과 +- **테스트 용이성:** Mock 기반 단위 테스트 가능 +- **일관된 오류 처리:** 모든 API에서 동일한 오류 응답 형식 +- **트랜잭션 명확성:** 어디서 롤백/커밋되는지 예측 가능 + +### 부정적 결과 +- **추가 코드:** DTO, Mapper, Exception 클래스 증가 +- **학습 곡선:** 개발자 교육 필요