跳到主要内容
Ed. notes

应用骨架:配置、启动与接口契约

长文 · 2026-11-11 · 合集第 4 / 11 篇

  • 配置
  • FastAPI
  • API设计
第 4 / 11 篇 · 查看全部章节 → 当前:应用骨架:配置、启动与接口契约

结论

后端把配置当成启动契约,而不是请求期的临时查询: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 和草稿规则怎样与前端保持一致。