FastAPI 是什么、为什么首选它

0030 秒速览：三句话，和你的第一个动作

读完这篇你能做到两件事：① 用一句人话说清 FastAPI 是什么、它和 Flask / Django（Python 里另外两个做网站和接口的常用工具）差在哪；② 判断「首选 FastAPI」这句话对你手上那个项目到底成不成立——包括它在什么条件下不成立。

如果只记三句话

接下来 60 秒：你的第一个动作

打开终端，粘这三行（第一行是检查版本，第二行是装包，第三行是起服务）：

python3 --version
uv add "fastapi[standard]"
uv run fastapi dev

终端会打印出一个 http://127.0.0.1:8000/docs 的地址。把它粘进浏览器——你会看到一个能直接点、能直接试的接口文档页。这一步值的不是那三行命令，是你亲眼看到「文档不是我写的，是它自己长出来的」。完整走查（包括怎么故意让它报错）在 §06。

关键数字（先有个量级感）

01先搞清楚一件事：FastAPI 名字里的「API」到底是什么

要理解 FastAPI，先得有一个「接口」的准确画面。这里用一个你一定经历过的场景。

接口就是餐厅的点单窗口

你去一家餐厅，不可能冲进后厨自己炒菜。你走到点单窗口，照着菜单说「一份宫保鸡丁，微辣少盐」，然后拿号、坐下等，最后从窗口把菜接走。

这个窗口就是接口（英文 API，全称「应用程序编程接口」——这个名字很唬人，但它描述的正是这件事：两个东西之间约定好的一个交界口）。

把它逐样对上，你就不需要再记任何新词：

为什么以前跟开发「对接口」，对的就是这个

你大概经历过这种场面：开发说「接口文档发你了，你按这个调」，然后你打开一个密密麻麻的网页，上面写着地址、参数、返回示例。那个网页就是这个窗口的菜单，而FastAPI 最出名的能力之一，就是让这份菜单自动生成。这一点在 §03 展开。

先记住一句：接口是一个「交界口」，不是一个「系统」。这句话会在 §07 变成你判断「该不该用 FastAPI」的第一把尺子。

02FastAPI 是什么：一句话，和它的四个「不是」

概念类的名词，最快搞懂的办法是先划掉它不是什么。

那它是什么

这句话里有两个词要拆开，拆完就没有生词了。

「框架」是什么，为什么不干脆直接写

框架就是一套已经搭好的骨架和规矩。回到餐厅：你可以从零开始盖一间厨房、砌灶台、定菜单格式、设计订单纸条；也可以租一个已经盖好的厨房，里面灶台、出菜口、洗碗池都到位了，你只需要决定「有人点宫保鸡丁时该怎么做」。

框架就是那个租来的厨房。它的价值在于：那些每道菜都要用的东西（窗口、菜单格式、订单纸条的格式），它已经做好且做了上千遍；你只写你这个项目独有的那一部分。代价是你要按它的规矩来——灶台的位置不能自己挪。

「类型标注」是什么，为什么它是 FastAPI 的地基

类型标注就是你在给一个名字起名的时候，顺手注明它装的是「文字」还是「数字」。比如你写「订单号」，你同时说明「这里的订单号是一个数字」。这在 Python 里是一行很短的写法，不需要学新语言。

这看着像废话，但对机器不是。因为一旦你注明了「订单号是数字」，FastAPI 就能替你做到三件事：检查每一单的订单号是不是真的数字；把这件事写进说明书；以及检查通过后把它交给你时，确认它已经是数字而不是一串文字。你只说了一遍，三件事一起办。

这也解释了它名字里的一半：Fast。它有两层意思，多数人只看到一层——

如果只能带走一句：FastAPI = 用 Python 自带的「注明类型」这个动作，换来自动检查 + 自动说明书 + 自动格式转换。你付的是「多写几个字」，换回来的是三件本来要手工做、而且一定会忘掉其中一件的事。

03如果没有它，你要自己做哪三件苦工

「它解决什么问题」这个问题，最好的问法是反过来问：不用它，会发生什么？答案是三件苦工，其中第三件是最要命的。

苦工一：从一堆乱七八糟的输入里，把你要的东西一个个抠出来

顾客递进来的订单纸条不会那么规矩。订单号可能是数字、可能是文字、可能压根没填、可能是空的、可能多写了一个字段。如果没有人替你在窗口做检查，那这段检查代码就要你自己写——而且要在每一个接口里写一遍。

