Quản Lý Dự Án FastAPI với Poetry và TOML

Phát triển Python hiện đại đã phát triển đáng kể, và các công cụ như Poetry cùng định dạng TOML đã trở nên thiết yếu để quản lý các dự án chuyên nghiệp. Trong hướng dẫn này, chúng ta sẽ khám phá cách sử dụng Poetry và TOML để quản lý các dự án FastAPI một cách hiệu quả.

TOML là gì?

TOML (Tom's Obvious, Minimal Language) là một định dạng file cấu hình được thiết kế để dễ đọc và viết nhờ ngữ nghĩa rõ ràng. Nó ánh xạ rõ ràng tới một hash table, khiến nó trở nên lý tưởng cho các file cấu hình.

TOML so với các định dạng khác

# TOML - Clean and readable
[tool.poetry]
name = "my-fastapi-app"
version = "0.1.0"
description = "A modern FastAPI application"
 
[tool.poetry.dependencies]
python = "^3.11"
fastapi = "^0.109.0"

// JSON - More verbose
{
  "tool": {
    "poetry": {
      "name": "my-fastapi-app",
      "version": "0.1.0",
      "description": "A modern FastAPI application",
      "dependencies": {
        "python": "^3.11",
        "fastapi": "^0.109.0"
      }
    }
  }
}

# YAML - Indentation-sensitive
tool:
  poetry:
    name: my-fastapi-app
    version: 0.1.0
    description: A modern FastAPI application
    dependencies:
      python: ^3.11
      fastapi: ^0.109.0

TOML kết hợp điểm mạnh của cả hai: tính rõ ràng của JSON và khả năng đọc của YAML.

Tại sao sử dụng Poetry cho dự án FastAPI?

Poetry là một công cụ quản lý dependencies và packaging, mang đến nhiều lợi thế so với pip truyền thống và requirements.txt:

1. Giải quyết Dependencies

Poetry tự động giải quyết dependencies và ngăn chặn xung đột:

# Old way - manual conflict resolution
pip install fastapi==0.109.0
pip install pydantic==2.5.0  # Might conflict!
pip install sqlalchemy==2.0.0  # Another potential conflict!
 
# Poetry way - automatic resolution
poetry add fastapi pydantic sqlalchemy

2. Phân tách mối quan tâm

Poetry phân biệt giữa dependencies production và development:

[tool.poetry.dependencies]
python = "^3.11"
fastapi = "^0.109.0"
uvicorn = {extras = ["standard"], version = "^0.27.0"}
 
[tool.poetry.group.dev.dependencies]
pytest = "^7.4.3"
black = "^23.12.1"
mypy = "^1.8.0"

3. Lock File

poetry.lock đảm bảo builds có thể tái tạo:

# Same versions on all machines
poetry install  # Uses poetry.lock

4. Quản lý Virtual Environment

Poetry tự động tạo và quản lý virtual environments:

# Poetry handles everything
poetry install
poetry run uvicorn main:app --reload

Thiết lập Poetry cho FastAPI

Cài đặt

# Install Poetry (Unix/macOS)
curl -sSL https://install.python-poetry.org | python3 -
 
# Install Poetry (Windows PowerShell)
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -
 
# Verify installation
poetry --version

Tạo dự án FastAPI mới

# Create new project
poetry new my-fastapi-app
cd my-fastapi-app
 
# Or initialize in existing directory
mkdir my-fastapi-app && cd my-fastapi-app
poetry init

Lệnh poetry init sẽ hướng dẫn bạn tạo file pyproject.toml:

[tool.poetry]
name = "my-fastapi-app"
version = "0.1.0"
description = "A modern FastAPI application"
authors = ["Your Name <[email protected]>"]
readme = "README.md"
license = "MIT"
 
[tool.poetry.dependencies]
python = "^3.11"
 
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

Thêm Dependencies cho FastAPI

# Add production dependencies
poetry add fastapi
poetry add "uvicorn[standard]"
poetry add sqlalchemy
poetry add pydantic-settings
poetry add python-jose[cryptography]
poetry add passlib[bcrypt]
poetry add python-multipart
 
# Add development dependencies
poetry add --group dev pytest
poetry add --group dev pytest-asyncio
poetry add --group dev httpx
poetry add --group dev black
poetry add --group dev ruff
poetry add --group dev mypy

File pyproject.toml của bạn sẽ được cập nhật:

[tool.poetry.dependencies]
python = "^3.11"
fastapi = "^0.109.0"
uvicorn = {extras = ["standard"], version = "^0.27.0"}
sqlalchemy = "^2.0.25"
pydantic-settings = "^2.1.0"
python-jose = {extras = ["cryptography"], version = "^3.3.0"}
passlib = {extras = ["bcrypt"], version = "^1.7.4"}
python-multipart = "^0.0.6"
 
[tool.poetry.group.dev.dependencies]
pytest = "^7.4.3"
pytest-asyncio = "^0.23.3"
httpx = "^0.26.0"
black = "^23.12.1"
ruff = "^0.1.11"
mypy = "^1.8.0"

Hiểu cấu trúc pyproject.toml

Metadata cơ bản

[tool.poetry]
name = "my-fastapi-app"
version = "0.1.0"
description = "A modern FastAPI application with authentication"
authors = ["Your Name <[email protected]>"]
maintainers = ["Team <[email protected]>"]
license = "MIT"
readme = "README.md"
homepage = "https://example.com"
repository = "https://github.com/username/my-fastapi-app"
documentation = "https://docs.example.com"
keywords = ["fastapi", "api", "rest"]
classifiers = [
    "Development Status :: 4 - Beta",
    "Intended Audience :: Developers",
    "License :: OSI Approved :: MIT License",
    "Programming Language :: Python :: 3.11",
]

Cách chỉ định Dependencies

[tool.poetry.dependencies]
python = "^3.11"  # Python version constraint
 
# Simple version constraint
fastapi = "^0.109.0"  # >=0.109.0, <0.110.0
 
# Exact version
pydantic = "2.5.0"  # Exactly 2.5.0
 
# Version range
sqlalchemy = ">=2.0.0,<3.0.0"
 
# With extras
uvicorn = {extras = ["standard"], version = "^0.27.0"}
 
# Multiple extras
databases = {extras = ["postgresql", "asyncpg"], version = "^0.8.0"}
 
# Optional dependencies
redis = {version = "^5.0.0", optional = true}
 
# Git dependencies
my-lib = {git = "https://github.com/username/my-lib.git", branch = "main"}
 
# Local path dependencies (for development)
my-local-lib = {path = "../my-local-lib", develop = true}
 
# Platform-specific dependencies
pywin32 = {version = "^305", platform = "win32"}

Nhóm Dependencies

[tool.poetry.group.dev.dependencies]
pytest = "^7.4.3"
black = "^23.12.1"
ruff = "^0.1.11"
 
[tool.poetry.group.test.dependencies]
pytest = "^7.4.3"
pytest-cov = "^4.1.0"
pytest-asyncio = "^0.23.3"
httpx = "^0.26.0"
 
[tool.poetry.group.docs.dependencies]
mkdocs = "^1.5.3"
mkdocs-material = "^9.5.3"

Scripts và Commands

[tool.poetry.scripts]
start = "my_fastapi_app.main:start"
migrate = "my_fastapi_app.cli:migrate"
 
# Now you can run:
# poetry run start
# poetry run migrate

Làm việc với Poetry

Các lệnh thông dụng

# Install all dependencies (including dev)
poetry install
 
# Install only production dependencies
poetry install --only main
 
# Add a new dependency
poetry add requests
 
# Add a development dependency
poetry add --group dev pytest
 
# Remove a dependency
poetry remove requests
 
# Update dependencies
poetry update
 
# Update a specific package
poetry update fastapi
 
# Show installed packages
poetry show
 
# Show package details
poetry show fastapi
 
# Show dependency tree
poetry show --tree
 
# Check for dependency issues
poetry check
 
# Build the project
poetry build
 
# Publish to PyPI
poetry publish

Chạy các Commands

# Run Python scripts
poetry run python main.py
 
# Run FastAPI server
poetry run uvicorn main:app --reload
 
# Run tests
poetry run pytest
 
# Run formatters
poetry run black .
poetry run ruff check .
 
# Activate virtual environment
poetry shell
 
# Get virtual environment path
poetry env info --path

Cấu trúc dự án FastAPI hoàn chỉnh với Poetry

my-fastapi-app/
├── pyproject.toml          # Poetry configuration
├── poetry.lock             # Locked dependencies
├── README.md
├── .gitignore
├── my_fastapi_app/
│   ├── __init__.py
│   ├── main.py
│   ├── config.py
│   ├── api/
│   │   ├── __init__.py
│   │   ├── routes/
│   │   │   ├── __init__.py
│   │   │   ├── users.py
│   │   │   └── items.py
│   │   └── dependencies.py
│   ├── models/
│   │   ├── __init__.py
│   │   ├── user.py
│   │   └── item.py
│   ├── schemas/
│   │   ├── __init__.py
│   │   ├── user.py
│   │   └── item.py
│   └── database.py
└── tests/
    ├── __init__.py
    ├── conftest.py
    ├── test_users.py
    └── test_items.py

Ví dụ pyproject.toml hoàn chỉnh

[tool.poetry]
name = "my-fastapi-app"
version = "0.1.0"
description = "A production-ready FastAPI application"
authors = ["Your Name <[email protected]>"]
readme = "README.md"
packages = [{include = "my_fastapi_app"}]
 
[tool.poetry.dependencies]
python = "^3.11"
fastapi = "^0.109.0"
uvicorn = {extras = ["standard"], version = "^0.27.0"}
sqlalchemy = "^2.0.25"
asyncpg = "^0.29.0"
pydantic-settings = "^2.1.0"
python-jose = {extras = ["cryptography"], version = "^3.3.0"}
passlib = {extras = ["bcrypt"], version = "^1.7.4"}
python-multipart = "^0.0.6"
alembic = "^1.13.1"
 
[tool.poetry.group.dev.dependencies]
pytest = "^7.4.3"
pytest-asyncio = "^0.23.3"
pytest-cov = "^4.1.0"
httpx = "^0.26.0"
black = "^23.12.1"
ruff = "^0.1.11"
mypy = "^1.8.0"
 
[tool.poetry.scripts]
dev = "uvicorn my_fastapi_app.main:app --reload"
migrate = "alembic upgrade head"
 
[tool.black]
line-length = 88
target-version = ['py311']
include = '\.pyi?$'
 
[tool.ruff]
line-length = 88
select = ["E", "F", "I"]
ignore = []
fixable = ["ALL"]
 
[tool.mypy]
python_version = "3.11"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true
 
[tool.pytest.ini_options]
testpaths = ["tests"]
asyncio_mode = "auto"
addopts = "--cov=my_fastapi_app --cov-report=term-missing"
 
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

Cấu hình Environment

Sử dụng pydantic-settings

# config.py
from pydantic_settings import BaseSettings, SettingsConfigDict
 
class Settings(BaseSettings):
    app_name: str = "FastAPI App"
    debug: bool = False
    database_url: str
    secret_key: str
    
    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8"
    )
 
