Playbooks

이 파트는 앞선 이론을 실제 서비스 설계 규칙으로 번역하는 섹션이다. Pythonic, typing, runtime, asyncio, FastAPI, Pydantic, SQLAlchemy를 각각 잘 아는 것만으로는 부족하고, 그것들이 한 서비스 안에서 어떻게 연결되어야 덜 꼬이는지가 더 중요하다.

빠른 요약: playbook은 "이론 요약"이 아니라 설계 의사결정 기준이다. 새 서비스 뼈대를 만들 때, 코드 리뷰할 때, 기존 구조를 리팩터링할 때 바로 적용할 수 있어야 한다.

이 파트에서 풀려는 질문

처음 서비스 뼈대는 어떻게 잡나

router, service, repository, schema, settings, logging, tests를 어디에 두고 어떻게 연결할지 제안한다.

환경변수와 설정은 어떻게 설계하나

`settings.py`, `pydantic-settings`, `.env`, secret source, dependency override를 어떤 기준으로 나눌지 정리한다.

FastAPI + Pydantic + SQLAlchemy를 어떻게 덜 꼬이게 붙이나

request DTO, transaction, ORM entity, response DTO 경계를 분리해 API가 길게 살아남는 구조를 잡는다.

타입 리뷰는 무엇을 봐야 하나

문법 사용 여부보다 `Any` 누수, alias 남용, protocol 설계, boundary 명확성을 먼저 보는 체크리스트를 제공한다.

테스트 fixture는 어떻게 설계하나

yield fixture, dependency override cleanup, DB 격리, client lifecycle을 어떻게 나눌지 실전 패턴으로 정리한다.

fixture 다음 테스트 층은 무엇인가

HTTP contract, websocket protocol, property-based test, idempotency invariant를 어느 도구로 잡을지 정리한다.

Lambda와 Kubernetes는 어떻게 고르나

트래픽 모양, DB 연결 방식, long-lived connection, 운영 표면적을 기준으로 선택하는 틀을 제안한다.

점진 배포 중 schema는 어떻게 안전하게 바꾸나

rolling, blue-green, canary, Lambda alias 환경에서 Alembic, backfill, feature flag 순서를 어떻게 잡을지 정리한다.

Schema, API, event는 어떻게 같이 진화시키나

DB migration, API versioning, event versioning, backfill/replay를 하나의 contract evolution 관점으로 묶어 본다.

retry와 duplicate delivery는 어떻게 다루나

idempotency key, outbox, publisher retry, dedupe를 같은 그림으로 묶어 본다.

이론과 실전은 어디서 만나나

descriptor, typing, runtime, asyncio 지식을 실제 API 서비스 설계와 연결하는 관점을 정리한다.

추천 읽기 순서

1. API Service Template
2. Settings and Pydantic Settings
3. Testing with Fixtures
4. Testing Beyond Fixtures
5. ABC + Fake UoW Testing
6. Use Case + UoW + ABC
7. FastAPI + Pydantic + SQLAlchemy
8. Lambda vs Kubernetes
9. Progressive Delivery + Alembic
10. 계약 진화와 지속가능한 CD
11. Idempotency와 Outbox
12. Typing Review Checklist

이 파트의 사용법

• 새 프로젝트를 시작할 때는 API Service Template부터 본다.
• 환경 변수, .env, secret source, get_settings() 경계를 잡고 싶다면 Settings and Pydantic Settings를 바로 본다.
• fixture, teardown, override cleanup 기준이 필요하면 Testing with Fixtures를 바로 본다.
• fixture 다음 단계로 contract/property/protocol 테스트를 확장하고 싶다면 Testing Beyond Fixtures를 바로 본다.
• use case를 DB 없이 빨리 검증하는 테스트가 필요하면 ABC + Fake UoW Testing을 본다.
• use case와 SQLAlchemy UoW를 abc.ABC 기반 경계와 함께 보고 싶다면 Use Case + UoW + ABC를 본다.
• 이미 FastAPI/SQLAlchemy 프로젝트가 있다면 FastAPI + Pydantic + SQLAlchemy를 먼저 본다.
• 배포 대상을 Lambda와 Kubernetes 중에서 비교해야 한다면 Lambda vs Kubernetes를 본다.
• rolling, blue-green, canary, Lambda alias 배포에서 Alembic과 backfill 순서를 잡고 싶다면 Progressive Delivery + Alembic을 본다.
• DB schema, public API, async event를 한 묶음의 contract evolution 문제로 정리하고 싶다면 계약 진화와 지속가능한 CD를 본다.
• retry-safe create API, idempotency key, outbox publish를 같이 설계하고 싶다면 Idempotency와 Outbox를 본다.
• 팀 코드 리뷰 기준을 만들고 싶다면 Typing Review Checklist를 기준 문서로 둔다.

같이 읽으면 좋은 페이지

• FastAPI
• Pydantic
• SQLAlchemy 2.0
• Typing