Python FastAPI 框架入门：从零搭建你的第一个高性能 API 服务

前言

前两篇文章我们分别介绍了"微框架" Flask 和"全家桶"框架 Django，今天来聊聊近几年异军突起的后起之秀------FastAPI。

如果说 Flask 追求简洁灵活、Django 追求功能齐全，那 FastAPI 的关键词就是**"快"------这个"快"是双重含义：一是 开发效率快**（代码补全友好、自动生成接口文档、错误提示清晰），二是运行性能快（基于异步框架 Starlette 和数据验证库 Pydantic，性能可以媲美 NodeJS 和 Go）。

正因为这些特点，FastAPI 自 2018 年发布以来迅速被大量互联网公司和 AI 团队采用，尤其是在构建 API 服务、微服务、AI 模型接口这类场景中，FastAPI 几乎已经成为 Python 生态里的首选。

本文将带你了解 FastAPI 的核心概念，并通过一个完整的小例子，让你在几分钟内跑起属于自己的第一个 FastAPI 服务，顺便体验一下它引以为傲的"自动接口文档"功能。

一、FastAPI 是什么？

FastAPI 由 Sebastián Ramírez 开发，构建在两大基石之上：

Starlette ：一个轻量级的 ASGI（异步网关接口）框架，负责底层路由与请求处理，天然支持异步（async/await）
Pydantic：一个基于 Python 类型注解的数据校验库，负责请求参数、请求体、响应体的自动校验与序列化

得益于这两位"地基选手"，FastAPI 天生自带异步能力和强类型校验，再加上它对 Python 类型注解（Type Hints）的充分利用，写出来的代码既是业务逻辑，也是接口文档和数据校验规则------真正做到"一份代码，三份价值"。

FastAPI 的主要特点

高性能：基于异步 ASGI，官方基准测试中性能接近 NodeJS/Go，是 Python Web 框架中最快的行列之一
自动生成交互式 API 文档：无需任何额外配置，启动服务后自动生成 Swagger UI 和 ReDoc 两套文档，可以直接在浏览器里测试接口
基于类型注解的数据校验：用 Python 原生的类型提示（Type Hints）定义参数类型，FastAPI 自动完成校验、转换、报错
开发效率高：IDE 智能提示完善，减少调试时间，官方宣称能减少 200%~300% 的人为错误
原生支持异步 ：async def 视图函数可以轻松应对高并发 I/O 密集型场景（如调用数据库、外部接口、AI 模型推理等）
标准兼容：完全基于 OpenAPI（Swagger）和 JSON Schema 标准，方便与前端、其他系统对接

三大框架简单对比

维度	Flask	Django	FastAPI
定位	微框架	全功能框架	现代高性能 API 框架
异步支持	需额外配置	逐步支持中	原生支持（ASGI）
数据校验	需手动或借助扩展	表单/序列化器	内置（基于 Pydantic），自动化程度最高
接口文档	需手动维护或引入扩展	需借助 DRF 等扩展	自动生成，开箱即用
学习曲线	平缓	较陡	平缓（但依赖类型注解思维）
适合场景	小型项目、原型	中大型完整系统	API 服务、微服务、AI 接口

二、环境准备

同样建议先创建虚拟环境：

bash 复制代码

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# macOS / Linux:
source venv/bin/activate

安装 FastAPI 以及一个 ASGI 服务器 uvicorn（用于运行服务，类似 Flask 内置的开发服务器）：

bash 复制代码

pip install fastapi "uvicorn[standard]"

三、动手实践：第一个 FastAPI 应用

1. 最小可运行示例

新建 main.py：

python 复制代码

from fastapi import FastAPI

# 创建 FastAPI 应用实例
app = FastAPI(title="我的第一个 FastAPI 服务")


@app.get("/")
def read_root():
    return {"message": "Hello, FastAPI!"}

在终端启动服务：

bash 复制代码

uvicorn main:app --reload

main:app 表示"main.py 文件里名为 app 的对象"
--reload 表示开启热重载，代码修改后自动重启，方便开发调试

看到类似输出即启动成功：

复制代码

INFO:     Uvicorn running on http://127.0.0.1:8000

打开浏览器访问 http://127.0.0.1:8000，会看到返回的 JSON：

json 复制代码

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

更神奇的是，直接访问 http://127.0.0.1:8000/docs，你会看到一个完全自动生成、可交互测试的 Swagger 接口文档页面------这是 FastAPI 最出圈的功能之一，几乎不需要额外写一行文档相关的代码。

2. 进阶一点：路径参数 + 请求体校验 + 数据模型

我们用一个"简易图书管理接口"来演示 FastAPI 的核心亮点：用类型注解自动完成参数校验。

python 复制代码

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field
from typing import Optional

app = FastAPI(title="图书管理 API 示例")

# 用 Pydantic 定义请求体的数据结构与校验规则
class Book(BaseModel):
    title: str = Field(..., min_length=1, max_length=50, description="书名")
    author: str = Field(..., description="作者")
    price: float = Field(..., gt=0, description="价格，必须大于 0")
    published: Optional[bool] = Field(default=True, description="是否已出版")