苦工二：判断每一格填得对不对，错了还要组织一句错误说明

「这个字段必须是数字」「这个必须是 1 到 100 之间」「这个字段没填就默认 10」。这些规则要一条条写下来（这种「按规矩逐格核对」的活，行业里叫校验），还要决定：填错了到底回什么？回一句人话，还是一堆英文报错？

苦工三（最要命）：写一份和代码永远一致的说明书

前两件苦工，累但看得见。第三件是隐形杀手：你要手工写一份接口文档，而且以后每次改代码，都要记得回来改文档。

人一定会忘。于是最常见的场景是：文档上写着这个字段可以不填，实际上代码早就改成必填了。前端同事照着文档写，一调就报错，然后大家花半天找原因——找的不是 bug，是过期文档。

这三件苦工，它分别怎么接走

04拆开看：真正干活的是三层，FastAPI 只是最上面那层

这一节是全文最「技术」的一节，但它回答两个你一定会遇到的问题：为什么它说自己快？以及，那句「快」到底在夸谁？

三层套娃

这个结构推出一个结论，它会让一句流行话当场缩水

既然 FastAPI 建在 Starlette 之上、Starlette 又建在 Uvicorn 之上，那就有一个绕不过去的数学事实：最上面那层不可能比下面那层快。每多一层，就多一层开销。

这不是本文的推测，是 FastAPI 官方 benchmark 页面自己写的原话，大意是：独立 benchmark 显示，跑在 Uvicorn 上的 FastAPI 是最快的 Python 框架之一，但它只低于 Starlette 和 Uvicorn 本身；并且 Uvicorn 只是一个负责收发的程序、Starlette 只是负责分单的那一层，拿它们和 FastAPI 一起排名的榜，本身就不该直接读。

05装好、跑起来：三分钟看到那一页自动文档

理论到此为止。这一节只有动作。

python3 --version
# 需要看到 3.10 以上。本文校对时 FastAPI 的底线就是 3.10

# 官方安装方式（macOS / Linux 通用）
curl -LsSf https://astral.sh/uv/install.sh | sh

# Mac 上更省事的一种：Homebrew
brew install uv

# 如果你已经有 pipx
pipx install uv

uv init my-api
cd my-api
uv add "fastapi[standard]"

python3 -m venv .venv
source .venv/bin/activate
pip install "fastapi[standard]"

uv run fastapi dev

Serving at: http://127.0.0.1:8000
API docs:  http://127.0.0.1:8000/docs
Running in development mode, for production use: fastapi run

那三条输出分别是什么意思

怎么关掉它

在那个终端窗口按 Ctrl + C。这是所有这类本地服务的通用关法——看到「服务跑了、终端没反应了」，第一反应该是它正占着这个窗口。

06最小例子：6 行代码，到一个会拦错数据的接口

这是官方文档里的最小示例，一个字都没改（只加了中文注释）。把它存成 main.py，放在 §05 建的那个文件夹里。

第一版：6 行，一个「你好世界」接口

from fastapi import FastAPI

app = FastAPI()


# 这行的意思是：有人访问网站根地址 / 时，交给下面这个函数处理
@app.get("/")
async def root():
    return {"message": "Hello World"}

跑起来：

uv run fastapi dev

然后打开浏览器，依次访问这三个地址。三个都值得看一眼：

第二版：加一个参数，看它自动拦错

现在把代码换成下面这样——多了一个「把订单内容交给我」的数据结构，和一条带订单号的接口：

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


# 这是在声明：一份订单必须有两格——title 是文字，size 是数字
class Item(BaseModel):
    title: str
    size: int


# 路径里的 {item_id} 是占位符；写 int 就是说「这里必须是数字」
@app.get("/items/{item_id}")
def read_item(item_id: int, q: str | None = None):
    return {"item_id": item_id, "q": q}


@app.post("/items/")
def create_item(item: Item):
    return item

重启服务后（fastapi dev 会自动重启），做三件小事——这三件事就是「它到底帮你挡了什么」的现场：

{"item_id": 5, "q": "somequery"}

{
  "title": "towel",
  "size": "XL"
}

如果你打算让 AI 来写，把这段任务卡直接粘给它

这份模板的价值在于它把「验收条件」一起写进去了——AI 交活时你能照着核：

