2.3 查询参数：可选参数、默认值与验证

FastAPI初学者教程：查询参数详解 - 可选参数、默认值与验证

FastAPI 教程

本教程为Python初学者提供FastAPI中查询参数的详细指南，包括如何定义可选参数、设置默认值和进行数据验证。通过生活化类比和简单示例，帮助您快速上手Web开发，建立信心。

FastAPI入门教程：查询参数（可选参数、默认值与验证）

欢迎来到FastAPI教程！如果你是Python新手，刚刚学会基础语法，但还没接触过Web开发，别担心！这个教程就像学做饭：我们从最简单的菜谱开始，一步一步教你做出美味的Web应用。今天，我们聚焦在查询参数上，这是Web开发中一个基础但强大的概念。想象一下，查询参数就像你点咖啡时说的"加糖"或"少冰"——它们是URL中的额外要求，服务器根据这些参数来返回定制化的内容。

准备好了吗？让我们一起动手，体验几个"成功时刻"，让你快速掌握查询参数的可选性、默认值和验证！

第1步：安装和设置FastAPI

在开始之前，确保你已经安装了Python（建议版本3.7+）。打开终端或命令行，运行以下命令安装FastAPI和Uvicorn（一个快速的服务器）：

pip install fastapi uvicorn

安装成功后，你就有了所有工具！接下来，我们创建一个简单的Web应用。

第2步：创建你的第一个FastAPI应用

新建一个Python文件，比如叫 main.py，并输入以下代码：

from fastapi import FastAPI

app = FastAPI()  # 创建一个FastAPI应用实例，就像给你的Web应用起个名字

@app.get("/hello")  # 定义一个GET路由，路径是/hello，类似访问一个网页
async def hello():
    return {"message": "Hello, World!"}

保存文件，然后在终端运行：

uvicorn main:app --reload  # --reload 表示热重载，代码改动后自动更新

打开浏览器访问 http://127.0.0.1:8000/hello，你会看到 {"message": "Hello, World!"} 的JSON响应。恭喜你，第一个FastAPI应用运行成功了！这就是你的成功时刻：看到Web服务在本地运行起来了。

第3步：引入查询参数的基础概念

查询参数是URL中问号（?）后面的部分，比如 http://127.0.0.1:8000/hello?name=Alice。在FastAPI中，你可以直接在函数参数中定义它们，就像Python函数一样简单。

让我们修改 main.py，添加一个带查询参数的端点：

from fastapi import FastAPI

app = FastAPI()

@app.get("/hello")
async def hello(name: str):  # 定义了一个查询参数 name，类型是字符串
    return {"message": f"Hello, {name}!"}

现在，访问 http://127.0.0.1:8000/hello?name=Alice，你会看到 {"message": "Hello, Alice!"}。这就是查询参数的作用：传递额外信息给服务器。

第4步：可选参数——让参数变得灵活

有时候，你可能不想总是提供参数。比如，在点餐时，你可以说"加糖"（可选），也可以不说。在FastAPI中，通过设置默认值为 None 或使用 Optional 类型来定义可选参数。

修改代码，让 name 参数可选：

from fastapi import FastAPI
from typing import Optional  # 导入Optional，用于定义可选类型

app = FastAPI()

@app.get("/hello")
async def hello(name: Optional[str] = None):  # name 现在是可选参数，如果不提供，默认是 None
    if name:
        return {"message": f"Hello, {name}!"}
    else:
        return {"message": "Hello, stranger!"}

试试不同的访问方式：

http://127.0.0.1:8000/hello → 返回 {"message": "Hello, stranger!"}
http://127.0.0.1:8000/hello?name=Bob → 返回 {"message": "Hello, Bob!"}

看，参数变得灵活了！这是你的又一个成功时刻：学会处理可选输入。

第5步：设置默认值——提供备选方案

当参数可选时，我们还可以给它一个默认值，而不是 None。这就像餐厅默认给你提供标准餐，除非你特别要求。

更新代码，为 name 设置默认值：

from fastapi import FastAPI

app = FastAPI()

