跳到主要内容

简介与安装

简介​

FastAPI 是一个用于构建 API 的现代、快速的 Web 框架，基于 Python 类型提示，并内置 OpenAPI（旧称 Swagger）文档生成。

本系列笔记基于以下环境整理，示例均已实测：

  • Python 3.13
  • FastAPI 0.141.1
  • Pydantic 2.13.4
  • Starlette 1.5.0
  • Uvicorn 0.52.1
提示

所有示例统一使用 Pydantic v2 写法（field_validator、model_config、model_dump*）。旧版写法（v1、on_event 等）以"历史写法/已废弃"标注保留，便于对照旧项目。

特性​

  • 性能良好：在 Python Web 框架中性能较好，支持异步协程。
  • 基于 Pydantic 模型，参数校验和类型提示更方便。
  • 支持依赖注入，便于代码复用。
  • 支持 WebSocket、后台任务、流式响应等。
  • 开箱即用的 OpenAPI（Swagger / ReDoc）文档。

技能图谱​

安装​

python -m pip install "fastapi[all]"

# 也可以只安装核心依赖，按需再装其它库
python -m pip install fastapi uvicorn

说明：

  • fastapi[all] 会附带 uvicorn、python-multipart（表单解析）、aiofiles（异步文件操作）、jinja2（模板）等常用依赖。
  • 表单/文件上传需要额外安装 python-multipart。
  • 渲染模板需要额外安装 jinja2。

Hello World​

# main.py
from fastapi import FastAPI
import uvicorn

app = FastAPI()


@app.get("/")
def index():
    return {"msg": "hello world"}


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

两种运行方式等价：

# 方式一：直接运行脚本（脚本内调用 uvicorn.run）
python main.py

# 方式二：用 uvicorn 命令启动，支持 --reload / --workers
uvicorn main:app --host 127.0.0.1 --port 8000 --reload

启动后：

  • Swagger 文档地址：http://127.0.0.1:8000/docs
  • ReDoc 文档地址：http://127.0.0.1:8000/redoc
  • OpenAPI JSON 地址：http://127.0.0.1:8000/openapi.json

uvicorn 常用参数​

参数说明
appFastAPI 的实例对象或 模块:app 字符串
host监听地址
port监听端口
--env-file环境变量配置文件
reload是否开启热重启，开发环境使用，生产环境慎开
workers工作进程数，默认为 1。多进程时注意定时任务、内存态数据会各自独立
--access-log是否输出访问日志，默认开启
注意

生产环境不要开启 --reload；多进程（--workers > 1）时，进程间的内存状态、后台定时任务互不共享，需要借助数据库/Redis 等外部机制协调（见 补充：基于 DB 的分布式锁）。

性能参考（wrk 压测）​

对上面的 Hello World 应用做了一次简单压测（6 线程、500 连接、30 秒）：

Running 30s test @ http://127.0.0.1:8000
  6 threads and 500 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency   155.60ms   16.76ms 227.92ms   71.30%
    Req/Sec   534.25    109.46   838.00     68.85%
  95940 requests in 30.10s, 12.99MB read
Requests/sec:   3187.74
Transfer/sec:    442.05KB

压测结果只代表本机环境下的参考值，实际性能取决于机器、路由数量、数据库等。

参考​