【FastAPI 學習筆記 EP.30】pydantic-settings 環境變數與設定管理

什麼是 pydantic-settings？

pydantic-settings 是基於 Pydantic 的設定管理工具，能自動從 .env 檔案或系統環境變數讀取設定值，並提供型別驗證。

1. 安裝套件：pip install pydantic-settings。
2. 建立繼承 BaseSettings 的設定類別，欄位名稱對應環境變數名稱（大小寫不敏感），可設預設值作為備援。
3. 在 model_config 中設定 SettingsConfigDict(env_file=".env") 讓 pydantic-settings 自動讀取 .env 檔案。
4. 使用 @lru_cache 包裝取得設定的函式，確保整個應用程式只建立一次設定物件，避免重複讀取 .env 檔案。
5. 搭配 Depends 將設定注入到路由中，.env 檔案不應提交至版本控制，改提交 .env.example 作為範本。

# .env 檔案（加入 .gitignore，不提交到 Git）
# APP_NAME=My FastAPI App
# SECRET_KEY=your-secret-key-here
# DEBUG=false
# DATABASE_URL=sqlite:///./app.db

from functools import lru_cache
from typing import Annotated
from fastapi import FastAPI, Depends
from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    app_name: str = "FastAPI App"   # 有預設值，env 未設定時使用此值
    secret_key: str                  # 無預設值，必須在 env 中設定
    debug: bool = False
    database_url: str

    model_config = SettingsConfigDict(env_file=".env")

@lru_cache
def get_settings() -> Settings:
    return Settings()

SettingsDep = Annotated[Settings, Depends(get_settings)]

app = FastAPI()

@app.get("/info/")
def app_info(settings: SettingsDep):
    return {
        "app_name": settings.app_name,
        "debug": settings.debug,
        # 注意：絕對不要在 API 回傳 secret_key 等敏感資訊
    }