• 查询 query 参数（上一篇）
• 路径 path 参数（本篇）
• 请求体 body 参数（下一篇）
• 请求头 header 参数

本篇项目目录结构：

Path 路径参数示例项目结构

1. 路径参数

路径参数是 URL 地址的一部分，是必填的。路径参数可以是：

• 常规路径参数
• 子路径参数（参数是路径）
• 枚举路径参数

FastAPI 框架同样提供了对路径参数进行条件校验的支持，通过如下图的 Path 实现。

path 类

下面一一介绍。

1.1. 常规路径参数

常规路径路由参数格式是使用花括号 {}，列如：

/patient/{patient_id}

上面的 {patient_id} 会使用传递的路径中的具体值替换。详细的示例如下：

# 通过 @app.get 装饰器创建一个 API 端点路由
# 常规路径参数
@app.get("/usr/{usr_id}/article/{article_id}", summary='获取用户文章')
async def query_user_article(usr_id: int, article_id: str):
    return {
        "user_id": usr_id,
        "article_id": article_id
    }

运行效果如下：

swagger ui

常规path参数

1.2. 子路径参数

路径参数的值本身是路径的情况，需要指定其为 path，语法格式：{参数: path}。示例如下：

# {file_path:path}，path 表明该参数是路径
@app.get("/usr/{file_path:path}", summary="获取文件")
async def get_file(file_path: str):
    return {
        "file_path": file_path
    }

运行效果如下：

swagger ui

路径示例1

路径示例2

1.3. 枚举路径参数

一般在参数的值是固定的几个值时，会用枚举，当传入的值不是这些值，FastAPI 会抛出异常。在使用枚举前，前花些时间了解一下 python 中的枚举类型吧，官方文档：

(1) https://docs.python.org/zh-cn/3/library/enum.html
(2) https://docs.python.org/zh-cn/3/howto/enum.html

下面先来定义自己的枚举，这里把 类 和 函数 两种方式都尝试了一下：

from enum import Enum

# 函数的方式
Weekday = Enum('Weekday', ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday'])

# 类的方式
class ColorModel(str, Enum):
    RED = 'red'
    GREEN = 'green'
    BLUE = 'blue'
    YELLOW = 'yellow'
    PURPLE = 'purple'

使用枚举类型作为参数：

from mymodels import ColorModel, Weekday

# 如果传入的值不是这些值，则会抛异常
@app.get("/info/{color}", summary="获取颜色信息")
async def get_color(color: ColorModel):
    if color == ColorModel.RED:
        msg = f'weekday: {Weekday.Monday.name}, color: {color.name}'
    elif color == ColorModel.GREEN:
        msg = f'weekday: {Weekday.Tuesday.value}, color: {color.value}'
    elif color == ColorModel.BLUE:
        msg = f'weekday: {Weekday.Monday.name} = {Weekday.Monday.value}, color: {color.name} = {color.value}'
    else:
        msg = f'{color} ignored'
    return {
        "weekday_color": msg
    }

运行效果如下：

swagger ui

枚举类型

抛异常

1.4. 路径参数条件校验

文章一开头已经提到 FastAPI 提供 Path 类的封装来设置 路径参数 的条件校验。下面是具体的示例代码：

from fastapi import FastAPI, Path

# FastAPI 提供对 Path 类的封装来设置 路径参数 的条件校验
# ... 表明必填
@app.get("/data/{data_id}/txt/{txt_id}", summary='获取数据')
async def query_data(data_id: int = Path(..., ge=100, title='数据ID', description='数据唯一编号'),
                     txt_id: str = Path(..., min_length=1, max_length=30)):
    return {
        "data_id": data_id,
        "txt_id": txt_id
    }

运行效果如下：

swagger ui

校验效果

python 的开发效率还是挺高的，在日常工具、DEMO等工作中发挥了不少的作用，个人觉得的确 值得学习的。