知识小屋

    配置管理

    项目里经常会有这些配置：

    • 应用名称
    • 是否开启调试模式
    • 数据库地址
    • JWT 密钥
    • Redis 地址
    • 第三方接口密钥

    这些值不应该散落在代码里，更不应该把生产密钥写死到代码仓库。

    FastAPI 项目通常用 pydantic-settings 管理配置。

    一、安装

    pip install pydantic-settings

    pydantic-settings 是 Pydantic 生态里的配置管理包，Pydantic v2 后它是单独安装的。

    二、创建配置类

    目录结构：

    app/
├── __init__.py
├── main.py
└── core/
    ├── __init__.py
    └── config.py

    app/core/config.py：

    from functools import lru_cache

from pydantic_settings import BaseSettings, SettingsConfigDict


class Settings(BaseSettings):
    app_name: str = "FastAPI Demo"
    debug: bool = False
    database_url: str = "sqlite:///./app.db"
    secret_key: str = "change-me-in-production"

    # 读取 .env 文件，extra="ignore" 可以忽略 .env 中暂时没用到的变量
    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        extra="ignore",
    )


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

    关键点：

    代码说明
    BaseSettings自动从环境变量和 .env 读取配置
    SettingsConfigDict配置 .env 文件路径和编码
    @lru_cache缓存配置对象，避免每次请求都重新读取
    extra="ignore".env 多出字段时不报错，适合初学项目

    三、创建 .env 文件

    项目根目录创建 .env：

    APP_NAME=我的 FastAPI 项目
DEBUG=true
DATABASE_URL=sqlite:///./dev.db
SECRET_KEY=dev-secret

    环境变量名默认不区分大小写，通常习惯用大写。

    app_name 会读取 APP_NAME，database_url 会读取 DATABASE_URL。

    四、在 main.py 中使用配置

    from fastapi import Depends, FastAPI

from app.core.config import Settings, get_settings

app = FastAPI()


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

    启动：

    fastapi dev app/main.py

    访问：

    GET /settings

    可以看到 .env 里的配置。

    五、让 FastAPI 标题也使用配置

    应用创建时还不能用 Depends，可以直接调用 get_settings()：

    from fastapi import FastAPI

from app.core.config import get_settings

settings = get_settings()

app = FastAPI(
    title=settings.app_name,
    debug=settings.debug,
)

    Depends 适合路由函数参数，普通 Python 代码里直接调用函数即可。

    六、不要提交真实密钥

    建议提交 .env.example，不要提交真实 .env。

    .env.example：

    APP_NAME=FastAPI Demo
DEBUG=false
DATABASE_URL=sqlite:///./app.db
SECRET_KEY=please-change-me

    .gitignore：

    .env

    七、配置命名建议

    配置建议字段
    应用名称app_name
    调试模式debug
    数据库地址database_url
    密钥secret_key
    Token 过期时间access_token_expire_minutes

    配置要集中管理。不要在不同文件里到处写：

    DATABASE_URL = "sqlite:///./app.db"
SECRET_KEY = "abc"

    项目变大后，这种写法很难维护。