---
id: wiki-2026-0508-소프트웨어-아키텍처-베스트-프랙티스
title: 소프트웨어 아키텍처 베스트 프랙티스
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [Architecture Best Practices, SW Architecture Patterns]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [architecture, best-practices, patterns]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: agnostic
  framework: agnostic
---

# 소프트웨어 아키텍처 베스트 프랙티스

## 매 한 줄
> **"매 best practice는 매 context-bound이며, 매 trade-off 의 명시 없이 적용 시 매 cargo cult로 전락한다"**. Fowler / Vernon / Newman의 매 distillation은 매 boundary 의 명확화, 매 dependency 의 inversion, 매 deployment 의 independence를 매 핵심으로 본다.

## 매 핵심

### 매 SOLID at architecture level
- **SRP**: 매 service 매 single business capability.
- **OCP**: 매 plugin / 매 extension point.
- **LSP**: 매 contract-based versioning.
- **ISP**: 매 client-specific API (BFF).
- **DIP**: 매 ports & adapters.

### 매 Cloud-native principles (12-factor + extensions)
- 매 stateless processes.
- 매 config via env.
- 매 backing services as attached resources.
- 매 disposability (fast startup, graceful shutdown).
- 매 logs as event streams.
- 매 health endpoints (`/healthz`, `/readyz`).
- 매 telemetry by default (OpenTelemetry).

### 매 응용
1. 매 deployment 독립성으로 매 release cadence 향상.
2. 매 boundary 명확화로 매 team autonomy.
3. 매 observability 매 ship-time guarantee.

## 💻 패턴

### Health endpoint (Spring Boot)
```java
@RestController
class HealthController {
    @GetMapping("/healthz") // liveness
    ResponseEntity<?> live() { return ResponseEntity.ok().build(); }

    @GetMapping("/readyz") // readiness
    ResponseEntity<?> ready(DataSource ds) {
        try (var c = ds.getConnection()) {
            c.prepareStatement("SELECT 1").execute();
            return ResponseEntity.ok().build();
        } catch (Exception e) {
            return ResponseEntity.status(503).build();
        }
    }
}
```

### Circuit breaker (Resilience4j)
```java
CircuitBreaker cb = CircuitBreaker.of("payment",
    CircuitBreakerConfig.custom()
        .failureRateThreshold(50)
        .slowCallDurationThreshold(Duration.ofSeconds(2))
        .waitDurationInOpenState(Duration.ofSeconds(30))
        .build());

Supplier<Receipt> guarded = CircuitBreaker
    .decorateSupplier(cb, () -> paymentClient.charge(req));
return Try.ofSupplier(guarded).recover(t -> Receipt.queued()).get();
```

### Outbox pattern (Postgres + Debezium)
```sql
BEGIN;
INSERT INTO orders (id, status) VALUES ($1, 'CONFIRMED');
INSERT INTO outbox (aggregate_id, type, payload)
  VALUES ($1, 'OrderConfirmed', $2);
COMMIT;
-- Debezium reads outbox table → publishes to Kafka
```

### Idempotency key (REST)
```python
@app.post("/payments")
def charge(req: ChargeReq, idempotency_key: str = Header(...)):
    cached = redis.get(f"idem:{idempotency_key}")
    if cached:
        return json.loads(cached)
    result = process(req)
    redis.setex(f"idem:{idempotency_key}", 86400, json.dumps(result))
    return result
```

### Feature flag (LaunchDarkly-style)
```typescript
if (await flags.isEnabled("new-checkout", { userId })) {
  return newCheckout(cart);
}
return legacyCheckout(cart);
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| 매 cross-service consistency | Outbox + Kafka |
| 매 retry safety | Idempotency key |
| 매 cascading failure 방지 | Circuit breaker |
| 매 zero-downtime release | Feature flag + blue/green |
| 매 schema evolution | Backward-compatible (additive) only |

**기본값**: 매 12-factor + OpenTelemetry + idempotency.

## 🔗 Graph
- 부모: [[소프트웨어 아키텍처 설계]]
- 변형: [[Microservices]] · [[Modular Monolith]]
- 응용: [[Outbox Pattern]] · [[Circuit Breaker]] · [[Saga]]
- Adjacent: [[12-Factor App]] · [[OpenTelemetry]]

## 🤖 LLM 활용
**언제**: 매 best practice 의 trade-off 설명 / 매 idempotency key generation.
**언제 X**: 매 specific SLA tuning — 매 production data 기반 결정 필요.

## ❌ 안티패턴
- **Cargo cult microservices**: 매 boundary 없이 매 split.
- **Distributed transaction**: 매 2PC across services.
- **Shared database**: 매 service 간 매 schema 공유.
- **Dual write**: 매 outbox 없이 매 DB + Kafka 동시 write.

## 🧪 검증 / 중복
- Verified (Newman, *Building Microservices 2e*; Vernon, *Implementing DDD*; Fowler, *Patterns of Enterprise Application Architecture*).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — 매 outbox / circuit breaker / idempotency 추가 |