---
id: platform-backend-api-development
title: "백엔드 API 개발 가이드"
category: "Platform_Engineering"
status: "draft"
verification_status: "conceptual"
canonical_id: ""
aliases: ["backend development", "백엔드 개발", "API design", "REST", "서버 아키텍처", "microservices"]
duplicate_of: ""
source_trust_level: "A"
confidence_score: 0.86
created_at: 2026-06-13
updated_at: 2026-06-13
review_reason: ""
merge_history: []
tags: ["platform", "backend", "api", "guide", "platform-independent"]
raw_sources: ["일반 백엔드 공학 지식", "ConnectAI/src/bridge.ts (소규모 서버 적용 예)"]
applied_in: ["ConnectAI"]
github_commit: ""
---

# [[백엔드 API 개발 가이드]]

## 🎯 한 줄 통찰 (One-line insight)
백엔드의 핵심은 "**계층 분리·명확한 API 계약·데이터 일관성·복원력(재시도/멱등/한도)·관측성**" 이며, 화려한 프레임워크보다 이 기본기가 신뢰성을 만든다.

## 🧠 핵심 개념 (Core concepts)
계층(라우터→서비스→리포지토리), API 계약(REST/GraphQL/RPC), 트랜잭션, 인증/인가, 멱등성, 레이트 리밋, 로깅/메트릭.

## 📖 세부 내용 (Details · 12-field)
- **Problem:** 동시 다수 클라이언트에 일관·안전·확장 가능한 데이터/로직 제공.
- **Recommended Architecture:** 계층형(라우터/컨트롤러 → 서비스(도메인) → 리포지토리(데이터)) + DTO 경계 + 의존성 주입. ([[Architecture Separation Pattern]])
- **Folder Structure:** `src/{routes|controllers, services, repositories, domain/models, middleware, infra(db,cache,queue), config}`.
- **Core Components:** 라우터/미들웨어, 서비스, 리포지토리([[Repository Pattern]]), 인증([[JWT Authentication Pattern]]), 캐시([[Caching Pattern]]), 큐/워커([[Background Worker Pattern]]), 에러 핸들러.
- **State Management:** 상태는 DB/캐시(서버는 가급적 무상태), 세션/토큰, 분산 락. SSOT.
- **Error Handling:** 표준 에러 응답(코드/메시지), 재시도(backoff)/서킷 브레이커, 멱등 키, 트랜잭션 롤백([[Error Handling Pattern]]).
- **Testing Strategy:** 단위(서비스/도메인), 통합(DB/리포), 계약 테스트(API), 부하 테스트.
- **Scaling Strategy:** 수평 확장(무상태), 캐시 계층, 읽기 복제/샤딩, 비동기 큐, 레이트 리밋, CDN.
- **Common Mistakes:** 컨트롤러에 비즈니스 로직, N+1 쿼리, 멱등성 부재(중복 처리), 트랜잭션 경계 오류, 검증 누락, 무한 재시도.
- **Refactoring Patterns:** 컨트롤러→서비스 로직 이동, 쿼리→리포지토리 캡슐화, 공통→미들웨어, 동기→큐 비동기화.
- **Real-world Tradeoffs:** 모놀리스(단순·일관 ↔ 확장/배포 결합) vs 마이크로서비스(독립 확장 ↔ 분산 복잡도/일관성), SQL(일관성 ↔ 확장) vs NoSQL(확장 ↔ 일관성), REST vs GraphQL.
- **Design Heuristics:** "서버 무상태로", "쓰기는 멱등하게", "경계에서 검증", "느린 작업은 큐로", "관측 가능하게(로그/메트릭/트레이스)".

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
마이크로서비스가 기본값은 아니다 — 대부분 모놀리스(또는 모듈러 모놀리스)로 시작해 *필요할 때* 분리하는 것이 안전(분산은 비싸다).

## 🛠️ 적용 사례 (Applied in summary)
ConnectAI BridgeServer(로컬 HTTP, 서비스 레이어로 로직 분리 — 소규모 백엔드의 계층 분리 예) [S2].

## 🔗 지식 그래프 (Knowledge Graph)
- **상위/루트:** [[플랫폼 개발 가이드 인덱스]]
- **관련 개념:** [[Repository Pattern]], [[API Client Pattern]], [[JWT Authentication Pattern]], [[Caching Pattern]], [[Event Bus Pattern]], [[이벤트 소싱 스토어 패턴]]
- **참조 맥락:** 작은 모델이 서버/API 를 설계할 때 상위 가이드로 참조.

## 📚 출처 (Sources)
- [S1] 일반 백엔드/API 공학 지식
- [S2] ConnectAI/src/bridge.ts — 소규모 서버 계층 분리 예

## 📝 변경 이력 (Change history)
- 2026-06-13: 플랫폼 독립 백엔드 개발 가이드 초안.
