FastAPI 配置分为两层。pyproject.toml 中的 [tool.fastapi] 配置 CLI 如何找到应用;应用 Settings 则配置创建出来的服务如何运行。
pyproject.toml
[tool.fastapi]
当前项目使用:
1[tool.fastapi] 2entrypoint = "app.main:app"
冒号左侧是模块路径,右侧是模块中的对象名:
入口 app.main:app 的冒号左侧是模块路径:app 表示 Python 包,main 表示包内的 app/main.py 模块。冒号右侧 app 表示该模块导出的 FastAPI 对象;CLI 导入模块并取得该对象。
FLOW / RELATIONSHIP
app
Python 包
app.main
app/main.py 模块
:app
模块中的 FastAPI 对象
对应代码是:
1from app.factory import create_app 2 3app = create_app()
FastAPI CLI 执行的效果相当于:
1from app.main import app
配置入口后,本地开发不必重复传文件路径:
1uv run fastapi dev 2uv run fastapi run
fastapi dev 面向开发,会启用自动重载;fastapi run 面向生产启动。[tool.fastapi] 不会决定监听端口、worker 数量或环境变量,这些仍由 CLI 参数和运行环境控制。
fastapi dev
fastapi run
需要特别注意,fastapi dev 会在导入应用前尝试设置 FASTAPI_ENV=development,而 fastapi run 不会自动设置生产值。上一篇的 Settings 读取的是 APP__ENVIRONMENT,并不会把 FASTAPI_ENV 自动转换成 settings.app.environment,因此部署时仍应显式设置 APP__ENVIRONMENT=production。
FASTAPI_ENV=development
APP__ENVIRONMENT
FASTAPI_ENV
settings.app.environment
APP__ENVIRONMENT=production
两条命令的默认监听地址也不同:fastapi dev 使用 127.0.0.1,只供本机访问;fastapi run 使用 0.0.0.0,可能被网络中的其他设备访问。生产部署还需要结合反向代理、HTTPS、防火墙和进程管理,不能把执行一条 fastapi run 当作完整的部署方案。
127.0.0.1
0.0.0.0
如果项目改成 src 布局,例如应用位于 src/agent_api/main.py,入口也必须同步调整:
src
src/agent_api/main.py
1[tool.fastapi] 2entrypoint = "agent_api.main:app"
这个写法要求 agent_api 已经按照 src 布局安装到当前 Python 环境中。只是在仓库里创建 src/agent_api 目录,却没有正确配置并安装项目时,Python 仍然可能找不到这个包。
agent_api
src/agent_api
入口配置错误时,FastAPI CLI 会在启动阶段报告模块无法导入或找不到 app,它与请求路由返回 404 是不同问题。
不要在 main.py 中读取几十个环境变量,再逐个创建中间件、数据库和模型。应用工厂可以把组装过程集中起来:
main.py
01from collections.abc import Callable 02from contextlib import AbstractAsyncContextManager 03 04from fastapi import FastAPI 05 06from app.api.router import router as api_router 07from app.core.settings import Settings, get_settings 08from app.middleware import register_middleware 09 10 11def create_app(settings: Settings | None = None) -> FastAPI: 12 current_settings = settings if settings is not None else get_settings() 13 14 app = FastAPI( 15 title=current_settings.app.name, 16 version="0.1.0", 17 debug=current_settings.app.environment == "development", 18 ) 19 app.state.settings = current_settings 20 21 register_middleware(app, current_settings) 22 app.include_router(api_router) 23 return app
settings 参数允许测试显式传入配置;正常启动则调用 get_settings()。这比在测试中修改全局环境变量后重新导入整个模块更可控。
settings
get_settings()
app.state.settings 把当前配置挂在应用实例上,适合需要从 Request 找到应用资源的依赖。它不是让所有业务代码直接访问全局状态的理由,业务服务仍应通过构造参数接收自己需要的配置。
app.state.settings
Request
Settings 可以在进程中缓存:
1from functools import lru_cache 2 3 4@lru_cache(maxsize=1) 5def get_settings() -> Settings: 6 return Settings()
缓存后,同一 worker 进程只读取和校验一次配置。部署多个 worker 时,每个进程都有自己的 Settings 和资源,Python 内存不会跨进程共享。
修改 .env 或 TOML 后,缓存对象不会自行变化。生产环境应重启或滚动更新应用,而不是尝试在请求中清除缓存。
.env
FastAPI 依赖可以把 Settings 提供给路由:
01from typing import Annotated 02 03from fastapi import Depends, Request 04 05from app.core.settings import Settings 06 07 08def get_current_settings(request: Request) -> Settings: 09 return request.app.state.settings 10 11 12SettingsDep = Annotated[Settings, Depends(get_current_settings)]
get_settings() 负责在创建应用时读取配置,get_current_settings() 则负责把这个已经确定的对象交给路由。名称看起来相近,但职责不同。这样测试向应用工厂传入 Settings 后,路由、中间件和 lifespan 都会看到同一个实例。
get_current_settings()
路由只声明需要配置,不负责读取配置文件:
01from fastapi import APIRouter 02 03from app.api.dependencies import SettingsDep 04 05router = APIRouter() 06 07 08@router.get("/runtime-info") 09async def runtime_info(settings: SettingsDep) -> dict[str, str]: 10 return { 11 "app_name": settings.app.name, 12 "environment": settings.app.environment, 13 "model": settings.model.name, 14 }
真实接口不一定应该公开模型名称和环境信息。这里用于演示依赖传递;生产健康检查只返回排障所需的非敏感字段。
依赖注入的价值不是少写一行导入,而是让对象来源明确且可以替换。对于 Settings,应用工厂参数就是最直接的替换入口:
1from app.factory import create_app 2 3 4def test_factory_uses_injected_settings(test_settings): 5 app = create_app(test_settings) 6 7 assert app.state.settings is test_settings
这里的 test_settings fixture 会在第 6 节定义。模型客户端等资源依赖仍然可以使用 app.dependency_overrides 替换,但覆盖完成后应及时清空,避免影响其他测试。
test_settings
app.dependency_overrides
如果路由自己调用 Settings(),测试就很难替换来源,还可能在每次请求中重复读取文件。
Settings()
Settings 是轻量配置对象,数据库连接池、异步 HTTP 客户端和 LangGraph checkpointer 则是需要创建与关闭的长期资源。它们适合放进 FastAPI lifespan,也就是从应用启动到应用停止的这段生命周期:
01from collections.abc import AsyncIterator 02from contextlib import asynccontextmanager 03 04from fastapi import FastAPI 05from httpx import AsyncClient, Timeout 06 07from app.agent.graph import create_graph 08from app.agent.model import create_model 09from app.core.checkpointer import open_checkpointer 10from app.core.settings import Settings 11 12 13def create_lifespan(settings: Settings): 14 @asynccontextmanager 15 async def lifespan(app: FastAPI) -> AsyncIterator[None]: 16 async with AsyncClient( 17 timeout=Timeout(settings.model.timeout_seconds), 18 ) as http_client: 19 async with open_checkpointer(settings) as checkpointer: 20 model = create_model(settings) 21 graph = create_graph( 22 model=model, 23 checkpointer=checkpointer, 24 ) 25 26 app.state.http_client = http_client 27 app.state.model = model 28 app.state.checkpointer = checkpointer 29 app.state.graph = graph 30 31 yield 32 33 return lifespan
create_lifespan() 是一个工厂:外层函数先接收 Settings,内层 lifespan() 再由 FastAPI 调用。yield 之前负责创建资源,yield 之后会按照 async with 的逆序自动关闭资源。
create_lifespan()
lifespan()
yield
async with
如果某个资源在 yield 之前创建失败,应用不会开始接收请求,已经进入的 async with 也会负责清理。这比先启动服务、等到请求到来后才发现核心资源不可用更容易排查。
示例中的 create_model()、create_graph() 和 open_checkpointer() 是项目自己的工厂函数,后续 LangChain/LangGraph 文章会实现。其中,open_checkpointer() 应返回异步上下文管理器,让内存和 PostgreSQL 两种实现拥有统一的打开、关闭方式。不能只把 checkpointer 传给编译图后,再假设可以从图对象中取回并关闭它。
create_model()
create_graph()
open_checkpointer()
最后,把这个 lifespan 工厂交给应用工厂:
01from fastapi import FastAPI 02 03from app.api.router import router as api_router 04from app.core.lifespan import create_lifespan 05from app.core.settings import Settings, get_settings 06from app.middleware import register_middleware 07 08AppLifespan = Callable[[FastAPI], AbstractAsyncContextManager[None]] 09 10 11def create_app( 12 settings: Settings | None = None, 13 *, 14 lifespan: AppLifespan | None = None, 15) -> FastAPI: 16 current = settings if settings is not None else get_settings() 17 is_production = current.app.environment == "production" 18 current_lifespan = ( 19 lifespan if lifespan is not None else create_lifespan(current) 20 ) 21 22 app = FastAPI( 23 title=current.app.name, 24 version="0.1.0", 25 debug=current.app.environment == "development", 26 openapi_url=None if is_production else "/openapi.json", 27 docs_url=None if is_production else "/docs", 28 redoc_url=None if is_production else "/redoc", 29 lifespan=current_lifespan, 30 ) 31 app.state.settings = current 32 33 register_middleware(app, current) 34 app.include_router(api_router) 35 return app
正常启动没有传入 lifespan 时,工厂会调用 create_lifespan(current);测试则可以传入不连接外部服务的生命周期。这样应用工厂、路由依赖、中间件和 lifespan 始终使用同一份 Settings。这里选择在生产环境关闭 OpenAPI Schema 和两个文档页面,但这属于产品策略,不是固定答案。即使关闭这些入口,接口本身仍需认证、授权和输入校验,不能把隐藏文档当作安全措施。
lifespan
create_lifespan(current)
请求需要使用生命周期资源时,可以通过依赖从 request.app.state 读取:
request.app.state
01from typing import Annotated 02 03from fastapi import Depends, Request 04from langchain_core.language_models import BaseChatModel 05 06 07def get_chat_model(request: Request) -> BaseChatModel: 08 return request.app.state.model 09 10 11ChatModelDep = Annotated[BaseChatModel, Depends(get_chat_model)]
路由获得的是抽象模型接口:
01from fastapi import APIRouter 02from pydantic import BaseModel, Field 03 04from app.api.dependencies import ChatModelDep 05 06router = APIRouter() 07 08 09class ChatRequest(BaseModel): 10 question: str = Field(min_length=1, max_length=4_000) 11 12 13class ChatResponse(BaseModel): 14 answer: str 15 16 17@router.post("/chat") 18async def chat(payload: ChatRequest, model: ChatModelDep) -> ChatResponse: 19 response = await model.ainvoke(payload.question) 20 return ChatResponse(answer=response.text)
ChatRequest 继承 BaseModel,所以 FastAPI 会把 JSON 请求体解析到 payload,并在调用模型前检查问题是否为空、长度是否超出当前项目限制。如果直接把 question: str 写在函数参数中,它默认会被当作查询参数,而不是 JSON 请求体。
ChatRequest
BaseModel
payload
question: str
资源范围需要区分:
thread_id
不能因为数据库 Engine 可以复用,就把一个可变的数据库 Session 也放到全局。thread_id 也不能设置成全进程共享值,否则不同用户的对话状态可能混在一起。配置决定如何创建资源,资源自身还要遵守正确生命周期。
第 4 节的完整应用工厂已经根据 settings.app.environment 设置标题、调试模式和文档地址。debug 只在 development 环境开启,不能简单写成 not is_production,否则 test 和 staging 也会意外进入调试模式。
debug
development
not is_production
test
staging
CORS 同样要把 Settings 中的值真正传给中间件:
01from fastapi import FastAPI 02from fastapi.middleware.cors import CORSMiddleware 03 04from app.core.settings import Settings 05 06 07def add_cors(app: FastAPI, settings: Settings) -> None: 08 app.add_middleware( 09 CORSMiddleware, 10 allow_origins=settings.server.cors.allow_origins, 11 allow_methods=settings.server.cors.allow_methods, 12 allow_headers=["Authorization", "Content-Type"], 13 allow_credentials=False, 14 )
上一篇的 CorsSettings 只声明了来源和请求方法,因此这里为请求头和凭据使用明确的安全值。如果项目需要让这两项随环境变化,应先把 allow_headers、allow_credentials 同时加入 Settings 模型和 TOML,再从 settings.server.cors 读取。配置项只有传入真实组件才会生效,仅在 TOML 中写下 allow_origins 不会自动改变浏览器跨域行为。
CorsSettings
allow_headers
allow_credentials
settings.server.cors
allow_origins
应用工厂允许测试直接构造 Settings:
01from collections.abc import AsyncIterator 02from contextlib import asynccontextmanager 03 04import pytest 05from fastapi import FastAPI 06 07from app.core.settings import Settings 08from app.factory import create_app 09 10 11@asynccontextmanager 12async def empty_lifespan(_app: FastAPI) -> AsyncIterator[None]: 13 yield 14 15 16@pytest.fixture 17def test_settings() -> Settings: 18 return Settings( 19 _env_file=None, 20 app={ 21 "name": "FastAPI LangChain Test", 22 "environment": "test", 23 "log_level": "WARNING", 24 }, 25 server={ 26 "host": "127.0.0.1", 27 "port": 8000, 28 "cors": { 29 "allow_origins": ["http://testserver"], 30 "allow_methods": ["GET", "POST", "OPTIONS"], 31 }, 32 }, 33 model={ 34 "provider": "fake", 35 "name": "fake-model", 36 "base_url": "https://example.test", 37 "api_key": None, 38 "temperature": 0, 39 "timeout_seconds": 5, 40 "max_retries": 0, 41 }, 42 langgraph={ 43 "recursion_limit": 10, 44 "checkpoint_backend": "memory", 45 }, 46 database={ 47 "url": None, 48 "pool_size": 1, 49 "pool_timeout_seconds": 5, 50 }, 51 langsmith_tracing=False, 52 langsmith_api_key=None, 53 ) 54 55 56@pytest.fixture 57def app(test_settings: Settings) -> FastAPI: 58 return create_app(test_settings, lifespan=empty_lifespan)
_env_file=None 会关闭 .env 读取;各个必填分组也都显式提供测试值,因此不会只覆盖两个字段却意外沿用生产密钥。第 42 篇自定义的 TOML 来源仍会参与收集,但初始化参数优先级最高。若配置测试需要完全隔离 TOML,应为测试定义专用 Settings 子类或测试配置文件,这部分会在后续测试章节展开。
_env_file=None
empty_lifespan 让只测试应用元数据或普通路由的用例不连接真实模型和数据库。需要验证资源型路由时,应改用能够写入 app.state.model 等假资源的测试 lifespan,或覆盖对应的 FastAPI 依赖。
empty_lifespan
app.state.model
创建 TestClient 时,如果要让 lifespan 真正运行,应把它作为上下文管理器使用。下面运行的是 fixture 中注入的 empty_lifespan,不会连接外部服务:
TestClient
1from fastapi.testclient import TestClient 2 3 4def test_runtime_info(app): 5 with TestClient(app) as client: 6 response = client.get("/runtime-info") 7 8 assert response.status_code == 200
如果测试必须修改环境变量,应在修改后清除缓存,并在测试结束时恢复环境。pytest 的 monkeypatch 可以管理这个过程:
monkeypatch
01from app.core.settings import get_settings 02 03 04def test_model_override(monkeypatch): 05 monkeypatch.setenv("MODEL__NAME", "test-model") 06 get_settings.cache_clear() 07 08 try: 09 settings = get_settings() 10 assert settings.model.name == "test-model" 11 finally: 12 get_settings.cache_clear()
monkeypatch 会在测试结束时恢复环境变量,finally 则保证即使断言失败也会清除 Settings 缓存。
finally
让公开配置真正控制应用标题、调试模式、文档地址与 lifespan,观察同一 Settings 如何被工厂和路由共同使用。
下面的代码直接读取工作区的原始文件,文章与下载项目使用同一份来源:
1from configured_app import create_app, load_settings 2 3app = create_app(load_settings()) 4
01from collections.abc import AsyncIterator 02from contextlib import asynccontextmanager 03from pathlib import Path 04from typing import Literal 05import tomllib 06 07from fastapi import FastAPI, Request 08from pydantic import BaseModel, ConfigDict, Field 09 10class Settings(BaseModel): 11 model_config = ConfigDict(extra="forbid") 12 name: str = Field(min_length=1, max_length=80) 13 environment: Literal["development", "test", "production"] 14 15def load_settings() -> Settings: 16 with Path(__file__).with_name("config.toml").open("rb") as file: 17 return Settings.model_validate(tomllib.load(file)["app"]) 18 19@asynccontextmanager 20async def lifespan(app: FastAPI) -> AsyncIterator[None]: 21 app.state.ready = True 22 print("应用生命周期启动") 23 try: 24 yield 25 finally: 26 app.state.ready = False 27 print("应用生命周期关闭") 28 29def create_app(settings: Settings) -> FastAPI: 30 production = settings.environment == "production" 31 app = FastAPI(title=settings.name, debug=settings.environment == "development", 32 docs_url=None if production else "/docs", 33 redoc_url=None if production else "/redoc", 34 openapi_url=None if production else "/openapi.json", lifespan=lifespan) 35 app.state.settings = settings 36 37 @app.get("/runtime-info") 38 async def runtime_info(request: Request) -> dict[str, object]: 39 current = request.app.state.settings 40 return {"title": request.app.title, "environment": current.environment, 41 "debug": request.app.debug, "docs_url": request.app.docs_url, 42 "ready": request.app.state.ready} 43 44 return app 45
1[app] 2name = "配置驱动的 FastAPI" 3environment = "development" 4
打开在线案例,点击运行,等待环境就绪,再发送默认 GET /runtime-info。本篇不需要模型密钥或外部服务。
GET /runtime-info
默认 title 为配置驱动的 FastAPI,environment=development、debug=true、docs_url="/docs"、ready=true。日志先记录生命周期启动,请求时读取的是应用已保存的 Settings。
把 environment 改为 production 并重新运行,debug 变为 false,docs_url 变为 null;此时用在线请求面板直接访问 /runtime-info,或者本机 curl 请求,不能继续依赖 /docs。配置在创建应用时读取,不随每次请求改写;本篇生命周期只管理本地状态,不创建模型、数据库或后台线程。
下载项目后,在项目目录执行:
1uv run fastapi dev main.py
再通过 http://127.0.0.1:8000/docs 发送同一请求。本机示例使用 Python 3.12,浏览器由共享 Pyodide 环境执行;本篇代码只使用两者都有的能力。
http://127.0.0.1:8000/docs
此段落已有评论,按 Enter 查看评论及回复列表。
连接 GitHub 后查看和发表评论,也可在 GitHub 查看公开讨论。
1. 入口
FastAPI 配置分为两层。
pyproject.toml中的[tool.fastapi]配置 CLI 如何找到应用;应用 Settings 则配置创建出来的服务如何运行。当前项目使用:
冒号左侧是模块路径,右侧是模块中的对象名:
入口 app.main:app 的冒号左侧是模块路径:app 表示 Python 包,main 表示包内的 app/main.py 模块。冒号右侧 app 表示该模块导出的 FastAPI 对象;CLI 导入模块并取得该对象。
FLOW / RELATIONSHIP
app
Python 包
app.main
app/main.py 模块
:app
模块中的 FastAPI 对象
对应代码是:
FastAPI CLI 执行的效果相当于:
配置入口后,本地开发不必重复传文件路径:
fastapi dev面向开发,会启用自动重载;fastapi run面向生产启动。[tool.fastapi]不会决定监听端口、worker 数量或环境变量,这些仍由 CLI 参数和运行环境控制。需要特别注意,
fastapi dev会在导入应用前尝试设置FASTAPI_ENV=development,而fastapi run不会自动设置生产值。上一篇的 Settings 读取的是APP__ENVIRONMENT,并不会把FASTAPI_ENV自动转换成settings.app.environment,因此部署时仍应显式设置APP__ENVIRONMENT=production。两条命令的默认监听地址也不同:
fastapi dev使用127.0.0.1,只供本机访问;fastapi run使用0.0.0.0,可能被网络中的其他设备访问。生产部署还需要结合反向代理、HTTPS、防火墙和进程管理,不能把执行一条fastapi run当作完整的部署方案。如果项目改成
src布局,例如应用位于src/agent_api/main.py,入口也必须同步调整:这个写法要求
agent_api已经按照src布局安装到当前 Python 环境中。只是在仓库里创建src/agent_api目录,却没有正确配置并安装项目时,Python 仍然可能找不到这个包。入口配置错误时,FastAPI CLI 会在启动阶段报告模块无法导入或找不到
app,它与请求路由返回 404 是不同问题。2. 应用工厂
不要在
main.py中读取几十个环境变量,再逐个创建中间件、数据库和模型。应用工厂可以把组装过程集中起来:settings参数允许测试显式传入配置;正常启动则调用get_settings()。这比在测试中修改全局环境变量后重新导入整个模块更可控。app.state.settings把当前配置挂在应用实例上,适合需要从Request找到应用资源的依赖。它不是让所有业务代码直接访问全局状态的理由,业务服务仍应通过构造参数接收自己需要的配置。Settings 可以在进程中缓存:
缓存后,同一 worker 进程只读取和校验一次配置。部署多个 worker 时,每个进程都有自己的 Settings 和资源,Python 内存不会跨进程共享。
修改
.env或 TOML 后,缓存对象不会自行变化。生产环境应重启或滚动更新应用,而不是尝试在请求中清除缓存。3. 依赖
FastAPI 依赖可以把 Settings 提供给路由:
get_settings()负责在创建应用时读取配置,get_current_settings()则负责把这个已经确定的对象交给路由。名称看起来相近,但职责不同。这样测试向应用工厂传入 Settings 后,路由、中间件和 lifespan 都会看到同一个实例。路由只声明需要配置,不负责读取配置文件:
真实接口不一定应该公开模型名称和环境信息。这里用于演示依赖传递;生产健康检查只返回排障所需的非敏感字段。
依赖注入的价值不是少写一行导入,而是让对象来源明确且可以替换。对于 Settings,应用工厂参数就是最直接的替换入口:
这里的
test_settingsfixture 会在第 6 节定义。模型客户端等资源依赖仍然可以使用app.dependency_overrides替换,但覆盖完成后应及时清空,避免影响其他测试。如果路由自己调用
Settings(),测试就很难替换来源,还可能在每次请求中重复读取文件。4. 生命周期
Settings 是轻量配置对象,数据库连接池、异步 HTTP 客户端和 LangGraph checkpointer 则是需要创建与关闭的长期资源。它们适合放进 FastAPI lifespan,也就是从应用启动到应用停止的这段生命周期:
create_lifespan()是一个工厂:外层函数先接收 Settings,内层lifespan()再由 FastAPI 调用。yield之前负责创建资源,yield之后会按照async with的逆序自动关闭资源。如果某个资源在
yield之前创建失败,应用不会开始接收请求,已经进入的async with也会负责清理。这比先启动服务、等到请求到来后才发现核心资源不可用更容易排查。示例中的
create_model()、create_graph()和open_checkpointer()是项目自己的工厂函数,后续 LangChain/LangGraph 文章会实现。其中,open_checkpointer()应返回异步上下文管理器,让内存和 PostgreSQL 两种实现拥有统一的打开、关闭方式。不能只把 checkpointer 传给编译图后,再假设可以从图对象中取回并关闭它。最后,把这个 lifespan 工厂交给应用工厂:
正常启动没有传入
lifespan时,工厂会调用create_lifespan(current);测试则可以传入不连接外部服务的生命周期。这样应用工厂、路由依赖、中间件和 lifespan 始终使用同一份 Settings。这里选择在生产环境关闭 OpenAPI Schema 和两个文档页面,但这属于产品策略,不是固定答案。即使关闭这些入口,接口本身仍需认证、授权和输入校验,不能把隐藏文档当作安全措施。5. 资源依赖
请求需要使用生命周期资源时,可以通过依赖从
request.app.state读取:路由获得的是抽象模型接口:
ChatRequest继承BaseModel,所以 FastAPI 会把 JSON 请求体解析到payload,并在调用模型前检查问题是否为空、长度是否超出当前项目限制。如果直接把question: str写在函数参数中,它默认会被当作查询参数,而不是 JSON 请求体。资源范围需要区分:
thread_id不能因为数据库 Engine 可以复用,就把一个可变的数据库 Session 也放到全局。
thread_id也不能设置成全进程共享值,否则不同用户的对话状态可能混在一起。配置决定如何创建资源,资源自身还要遵守正确生命周期。6. 服务与测试
第 4 节的完整应用工厂已经根据
settings.app.environment设置标题、调试模式和文档地址。debug只在development环境开启,不能简单写成not is_production,否则test和staging也会意外进入调试模式。CORS 同样要把 Settings 中的值真正传给中间件:
上一篇的
CorsSettings只声明了来源和请求方法,因此这里为请求头和凭据使用明确的安全值。如果项目需要让这两项随环境变化,应先把allow_headers、allow_credentials同时加入 Settings 模型和 TOML,再从settings.server.cors读取。配置项只有传入真实组件才会生效,仅在 TOML 中写下allow_origins不会自动改变浏览器跨域行为。测试与排查
应用工厂允许测试直接构造 Settings:
_env_file=None会关闭.env读取;各个必填分组也都显式提供测试值,因此不会只覆盖两个字段却意外沿用生产密钥。第 42 篇自定义的 TOML 来源仍会参与收集,但初始化参数优先级最高。若配置测试需要完全隔离 TOML,应为测试定义专用 Settings 子类或测试配置文件,这部分会在后续测试章节展开。empty_lifespan让只测试应用元数据或普通路由的用例不连接真实模型和数据库。需要验证资源型路由时,应改用能够写入app.state.model等假资源的测试 lifespan,或覆盖对应的 FastAPI 依赖。创建
TestClient时,如果要让 lifespan 真正运行,应把它作为上下文管理器使用。下面运行的是 fixture 中注入的empty_lifespan,不会连接外部服务:如果测试必须修改环境变量,应在修改后清除缓存,并在测试结束时恢复环境。pytest 的
monkeypatch可以管理这个过程:monkeypatch会在测试结束时恢复环境变量,finally则保证即使断言失败也会清除 Settings 缓存。7. 在线实验
让公开配置真正控制应用标题、调试模式、文档地址与 lifespan,观察同一 Settings 如何被工厂和路由共同使用。
下面的代码直接读取工作区的原始文件,文章与下载项目使用同一份来源:
打开在线案例,点击运行,等待环境就绪,再发送默认
GET /runtime-info。本篇不需要模型密钥或外部服务。默认 title 为配置驱动的 FastAPI,environment=development、debug=true、docs_url="/docs"、ready=true。日志先记录生命周期启动,请求时读取的是应用已保存的 Settings。
把 environment 改为 production 并重新运行,debug 变为 false,docs_url 变为 null;此时用在线请求面板直接访问 /runtime-info,或者本机 curl 请求,不能继续依赖 /docs。配置在创建应用时读取,不随每次请求改写;本篇生命周期只管理本地状态,不创建模型、数据库或后台线程。
下载项目后,在项目目录执行:
再通过
http://127.0.0.1:8000/docs发送同一请求。本机示例使用 Python 3.12,浏览器由共享 Pyodide 环境执行;本篇代码只使用两者都有的能力。