请用 FastAPI 给我做一个「查询订单状态」的接口，写在 main.py 里。

要求：
1. 用 Python 3.12 + FastAPI，依赖用 uv 管理；
2. 地址是 GET /orders/{order_id}，其中 order_id 必须是数字；
3. 订单号不存在时，返回 404 和一句中文说明，不要让它变成 500；
4. 用一个 Pydantic 模型描述返回内容：订单号、状态、金额、下单时间；
5. 每个处理函数上面写一行中文注释，说明「它收什么、回什么、什么情况会报错」；
6. 以后要接数据库，所以请把「查数据」那一段单独抽成一个函数，别混在接口里；
7. 请把 FastAPI 的版本号写死，不要用「最新版」。

拿到代码后，你用四个问题验收，全程不需要读懂代码：

07「为什么首选」这句话，适用范围在哪

这是全文最该慢慢读的一节。因为「首选」这两个字，是你在跟 AI 讨论技术方案时最容易照单全收、也最容易付代价的一句。

先把那句原话和它的口径摊开

官网首页的原始表述是这几句（本文照抄，附自己的翻译）：

• 「a modern, fast (high-performance), web framework for building APIs with Python based on standard Python type hints」——一个现代的、高性能的、用 Python 标准类型标注来构建接口的 Web 框架。
• 「Very high performance, on par with NodeJS and Go (thanks to Starlette and Pydantic). One of the fastest Python frameworks available.」——性能与 NodeJS 和 Go 相当，是最快的 Python 框架之一。
• 「Fast to code: Increase the speed to develop features by about 200% to 300%. *」——开发快，约 200% 到 300%。注意那个星号。

「首选」成立要同时满足四条

把这四条当成一张清单，逐条对你手上的项目打勾。缺任何一条，这句话对你就打了折扣。

给「首选」补上缺掉的主语

网上那句话完整的版本其实是这样，只是主语经常被省略：

它到底有多流行：三个数字，和每个数字的口径

「首选」这种说法需要流行度支撑。下面三个数字都是 2026-09-23 当天实测的，但每个数字能证明什么，比数字本身重要。

结论：这句话在你的决策里该怎么用

把它从「结论」降级成「一条信息」——它告诉你「在这个特定场景里，有一个被广泛验证过的默认选项」。你还需要自己补两个判断：我这个场景是不是那个场景（四条清单）；以及，我为了用它要额外付什么（§10）。

08该用 / 不该用：按你手上有的东西对号入座

这一节是场景索引——读第二遍时直接从你这行找起。

明确不该用的四种情况

09五个最容易信的说法，逐个对一遍

这五句话你大概率已经在别处见过。每一条都附上「它原本在说什么」和「你该怎么复述」。

误解 1：「它和 Node.js、Go 一样快」

它原本在说什么：官网原句是「性能与 NodeJS 和 Go 相当（得益于 Starlette 和 Pydantic）」。而官方 benchmark 页面自己补充了三件事：这是框架这一层的开销比较；FastAPI 不可能比它下面的 Starlette 快，Starlette 不可能比 Uvicorn 快；把负责收发的程序、只管分单的那一层、和完整框架混在同一张榜上排名，读法要特别小心。

你该怎么复述：「它自己额外加的开销很小。」

为什么这个误解很诱人：因为「快」是最好传播的一个词。而真实世界里你的应用慢，通常慢在数据库查询、调用外部服务（比如调用 AI 模型）、或者某个会卡住的写法上——这三处换任何框架都一样。把「框架快」当成「应用快」，会让你在真正该优化的时候看错地方。

误解 2：「加上 async 就一定更快」

它原本在说什么：官方文档给的规则完全不是「都用 async」，而是一张对照表（下一节展开）：你调用的库支持异步，就用 async def；不支持，就用普通的 def；不知道，就用 def。

你该怎么复述：「用哪种写法，取决于你调的库，不取决于你想不想快。写错了会拖慢整个服务，不是拖慢这一个请求。」

这条是本文认为最容易造成真实损失的一条，所以它在 §10 排第一。

误解 3：「有自动文档，就不用写接口文档了」

它原本在说什么：自动生成的那页，内容是「有哪些接口、每个接口收什么字段、什么类型、哪些必填」。

