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:

my_project/ ├── app/ │ ├── 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/ │ │ ├── users.py │ │ └── items.py │ ├── schemas/ # Pydantic Models (Data shapes) │ │ ├── user.py │ │ └── item.py │ ├── services/ # Business Logic Layer │ │ ├── user_service.py │ │ └── auth_service.py │ ├── crud/ # Database Access Layer │ │ └── user_crud.py │ ├── models/ # SQLAlchemy/Database Models │ │ └── user.py │ └── database.py # Kết nối DB ├── tests/ # Unit & Integration Tests ├── .env # Biến môi trường └── requirements.txt 

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.pyfrom fastapi import APIRouter from app.services import user_service router = APIRouter() @router.post("/users/")defcreate_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.pydefcreate_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.pyfrom pydantic import BaseModel, EmailStr classUserCreateSchema(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.