FastAPI 开发知识（第一篇）：从入门到核心基础

FastAPI 是一个现代、快速（高性能）的 Web 框架，用于构建 API，基于 Python 3.7+ 的标准类型提示。它提供了自动生成交互式文档、数据验证、依赖注入等开箱即用的功能，是构建 RESTful API 的理想选择。

本教程将分两篇深入讲解 FastAPI 的核心知识。第一篇将涵盖 FastAPI 的安装、开发环境配置、第一个应用、自动 API 文档、路由基础、请求与响应处理，以及如何使用 Pydantic 模型进行数据验证和序列化。通过详细的实例，帮助你快速掌握 FastAPI 的基本使用。

1. FastAPI 简介

FastAPI 的主要特点包括：

• 快速：与 Node.js 和 Go 相当的性能（归功于 Starlette 和 Pydantic）。
• 快速编码：将开发速度提升约 200% 到 300%。
• 更少的 Bug：减少约 40% 的人为错误。
• 直观：强大的编辑器支持，自动补全随处可用。
• 简单：设计易于使用和学习，减少阅读文档的时间。
• 简短：代码重复最小化，每个参数声明可以完成多个功能。
• 健壮：生产可用级别的代码，还有自动生成的交互式文档。
• 基于标准：完全兼容 API 的开放标准：OpenAPI（以前称为 Swagger）和 JSON Schema。

2. 安装 FastAPI 和 Uvicorn

FastAPI 本身是一个框架，实际运行需要 ASGI 服务器，如 Uvicorn 或 Hypercorn。这里我们使用 Uvicorn。

2.1 安装 FastAPI

pipinstallfastapi

2.2 安装 ASGI 服务器

pipinstalluvicorn[standard]

[standard]会安装一些推荐的额外依赖（如uvloop等），以提高性能。

3. 开发环境配置（VSCode 推荐）

虽然任何编辑器都可以编写 FastAPI 应用，但 VSCode 配合 Python 插件可以提供极佳的自动补全和类型检查体验。

1. 安装 Python 插件（由 Microsoft 提供）。
2. 打开项目文件夹，创建一个 Python 虚拟环境并激活：

   python-mvenv venvsourcevenv/bin/activate# Linux/Macvenv\Scripts\activate# Windows

3. 在 VSCode 中按Ctrl+Shift+P，选择 “Python: Select Interpreter”，然后选择虚拟环境中的 Python。
4. 安装上述依赖到虚拟环境中。

现在，一切就绪，可以开始编写第一个 FastAPI 应用了。

4. 第一个 FastAPI 应用

创建一个文件main.py，写入以下代码：

fromfastapiimportFastAPI app=FastAPI()@app.get("/")defread_root():return{"message":"Hello, FastAPI!"}

4.1 运行应用

在终端执行：

uvicorn main:app--reload

• main：模块文件名（即main.py）。
• app：FastAPI 实例的名称（在main.py中创建的app对象）。
• --reload：开发模式下启用，代码修改后自动重启服务器。

看到输出如下，表示启动成功：

INFO: Uvicorn running on http://127.0.0.1:8000 INFO: Application startup complete.

4.2 测试 API

打开浏览器访问http://127.0.0.1:8000/，你将看到 JSON 响应：

{"message":"Hello, FastAPI!"}

恭喜！你已经成功创建并运行了第一个 FastAPI 应用。

5. 交互式 API 文档

FastAPI 自动生成两种交互式 API 文档，无需额外配置。

5.1 Swagger UI

访问http://127.0.0.1:8000/docs，你会看到一个自动生成的 Swagger UI 界面，列出了所有可用的路径操作（本例中只有GET /）。你可以直接在界面上测试 API。

5.2 ReDoc

访问http://127.0.0.1:8000/redoc，可以看到另一种风格的文档，同样由 FastAPI 自动生成。

这些文档不仅美观，而且完全基于 OpenAPI 规范，可以导出为 JSON 或 YAML 文件。

6. 基本路由

FastAPI 通过装饰器定义路由，支持常见的 HTTP 方法：@app.get(),@app.post(),@app.put(),@app.delete()等。

6.1 路径参数

你可以在路径中使用 Python 格式的字符串参数，FastAPI 会自动将其作为路径参数传递给函数。

@app.get("/items/{item_id}")defread_item(item_id:int):return{"item_id":item_id}

• item_id的类型声明为int，FastAPI 会自动验证并转换为整数。如果传入非整数，将返回一个自动的错误响应。

6.2 查询参数

当你在函数中声明的参数不是路径参数时，它们会自动被解释为查询参数。

