Bài viết gần đây

| Kiiến trúc FastAPI

Được viết bởi thanhdt vào ngày 27/01/2026 lúc 08:00 | 31 lượt xem

Kiiến trúc FastAPI

Một trong những sai lầm lớn nhất của người mới học FastAPI là viết tất cả mọi thứ vào một file main.py.

Khi dự án nhỏ (demo), điều đó không sao. Nhưng khi dự án lớn lên với hàng chục API, hàng nghìn dòng code, file main.py đó sẽ trở thành cơn ác mộng.

Để xây dựng một hệ thống bền vững, bạn cần một Kiến trúc chuẩn (Clean Architecture) ngay từ đầu. Bài viết này sẽ hướng dẫn bạn cách tổ chức thư mục dự án FastAPI chuyên nghiệp.

1. Tại sao cần chia tách (Separation of Concerns)?

Tư duy cốt lõi là: Mỗi thành phần chỉ làm đúng một việc.

  • Router: Chỉ lo việc nhận request và trả về response. Không xử lý logic kinh doanh, không gọi database trực tiếp.
  • Service: Chứa logic kinh doanh (Business Logic). Ví dụ: Tính toán thuế, kiểm tra kho hàng.
  • Repository/CRUD: Chỉ lo làm việc với Database (Query, Insert, Update).
  • Schema: Định nghĩa dữ liệu đầu vào/đầu ra (Pydantic models).

2. Cấu trúc thư mục đề xuất

Đây là cấu trúc mà mình áp dụng cho hầu hết các dự án production:

Thư mục / File Mô tả
my_project/ Thư mục gốc dự án
├── app/ Source code chính
│ ├── main.py Điểm khởi chạy ứng dụng
│ ├── core/ Cấu hình cốt lõi (Config, Security)
│ ├── api/ Chứa các Routers (Endpoints)
│ │ └── v1/ Version 1 của API
│ │ ├── users.py API User
│ │ └── items.py API Items
│ ├── schemas/ Pydantic Models (Data shapes)
│ │ ├── user.py Schema User
│ │ └── item.py Schema Item
│ ├── services/ Business Logic Layer
│ │ ├── user_service.py Logic xử lý User
│ │ └── auth_service.py Logic xử lý Auth
│ ├── crud/ Database Access Layer
│ │ └── user_crud.py Truy vấn DB cho User
│ ├── models/ SQLAlchemy/Database Models
│ │ └── user.py Model User trong DB
│ └── database.py Kết nối DB
├── tests/ Unit & Integration Tests
├── .env Biến môi trường
└── requirements.txt Danh sách thư viện

3. Chi tiết từng tầng (Layers)

Tầng 1: Routers (API Endpoints)

Nơi định nghĩa đường dẫn API (URL).

# app/api/v1/users.py
from fastapi import APIRouter
from app.services import user_service

router = APIRouter()

@router.post("/users/")
def create_user(user_in: UserCreateSchema):
    return user_service.create_user(user_in)

Tầng 2: Services (Business Logic)

Nơi “bộ não” hoạt động. Nó nhận dữ liệu từ Router, xử lý, và gọi xuống tầng CRUD nếu cần.

# app/services/user_service.py
def create_user(user_in):
    # Logic: Kiểm tra email trùng, mã hóa mật khẩu...
    if user_exists(user_in.email):
        raise HTTPException(...)
    return user_crud.create(user_in)

Tầng 3: Schemas (Pydantic – Data Validation)

Định nghĩa dữ liệu trông như thế nào. Pydantic giúp đảm bảo dữ liệu sạch trước khi vào hệ thống.

# app/schemas/user.py
from pydantic import BaseModel, EmailStr

class UserCreateSchema(BaseModel):
    username: str
    email: EmailStr
    password: str

4. Lợi ích của kiến trúc này

  1. Dễ bảo trì: Logic nằm gọn trong Service. Khi sửa logic, không sợ ảnh hưởng đến Router hay Database.
  2. Dễ test: Bạn có thể viết Unit Test cho từng Service riêng biệt mà không cần chạy cả server.
  3. Dễ làm việc nhóm: Backend dev A làm module Users, dev B làm module Orders mà không dẫm chân nhau (ít bị conflict git).
  4. Scalable: Dễ dàng mở rộng thêm tính năng mới.

Kết luận

“Code chạy được” chỉ là bước đầu tiên. “Code đẹp, dễ đọc, dễ bảo trì” mới là đẳng cấp của Senior Developer.

Hãy tập thói quen tổ chức code bài bản ngay từ dự án nhỏ nhất. Nó sẽ tiết kiệm cho bạn hàng trăm giờ debug sau này.

Thực hành xây dựng dự án chuẩn:

Khóa học Python FastAPI Thực Chiến sẽ cung cấp cho bạn một Project Template chuẩn xịn (có sẵn Docker, CI/CD, Authentication) để bạn có thể bắt đầu dự án mới ngay lập tức.