@app.get("/hello")
async def hello(name: str = "World"):  # 设置默认值为 "World"
    return {"message": f"Hello, {name}!"}

现在：

http://127.0.0.1:8000/hello → 返回 {"message": "Hello, World!"}
http://127.0.0.1:8000/hello?name=Charlie → 返回 {"message": "Hello, Charlie!"}

这样一来，如果没有提供 name，它会自动使用 "World"。简单吧？

第6步：验证参数——确保输入正确

在Web开发中，验证很重要，就像检查点餐单是否正确，避免错误。FastAPI内置了数据验证功能，使用Pydantic（一个强大的数据验证库）。我们可以添加验证规则，比如限制参数长度或类型。

让我们给 name 添加一个简单验证：要求它至少2个字符。修改代码：

from fastapi import FastAPI, Query  # 导入Query，用于定义查询参数的额外规则

app = FastAPI()

@app.get("/hello")
async def hello(name: str = Query(default="World", min_length=2)):  # 使用Query设置默认值和最小长度验证
    return {"message": f"Hello, {name}!"}

这里，Query 是一个辅助类，让你添加验证。试试看：

http://127.0.0.1:8000/hello → 正常返回 {"message": "Hello, World!"}
http://127.0.0.1:8000/hello?name=A → FastAPI会自动返回错误，因为长度小于2。访问时会看到JSON错误信息，比如 {"detail":[{"loc":["query","name"],"msg":"ensure this value has at least 2 characters","type":"value_error.any_str.min_length"}]}。

这展示了验证的强大：自动检查输入，保护你的应用。成功时刻：看到验证在起作用，错误被优雅处理。

第7步：更多示例和动手实践

为了巩固学习，试试这个扩展示例：创建一个端点，模拟在线商店搜索产品。假设用户可以按名称和价格过滤产品。

在 main.py 中添加新代码：

from fastapi import FastAPI, Query
from typing import Optional

app = FastAPI()

# 假设我们有一些产品数据
products = [
    {"id": 1, "name": "Laptop", "price": 1000},
    {"id": 2, "name": "Mouse", "price": 20},
    {"id": 3, "name": "Keyboard", "price": 50},
]

@app.get("/products")
async def get_products(
    name: Optional[str] = Query(None, description="Filter by product name"),  # 可选参数，用于名称过滤
    max_price: Optional[float] = Query(None, ge=0, description="Maximum price filter"),  # 可选参数，验证价格>=0
):
    filtered_products = products
    if name:
        filtered_products = [p for p in filtered_products if name.lower() in p["name"].lower()]
    if max_price is not None:
        filtered_products = [p for p in filtered_products if p["price"] <= max_price]
    return {"products": filtered_products}

运行应用，然后访问：

http://127.0.0.1:8000/products → 返回所有产品
http://127.0.0.1:8000/products?name=lap → 返回包含"lap"的产品（如Laptop）
http://127.0.0.1:8000/products?max_price=30 → 返回价格≤30的产品
http://127.0.0.1:8000/products?name=key&max_price=100 → 组合过滤

玩转这些URL，你会看到一个实用的Web API在运行！这是最终的成功时刻：创建了一个带查询参数的真实示例。

总结

在这个教程中，我们学习了：

查询参数是什么：就像URL中的额外要求，用于定制响应。
如何定义可选参数：使用 Optional 类型或设置默认值 None，让参数灵活可选。
如何设置默认值：给参数一个备选值，简化用户输入。
如何验证参数：利用 Query 和 FastAPI 的内置验证，确保数据正确性。

记住，FastAPI 让Web开发变得简单直观，特别是对于Python初学者。你已经掌握了查询参数的核心概念，可以继续探索更多功能，比如路径参数、请求体等。

下一步行动：尝试修改代码，添加更多参数和验证规则，或者创建一个自己的小项目。遇到问题时，查阅FastAPI官方文档，那里有更多详细示例。

加油，你已经在Web开发的道路上迈出了坚实的一步！

上一章 2.2 路径参数：定义、类型转换与验证

下一章 2.4 请求体：POST、PUT、PATCH 请求