1. FastAPI 简析

FastAPI 中文教程: FastAPI - FastAPI 框架

FastAPI 英文教程: FastAPI

源代码： https://github.com/fastapi/fastapi

0. 结论

FastAPI 是一个面向“服务端接口层”的现代 Python Web 框架，用来构建高性能、强类型、可维护的 API / WebSocket / 轻量 Web 应用。

它解决的核心问题只有一个：

如何以最小的人力成本，构建工程质量可靠的服务接口。

---

一、FastAPI 在软件架构中的位置

1. FastAPI 不等于“网站框架”

在现代系统中，Web 架构已经发生了变化：

[ 前端 ]  <--HTTP/WebSocket-->  [ 后端服务 ]
Vue / React                    FastAPI
Flutter / App                  Spring / Go
设备 / 机器人                  Rust / Node

FastAPI 处在后端服务接口层，而不是“页面渲染层”。

2. FastAPI 的职责边界

FastAPI 负责：

• HTTP / WebSocket 接入
• 参数解析与校验
• 请求分发
• 返回结构化数据
• 协议与接口稳定性

FastAPI 不负责：

• 复杂业务规则
• 数据库设计
• 前端工程
• 任务调度（需配合 Celery 等）

---

二、FastAPI 的核心设计思想（非常重要）

思想 1：接口即契约（Contract First）

在 FastAPI 中：

def create_user(user: UserCreate) -> UserOut:
    ...

这行代码同时定义了：

• 输入数据结构
• 输出数据结构
• 校验规则
• API 文档
• 前后端契约

接口不是“字符串 + dict”，而是明确的结构契约。

思想 2：类型注解不是注释，而是运行时能力

FastAPI 将 Python 类型注解提升为：

• 校验规则
• 序列化规则
• 文档生成规则

这和传统 Python 框架是本质区别。

思想 3：I/O 是常态，异步是默认选项

FastAPI 天然假设：

• 数据库是 I/O
• 网络是 I/O
• 文件是 I/O

因此：

• 原生支持 async / await
• 使用 ASGI 而非 WSGI

---

三、FastAPI 的基本构成

一个 FastAPI 应用由 6 个核心部分组成：

1. 应用实例（App）

from fastapi import FastAPI

app = FastAPI()

这是：

• 路由注册中心
• 中间件挂载点
• 生命周期管理器

2. 路由（Router）

@app.get("/ping")
def ping():
    return {"msg": "pong"}

路由 = 协议入口

每一个路由都代表一个“外部可调用能力”。

3. 请求数据（Request Data）

FastAPI 自动区分数据来源：

来源	示例
Path	/users/{id}
Query	?page=1
Body	JSON
Header	Token
Cookie	Session

你不需要手工解析。

4. 数据模型（Pydantic）

from pydantic import BaseModel

class User(BaseModel):
    id: int
    name: str

这是 FastAPI 的灵魂组件：

• 校验
• 反序列化
• 序列化
• 文档生成

5. 响应（Response）

FastAPI 自动：

• 转 JSON
• 设置状态码
• 处理异常

你只关心业务返回值。

6. 自动文档（Swagger）

访问：

• /docs
• /redoc

文档不是“写出来的”，而是从代码推导出来的。

---

四、FastAPI 的典型使用模式

模式 1：纯 API 服务（最常见）

Client -> FastAPI -> Service -> DB

特点：

• 无页面
• 全 JSON
• 前后端分离

模式 2：API + WebSocket

Browser
  | HTTP     | WebSocket
  v          v
FastAPI ---- Status Push

适合：

• 实时状态
• 设备监控
• 日志推送

模式 3：轻量 Web 应用（控制台）

FastAPI
├── API
├── WebSocket
├── HTML (Jinja2)
└── Static Files

适合：

• 管理后台
• 内部工具
• 设备配置界面

五、FastAPI 的推荐工程结构

不要把所有代码写在一个文件里。

推荐结构：

app/
├── main.py          # 应用入口
├── routers/         # 路由层
├── schemas/         # Pydantic 模型
├── services/        # 业务逻辑
├── core/            # 配置 / 生命周期
└── utils/

核心原则：

路由薄，业务厚

---

六、FastAPI 与 Flask / Django 的认知对比

vs Flask

维度	Flask	FastAPI
类型系统	无	强
校验	手写	自动
文档	手写	自动
异步	扩展	原生

FastAPI 是 Flask 的工程化进化版本。

vs Django

维度	Django	FastAPI
定位	全栈	接口层
ORM	内建	外部
Admin	强	无
学习曲线	高	中

FastAPI 不试图“包办一切”。

---

七、FastAPI 的常见误区（务必避免）

❌ 误区 1：把 FastAPI 当脚本服务器

• 全部逻辑写在路由里
• 无模型
• 无分层

→ 直接失去 FastAPI 的价值。

❌ 误区 2：忽略类型注解

不用 Pydantic，只用 dict

→ 等于“用 FastAPI 写 Flask”。

❌ 误区 3：用它做复杂页面网站

SEO / CMS / 博客

→ 选型错误。