FastAPI 的历史、设计与未来：从替代框架调研到类型提示驱动 API 的设计哲学

本文基于 FastAPI 官方文档 history-design-future（对应英文版本 docs/en/docs/history-design-future.md）展开，完整还原了 FastAPI 从“多年替代方案调研”到“落地开发”的全过程：为何基于标准 Python 类型提示、如何研究 OpenAPI/JSON Schema/OAuth2 规范、怎样围绕编辑器体验做设计、最终依赖 Pydantic 与 Starlette 两大核心组件。结合当前仓库的源码与配置，你将能理解 FastAPI 每一项设计决策的来龙去脉，以及它在当前代码库中留下的实现痕迹。

缘起：一个来自用户的提问

多年前，一位 FastAPI 用户在仓库的 issue 中提问：

“这个项目的历史是什么？它似乎从一无所有，在几周内就变成了了不起的东西……”

于是作者写下了这段历史。FastAPI 的历史，在很大程度上就是它的前身（predecessors）的历史。要理解 FastAPI 为什么是今天的模样，必须先理解作者在这之前用过什么、踩过什么坑。

前史：长期调研众多替代框架

作者在创建 API 方面拥有多年经验，长期构建具有复杂需求的 API（机器学习、分布式系统、异步任务、NoSQL 数据库等），并带领过多支开发团队。在这个过程中，他调研、测试并实际使用了大量替代方案，包括：

前身工具	对 FastAPI 的关键启发
Django / Django REST Framework	自动 API 文档 Web UI 是最早的灵感来源之一
Flask	保持“微框架”定位，组件可自由组合；提供简单直观的路由系统
Requests	简单直观的 API 设计；直接用 HTTP 方法名（requests.get(...) 之于 @app.get(...)）；合理的默认值 + 强大的自定义能力
Swagger / OpenAPI	采用开放标准描述 API，而不是自定义 schema；集成 Swagger UI、ReDoc 等标准化工具
Marshmallow / Webargs	用代码定义 schema 来自动提供数据验证、解析与序列化
APISpec / Flask-apispec	由同一份定义验证和序列化的代码自动生成 OpenAPI schema
NestJS（及 Angular）	用类型获得出色的编辑器支持；构建功能强大的依赖注入系统，同时最小化代码重复
Sanic	追求极致的性能，因此基于 Starlette 这一当时最快的 ASGI 框架
Falcon / Hug	寻找高性能的实现方式；在函数中声明 response 参数（FastAPI 中为可选，主要用于设置响应头、Cookie 和状态码）
Molten	用模型属性的“默认值”定义额外的数据约束，改进编辑器支持——这一思路后来反哺了 Pydantic 本身
APIStar（≤ 0.5）	“存在”的直接灵感：用同一套 Python 类型同时声明数据验证、序列化和文档，并获得出色的编辑器支持

作者在 替代方案（Alternatives） 一节中明确写道（此处为原文档引用的核心立场）：

FastAPI 若没有他人的先前工作，就不会存在。此前有许多工具帮助启发了它的诞生。

我多年来一直在避免创建一个新框架。首先，我尝试用许多不同的框架、插件和工具来组合解决 FastAPI 覆盖的所有功能。

但到了某个节点，除了创造一样能同时提供所有这些功能、吸收先前工具最佳想法、并以前所未有的语言特性（Python 3.6+ 类型提示）将它们以最优方式组合起来的东西之外，已别无选择。

值得注意的历史细节：APIStar 曾是最接近作者理想形态的方案，但它后来转向了 Starlette 方向、不再作为 Web 框架演进。作者认为 FastAPI 是 APIStar 的“精神继任者”（spiritual successor），在其基础上改进了类型系统、安全集成和其他部分。而 APIStar、Starlette、Uvicorn 以及 Django REST Framework 都出自同一位创造者之手，这条线索贯穿了 FastAPI 的技术基因。

研究阶段：先吃透标准，再动第一行代码

使用过所有这些替代方案后，作者得以从每一处学习、吸收想法，并以最适合自己的方式组合它们。其中最明确的两点结论是：

1. 理想情况下应基于标准 Python 类型提示（type hints）。类型提示是 Python 语言层面的一等特性，编辑器支持天然良好。
2. 应复用已存在的标准，而不是自造 schema 格式。

因此在真正开始编写 FastAPI 代码之前，作者花了数月时间研究 OpenAPI、JSON Schema、OAuth2 等规范的规格文档，理解它们之间的关系、重叠与差异。当前仓库中这部分投入的直接成果可以追溯到 fastapi/openapi/ 目录：

• fastapi/openapi/models.py：以 Pydantic 模型实现 OpenAPI 3.1 的完整 schema 结构；
• fastapi/openapi/utils.py：从路由、类型提示、Pydantic 模型到 OpenAPI 文档的核心生成逻辑；
• fastapi/openapi/docs.py：集成 Swagger UI、ReDoc、Scalar 等标准文档界面。

此外，fastapi/security/ 目录下的 OAuth2、OpenID Connect、API Key 等实现，正是对 OAuth2 规范长期研究的结果。

设计阶段：为开发者设计“开发者 API”

在写框架代码之前，作者先花时间设计了作为使用者（即使用 FastAPI 的开发者）所期望拥有的“开发者 API”。他针对当时最流行的 Python 编辑器逐一测试了多个设计思路：

• PyCharm
• VS Code
• 基于 Jedi 的编辑器

依据当时的 JetBrains Python 开发者调查，这三类编辑器覆盖了约 80% 的 Python 开发者。这意味着 FastAPI 是被针对 80% 用户在用的编辑器专门测试过的；而由于其他编辑器工作方式大体相似，这些收益应该对几乎所有编辑器都有效。