它给不了什么：这些字段为什么存在、什么业务场景下该传什么值、这个状态码（422、404、500 这类编号）背后的业务含义是什么、出错时用户该看到什么。这些是业务规则，机器推不出来。

你该怎么复述：「它消灭的是『文档和代码不一致』这个问题，不是『写文档』这件事。」

顺带说，这一条对你的实际影响是正面的：机器能生成的那部分不用你操心，你该负责的正好是它生成不了的那部分——业务规则。这是一个很舒服的分工。

误解 4：「网上都说首选，所以我就该用」

它原本在说什么：那句「首选」有主语和前提，见 §07 的四条清单。

你该怎么复述：「在 Python 里做接口，它是默认选项。我这件事是不是那个场景，得我自己核。」

为什么这个误解很诱人：因为它省事。「首选」听起来是一个已经替你做完的判断，而它其实只是一个起点。本文把整节 §07 给它，就是因为这四个字的省略成分太多了。

误解 5：「它和 Django 是一个位置上的东西，只是更新」

它原本在说什么：这两个东西不在一个位置上。Django 是一整套后端方案（页面、后台管理、账号权限、数据库工具都有，适合「建一个网站」）；FastAPI 是接口这一层的专用工具（适合「建一个数据服务」）。

你该怎么复述：「Django 是整套房子的装修方案，FastAPI 是一个特别好用的接活窗口。」

“更新”也不构成理由。Django 同样是活跃维护的项目，当前版本 6.1.1（2026-09-02 发布），FastAPI 是 0.141.1（2026-07-29 发布）——两者都在持续更新，只是各自解决的形状不同。

顺手放在一起的一个近亲，省得你以后混

10真上手之后才会知道的三件事

这一节的三件事，教程里通常不讲，但它们是「用起来之后」才会碰到的东西。

第一件：async def 还是 def——一条能让整个服务卡住的规则

先说结论，这是官方文档给的原话级规则：

为什么这条规则值得你这种不写代码的人也记住？因为写错的代价不对称。

（上面提到的「外部线程池」，你可以理解成另开几个窗口同时办事；而 async 那条通道更像一个窗口靠不停切换来同时应付很多人——一旦有个人在窗口前站着不动，后面的人全堵住。）

第二件：它省的是你的时间，不是你的服务器账单

「异步」这个词很容易让人得出一个推论：它更省资源，所以更省钱。真实情况比这复杂，有一个公开记录在案的例子。

这个案例对你有两重价值：

• 它是一手材料，不是二手转述——原文出自当事公司的工程博客，写清了时间、现象、他们怎么定位、以及业务后果。本文引它，是因为它同时展示了「异步服务」的真实失败形态。
• 它给出了一个反直觉的结论：异步架构的坑，往往不表现为「崩了」，而表现为「慢慢变贵」。而「变贵」恰好是你要盯的那张表——这也解释了为什么一个技术选型问题，最后会落到你的成本判断上。

第三件：它动得快，所以别让版本把你带走

这是「活跃维护」的另一面。三个可核对的事实：

落到做法上只有两条：

# 1. 装的时候把版本写死，别用「最新版」
uv add "fastapi[standard]==0.141.1"

# 2. 隔一段时间主动升一次：把用到的包按清单升到允许的最新版
uv sync

如果你不直接操作命令，就把这句话写进给 AI 的任务卡里（§06 那份模板的第 7 条已经写了）：「把版本号写死，并且每次改动前先告诉我你要动哪个包、从哪个版本到哪个版本。」——这样版本变动就从一个「悄悄发生的事」变成了一个你能看见的决定。

11一页纸：命令、地址、判断清单

命令速查

地址速查

「该不该用」三问

给 AI 的四句验收话

这四句是本文最可以直接抄走的东西——它们把「我看不懂代码」这个劣势，换成了「我问得出有明确答案的问题」这个优势：

1. 打开 /docs，把每个接口的地址、收什么、回什么，逐条念给我听。
2. 我故意传错一个字段的类型，你预计会返回什么？然后我们一起试一次。
3. 这个 async def 里的每个调用，都是原生支持 await 的库吗？有一个不是就改回 def。
4. 这次改动你动了哪些依赖、从哪个版本到哪个版本？请列出来。

12名词速查：见到它们时别当成什么用

这些词你在对接、看文档、问 AI 时都会撞见。第三列是本文认为最有用的一列——它告诉你这个词不该被当成什么。

