ThankNeko's Blog
Hoshinozora
2025-11-23
目录

FastAPI介绍

# FastAPI介绍

# FastAPI简介

FastAPI是一个基于Python的、现代的、快速(高性能)的Web框架，用于构建API。

官方文档：https://fastapi.tiangolo.com/zh/

# FastAPI特点

  1. 快速和高性能

    FastAPI的性能可与Node.js和Go相媲美，是最快的Python Web框架之一。这得益于它对Starlette(ASGI框架)和Pydantic(数据验证与序列化)的高效实现。

  2. 易于学习和使用

    语法简洁直观，即使对新手也友好。同时适合构建小型脚本或大型企业级应用。

  3. 自动生成交互式API文档

    FastAPI能自动生成OpenAPI和JSON Schema，并提供两种交互式文档界面。

  4. 类型安全 & 自动数据验证

    利用Python的类型提示结合Pydantic模型，FastAPI自动进行请求数据验证、序列化和错误处理。

  5. 异步支持（Async/Await）

    原生支持异步编程，可轻松编写高性能的异步端点（endpoints），适用于I/O密集型任务（如数据库查询、HTTP 请求等）。

  6. 依赖注入系统

    内置强大的依赖注入机制，便于管理复杂依赖关系（如数据库连接、认证逻辑、权限校验等），提高代码复用性和可测试性。

  7. 符合开放标准

    完全兼容OpenAPI和JSON Schema，便于与其他工具集成（如前端生成器、Postman、自动化测试等）。

# WSGI协议

# WSGI介绍

WSGI(Web Server Gateway Interface, Web服务器网关接口)，是Python中用于Web服务器与Web应用/框架之间通信的标准接口协议。

WSGI的主要目的是解耦Web服务器和Web应用，使得任何符合WSGI协议的Web服务器，都能运行任何符合WSGI协议的应用。

# WSGI角色

角色 说明
Server（服务器） 如 Gunicorn、uWSGI、mod_wsgi。负责接收 HTTP 请求，解析后调用 WSGI 应用
Application（应用） 如 Flask、Django（在同步模式下）。处理业务逻辑并返回响应
Middleware（中间件） 位于 Server 和 Application 之间，也是一个 WSGI 应用，可对请求/响应进行预处理或后处理（如日志、认证、路由分发）

# WSGI服务器

服务器 特点
Gunicorn 纯 Python，简单易用，常用于 Linux 部署
uWSGI C 编写，高性能，功能丰富（支持多语言、缓存、RPC 等）
mod_wsgi Apache 模块，适合与 Apache 集成
Waitress 纯 Python，跨平台（Windows 友好）

# WSGI局限性

  1. 仅支持同步阻塞模型，无法使用async/await异步，存在性能瓶颈。

    虽然支持异步的ASGI是未来趋势，但WSGI在同步场景下依然稳定、成熟、高效。

  2. 不支持WebSocket、HTTP/2、长连接等现代协议。

# ASGI协议

# ASGI介绍

ASGI(Asynchronous Server Gateway Interface, 异步服务器网关接口)，是Python中用于异步Web服务器与异步Web应用/框架之间通信的现代标准接口规范。

WSGI的主要目的是在保持与WSGI类似简洁性的同时，拓展支持高性能的异步I/O和多种网络协议(如 HTTP/1.1、HTTP/2、WebSocket 等)。

# ASGI服务器

服务器 特点
Uvicorn 基于 uvloop 和 httptools，极快，开发首选。
Hypercorn 支持 HTTP/2 和 QUIC，兼容 Trio/asyncio。
Daphne 由 Django Channels 团队开发，早期 ASGI 服务器。

# ASGI与WSGI对比

对比项 WSGI ASGI
同步/异步 仅同步 原生异步
协议支持 仅 HTTP HTTP、WebSocket、HTTP/2 等
并发模型 多进程/线程 单线程事件循环（asyncio）
适用场景 传统 Web 应用 现代高并发、实时应用
代表框架 Flask, Django（同步） FastAPI(底层是Starlette), Starlette, Quart

# FastAPI依赖

Python3.8及更高版本。

Starlette库，负责Web部分。

Pydantic库，负责数据部分。

# FastAPI基本使用

# 安装FastAPI

# 安装FastAPI
pip3 install fastapi

# 安装ASGI服务器，standard版本包含额外的依赖，可以提供更好的性能和功能，如自动重载、HTTP/2等。
pip3 install "uvicorn[standard]"
1
2
3
4
5

# 编写应用实例

main.py

from fastapi import FastAPI

# 创建一个FastAPI应用实例
app = FastAPI()

# 使用get装饰器定义一个请求方式为GET、访问路径为"/"的同步路径操作函数(即视图函数)
@app.get("/")
def read_root():
    # 返回"application/json"类型资源
    return {"Hello": "World"}

# 请求方式为GET、访问路径为"/items/{item_id}"的异步路径操作函数
# 例如访问"/items/2333?q=hello"时，传入参数为(item_id=2333, q="hello")
@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str | None = None):
    return {"item_id": item_id, "q": q}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# Uvicorn运行

