S10-A01 · Web 框架选型 ADR（FastAPI / Flask / Django）

适用读者：要为团队选 Python Web 框架并承担后果的人。
前置：S10-J02。
版本基线：FastAPI 0.162.x、Flask 3.1.x、Django 5.x（示例口径）。
覆盖旧文：—（E 驱动）
覆盖扩展：E-S10-013（选型四维度）。
上一篇：S10-J02 · Flask ↔ FastAPI：迁移与对照
下一篇：S10-A02 · 学习路线与团队准入。

1. 一句话结论

选框架不是选"最好的"，是选"最匹配你的交付形态"：API 优先、内容站、还是后台管理系统——三者答案不同。

交付形态	首选	原因
纯 API / 微服务	FastAPI	类型即校验与文档，异步原生
小型服务 / 脚本附带 Web	Flask	最小依赖，改动成本低
内容站 / 后台管理（含 ORM、Admin、Auth）	Django	全家桶，避免重复造轮
需要大量实时推送	FastAPI（+ WebSocket）/ 或 Node	异步生态更顺

2. 四个选型维度（E-S10-013）

维度	问题	权重（示例）
交付形态匹配	是 API、页面，还是后台？	40%
团队熟悉度	现有成员能否 2 周内上手？	25%
生态完备性	校验/文档/ORM/迁移/鉴权是否现成？	20%
运维与性能	部署方式、并发模型、可观测性	15%

为什么"交付形态"权重最高：框架的核心差异在"它替你决定了什么"。逆着形态选，会用十倍代码量补差距。

3. 三维对比表（可交付）

维度	FastAPI	Flask	Django
类型校验	✅ 内建（Pydantic）	❌ 手写/插件	⚠️ Forms/DRF Serializer
自动文档	✅ `/docs` `/openapi.json`	❌ 需扩展	⚠️ DRF 有，需配置
异步	✅ 原生	⚠️ 3.x 支持	⚠️ 5.x 部分支持
ORM	⚠️ 自选（SQLAlchemy）	⚠️ 自选	✅ 内建（含迁移）
Admin 后台	❌	❌	✅ 内建
学习曲线	低-中	最低	中（概念多）
最小依赖	中	低	高
适合团队规模	1–20	1–10	5–100

4. ADR 样例（可直接落库）

# ADR-0012 · 选用 FastAPI 作为对外 API 框架

- 状态：已采纳 ｜ 日期：2026-11-05 ｜ 决策者：平台组
- 影响范围：新建 API 服务 ｜ 相关：ADR-0009（Python 版本基线）

## 背景
新服务以 JSON API 为主，需要请求校验、文档与异步支持；团队 3 人，均熟悉 Flask。

## 决策
新 API 服务统一用 FastAPI（Python 3.12），错误响应结构由统一中间件包装。

## 备选方案与被否原因
1. **Flask**：团队最熟，但校验/文档全靠手写与插件，长期维护成本高。
2. **Django**：能力最全，但本项目无页面与 Admin 需求，等于为不需要的能力付费（依赖与学习成本）。
3. **坚持 Flask + pydantic 手工整合**：能实现，但等于自己造一个"轻量 FastAPI"，不如用成熟实现。

## 后果
- 正面：校验与文档零成本；异步可支撑高并发 IO。
- 负面：团队需学类型标注与异步；同步库（requests 等）需替换为异步实现。
- 回滚：Flask 服务不受影响，新服务可逐个回退（服务独立部署）。

## 验证
三个服务迁移后：错误响应结构一致；`/openapi.json` 可被网关导入；P99 与迁移前持平或更优。

注意最后一段"验证"：没有验证方式的 ADR 是空话（S01-A04 §3 的评审清单同理）。

5. 什么时候该选 Django（容易被忽略）

场景	为什么 Django
需要后台管理界面（运营配置）	Admin 开箱即用，省 2–4 周
需要用户/权限/会话体系	内建 auth
需要数据库迁移管理	migrations 内建
团队有 Django 经验	学习成本最低

判据："有没有大量 CRUD 页面与后台操作？" 有 → Django；纯 JSON API → FastAPI。

6. 五个误区

误区	真相
"FastAPI 是 Flask 的升级版"	定位不同：一个偏 API 契约，一个偏微框架
"Django 太老不能用"	后台/内容场景仍是最省事的选择
"性能数据决定选型"	多数项目瓶颈在 DB 与外部 IO，不在框架
"选型一次定终身"	服务级选型可以不同（网关 API 与内部小工具不必一致）
"没有 ADR 也能选"	半年后没人记得为什么选它，改起来阻力极大

7. 自检（架构师版）

四个选型维度中，为什么"交付形态"权重最高？
什么场景下 Django 明显优于 FastAPI？给出三个具体信号。
为什么"自己用 Flask + pydantic 整合"通常不划算？
ADR 的"验证"段缺失会有什么后果？
团队里同时存在 FastAPI 与 Flask 服务，如何避免混乱？

8. 下一篇

S10-A02 · 学习路线与团队准入

选型定完，最后一个问题是"人要多久能上手"。下一篇给六周路线与可度量的准入清单。

本篇属于系列《S10 · Python 语言与环境》，架构师层第 1 篇。扩展点 E-S10-013。