应用骨架:配置、启动与接口契约
结论
后端把配置当成启动契约,而不是请求期的临时查询:load_settings() 在 FastAPI 的 lifespan 里先执行,基础配置缺失时进程拒绝启动。请求进入后,Pydantic 负责输入校验,异常处理器负责把 422 / 500 收敛成固定 JSON,/health 单独报告数据库状态。
问题与设计
如果配置在每个请求里随手读,服务会带着坏配置启动,直到第一个请求才报错;入库命令和 Web 服务也可能各自读一套。输入校验和错误格式也一样:如果每个路由自己写,前端就得处理多种错误形状。
这里的职责划分是:
config.py:读取来源、类型转换、范围校验、必填项检查。lifespan:启动时执行一次,基础配置缺失直接让进程退出。- Pydantic model:请求体和字段约束,失败统一返回 422。
- exception handler:未处理异常统一返回 500,不泄露内部细节。
/health:单独探测数据库,失败返回 503。
关键代码
路径从代码文件推导,不依赖启动目录:
PROJECT_ROOT = Path(__file__).resolve().parents[2]
REPO_ROOT = PROJECT_ROOT.parent
DEFAULT_ENV_FILE = PROJECT_ROOT / ".env"
配置对象不可变:
@dataclass(frozen=True)
class Settings:
database_url: str
content_dir: Path
embedding_provider: str = "fake"
embedding_dimension: int = 384
embedding_batch_size: int = 32
chat_timeout_seconds: float = 60.0
rag_top_k: int = 5
rag_max_context_chars: int = 6000
rag_min_score: float = 0.0
来源优先级是 .env 先读、真实环境变量覆盖;ENV_FILE 可换配置文件。load_settings(env=...) 显式传入输入时不读文件,测试因此不受本机 .env 影响。
数值配置统一转换并检查范围:
rag_top_k=_int(values, "RAG_TOP_K", 5, minimum=1, maximum=10)
rag_min_score=_float(values, "RAG_MIN_SCORE", 0.0, minimum=0.0, maximum=1.0)
lifespan 在应用启动时执行一次:
@asynccontextmanager
async def lifespan(_app: FastAPI) -> AsyncIterator[None]:
load_settings()
yield
请求模型把约束放在类型旁边。对前端读者,可以把它当成运行时的 Zod schema:
class SearchRequest(BaseModel):
model_config = ConfigDict(str_strip_whitespace=True)
query: str = Field(min_length=1, max_length=500)
limit: int = Field(default=5, ge=1, le=20)
class ChatRequest(BaseModel):
query: str = Field(min_length=1, max_length=500)
history: list[HistoryMessage] = Field(default_factory=list, max_length=6)
top_k: int | None = Field(default=None, ge=1, le=10)
错误契约集中注册,路由不重复处理:
@app.exception_handler(RequestValidationError)
async def handle_validation_error(...):
return JSONResponse(status_code=422, content={
"error": {"code": "invalid_request", "message": "请求参数不合法"}
})
@app.exception_handler(Exception)
async def handle_unexpected_error(...):
logger.exception("未处理的异常", exc_info=error)
return JSONResponse(status_code=500, content={
"error": {"code": "internal_error", "message": "服务内部错误"}
})
健康检查只回答“服务能否连数据库”,不触发模型调用:
@app.get("/health")
def health(settings: Settings = Depends(get_settings)):
try:
with connect(settings.database_url) as conn:
count = conn.execute("SELECT count(*) FROM chunks").fetchone()[0]
except psycopg.Error:
return JSONResponse(status_code=503, content={
"status": "error",
"code": "database_unavailable",
"message": "数据库不可用",
})
return {"status": "ok", "chunks": count}
聊天模型缺失则单独降级:get_chat_model() 捕获 ConfigError 返回 None,/api/chat 返回 503 chat_unavailable;健康检查和检索继续可用。
验证
配置测试用显式输入验证默认值和错误:
embedding_provider='fake' embedding_dimension=384 rag_top_k=5
真实 embedding 缺少必需配置:EMBEDDING_BASE_URL or LLM_BASE_URL, LLM_API_KEY, EMBEDDING_MODEL
EMBEDDING_DIMENSION 必须是整数,实际为 'many'
接口与配置测试一起运行:
uv run pytest tests/test_api.py tests/test_config.py -q
27 passed in 2.07s
测试覆盖空 query、越界 limit、非法 history、chat_unavailable、未知异常不泄露内部信息,以及 /health 在数据库不可用时返回 503。
边界
lifespan使用默认真实配置;测试里要用依赖覆盖或显式环境输入。- 统一错误格式只覆盖校验错误和未处理异常;业务上仍需为“功能未配置”“上游超时”定义专门错误码。
- 错误信息可以列变量名,不能输出变量值;Key 和数据库连接串不能进响应或日志。
/health只检查数据库,不检查模型服务;模型不可用时聊天错误在流里返回。.env是本地开发便利,不是生产密钥管理方案。
下一篇进入内容层:哪些 Markdown 能进入索引,slug 和草稿规则怎样与前端保持一致。