FastAPI：高性能Python Web框架

一. FastApi简介

FastAPI 是一个现代、快速（高性能）的 Web 框架，用于构建 API。它具有自动生成交互式 API 文档、数据验证、依赖注入等强大功能。在本节中，我们将通过一个用户管理系统的案例，学习 FastAPI 的基础知识。

二. fastapi基础应用创建与启动

2.1 安装依赖

首先需要安装FastAPI及其依赖项：

pip install fastapi
pip install uvicorn

FastAPI 需要一个 ASGI 服务器来运行，这里我们使用 Uvicorn。

from fastapi import FastAPI
import uvicorn

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

# 创建接口
@app.get("/")
async def root():
    return {"message": "Hello World"}

# 启动服务
if __name__ == "__main__":
    uvicorn.run(app, host="127.0.0.1", port=8080)

这个简单的应用创建了一个 FastAPI 实例，并定义了一个根路由 /，当访问时会返回 JSON 格式的 {"message": "Hello World"}

2.2 启动应用

使用 Uvicorn 启动应用：

uvicorn main:app --reload

参数说明：

• main:app：main 是模块名，app 是 FastAPI 实例变量名
• --reload：开发模式下自动重载，代码修改后会自动重启服务

2.3 访问应用

启动成功后，默认会在 http://127.0.0.1:8000 提供服务。可以使用浏览器访问：

http://127.0.0.1:8000/

2.4. 要点说明

• FastAPI() 创建应用实例
• uvicorn 是 ASGI 服务器，用于运行 FastAPI 应用
• host 和 port 参数指定服务监听地址和端口

三. 路由与请求方法装饰器

FastAPI使用装饰器定义路由和处理函数：

@L.get("/login")        # GET 请求
def login(username:str, userpass:str):
    ...

@L.post("/register")    # POST 请求
def register(id:str, username:str, ...):
    ...

常用请求处理装饰器：

• @app.get(): 处理 HTTP GET 请求，用于获取资源。通常用于查询数据而不改变服务器状态
• @app.post(): 处理 HTTP POST 请求，用于创建新资源。常用于提交表单数据或上传文件
• @app.put(): 处理 HTTP PUT 请求，用于完整更新现有资源。要求客户端提供完整的更新后资源
• @app.delete(): 处理 HTTP DELETE 请求，用于删除指定资源

四. 几种传递参数的方式

方式一：查询参数

查询参数是在 URL 中 ? 后面的部分，例如 http://127.0.0.1/items?id=123\&name=test

from fastapi import FastAPI
from typing import Union

app = FastAPI()

@app.get("/items")
def read_items(item_id: int, q: Union[str, None] = None):
    if q:
        return {"item_id": item_id, "q": q}
    return {"item_id": item_id}

特点:

• 出现在 URL 的 ? 之后
• 用 & 连接多个参数
• 适合 GET 请求，传递少量数据
• 参数名必须与 URL 中的参数名一致
• 可以设置默认值（如 q: Union[str, None] = None）
• 使用 Union[str, None] 表示参数可以为 None

方式二：路径参数

路径参数是在 URL 路径中的动态部分，例如 /users/{user_id}

@L.get("/user/{user_id}")
def get_user(user_id: int):  # 路径中的 {user_id} 会自动传递给函数参数
    return {"user_id": user_id}

特点：

• 参数是 URL 路径的一部分
• 适合标识资源的唯一标识符
• 使用花括号 {} 定义参数位置
• 可以添加类型提示，FastAPI 会自动转换类型

方式三： 使用 Request 对象获取参数

# 服务端
@api_user.get("/get")
def get_test(request: Request):
    """
    处理员工信息查询的 GET 请求
    
    参数说明：
    - request: FastAPI Request 对象，封装了 HTTP 请求的所有信息
    
    该函数从请求的查询参数中提取员工相关信息，并返回格式化的响应数据
    """
    # 从请求的查询参数中获取员工ID
    s_id = request.query_params["s_id"]
    # 从请求的查询参数中获取员工姓名  
    s_name = request.query_params["s_name"]
    # 从请求的查询参数中获取员工密码
    s_pass = request.query_params["s_pass"]
    # 返回包含方法标识和员工信息的字典，员工信息以特定格式拼接
    return {"methods": "员工get⽅法", "data": f"{s_id}--{s_name}--{s_pass}"}

# 客户端

# 客户端通过 params 参数传递查询参数
response = requests.get(f'{url}yh/get', params={'s_id': '1001', 's_name': '张三', 's_pass': 'password'})

五. 项目组织结构

以下述案例解释：

├── main.py # 主应用入口文件

└── api/ # API 模块目录

├── kucun.py # 库存管理模块

└── yonghu.py # 用户管理模块

1. 主应用文件（main.py）

• 创建 FastAPI 实例
• 导入各个功能模块的 APIRouter
• 使用 app.include_router() 将模块集成到主应用
• 配置路由前缀和标签

2.功能模块目录（api）

• 存放独立的功能模块文件
• 每个模块专注于特定业务领域
• 便于代码管理和维护

3.模块文件

• 使用 APIRouter() 创建独立路由实例
• 定义该模块的 API 端点
• 实现具体业务逻辑

具体流程

1. 模块创建

在功能模块文件中，使用 APIRouter() 创建一个独立的路由实例。每个模块（如用户管理、订单管理等）拥有自己的路由对象，便于实现路由的模块化拆分与隔离 。这样可以避免所有路由集中在主应用中，提高代码的可读性与可维护性。

# 在每个模块文件中
api_user = APIRouter()  # 创建独立的路由实例

2. 接口定义

在模块路由实例上，通过装饰器（如 @api_user.get()）定义该模块相关的 API 接口。这些接口仅属于当前模块 ，并实现具体的业务逻辑。这种组织方式使得接口与功能模块紧密关联，便于开发、测试与调试，同时支持接口级别的中间件、依赖注入等独立配置。

@api_user.get("/get")  # 在模块路由上定义接口
def some_function():
    pass

3. 模块集成

在主应用（main.py）中，通过 app.include_router() 方法将各模块路由集成到统一的 FastAPI 应用中。通过 prefix 参数可为模块设置统一的路由前缀（如 /yh),``tags 参数则用于在交互式 API 文档中对接口进行分类展示，使整体项目结构清晰、便于管理。

# 在 main.py 中
app.include_router(api_user, prefix="/yh", tags=["用户管理"])

六. 总结

路由请求方法：

FastAPI 使用 @app.get()、@app.post() 等装饰器定义路由，分别对应 HTTP 的 GET（查询）、POST（创建）、PUT（更新）和 DELETE（删除）等操作，清晰映射资源操作语义。

多种参数传递形式：

提供多种常用方式来接收客户端数据：路径参数 （URL嵌入资源标识）、查询参数 （URL ? 后附加过滤选项）以及通过 Request 对象 直接获取原始请求信息等等。

模块化组织项目

推荐使用 APIRouter 进行模块化开发，通过 创建独立路由 → 定义模块接口 → 集成至主应用 的清晰流程，使项目结构层次分明、职责清晰，极大提升了代码的可维护性和团队协作效率。