settings = Settings()

File .env

# .env
APP_NAME="My FastAPI App"
DEBUG=true
DATABASE_URL=postgresql+asyncpg://user:pass@localhost/dbname
SECRET_KEY=your-secret-key-here

Thêm python-dotenv

poetry add python-dotenv

Tích hợp Docker với Poetry

Dockerfile

FROM python:3.11-slim
 
WORKDIR /app
 
# Install Poetry
RUN pip install poetry
 
# Copy dependency files
COPY pyproject.toml poetry.lock ./
 
# Install dependencies
RUN poetry config virtualenvs.create false \
    && poetry install --only main --no-interaction --no-ansi
 
# Copy application
COPY . .
 
# Run application
CMD ["uvicorn", "my_fastapi_app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Multi-stage Docker Build (Tối ưu hóa)

# Stage 1: Build dependencies
FROM python:3.11-slim as builder
 
WORKDIR /app
 
RUN pip install poetry
 
COPY pyproject.toml poetry.lock ./
 
RUN poetry export -f requirements.txt --output requirements.txt --without-hashes
 
# Stage 2: Runtime
FROM python:3.11-slim
 
WORKDIR /app
 
COPY --from=builder /app/requirements.txt .
 
RUN pip install --no-cache-dir -r requirements.txt
 
COPY . .
 
CMD ["uvicorn", "my_fastapi_app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Best Practices

1. Ràng buộc Version

[tool.poetry.dependencies]
# Good: Allows minor updates
fastapi = "^0.109.0"  # >=0.109.0, <0.110.0
 
# Good: Allows patch updates
pydantic = "~2.5.0"  # >=2.5.0, <2.6.0
 
# Avoid: Too restrictive
sqlalchemy = "2.0.25"  # Exactly this version
 
# Avoid: Too permissive
requests = "*"  # Any version

2. Sử dụng Dependency Groups

[tool.poetry.group.dev.dependencies]
pytest = "^7.4.3"
black = "^23.12.1"
 
[tool.poetry.group.test.dependencies]
pytest-cov = "^4.1.0"
httpx = "^0.26.0"
 
[tool.poetry.group.docs.dependencies]
mkdocs = "^1.5.3"

3. Lock File trong Version Control

# Always commit poetry.lock
git add poetry.lock
git commit -m "Update dependencies"

4. Sử dụng Poetry Scripts

[tool.poetry.scripts]
dev = "uvicorn my_fastapi_app.main:app --reload --port 8000"
test = "pytest tests/ -v"
lint = "ruff check ."
format = "black ."

5. Cấu hình Tools trong pyproject.toml

[tool.black]
line-length = 88
target-version = ['py311']
 
[tool.ruff]
line-length = 88
select = ["E", "F", "I", "N"]
 
[tool.mypy]
python_version = "3.11"
strict = true
 
[tool.pytest.ini_options]
asyncio_mode = "auto"
testpaths = ["tests"]

Xử lý các vấn đề thường gặp

Vấn đề: Poetry Install chậm

# Use parallel installation
poetry config installer.parallel true
 
# Use modern installer
poetry config installer.modern-installation true

Vấn đề: Xung đột Dependencies

# Show dependency tree
poetry show --tree
 
# Update lock file
poetry lock --no-update
 
# Force update
poetry update

Vấn đề: Không tìm thấy Virtual Environment

# Show environment info
poetry env info
 
# List all environments
poetry env list
 
# Remove environment
poetry env remove python3.11
 
# Create new environment
poetry install

Vấn đề: Lỗi Cache

# Clear cache
poetry cache clear pypi --all
 
# Reinstall dependencies
poetry install --no-cache

Chuyển đổi từ requirements.txt

Export sang requirements.txt

# Export all dependencies
poetry export -f requirements.txt --output requirements.txt
 
# Export without dev dependencies
poetry export -f requirements.txt --output requirements.txt --without dev
 
# Export without hashes (for compatibility)
poetry export -f requirements.txt --output requirements.txt --without-hashes

Import từ requirements.txt

# Add all requirements
cat requirements.txt | xargs poetry add
 
# Or manually
poetry add $(cat requirements.txt)

Kết luận

Poetry và TOML đã hiện đại hóa quản lý dự án Python:

TOML cung cấp định dạng cấu hình sạch sẽ, dễ đọc
Poetry tự động xử lý giải quyết dependencies
pyproject.toml tập trung hóa toàn bộ cấu hình dự án
poetry.lock đảm bảo builds có thể tái tạo
Dependency groups phân tách mối quan tâm hiệu quả

Đối với các dự án FastAPI, Poetry mang lại:

Quản lý dependencies dễ dàng
Phân tách rõ ràng dependencies dev/test/prod
Xử lý virtual environment tự động
Cộng tác tốt hơn thông qua lock files
Đơn giản hóa deployment với Docker

Bắt đầu sử dụng Poetry trong dự án FastAPI tiếp theo của bạn và trải nghiệm phát triển Python hiện đại!

Tham khảo nhanh

# Create project
poetry new my-app
poetry init
 
# Dependencies
poetry add fastapi
poetry add --group dev pytest
poetry remove requests
 
# Install & Run
poetry install
poetry run uvicorn main:app --reload
poetry shell
 
# Update & Maintain
poetry update
poetry show --tree
poetry check
 
# Export
poetry export -f requirements.txt --output requirements.txt

Poetry làm cho việc quản lý các dự án FastAPI trở nên dễ dàng. Hãy thử ngay! 🚀