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

# 백엔드 설계

> 한 줄 정의
> 외주·SI에서 백엔드가 내려야 하는 설계 결정의 목록·판단 기준과, 그 결과가 **API정의서·기능사양서**로 납품·검수되는 연결. 구현 원리(신뢰성 메커니즘 채택 기준 등)는 [[백엔드 원리]]가 정본 — 여기서는 결정 항목과 경계만 다룬다.

## 설계 대상과 납품 산출물

| 설계 대상 | 납품 산출물 | 검수에서 판정되는 것 |
|---|---|---|
| API 계약(리소스·요청·응답·에러·권한) | **API정의서(인터페이스 정의서)** | 발주사 연동팀·프론트가 문서만으로 연동 가능한가 |
| 기능별 입력·처리·출력·예외 | **기능사양서** | 요구 ID(RTM)와 1:1로 추적되는가 |
| 트랜잭션·외부 연동·실패 처리 | 기능사양서의 예외 절 + 테스트케이스 | 실패 시나리오가 검수 케이스로 재현 가능한가 |

기획 측 입력 템플릿: [[01_API 계약]] · [[02_도메인·오류 정책]] · [[03_DB·외부연동 의존성]]. API·데이터 계약의 설계 단계 정본은 [[02_API·데이터 계약]](Tech Lead) — 구현 단계 원본이 [[01_API 계약]], 납품본은 코드에서 역생성한다.

## 핵심 결정 항목 — 판단 기준

| 결정 | 판단 기준 | 기록 위치 |
|---|---|---|
| API 스타일·에러 규약 | 리소스 중심 + 응답 envelope 프로젝트당 1회 확정 ([[백엔드 원리]] API 설계) — 발주사 표준(전사 규약)이 있으면 그것이 우선 | API정의서 서두 |
| 버저닝 | 검수 후 유지보수 계약이 있으면 깨지는 변경 정책을 **착수 전** 문서화. 없으면 v1 고정 | API정의서 |
| 도메인 계층 분리 | 계층형+순수 도메인이 기본값, 승격은 [[아키텍처 스타일 선택]] 조건표로 | ADR(승격 시) |
| 트랜잭션 경계 | 업무상 "전부 아니면 전무" 단위 = 기능사양서의 기능 단위와 일치시킨다. 단 상위 원칙은 한 트랜잭션 한 aggregate([[도메인 경계 설계]]) — 기능이 여러 aggregate에 걸치면 이벤트+최종 일관성으로 분해. 외부 API 호출은 경계 밖 | 기능사양서 |
| 외부 연동(발주사 기존 시스템) | 타임아웃·재시도·멱등 키를 **연동 명세에 명시** — 상대 시스템 스펙 미제공은 발주사 의존으로 기록 | API정의서 연동 절 + 의존 대장 |
| 비동기 승격 | 사용자 대기 한계 초과 작업만 202+상태 조회로. 큐 도입은 [[백엔드 원리]] 채택 기준표 | ADR |

## 다른 역할과의 경계

- **프론트엔드**: API 계약의 Owner는 백엔드, 프론트는 소비·합의자 ([[00_역할별 설계 지도]]). 화면 필요 데이터는 프론트가 역제안하고 백엔드가 계약에 반영한다.
- **데이터·DB**: 스키마 Owner는 [[02_데이터·DB 설계]]. 백엔드는 Repository 뒤에서 소비하며 스키마 변경은 DB Owner 경유.
- **보안**: 인증·인가 모델은 [[05_보안 설계]]가 정하고 백엔드는 엔드포인트·도메인 행동 단위로 구현한다. deny-by-default 위반은 보안 판정 사항.
- **인프라**: 배포 형태·환경 변수 체계는 [[04_인프라 설계]] 소관 — 코드에 환경 하드코딩 금지.

## 외주 특수 제약

- 에러 규약·페이지네이션 상한 같은 "당연한" 기본값도 API정의서에 **명시**한다 — 문서에 없으면 검수에서 발주사 해석이 이긴다.
- 발주사 프레임워크·DB 표준이 설계 기본값을 이길 수 있다 — 계약·회의록 근거를 확인하고 ADR 입력으로 기록 ([[설계 결정과 리뷰]]).
- 성능 개선·신규 연동 요청은 CR 회부 ([[SI 수주와 범위 관리]]) — "됩니다, N일 추가됩니다"로 응답.

## 안티패턴

- **구현 후 역생성한 API정의서만 존재** — 착수 합의본이 없으면 연동 지연 책임을 수행사가 진다. 초안 계약 먼저, 최종본은 코드에서 역생성 ([[외주 개발 산출물]]).
- **기능사양서 없는 예외 처리** — 코드에만 있는 예외 분기는 검수 케이스가 못 되고, 하자보수 분쟁에서 "미구현"으로 취급된다.
- **트랜잭션 안의 외부 호출** — 발주사 시스템 지연이 곧 우리 장애가 된다.
- **미리 만든 v1/v2 체계·추측성 확장점** — 계약에 없는 확장성은 무상 노동이다.

## 관련 문서

- [[00_설계 허브]] · [[00_역할별 설계 지도]] · [[02_데이터·DB 설계]] · [[05_보안 설계]]
- [[백엔드 원리]] · [[도메인 경계 설계]] · [[분산 신뢰성 패턴]] · [[아키텍처 스타일 선택]] · [[호환성과 계약 진화]] · [[SLO·성능·용량 설계]]
- [[API-명세-템플릿]] · [[백엔드-체크리스트]] · [[외주 개발 산출물]]