fake_db=[{"name":"Foo"},{"name":"Bar"},{"name":"Baz"}]@app.get("/items/")deflist_items(skip:int=0,limit:int=10):returnfake_db[skip:skip+limit]

访问/items/?skip=1&limit=2将返回从索引 1 开始的 2 个条目。查询参数支持默认值和可选值（通过Optional或默认值None）。

6.3 路径参数和查询参数混合

@app.get("/items/{item_id}")defget_item(item_id:int,q:str=None):return{"item_id":item_id,"q":q}

这里item_id是路径参数，q是可选查询参数。访问/items/5?q=test将返回{"item_id":5,"q":"test"}。

7. 请求和响应

7.1 请求体（Request Body）

当需要接收 JSON 数据（例如 POST、PUT 请求）时，可以使用 Pydantic 模型来声明请求体（将在下一节详细讲解），也可以直接使用fastapi.Request对象获取原始请求，但通常推荐使用 Pydantic 模型。

7.2 响应模型

你可以通过response_model参数指定响应数据的结构，FastAPI 会自动进行数据过滤、转换和文档生成。

frompydanticimportBaseModelclassItem(BaseModel):name:strprice:float@app.post("/items/",response_model=Item)defcreate_item(item:Item):# 这里可以保存到数据库等操作returnitem# 直接返回 item，FastAPI 会按照 Item 模型序列化

7.3 自定义响应状态码

使用status_code参数或直接返回Response对象。

fromfastapiimportstatus@app.post("/items/",status_code=status.HTTP_201_CREATED)defcreate_item(item:Item):# ...returnitem

7.4 直接返回 Response 对象

如果你需要完全控制响应，可以直接返回Response或其子类，如JSONResponse,HTMLResponse等。

fromfastapi.responsesimportJSONResponse@app.get("/custom")defcustom_response():returnJSONResponse(content={"message":"custom"},status_code=200)

8. Pydantic 模型

Pydantic 是 FastAPI 的核心依赖，用于数据验证和设置管理。它利用 Python 类型提示进行运行时数据验证，并提供了强大的序列化和反序列化能力。

8.1 定义模型

创建一个继承自BaseModel的类，并声明字段类型。

frompydanticimportBaseModelfromtypingimportOptionalclassItem(BaseModel):name:strdescription:Optional[str]=Noneprice:floattax:Optional[float]=None

• Optional[str] = None表示该字段可选，默认为None。
• 如果提供了tax，则必须为float，否则可以省略。

8.2 在路径操作中使用模型

作为请求体：

@app.post("/items/")defcreate_item(item:Item):# item 已经是经过验证的 Item 实例return{"item_name":item.name,"item_price":item.price}

作为响应模型：

@app.get("/items/{item_id}",response_model=Item)defread_item(item_id:int):# 假设从数据库获取了 item_dataitem_data={"name":"Foo","price":50.2}returnitem_data# 字典也会自动转换为 Item 模型

8.3 数据验证

Pydantic 会自动验证传入的数据：

• 类型不匹配时，返回 422 错误，包含详细的验证信息。
• 可以使用字段约束，如Field(..., max_length=10)或使用constr,conint等。

frompydanticimportBaseModel,FieldclassItem(BaseModel):name:str=Field(...,max_length=10)# ... 表示必填price:float=Field(...,gt=0)# 大于 0

8.4 嵌套模型

Pydantic 模型可以嵌套，非常适合表示复杂的数据结构。

classImage(BaseModel):url:strname:strclassItem(BaseModel):name:strprice:floatimage:Image# 嵌套模型tags:list[str]=[]# 类型为字符串列表

请求体 JSON 示例：

{"name":"Foo","price":42.0,"image":{"url":"http://example.com/foo.jpg","name":"Foo Image"},"tags":["food","discount"]}

8.5 验证错误处理

FastAPI 会自动捕获 Pydantic 的验证错误，并返回一个包含错误详情的 422 响应。你可以在应用中全局处理这些错误，但默认行为已经足够友好。

总结

在第一篇教程中，我们学习了：

• FastAPI 的安装和开发环境配置。
• 如何创建第一个 FastAPI 应用并运行。
• 自动生成的交互式 API 文档。
• 基本路由：路径参数和查询参数。
• 请求和响应的基本处理，以及状态码定制。
• Pydantic 模型的定义、使用和数据验证。

这些是构建任何 FastAPI 应用的基础。在下一篇教程中，我们将深入探讨更高级的主题，包括路径操作依赖项、表单数据、文件上传、中间件、数据库集成以及安全性等内容。敬请期待！