FastAPI教程-查询参数 作者：马育民 • 2026-08-12 22:23 • 阅读：10003 # 介绍 URL：`/student?name=李雷&age=18`，在 `?` 后面，函数参数不在路径 `{}` 里就是查询参数。 ### 应用场景 - 条件查询、分页、排序，不会改变服务器资源，都是 GET 请求。 如B站搜索 `王者荣耀` 的URL：https://search.bilibili.com/all?vt=79105200&keyword=王者荣耀from_source=web_search&search_source=5 # 1. 基础用法 URL中不加 `{}`，如：`@app.get('/student')` ### 例子 ```python from fastapi import FastAPI app = FastAPI() @app.get('/student') async def get_student(name:str): print(f"根据{name}进行查询！" ) return { "name":name, "sex":"男" } ``` ### 测试：成功 访问：http://127.0.0.1:8000/student?name=lilei ，浏览器显示如下： ``` { "name": "lilei", "sex": "男" } ``` - - 类型会自动转换，传字符串会自动校验报错 ### 测试：不传参数 不传参数：直接返回422参数校验错误 访问：http://127.0.0.1:8000/student ，浏览器显示如下： ``` { "detail": [ { "type": "missing", "loc": [ "query", "name" ], "msg": "Field required", "input": null } ] } ``` **解释：** - `"type": "missing",`：错误类型，缺失参数 - `query`：表示查询参数 - `name`：表示查询参数 `name` - `msg": "Field required`：错误信息，翻译：需要字段 - `"input": null`：表示输入的是 `null`，即：没传参数 # 类型声明 直接在函数参数写类型，FastAPI自动做 **解析、校验** ### 支持类型 - `str`：默认类型，几乎可以接受任意类型参数 - `int` - `?age=18`，转成 `int` 类型的 `18` - `?age=12.3`、`?age=abc`，校验报错422 - `float` - `?price=99.99`，转成 `float` 类型的 `99.99` - `?price=100`，转为 `100.0` - `bool` - `?man=true`、`?man=1`，转为 `True` - `?man=false`、`?man=0`，转为 `False` - `bytes`：URL 传入 base64 编码字符串，自动解码为 bytes。 - `uuid.UUID` - 访问 `?id=550e8400‑e29b‑41d4‑a71c‑95a26cf3d479`正常转换 - 格式不对直接报 `422` 错误 # 2. 多个参数 需要传入 `name`、`age` **注意：**`age` 是 `int` 类型 如下： ``` @app.get('/student') async def get_student(name:str,age:int): print(f"根据{name}、{age} 进行查询！" ) return { "name":name, "age":age } ``` ### 测试成功 访问：http://127.0.0.1:8000/student?name=lilei&age=18 ，浏览器显示： ``` { "name": "lilei", "age": 18 } ``` **注意：**传入 `18`，自动转为 `int` 类型 ### 测试类型转换失败 访问：http://127.0.0.1:8000/student?name=lilei&age=a ，浏览器显示： ``` { "detail": [ { "type": "int_parsing", "loc": [ "query", "age" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "a" } ] } ``` **解释：** 因为 `age=a`，不能将 `a` 转为 `int` 类型，所以报错 - `"type": "int_parsing",`：错误类型 - `query`：表示查询参数 - `age`：表示查询参数 `age` - `msg": "Input should be a valid integer, unable to parse string as an integer`：错误信息，翻译：应该输入 `integer` 类型，否则不能将字符串转为 `integer` 类型 - `"input": "a"`：表示输入的是 `a` # 3. 设置默认值 在大学管理系统中，一般学生年龄是 `18` 岁，所以可设置默认值是 `18` ```python @app.get('/student') async def get_student(name:str,age:int = 18): print(f"根据{name}、{age} 进行查询！" ) return { "name":name, "age":age } ``` ### 测试：不传年龄 访问 http://127.0.0.1:8000/student?name=lilei ，不传年龄，那么年龄就取默认值 `18`，浏览器显示如下： ``` { "name": "lilei", "age": 18 } ``` ### 测试：传年龄 访问 http://127.0.0.1:8000/student?name=lilei&age=16 ，传年龄，那么年龄就取传入的 `16`，浏览器显示如下： ``` { "name": "lilei", "age": 16 } ``` # 4. 可选查询参数(允许None) 给默认值 `None`，参数可以不传 ```python @app.get('/student') async def get_student(name:str,age:int | None = None): print(f"根据{name}、{age} 进行查询！" ) return { "name":name, "age":age } ``` ### 测试：不传年龄 访问 http://127.0.0.1:8000/student?name=lilei ，不传年龄，那么年龄就取默认值 `18`，浏览器显示如下： ``` { "name": "lilei", "age": null } ``` ### 测试：传年龄 访问 http://127.0.0.1:8000/student?name=lilei&age=16 ，传年龄，那么年龄就取传入的 `16`，浏览器显示如下： ``` { "name": "lilei", "age": 16 } ``` 原文出处：/show_1GW3r8vhHdX6.html