Kiến trúc backend Python: layered, DI, cấu hình, FastAPI vs Django vs Flask
Tổ chức codebase Python lớn: tầng router/service/repository, Unit of Work, cấu hình bằng pydantic-settings, logging có cấu trúc, domain event, modular monolith; và cách chọn giữa FastAPI, Django, Flask, Litestar cho từng dự án.
Python không áp đặt cấu trúc như NestJS hay Laravel, nên codebase Python lớn rất dễ thành 'đống script'. Senior Python được trả lương cao vì biết tổ chức code để 10 người cùng làm mà không giẫm chân, test được nghiệp vụ mà không cần database, và chọn đúng framework cho bài toán thay vì theo thói quen. 'Bạn tổ chức một dự án FastAPI lớn thế nào?' là câu hỏi gần như chắc chắn gặp.
🎯 Mục tiêu học tập
- Phân tầng router → service → repository; domain không phụ thuộc framework
- Quản lý transaction bằng Unit of Work, inject phụ thuộc qua Depends/constructor
- Cấu hình theo môi trường bằng pydantic-settings; logging có cấu trúc với request id
- Tổ chức modular monolith với ranh giới module rõ
- So sánh và chọn FastAPI, Django, Flask, Litestar có lý do
Phân tầng và Unit of Work
class UnitOfWork:
def __init__(self, session_factory: async_sessionmaker[AsyncSession]):
self._factory = session_factory
async def __aenter__(self) -> "UnitOfWork":
self.session = self._factory()
self.tasks = TaskRepository(self.session)
self.outbox = OutboxRepository(self.session)
return self
async def __aexit__(self, exc_type, *_):
if exc_type: await self.session.rollback()
await self.session.close()
async def commit(self) -> None: await self.session.commit()
class CompleteTask: # use case — test được bằng fake UoW
def __init__(self, uow: UnitOfWork) -> None: self.uow = uow
async def __call__(self, task_id: int, actor: User) -> Task:
async with self.uow as uow:
task = await uow.tasks.get_for_update(task_id, actor.org_id)
task.complete(by=actor) # quy tắc nghiệp vụ nằm trên domain object
await uow.outbox.add(TaskCompleted(task.id))
await uow.commit()
return task
| Mức | Khi nào |
|---|---|
| Router → service → SQLAlchemy trực tiếp | CRUD đơn giản — đủ cho phần lớn module |
| + Repository + Unit of Work | Cần test nghiệp vụ không có DB, transaction trải nhiều repository |
| Domain model thuần + port/adapter | Nghiệp vụ phức tạp (billing, đặt chỗ) — chỉ cho module lõi |
Cấu hình và logging
from pydantic_settings import BaseSettings, SettingsConfigDict
from pydantic import PostgresDsn, SecretStr
class Settings(BaseSettings):
model_config = SettingsConfigDict(env_file=".env", env_prefix="APP_")
env: Literal["dev", "test", "prod"] = "dev"
database_url: PostgresDsn
redis_url: str
jwt_secret: SecretStr # không in ra log
stripe_key: SecretStr
settings = Settings() # thiếu biến → lỗi ngay khi khởi động
# structlog: log JSON có ngữ cảnh
log = structlog.get_logger()
log.info("task.completed", task_id=task.id, org_id=actor.org_id)
Middleware gắn request_id vào context (contextvars) để mọi dòng log của request có cùng id; trả id trong header
response. Không dùng print trên production.
Modular monolith
- Module theo domain (
identity,projects,billing), mỗi module có API công khai trong__init__.py; module khác không import vào phần nội bộ. - Cưỡng chế ranh giới bằng công cụ:
import-linterhoặctachtrong CI. - Giao tiếp chéo module qua service công khai hoặc domain event (in-process hoặc qua queue).
- Tách thành service riêng chỉ khi có lý do đo được (team, tải, tách biệt bảo mật).
Chọn framework
| FastAPI | Django (+ DRF/Ninja) | Flask | Litestar | |
|---|---|---|---|---|
| Thế mạnh | API async, type hints, OpenAPI, dịch vụ AI | "Pin kèm": ORM, admin, auth, migration, form, template | Tối giản, linh hoạt | Giống FastAPI, nhiều tính năng tích hợp, hiệu năng tốt |
| Hợp với | Microservice, backend cho SPA/mobile, LLM API | Sản phẩm CRUD lớn, back-office, nội dung, team cần quy ước | Dự án nhỏ, legacy | Team muốn tích hợp sẵn nhiều hơn |
| Bạn tự lắp | ORM, migration, auth, admin | Ít | Gần như mọi thứ | Ít hơn FastAPI |
Khoá dùng FastAPI làm trục chính (phổ biến cho backend/AI), và dành Module 7 cho Django vì nó vẫn là framework Python được tuyển dụng nhiều nhất cho sản phẩm web. Một senior Python nên làm việc thoải mái với cả hai.
🏋️ Bài tập thực hành
(1) Tách API Module 4 thành module projects, identity, billing với API công khai; thêm
import-linter chặn import chéo vào phần nội bộ. (2) Unit of Work + repository; viết unit test cho use case CompleteTask
bằng fake UoW không cần DB. (3) pydantic-settings với SecretStr, structlog JSON, middleware request_id. (4) Viết
docs/adr/001-framework.md giải thích vì sao chọn FastAPI cho API và khi nào bạn sẽ chọn Django.
📚 Tài nguyên học tập
-
Architecture Patterns with Python (Cosmic Python)Repository, Unit of Work, domain events — miễn phí onlineSách
-
pydantic-settingsCấu hình từ biến môi trườngDocs
-
structlogLogging có cấu trúcDocs
-
import-linterCưỡng chế ranh giới moduleDocs
✅ Tự đánh giá hoàn thành
- Service/use case test được không cần DB
- Cấu hình validate khi khởi động, secret không lộ ra log
- Ranh giới module được cưỡng chế bằng công cụ
- Giải thích được khi nào chọn FastAPI, khi nào Django