Làm thế nào để quản lý settings với Pydantic?

Question

Accepted Answer

Ứng dụng FastAPI quản lý cấu hình với **`pydantic-settings`** (`BaseSettings`) — một class đọc cấu hình từ **biến môi trường** (và file `.env`) với **validation và chuyển đổi kiểu**, giữ secret ngoài code và đảm bảo cấu hình đúng tại thời điểm khởi động.

## Định nghĩa settings

```python
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    app_name: str = "My API"
    database_url: str                       # bắt buộc — phải được cung cấp
    secret_key: str                          # bắt buộc (một secret)
    debug: bool = False
    max_connections: int = 10

class Config:
        env_file = ".env"                    # cũng đọc từ một file .env

settings = Settings()                        # đọc & VALIDATE biến môi trường tại khởi động
```

`BaseSettings` tự động đọc mỗi field từ một **biến môi trường** khớp (ví dụ `DATABASE_URL`), chuyển đổi kiểu (`"true"` → `bool`, `"10"` → `int`), và **validate** — một giá trị bắt buộc bị thiếu hoặc sai kiểu fail ngay lập tức tại khởi động với một lỗi rõ ràng (fail-fast).

## Dùng settings (qua dependency injection)

```python
from functools import lru_cache
from fastapi import Depends

@lru_cache                              # tạo Settings một lần (được cache)
def get_settings():
    return Settings()

@app.get("/info")
def info(settings: Settings = Depends(get_settings)):
    return {"app": settings.app_name, "debug": settings.debug}
```

Tiêm settings qua một dependency được cache khiến chúng **testable** (ghi đè trong test) và đảm bảo một instance duy nhất.

## File .env và secret

```bash
# .env — cấu hình cục bộ, ĐƯỢC GITIGNORE (không bao giờ commit secret)
DATABASE_URL=postgresql://localhost/mydb
SECRET_KEY=dev-secret
DEBUG=true
```

```text
✓ Giữ secret trong biến môi trường / .env (gitignore); commit một .env.example tài liệu hóa các key
✓ Trong production, tiêm cấu hình qua môi trường / secret manager của nền tảng
✓ Validation tại khởi động bắt cấu hình sai ngay lập tức (không phải sâu trong một request)
```

## Tại sao điều này quan trọng

Quản lý settings đúng đắn vừa là một **nhu cầu vận hành** (app cần cấu hình khác nhau giữa dev/staging/production) vừa là một **yêu cầu bảo mật** (secret như database URL và key không bao giờ được hardcode trong source control — một vi phạm phổ biến, nghiêm trọng). `BaseSettings` của Pydantic cung cấp giải pháp idiomatic của FastAPI, và hiểu nó là kiến thức hằng ngày quan trọng.

Các lợi thế then chốt của nó: đọc cấu hình từ **biến môi trường** (giữ secret ngoài code, cách tiếp cận twelve-factor) với **chuyển đổi kiểu và validation** tự động — nên cấu hình sai fail nhanh tại khởi động với lỗi rõ ràng thay vì là một lỗi runtime khó hiểu.

Kết hợp với dependency injection (khiến settings testable và singleton) và thực hành dùng file `.env` được gitignore cho phát triển cục bộ, điều này cho bạn cấu hình an toàn, được validate, phù hợp môi trường.

Biết cách định nghĩa settings, dùng chúng qua DI, và xử lý secret an toàn là cơ bản để xây dựng ứng dụng FastAPI sẵn sàng cho production.