# 第一种方式

命令行通过uvicorn直接运行：uvicorn <模块名>:<应用实例名>。

模块名：Python文件名，不包含.py后缀。

应用实例名：Python文件中FastAPI或Starlette实例的变量名。

# 使用--reload参数运行会开启热重载功能
uvicorn main:app --reload
1
2

常用启动参数：

--host：指定监听的网络接口。

--port：指定监听使用的端口。

--reload：启用热重载。

  • 会监听运行目录中的文件变化，如果变化则自动进行重载，可以极大提高开发效率，生产环境则不要使用。

--workers：指定工作进程数量。

  • 默认是单进程运行，可以指定进程数量以利用多核性能，一般进程数量可以设置为CPU核心数+1。
  • 注意：--workers不能与--reload同时使用。

--log-level：设置Uvicorn输出的日志级别。

  • 默认为--log-level info级别。

# 第二种方式

在代码中通过uvicorn.run函数运行。

if __name__ == "__main__":
    import uvicorn
    # 如果文件路径是./app/main.py则需要写成app.main:app
    uvicorn.run("main:app", reload=True)
1
2
3
4

注意：使用该方式时，如果程序是通过Pycharm运行，则可能出现无法重载或重载过慢问题，这是Pycharm的Bug导致。

可以在运行/调试配置中，添加Shell Script配置，并在脚本文本中添加python main.py运行命令，然后通过该配置运行即可。

# 访问接口

# 运行程序后，会显示运行日志，其中会有访问地址，通过该地址访问即
> INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
> INFO: Started reloader process [41804] using WatchFiles
> INFO: Started server process [44640]
> INFO: Waiting for application startup.
> INFO: Application startup complete.
1
2
3
4
5
6

# API文档

FastAPI在启动时会自动生成两种界面风格的API文档，适用于不同的人群使用，可以通过/docs和/redoc来访问。

如果在生产环境中不想暴露API文档，可以通过中间件限制访问或者添加认证，也可以在创建FastAPI实例时通过docs_url=None、redoc_url=None参数来禁用文档。

例如：app = FastAPI(docs_url=None, redoc_url=None)

特性 Swagger UI ReDoc
默认路径 /docs /redoc
交互性 ✅ 高度交互（可直接在页面测试 API） ❌ 只读文档（不能发送请求）
UI 风格 简洁、紧凑、开发者友好 美观、阅读友好、类似技术文档
请求测试 支持填写参数、发送请求、查看响应 不支持
响应示例 显示实际调用后的响应 显示静态 Schema 示例
适合人群 开发者、测试人员（调试用） 产品经理、前端、文档读者（查阅用）

# 同步与异步

FastAPI支持在路径操作函数中混合使用 def(同步) 和 async def(异步)，以适配不同的使用场景。

比如：使用的第三方模块不支持异步操作时，就可以直接使用def声明路径操作函数，这样访问对应路径时，会在线程池中以同步方式执行该函数。

def 同步函数：

  • 函数体内不能使用 await。
  • 执行时会在一个线程池中运行，不会阻塞主线程的事件循环。

async def 异步函数：

  • 函数体内可以使用 await 调用异步操作。
  • 执行时会在主线程的事件循环(协程)中直接运行，更高效没有线程切换的开销。

注意：永远不要在 async def 中直接使用同步IO操作，会阻塞主线程的事件循环。

# 目录结构例子

分层架构：路由(API) → 业务逻辑(Services，可选) → 数据访问(Models / DB)

my_fastapi_app/
├── app/
│   ├── __init__.py
│   ├── main.py                 # 应用入口
│   ├── core/                   # 核心配置、安全
│   │   ├── settings.py
│   │   ├── security.py
│   │   ├── exceptions.py
│   │   └── logger.py
│   ├── schemas/                # Pydantic 模型（请求/响应体）
│   │   ├── __init__.py
│   │   ├── request/
│   │   └── response/
│   ├── api/                    # API 路由层（按功能模块划分）
│   │   ├── __init__.py
│   │   ├── v1/                 # API 版本控制（可选）
│   │   │   ├── __init__.py
│   │   │   ├── users.py        # 用户相关路由
│   │   │   ├── items.py        # 商品相关路由
│   │   └   └── auth.py         # 认证路由
│   ├── depends/                   # 依赖注入
│   ├── utils/                  # 其他工具函数
│   ├── enums/                  # 枚举类
│   ├── models/                 # 数据库模型
│   └── db/                     # 数据库方法
├── tests/                      # 测试
├── .env                        # 环境变量
├── requirements.txt
└── README.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
#Python#模块#FastAPI#WEB#后端
Pydantic验证
FastAPI请求

← FastAPI请求→

最近更新
01
Vue路由
12-09
02
FastAPI实现用户管理
11-23
03
Tortoise ORM
11-23
更多文章>
Theme by Vdoing | Copyright © 2022-2026 Hoshinozora | MIT License
湘ICP备2022022820号-1