---
type: knowledge
domain: backend
status: active
last-reviewed: 2026-07-27
---

# 백엔드 원리

> 한 줄 정의
> 프레임워크와 무관한 백엔드 설계 원리와 선택 기준. Spring Boot·FastAPI 등의 API는 공식 문서에서 조회한다. 여기서는 **신뢰성 메커니즘의 채택 기준**을 결정한다.

## API 설계

- 리소스 중심 URL + 표준 메서드. RPC식 동사 엔드포인트는 워크플로우 트리거에만.
- 응답 envelope 통일 (success·data·error·meta) — 프로젝트당 한 번 정의하고 전부 따른다(발주사 API 표준이 있으면 그쪽이 우선) → [[API-명세-템플릿]].
- 목록 API는 예외 없이 페이지네이션 + 상한.
- 버저닝은 깨지는 변경이 실제로 생길 때 — 미리 v1/v2 체계를 만들지 않는다. breaking 판별·Expand–Contract·폐기 절차의 정본은 [[호환성과 계약 진화]].

## 도메인 설계

- 도메인 로직은 프레임워크·DB 접근에서 분리된 순수 계층에 (테스트 가능성의 핵심).
- 저장소 접근은 Repository 인터페이스 뒤로 — 구현 교체·모킹 가능.
- 서비스가 서로를 호출하며 트랜잭션이 얽히기 시작하면 도메인 경계를 다시 그린다.

## 신뢰성 메커니즘 — 채택 기준

| 메커니즘 | 기본값 | 채택 조건 |
|----------|--------|----------|
| Timeout | **전 외부 호출 필수** | 예외 없음. 기본값 방치 금지 ([[AI-실수패턴]] #5) |
| Retry | 재시도 대상 에러만(5xx·타임아웃, 429는 Retry-After 존중), 백오프+상한 | 그 외 4xx 재시도 금지, 멱등 작업에만 |
| Idempotency | 변이+비동기면 필수 | 멱등 키 또는 자연 키 중복 검사 |
| Queue | 불필요가 기본 | 처리시간 > 대기 허용, 스파이크 흡수 ([[TECHNOLOGY-DECISION-GUIDE]] 9축) |
| DLQ | 큐 쓰면 필수 | 실패 메시지 격리 + 재처리 경로 |
| Circuit Breaker | 불필요가 기본 | 의존 서비스 장애가 연쇄될 규모일 때만 |
| Scheduler/Batch | cron 1개부터 | 중복 실행 방지(유니크 키·락) + 실패 알림 필수 세트 |
| Event-driven | 불필요가 기본 | 다수 소비자가 독립 반응해야 할 때만. 2개 서비스면 직접 호출 |

원칙: 표의 왼쪽 아래로 갈수록 운영 복잡도가 커진다. **위에서부터 채택하고, 아래는 근거를 spec에 쓴다.**

## 비동기 처리

- 사용자 대기 한계(수 초)를 넘는 작업은: 작업 생성(202 + job id) → 상태 조회/알림.
- 작업 상태는 DB에 명시적 상태 필드로 (queued → running → done/failed). 에이전트 장기 실행도 동일 패턴 → [[State Management]].

## 인증·인가

- 인증(누구인가)과 인가(무엇을 할 수 있나)를 분리해 설계.
- 인가는 기본 거부(deny-by-default), 엔드포인트가 아니라 도메인 행동 단위로.
- 멀티테넌시: 테넌트 ID를 모든 쿼리에 강제하는 계층 하나로 (개별 쿼리 신뢰 금지). 격리 수준(행 기반 → 스키마 → DB 분리)은 규제·규모 근거로 승격 — 승격 기준·책임 경계의 정본은 [[멀티테넌시 설계와 책임 경계]].

## 캐시

- 순서: 없이 시작 → 측정 → 병목에만. 무효화 전략을 함께 설계하지 못하면 캐시를 넣지 않는다.

## 로깅·모니터링

- 구조화 로그(JSON) + 요청 ID 전파 + PII 마스킹 ([[PII Redaction]]).
- 최소 지표: 에러율, 지연 p95, 큐 적체, (LLM이면) 토큰 비용/건 → [[Cost Monitoring]].

## 테스트

- 도메인 로직 단위 테스트가 1순위. 외부 연동은 실패 시나리오(타임아웃·5xx·malformed) 테스트가 성공 케이스보다 가치 있다.

## 관련 문서

- [[00_백엔드 허브]] · [[01_백엔드 설계]] — 설계 결정·납품 연결
- [[분산 신뢰성 패턴]] · [[SLO·성능·용량 설계]] · [[호환성과 계약 진화]]
- [[백엔드-체크리스트]] · [[데이터 원리]] · [[API-명세-템플릿]] · [[TECHNOLOGY-DECISION-GUIDE]]