📚 课程目录第1章项目初始化与配置管理

1. 项目初始化与配置管理

任务说明

本案例目标为：搭建一个可运行的 FastAPI 项目骨架，使用 Pydantic Settings 实现环境变量加载与配置分离。你将得到一个最小但完整的项目结构，包含应用入口、配置模型、示例路由，并验证配置是否按环境正确加载。

项目结构

fastapi_config_demo/
├── app/
│   ├── __init__.py
│   ├── main.py          # FastAPI 应用入口
│   ├── config.py        # Pydantic Settings 配置模型
│   └── routers/
│       ├── __init__.py
│       └── health.py    # 健康检查路由，展示配置值
├── .env.example         # 环境变量模板
├── .env                 # 本地环境变量（实际使用）
└── requirements.txt

实现代码

requirements.txt

fastapi==0.115.6
uvicorn[standard]==0.34.0
pydantic-settings==2.7.1

app/config.py

from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    """应用配置模型，自动从环境变量 / .env 文件加载"""

    app_name: str = "FastAPI Config Demo"
    debug: bool = False
    database_url: str = "sqlite:///./default.db"
    api_prefix: str = "/api/v1"

    model_config = SettingsConfigDict(
        env_file=".env", env_file_encoding="utf-8", extra="ignore"
    )

# 模块级单例，供全局导入使用
settings = Settings()

app/routers/health.py

from fastapi import APIRouter

from app.config import settings

router = APIRouter()

@router.get("/health")
def health_check():
    """返回服务状态与当前配置关键项（仅用于验证配置加载）"""
    return {
        "status": "ok",
        "app_name": settings.app_name,
        "debug": settings.debug,
        "database_url": settings.database_url,
    }

app/main.py

from fastapi import FastAPI

from app.config import settings
from app.routers import health

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

# 注册路由，统一挂载在配置的 api_prefix 下
app.include_router(health.router, prefix=settings.api_prefix)

@app.get("/")
def root():
    return {"message": f"Welcome to {settings.app_name}"}

app/__init__.py 与 app/routers/__init__.py 均为空文件。

.env.example

APP_NAME=FastAPI Config Demo
DEBUG=false
DATABASE_URL=sqlite:///./app.db
API_PREFIX=/api/v1

.env（实际使用，内容可同 .env.example）

APP_NAME=FastAPI Config Demo
DEBUG=true
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
API_PREFIX=/api/v1

配置加载机制说明

Pydantic Settings 在实例化 Settings() 时按以下优先级读取：环境变量 > .env 文件 > 代码中的默认值。因此，若在 shell 中导出了 DATABASE_URL，则 .env 中的同名值会被覆盖。本案例中 extra="ignore" 表示 .env 中多余的键不会导致报错。

运行方式

cd fastapi_config_demo
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

验证方法与判定标准

配置加载验证：访问 http://127.0.0.1:8000/api/v1/health，应返回 JSON，其中 app_name 为 FastAPI Config Demo，debug 为 true，database_url 为 postgresql://user:pass@localhost:5432/mydb（与 .env 中一致）。若返回这些值，说明 .env 文件被正确读取。
环境变量优先级验证：在终端执行 export DATABASE_URL="sqlite:///./override.db" 后重启服务，再次访问上述地址，database_url 应变为 sqlite:///./override.db，证明环境变量覆盖 .env 文件。
接口连通性验证：访问 http://127.0.0.1:8000/，返回欢迎信息，说明应用入口正常。

以上验证均通过，即表示项目骨架搭建成功，配置分离与加载机制工作正常。