FastAPI开发教程：查询参数实战

开发Web应用时，有时会需要在访问链接中附加一些额外信息，比如分页或筛选条件。

这些额外的信息通常通过“查询参数”来实现，今天我们就来学习如何用FastAPI简单搞定这些内容。

---

什么是查询参数？

查询参数是URL中的一部分，用来向服务器传递额外的信息。

它们用?开头，多个参数用&分隔。例如：

http://example.com/items?skip=5&limit=10

这里的skip和limit就是查询参数，它们告诉服务器：我们想从第5个开始，最多取10个。

---

快速上手：创建支持查询参数的接口

以下代码展示了如何在FastAPI中实现一个简单的查询参数功能：

from fastapi import FastAPI

app = FastAPI()

@app.get("/items")
async def list_items(skip: int = 0, limit: int = 10):
    fake_items_db = ["苹果", "香蕉", "橙子"]
    return fake_items_db[skip: skip + limit]

代码解读：

1. 定义了一个GET接口/items。
2. skip
   
   和limit是查询参数，它们有默认值，分别是0和10。
3. 模拟了一个“数据库”fake_items_db，通过skip和limit控制返回数据的范围。

调用这个接口：

GET /items?skip=1&limit=2

返回结果：

["香蕉", "橙子"]

---

路径参数与查询参数的组合

路径参数和查询参数可以一起使用。以下是一个例子：

from typing import Optional

@app.get("/items/{item_id}")
async def get_item(item_id: str, query: Optional[str] = None):
    if query:
        return {"item_id": item_id, "query": query}
    return {"item_id": item_id}

代码解读：

1. item_id
   
   是路径参数，它必须在URL中提供。
2. query
   
   是查询参数，它是可选的（默认值为None）。

调用接口：

GET /items/123?query=test

返回结果：

{"item_id": "123", "query": "test"}

---

查询参数的更多技巧

1. 可选参数：
   
   通过Optional或设置默认值为None，你可以轻松实现可选查询参数。

from typing import Optional

@app.get("/search")
async def search_items(term: Optional[str] = None):
    return {"term": term if term else "未提供关键词"}

1. 类型转换与布尔值参数：
   
   FastAPI支持类型转换。例如：

@app.get("/filter")
async def filter_items(short: bool = False):
    return {"short": short}

无论你传递short=1还是short=true，FastAPI都会将其转换为布尔值True。

1. 必填参数：
   
   使用Query模块可以指定查询参数为必填。

from fastapi import Query

@app.get("/required")
async def required_param(param: str = Query(...)):
    return {"param": param}

如果未提供param参数，FastAPI会返回错误。

---

实战：路径和查询参数的复杂用法

以下代码演示了如何结合路径参数与查询参数：

@app.get("/users/{user_id}/items/{item_id}")
async def get_user_item(user_id: int, item_id: str, query: Optional[str] = None, short: bool = False):
    item = {"item_id": item_id, "owner_id": user_id}
    if query:
        item.update({"query": query})
    if not short:
        item.update({"description": "这是一段详细描述。"})
    return item

调用接口：

GET /users/1/items/abc?query=example&short=true

返回结果：

{
  "item_id": "abc",
  "owner_id": 1,
  "query": "example"
}

---

总结

查询参数可以让你的API更加灵活：

1. 实现分页、筛选等动态功能。
2. 与路径参数结合，实现复杂的业务逻辑。
3. 借助FastAPI的类型支持，确保参数的安全性和正确性。

来源：猫十