设计目标很具体：最大限度地减少代码重复，让自动补全、类型检查与错误检查在到处（everywhere）都能工作，让所有开发者获得最好的开发体验。当前仓库中 python-types.md 所强调的“类型提示是核心”，以及 editor-support.md 描述的编辑器生态（例如官方 FastAPI 扩展提供的路径操作探索、路由跳转等），都是这一阶段设计理念的直接延续。

需求阶段：选定 Pydantic 与 Starlette，并反向贡献

在测试了若干数据验证方案后，作者决定使用 Pydantic，理由是其基于类型提示的数据验证、序列化与 JSON Schema 文档生成的优势。随后他反过来向 Pydantic 贡献代码，使其：

• 完全兼容 JSON Schema；
• 支持用多种方式定义约束声明（例如通过模型属性的“默认值”声明验证规则，这一想法源自对 Molten 的观察）；
• 改进编辑器支持（类型检查、代码自动补全），并基于多个编辑器的实测进行验证。

另一个关键需求是 Starlette——一个轻量级的 ASGI 框架/工具包。在开发过程中，作者同样向 Starlette 贡献了代码。Starlette 提供了高性能内核、WebSocket、后台任务、启动/关闭事件、CORS、GZip、静态文件、流式响应、会话与 Cookie 支持等基础能力，但它不提供自动数据验证、序列化和文档生成——这恰恰是 FastAPI 在其上层添加的核心价值。

这一架构关系在当前仓库中有两处硬证据：

1. pyproject.toml 中的核心依赖声明，starlette 与 pydantic 是仅有的两个框架级硬依赖（外加 typing 相关辅助库）：

   dependencies = [
       "starlette>=0.46.0",
       "pydantic>=2.9.0",
       "typing-extensions>=4.8.0",
       "typing-inspection>=0.4.2",
       "annotated-doc>=0.0.2",
   ]
   

   同时 requires-python = ">=3.10"，classifiers 声明支持 Python 3.10 至 3.14，说明当年的 Python 3.6+ 类型提示理念如今已演进为对整个 3.10–3.14 区间的完整类型支持。

2. fastapi/applications.py 中 class FastAPI(Starlette) 直接继承自 Starlette——正如文档所说，“FastAPI 基本上就是加了激素（on steroids）的 Starlette”：凡是 Starlette 能做的，FastAPI 都能直接做，再叠加验证、依赖注入、OpenAPI 生成等能力。FastAPI 自身的依赖注入系统则实现在 fastapi/dependencies/ 模块中。

开发阶段：一切就绪，水到渠成

当作者真正开始创建 FastAPI 本身时，大部分拼图早已就位：

• 设计（开发者 API）已定义完成；
• 需求与工具（Pydantic、Starlette）已就绪，且经过反向贡献得到增强；
• 对 OpenAPI、JSON Schema、OAuth2 等标准的理解清晰而新鲜。

当前仓库中的最小示例 docs_src/first_steps/tutorial001_py310.py 就是这套设计的浓缩体现——路由、类型提示、默认文档 UI 全部开箱即用：

from fastapi import FastAPI

app = FastAPI()


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

这个只有 7 行的示例背后，是类型提示驱动的验证与 OpenAPI 文档生成、Starlette 提供的 ASGI 高性能内核、以及从 Requests 借鉴的 @app.get(...) 路由直觉。

未来：已验证的价值与仍在进行的工作

文档在“未来”一节给出的判断是：FastAPI 及其理念已经对很多人产生了价值，正因其更适合许多使用场景而被选为替代旧方案；许多开发者和团队（包括作者自己的团队）已经在项目上依赖 FastAPI。同时，仍有许多改进和功能在路上，FastAPI 拥有光明的未来，社区的帮助（参见 help-fastapi.md）将受到高度珍视。

从当前仓库的结构可以印证“未来”仍在兑现：

• 版本已演进至 0.141.1，pyproject.toml 的 classifiers 声明支持 Python 3.10–3.14，并集成 Pydantic v2（Framework :: Pydantic :: 2）；
• fastapi/ 主包持续扩展出 sse.py（Server-Sent Events）、staticfiles.py、templating.py、cli.py 等模块；
• tests/ 目录下有数百个测试文件，docs_src/ 中的每个教程示例都配有对应的 tests/test_tutorial/ 测试，保证文档示例始终真实可运行；
• 开发流程使用 scripts/test.sh、scripts/lint.sh 等脚本，以及 uv 锁定的依赖（uv.lock），工程化程度远高于项目初创时期。

小结：一段“先标准、再设计、后编码”的工程方法论

把这段历史压缩成可复用的方法论，FastAPI 的诞生遵循了一条清晰的路线：

1. 多年生产环境驱动：先在实际业务中调研并组合既有框架与工具；
2. 先吃透标准：用数月时间吃透 OpenAPI、JSON Schema、OAuth2 规范，选择开放标准而非私有格式；
3. 先设计开发者体验：在 PyCharm、VS Code、Jedi 系编辑器上验证自动补全与类型检查，把“减少代码重复”作为一等目标；
4. 选型并反向贡献：选定 Pydantic 与 Starlette 作为两大支柱，并通过上游贡献补全能力缺口；
5. 最后才编码：当设计、需求、标准知识全部就绪时，框架的实现成为水到渠成之事。

对于正在设计新框架或重构现有 API 项目的开发者而言，这条路线——尤其是“类型提示作为唯一事实来源（验证、序列化、文档三位一体）”与“在主流编辑器中实测开发者体验”这两个决策——仍然值得借鉴。