# 模拟一个内存数据库
books_db: dict[int, Book] = {}
next_id = 1


@app.get("/books")
def list_books():
    """获取所有图书列表"""
    return books_db


@app.get("/books/{book_id}")
def get_book(book_id: int):
    """根据 ID 查询单本图书，book_id 会被自动校验为整数类型"""
    if book_id not in books_db:
        raise HTTPException(status_code=404, detail="图书不存在")
    return books_db[book_id]


@app.post("/books", status_code=201)
def create_book(book: Book):
    """新增一本图书，请求体会自动按照 Book 模型进行校验"""
    global next_id
    books_db[next_id] = book
    result = {"id": next_id, **book.model_dump()}
    next_id += 1
    return result


@app.delete("/books/{book_id}")
def delete_book(book_id: int):
    """删除指定图书"""
    if book_id not in books_db:
        raise HTTPException(status_code=404, detail="图书不存在")
    del books_db[book_id]
    return {"message": f"图书 {book_id} 已删除"}

运行 uvicorn main:app --reload 后，打开 http://127.0.0.1:8000/docs，你会看到 4 个接口（GET 列表、GET 详情、POST 新增、DELETE 删除）已经自动生成好了，并且每个接口的参数、字段类型、说明文字都清清楚楚。可以直接在网页上点击"Try it out"测试：

调用 POST /books，传入：
json 复制代码
```
{
  "title": "Python编程：从入门到实践",
  "author": "埃里克·马瑟斯",
  "price": 89.5
}
```
会返回新增成功的图书数据（包含自动生成的 id）。
如果故意传一个负数价格，比如 "price": -10，FastAPI 会自动返回 422 错误，并清楚地告诉你是 price 字段"必须大于 0"，完全不需要自己写校验逻辑。

3. 代码要点解析

@app.get() / @app.post() / @app.delete()：对应 HTTP 方法的路由装饰器，语义比 Flask 的统一 @app.route() 更清晰。
book_id: int：路径参数直接写类型注解，FastAPI 会自动完成字符串到整数的转换和校验，如果传入非数字会自动返回错误提示。
class Book(BaseModel)：这是 Pydantic 模型，用来描述请求体的结构。字段类型、是否必填（... 表示必填）、取值范围（gt=0 表示大于 0）都在这里声明，FastAPI 会自动完成解析、校验、报错的全部工作。
raise HTTPException(status_code=404, detail="...")：手动抛出 HTTP 错误的标准写法，会被自动转换为对应状态码的 JSON 错误响应。
视图函数直接 return 字典或 Pydantic 模型，FastAPI 会自动序列化成 JSON------这一点和 Flask 类似，但 FastAPI 还会根据返回类型自动生成对应的响应文档结构。
异步支持 ：上面例子里用的是普通 def，如果换成 async def，配合 await 调用数据库、HTTP 客户端等异步库，就能获得更高的并发处理能力，非常适合 I/O 密集型场景。

四、常用生态一览

库/工具	用途
Pydantic	数据校验与序列化（FastAPI 的核心依赖）
SQLAlchemy / SQLModel	数据库 ORM（SQLModel 由 FastAPI 作者开发，与 Pydantic 无缝衔接）
Uvicorn / Gunicorn	ASGI 服务器，生产环境常用 Gunicorn + Uvicorn Worker 组合
Alembic	数据库迁移工具
python-jose / passlib	JWT 认证、密码加密
pytest + httpx	接口自动化测试

五、总结

通过本文，我们了解了：

FastAPI 是一个基于 Starlette（异步）和 Pydantic（数据校验）构建的现代 Python API 框架，兼顾高性能与高开发效率；
只需几行代码即可启动服务，并自动获得一份可交互测试的 Swagger 接口文档，这是它区别于 Flask、Django 最直观的亮点；
通过 Python 类型注解和 Pydantic 模型，请求参数、请求体的校验几乎"零代码"完成，大幅减少手写校验逻辑和相关 bug；
原生支持异步（async/await），非常适合高并发的 API 网关、微服务、AI 模型推理接口等场景。

如果你的项目核心诉求是"对外提供 API 接口"（不管是给前端用，还是给其他系统调用，或是给 AI 模型做服务化封装），FastAPI 大概率会是目前最顺手的选择；而如果你需要的是传统的服务端渲染网站、内容管理后台，Django 依然更有优势；如果只是想写点轻量的小工具，Flask 依然值得考虑。三者并不是互相替代的关系，理解各自的定位，才能在实际项目中做出更合适的技术选型。

至此，Flask、Django、FastAPI 三大 Python Web 框架的入门系列就完结啦，后续我会挑几个方向继续深入，比如 FastAPI + SQLModel 做完整的增删改查项目、JWT 用户认证、Docker 容器化部署等，欢迎关注～

参考资料

FastAPI 官方文档：https://fastapi.tiangolo.com/
Pydantic 官方文档：https://docs.pydantic.dev/
Starlette 官方文档：https://www.starlette.io/