📚 课程目录第4章 FastAPI框架入门

4. FastAPI 框架入门：安装、路由与自动文档

FastAPI 是一个现代、高性能的 Python Web 框架，专为构建 API 而生。它基于 Starlette（异步网络能力）和 Pydantic（数据校验与序列化），天然支持异步编程，并自动生成符合 OpenAPI 规范的交互式文档。在精算模型部署场景中，FastAPI 的低延迟特性与自动校验能力，使其成为将精算引擎暴露为 RESTful 服务的首选框架。

4.1 FastAPI 安装与 Hello World

FastAPI 的安装极为简洁，推荐使用 pip 在虚拟环境中进行。生产环境还需安装 ASGI 服务器（如 Uvicorn）以运行应用。

安装命令：

pip install fastapi uvicorn

验证安装：python -c "import fastapi; print(fastapi.__version__)"

以下是一个完整的 Hello World 应用，演示了 FastAPI 的最小化启动流程：

# main.py
from fastapi import FastAPI

app = FastAPI(title="精算模型 API", version="1.0.0")

@app.get("/")
async def root():
    return {"message": "Hello, Actuarial World!"}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

启动服务：python main.py，访问 http://127.0.0.1:8000 即可看到 JSON 响应。

关键点：FastAPI 应用实例 app 是核心入口；@app.get("/") 装饰器将函数绑定到 HTTP GET 方法及根路径；异步函数 async def 并非强制，但推荐用于 I/O 密集型精算计算。

4.2 路由与请求响应模型

路由（Route）是 URL 路径与处理函数之间的映射。FastAPI 支持路径参数、查询参数、请求体等多种数据来源，并通过类型注解自动完成校验与转换。

4.2.1 路径参数与查询参数

参数类型	URL 示例	函数签名	说明
路径参数	`/models/{model_id}`	`async def get_model(model_id: int)`	从 URL 路径中提取，自动类型转换
查询参数	`/models?version=2.0`	`async def list_models(version: str = "1.0")`	从 URL 问号后提取，可设置默认值
请求体	POST `/calculate`	`async def calculate(data: InputSchema)`	通过 Pydantic 模型接收 JSON 数据

示例代码：

from fastapi import FastAPI, Query
from pydantic import BaseModel

app = FastAPI()

class PremiumInput(BaseModel):
    age: int
    sum_assured: float
    gender: str = "M"

@app.get("/models/{model_id}")
async def get_model(model_id: int, version: str = Query("1.0", description="模型版本号")):
    return {"model_id": model_id, "version": version}

@app.post("/calculate")
async def calculate_premium(data: PremiumInput):
    # 模拟精算计算
    premium = data.sum_assured * 0.05 * (1.1 if data.gender == "M" else 0.9)
    return {"premium": round(premium, 2)}

避坑提示：路径参数必须与 URL 中的变量名一致；查询参数若未提供默认值，则视为必填项，FastAPI 会自动返回 422 校验错误。

4.2.2 请求与响应模型

FastAPI 的请求-响应生命周期遵循以下流程：

接收请求：ASGI 服务器（Uvicorn）将 HTTP 请求解析为 ASGI Scope。
路由匹配：FastAPI 根据请求方法 + 路径查找对应的路径操作函数。
参数提取与校验：自动从路径、查询、请求头、请求体中提取参数，并通过 Pydantic 模型进行类型校验。
业务逻辑执行：调用路径操作函数，执行精算计算或模型推理。
响应序列化：函数返回值自动转换为 JSON（或指定响应模型），并设置 HTTP 状态码。

4.3 自动 API 文档生成

FastAPI 最突出的特性之一是零配置自动生成 API 文档。框架基于 OpenAPI 规范（原 Swagger）和 JSON Schema，自动从路由定义、Pydantic 模型、参数注解中提取元数据，生成交互式文档页面。

4.3.1 内置文档界面

启动应用后，FastAPI 默认提供两个文档入口：

文档类型	URL 路径	技术栈	特点
Swagger UI	`/docs`	Swagger UI + OAuth2	交互式测试面板，支持 Try it out 直接发送请求
ReDoc	`/redoc`	ReDoc	三栏式布局，适合阅读和打印
OpenAPI JSON	`/openapi.json`	纯 JSON	机器可读，可导入 Postman、Insomnia 等工具

4.3.2 文档内容来源

文档的丰富程度取决于开发者在代码中提供的元数据：

路径操作装饰器参数：summary、description、tags、response_description。
Pydantic 模型字段：Field(description=...)、Field(example=...)、Field(ge=0, le=100) 等约束。
查询参数注解：Query(description=..., deprecated=True)。
响应模型：response_model=OutputSchema 定义返回结构。

示例：为精算接口添加文档元数据

from fastapi import FastAPI, Query, Path
from pydantic import BaseModel, Field

app = FastAPI(title="精算定价 API", description="用于保险产品定价的精算模型接口", version="2.0.0")

class PricingInput(BaseModel):
    age: int = Field(..., ge=18, le=100, description="被保险人年龄（18-100）")
    sum_assured: float = Field(..., gt=0, description="保额（元）")
    smoking: bool = Field(False, description="是否吸烟")

class PricingOutput(BaseModel):
    premium: float = Field(..., description="计算所得保费")
    loading: float = Field(0.0, description="风险附加费")

@app.post("/pricing", summary="保费计算", description="根据年龄、保额、吸烟状态计算保费", 
          response_model=PricingOutput, tags=["定价"])
async def calculate_pricing(data: PricingInput):
    base = data.sum_assured * 0.03
    loading = base * 0.2 if data.smoking else 0.0
    return PricingOutput(premium=round(base + loading, 2), loading=round(loading, 2))

最佳实践：为每个接口添加 summary 和 tags，为每个模型字段添加 description 和 example，可使文档对业务人员和非技术用户更加友好。精算模型接口尤其需要明确参数单位与取值范围。

4.4 本章小结

通过本章学习，你已掌握 FastAPI 的核心入门技能：

安装与启动：使用 pip install fastapi uvicorn 搭建最小化 API 服务。
路由与参数：路径参数、查询参数、请求体三种数据来源的声明方式与自动校验机制。
请求-响应生命周期：从 HTTP 请求到业务逻辑再到 JSON 响应的完整链路。
自动文档：零配置获得 Swagger UI、ReDoc 和 OpenAPI JSON，大幅降低前后端协作成本。