98来源与证据边界

这篇里凡是「现在是多少」「当前叫什么」「谁说的」的判断，都来自下面这些页面，核对日期统一为 2026-09-23。

官方文档与官方数据（一手）

• fastapi.tiangolo.com — 首页 — 一句话定义、四大卖点、「性能与 NodeJS 和 Go 相当」的原句、200%–300% 与 40% 的估计及脚注说明「基于内部团队自测」、行业用户原话（Microsoft / Uber / Netflix / Cisco）、安装命令（§02、§05、§07、§09）
• fastapi.tiangolo.com — Benchmarks — 「最快的 Python 框架之一，只低于 Starlette 和 Uvicorn 本身」，以及三层结构为什么决定了上层不可能比下层快（§04、§09）
• fastapi.tiangolo.com — 并发与 async / await — 「def 会被放到外部线程池执行」「不知道就用 def」等官方规则；并发与并行的餐厅比喻也出自这一页（§09、§10）
• fastapi.tiangolo.com — First Steps — §06 那 6 行代码、/docs、/redoc、/openapi.json 三个地址、以及 uv run fastapi dev 的实际输出（§05、§06）
• fastapi.tiangolo.com — 处理错误 — 422 与校验错误回应的形态；§06 第二版示例里的模型出自这一页（§06、§10）
• fastapi.tiangolo.com — 特性列表 — 基于开放标准（OpenAPI 与描述数据格式的 JSON Schema）、两套默认文档界面（§03、§04）
• fastapi/fastapi — Release Notes — 移除 Python 3.8 支持（PR #14563，官方特别说明装 3.8 的机器只会装到 0.124.4）、移除 Python 3.9 支持（PR #14897）（§10）
• PyPI — fastapi 项目数据 — 本文校对时为 0.141.1（2026-07-29 上传）、要求 Python ≥3.10、累计 317 个发行版本、依赖声明（starlette>=0.46.0、pydantic>=2.9.0）（§00、§07、§10）
• pypistats.org — 各框架的 PyPI 下载量：FastAPI 上月约 359,347,176 次、Flask 约 131,653,752 次、Django 约 40,501,870 次（均取 2026-09-23 当天页面的 recent 数字）（§00、§07）
• docs.astral.sh — 安装 uv — §05 里的三种装法（官方安装方式 / Homebrew / pipx）逐条出自此页

独立来源（不是厂商自述）

• BetterUp 工程博客 — 「Chasing a Memory Leak in our Async FastAPI Service」（2025-09-22） — §10 第二件事的全部事实（全异步 FastAPI 服务、内存线性爬升、按内存触发的自动扩容导致机器加到上限而吞吐未升、根因在原生扩展与分配器、以 jemalloc 解决）。这是当事公司的第一手复盘，不是转述

本文自己做的核对（不是转述）

• 三个框架的下载量对比（§07）是本文在校对当天从 pypistats.org 的接口逐个取数后并列的，不是引用某篇对比文章。复核方式：打开 pypistats.org/packages/fastapi（把包名换成 flask、django 即可），看 recent 一栏的 last_month。建议你自己重做一遍，因为它同时是「下载量该怎么读」的现场示范。
• 「官网那句快，脚注是什么」（§07）是本文把首页原句与页面底部带星号的脚注对照后写出来的。多数二手文章只引前半句，你可以打开首页搜 estimation based on tests 自行核对。
• 「三层结构决定上层不可能更快」（§04）这个推论不是本文的原创判断，而是官方 benchmark 页里已经写明的层级关系；本文做的是把它翻译成一句可以直接用的判断法。

99一句话总结

留给你自己验的那一条

前面所有内容你都可以在文章里找到答案，只有这一条不行——它需要你自己的场景。请做一次：

拿你手上某个半途停下的项目，用 §11 的「该不该用三问」过一遍，然后写出你自己的那三行答案。例如：「我要做的是一个给自己用的数据看板，前端要读数据 → 这是接口，属于它的地盘；我这台电脑上有 Python 3.12，是之前学的时候装的 → 条件①成立；但我不需要后台管理，所以我要的确实只是一个窗口 → 条件②成立。」

如果你写完发现某一条卡住了（多半是「谁维护 Python 环境」这一条），那个卡住的地方就是你这个项目真正的下一个动作——而不是再读一篇框架介绍。