224 lines
10 KiB
Markdown
224 lines
10 KiB
Markdown
# ADR-001: Spring 경계 아키텍처 정의
|
|
|
|
## Context
|
|
|
|
runtime-role-matrix-live 프로젝트는 역할(Role) 기반 접근 제어 시스템을 구현한다. 다중 계층 구조에서 Controller, Service, Repository 간의 책임 분리와 오류 처리, 트랜잭션 관리가 명확히 정의되지 않아 다음 문제가 발생한다.
|
|
|
|
| 문제점 | 영향 |
|
|
|--------|------|
|
|
| Controller에서 비즈니스 로직 직접 실행 | 단일 책임 원칙 위반, 테스트 어려움 |
|
|
| Service에서 unchecked exception 무분별한 전파 | 일관된 오류 응답 불가 |
|
|
| Repository에서 트랜잭션 경계 불분명 | 데이터 정합성 위험 |
|
|
| 각 계층 간 계약(contract) 부재 | API 스펙 변경 시 파급 효과 예측 불가 |
|
|
|
|
## Decision
|
|
|
|
### 1. Controller-Service-Repository 경계
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Controller Layer │
|
|
│ - HTTP 요청/응답 처리 │
|
|
│ - 입력 검증 (DTO 변환, Bean Validation) │
|
|
│ - HTTP 상태 코드 결정 │
|
|
│ - Service 호출 및 결과 매핑 │
|
|
│ - 예외를 HTTP 응답으로 변환 │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Service Layer │
|
|
│ - 비즈니스 로직 수행 │
|
|
│ - 도메인 객체 조작 │
|
|
│ - 트랜잭션 경계 설정 (@Transactional) │
|
|
│ - Repository 호출 │
|
|
│ - 도메인 예외을 ServiceException으로 변환 │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Repository Layer │
|
|
│ - 데이터 접근 (JPA Repository) │
|
|
│ - 엔티티 ↔ 도메인 객체 변환 │
|
|
│ - 순수 데이터 조작만 담당 │
|
|
│ - 예외는 그대로 전파 (DataAccessException) │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
**책임 매트릭스**
|
|
|
|
| 책임 | Controller | Service | Repository |
|
|
|------|:----------:|:-------:|:----------:|
|
|
| HTTP 파라미터 바인딩 | ✅ | ❌ | ❌ |
|
|
| Bean Validation | ✅ | △ (도메인 검증) | ❌ |
|
|
| 비즈니스 로직 | ❌ | ✅ | ❌ |
|
|
| 트랜잭션 관리 | ❌ | ✅ | ❌ |
|
|
| 데이터 접근 | ❌ | ❌ | ✅ |
|
|
| DTO ↔ Entity 변환 | ✅ | △ (도메인 변환) | ✅ |
|
|
| 예외 → HTTP 응답 | ✅ | ❌ | ❌ |
|
|
|
|
### 2. 오류 계약 (Error Contract)
|
|
|
|
**예외 계층 구조**
|
|
|
|
```
|
|
RuntimeException
|
|
├── ServiceException (체크 예외, 비즈니스 오류)
|
|
│ ├── RoleNotFoundException
|
|
│ ├── RoleAlreadyExistsException
|
|
│ └── PermissionDeniedException
|
|
└── DataAccessException (Spring, unchecked)
|
|
```
|
|
|
|
**ServiceException 스펙**
|
|
|
|
| 필드 | 타입 | 필수 | 설명 |
|
|
|------|------|:----:|------|
|
|
| code | String | ✅ | 오류 코드 (e.g., "ROLE_NOT_FOUND") |
|
|
| message | String | ✅ | 사용자에게 표시할 메시지 |
|
|
| details | Map | ❌ | 추가 메타데이터 |
|
|
| timestamp | Instant | ✅ | 발생 시각 |
|
|
|
|
**HTTP 상태 코드 매핑**
|
|
|
|
| 예외 | HTTP 상태 | 이유 |
|
|
|------|:---------:|------|
|
|
| RoleNotFoundException | 404 | 리소스 없음 |
|
|
| RoleAlreadyExistsException | 409 | 리소스 충돌 |
|
|
| PermissionDeniedException | 403 | 권한 없음 |
|
|
| ValidationException | 400 | 잘못된 요청 |
|
|
| ServiceException (기타) | 500 | 내부 서버 오류 |
|
|
|
|
**오류 응답 형식 (RFC 7807 Problem Details)**
|
|
|
|
```json
|
|
{
|
|
"type": "https://api.example.com/errors/role-not-found",
|
|
"title": "Role Not Found",
|
|
"status": 404,
|
|
"code": "ROLE_NOT_FOUND",
|
|
"message": "ID가 'admin'인 역할을 찾을 수 없습니다.",
|
|
"details": {
|
|
"roleId": "admin",
|
|
"timestamp": "2026-07-14T10:58:18Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3. 트랜잭션 경계
|
|
|
|
**트랜잭션 전파 정책**
|
|
|
|
| 시나리오 | 전파 방식 | 설명 |
|
|
|---------|:---------:|------|
|
|
| Service → Repository | REQUIRED (기본) | 기존 트랜잭션 참여 또는 신규 생성 |
|
|
| Service → Service (내부 호출) | REQUIRED | 같은 트랜잭션 내에서 실행 |
|
|
| readOnly 조회 | readOnly=true | 성능 최적화,Dirty checking 비활성화 |
|
|
| 쓰기 작업 | readOnly=false (기본) | 기본값, 명시적 지정 불필요 |
|
|
|
|
**트랜잭션 경계 설정 규칙**
|
|
|
|
1. **트랜잭션 시작점**: Service 계층의 public 메서드
|
|
2. **트랜잭션 종료점**: Service 메서드 종료 시 commit, 예외 발생 시 rollback
|
|
3. **Controller에서 @Transactional 금지**: HTTP 요청 스레드와 트랜잭션 바인딩 분리
|
|
4. **Repository에서 @Transactional 금지**: 데이터 접근만 담당
|
|
|
|
**트랜잭션 시퀀스 다이어그램**
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant C as Controller
|
|
participant S as Service
|
|
participant R as Repository
|
|
participant DB as Database
|
|
|
|
C->>+S: createRole(dto)
|
|
S->>S: @Transactional 시작
|
|
S->>+R: existsByRoleId(id)
|
|
R->>+DB: SELECT
|
|
DB-->-R: 결과
|
|
R-->-S: false
|
|
alt 역할 존재 시
|
|
S-->>C: 예외 발생 (RoleAlreadyExistsException)
|
|
else 역할 미존재 시
|
|
S->>+R: save(entity)
|
|
R->>+DB: INSERT
|
|
DB-->-R: 저장된 엔티티
|
|
R-->-S: 저장된 엔티티
|
|
S-->>S: @Transactional 커밋
|
|
S-->>-C: 생성된 역할 DTO
|
|
end
|
|
|
|
Note over S,DB: 예외 발생 시 자동 Rollback
|
|
```
|
|
|
|
**외부 시스템 연동 시 트랜잭션 처리**
|
|
|
|
```
|
|
┌──────────────────────────────────────────────────────────────┐
|
|
│ @Transactional │
|
|
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │
|
|
│ │ DB 저장 │ │ 메시지 발송 │ │ 외부 API 호출 │ │
|
|
│ │ (트랜잭션 참여)│ │ (로컬 트랜잭션)│ │ (비트랜잭션) │ │
|
|
│ └────────────────┘ └────────────────┘ └────────────────┘ │
|
|
│ │
|
|
│ 실패 시: DB 저장만 롤백, 메시지/외부API는 별도 보상 처리 필요 │
|
|
└──────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Alternatives
|
|
|
|
### 대안 1: Controller에서 직접 Repository 호출
|
|
|
|
| 항목 | 내용 |
|
|
|------|------|
|
|
| 장점 | 간단한 CRUD에 코드량 감소 |
|
|
| 단점 | 비즈니스 로직 분산, 테스트 어려움, 트랜잭션 관리 불가 |
|
|
| 채택 여부 | ❌ 불채택 - 확장성 및 유지보수성 저하 |
|
|
|
|
### 대안 2: Service 계층 없이 도메인 객체에 비즈니스 로직 포함
|
|
|
|
| 항목 | 내용 |
|
|
|------|------|
|
|
| 장점 | 도메인 주도 설계(DDD) 접근, 객체지향적 |
|
|
| 단점 | 도메인 객체가 프레임워크 의존성 발생, 테스트 복잡 |
|
|
| 채택 여부 | ❌ 불채택 - 현재 프로젝트 규모에서 과도한 복잡성 |
|
|
|
|
### 대안 3: 전역 예외 처리 (@ControllerAdvice)만 사용, 계층별 예외 변환 없음
|
|
|
|
| 항목 | 내용 |
|
|
|------|------|
|
|
| 장점 | 구현 단순화 |
|
|
| 단점 | 예외 처리 로직 중앙화되어 단일 책임 위반, 테스트 어려움 |
|
|
| 채택 여부 | ❌ 불채택 - 계층별 명확한 오류 계약 필요 |
|
|
|
|
## Consequences
|
|
|
|
### 긍정적 결과
|
|
|
|
- **단일 책임 원칙 준수**: 각 계층이 명확한 역할을 담당
|
|
- **테스트 용이성**: Mock을 통한 단위 테스트 가능
|
|
- **일관된 오류 처리**: RFC 7807 표준 준수, 예측 가능한 API 응답
|
|
- **트랜잭션 관리 명확성**: Service 계층에서 트랜잭션 경계 집중 관리
|
|
- **유지보수성 향상**: 변경 시 파급 효과 최소화
|
|
|
|
### 부정적 결과 (적용 부담)
|
|
|
|
- **코드량 증가**: DTO 변환, 예외 변환 로직 추가
|
|
- **학습 곡선**: 개발자 역량 요구사항 상승
|
|
- **추가 의존성**: 예외 계층 구조 관리 필요
|
|
|
|
### 모니터링 및 검증
|
|
|
|
| 지표 | 측정 방법 |
|
|
|------|----------|
|
|
| 계층 분리 준수율 | 코드 리뷰 시 Controller에 비즈니스 로직 존재 여부 체크 |
|
|
| 예외 처리 일관성 | @ControllerAdvice 로그 분석 |
|
|
| 트랜잭션 커밋/롤백 비율 | 트랜잭션 로그 모니터링 |
|
|
|
|
### 마이그레이션 계획
|
|
|
|
1. 기존 코드를 점진적으로 리팩토링 (하위 호환 유지)
|
|
2. 새로운 기능은 ADR 규칙 즉시 적용
|
|
3. 공통 예외 클래스를 `exception` 패키지에 배치
|
|
4. DTO 클래스를 `dto` 패키지에 배치
|