# 查询参数
-声明不属于路径参数的其他函数参数时，它们将被自动解释为"查询字符串"参数
+声明的参数不是路径参数时，路径操作函数会把该参数自动解释为**查询**参数。
```Python hl_lines="9"
{!../../../docs_src/query_params/tutorial001.py!}
```
-查询字符串是键值对的集合，这些键值对位于 URL 的 `？` 之后，并以 `&` 符号分隔。
+查询字符串是键值对的集合，这些键值对位于 URL 的 `?` 之后，以 `&` 分隔。
-例如，在以下 url 中：
+例如，以下 URL 中：
```
http://127.0.0.1:8000/items/?skip=0&limit=10
```
-...查询参数为：
+……查询参数为：
-* `skip`ï¼\9a对åº\94ç\9a\84å\80¼ä¸º `0`
-* `limit`ï¼\9a对åº\94ç\9a\84å\80¼ä¸º `10`
+* `skip`：值为 `0`
+* `limit`：值为 `10`
-由于它们是 URL 的一部分，因此它们的"原始值"是字符串。
+这些值都是 URL 的组成部分，因此，它们的类型**本应**是字符串。
-但是，当你为它们声明了 Python 类型（在上面的示例中为 `int`）时，它们将转换为该类型并针对该类型进行校验。
+但声明 Python 类型（上例中为 `int`）之后，这些值就会转换为声明的类型，并进行类型校验。
-应用于路径参数的所有相同过程也适用于查询参数：
+所有应用于路径参数的流程也适用于查询参数：
-* （很明显的）编辑器支持
-* 数据<abbr title="将来自 HTTP 请求的字符串转换为 Python 数据类型">"解析"</abbr>
+* （显而易见的）编辑器支持
+* 数据<abbr title="将来自 HTTP 请求的字符串转换为 Python 数据类型">**解析**</abbr>
* 数据校验
-* 自动生成文档
+* API 文档
## 默认值
-由于查询参数不是路径的固定部分，因此它们可以是可选的，并且可以有默认值。
+查询参数不是路径的固定内容，它是可选的，还支持默认值。
-在上面的示例中，它们具有 `skip=0` 和 `limit=10` 的默认值。
+上例用 `skip=0` 和 `limit=10` 设定默认值。
-因此，访问 URL：
+访问 URL：
```
http://127.0.0.1:8000/items/
```
-将与访问以下地址相同：
+与访问以下地址相同：
```
http://127.0.0.1:8000/items/?skip=0&limit=10
```
-但是，如果你访问的是：
+但如果访问：
```
http://127.0.0.1:8000/items/?skip=20
```
-函数中的参数值将会是：
+查询参数的值就是：
* `skip=20`：在 URL 中设定的值
* `limit=10`：使用默认值
## 可选参数
-通过同样的方式，你可以将它们的默认值设置为 `None` 来声明可选查询参数：
+同理，把默认值设为 `None` 即可声明**可选的**查询参数：
=== "Python 3.10+"
```
-在这个例子中，函数参数 `q` 将是可选的，并且默认值为 `None`。
+本例中，查询参数 `q` 是可选的，默认值为 `None`。
-!!! check
- 还要注意的是，**FastAPI** 足够聪明，能够分辨出参数 `item_id` 是路径参数而 `q` 不是，因此 `q` 是一个查询参数。
+!!! check "检查"
+
+ 注意，**FastAPI** 可以识别出 `item_id` 是路径参数，`q` 不是路径参数，而是查询参数。
+
+!!! note "笔记"
+
+ 因为默认值为 `= None`，FastAPI 把 `q` 识别为可选参数。
+
+ FastAPI 不使用 `Optional[str]` 中的 `Optional`（只使用 `str`），但 `Optional[str]` 可以帮助编辑器发现代码中的错误。
## 查询参数类型转换
-你还可以声明 `bool` 类型，它们将被自动转换：
+参数还可以声明为 `bool` 类型，FastAPI 会自动转换参数类型：
-```Python hl_lines="7"
+```Python hl_lines="9"
{!../../../docs_src/query_params/tutorial003.py!}
```
-这个例子中，如果你访问：
+本例中，访问：
```
http://127.0.0.1:8000/items/foo?short=1
http://127.0.0.1:8000/items/foo?short=yes
```
-或任何其他的变体形式（大写，首字母大写等等），你的函数接收的 `short` 参数都会是布尔值 `True`。对于值为 `False` 的情况也是一样的。
+或其它任意大小写形式（大写、首字母大写等），函数接收的 `short` 参数都是布尔值 `True`。值为 `False` 时也一样。
## 多个路径和查询参数
-你可以同时声明多个路径参数和查询参数，**FastAPI** 能够识别它们。
+**FastAPI** 可以识别同时声明的多个路径参数和查询参数。
-而且你不需要以任何特定的顺序来声明。
+而且声明查询参数的顺序并不重要。
-它们将通过名称被检测到：
+FastAPI 通过参数名进行检测：
-```Python hl_lines="6 8"
+```Python hl_lines="8 10"
{!../../../docs_src/query_params/tutorial004.py!}
```
-## å¿\85é\9c\80查询参数
+## å¿\85é\80\89查询参数
-当你为非路径参数声明了默认值时（目前而言，我们所知道的仅有查询参数），则该参数不是必需的。
+为不是路径参数的参数声明默认值（至此，仅有查询参数），该参数就**不是必选**的了。
-如果你不想添加一个特定的值，而只是想使该参数成为可选的，则将默认值设置为 `None`。
+如果只想把参数设为**可选**，但又不想指定参数的值，则要把默认值设为 `None`。
-但当你想让一个查询参数成为必需的，不声明任何默认值就可以：
+如果要把查询参数设置为**必选**，就不要声明默认值：
```Python hl_lines="6-7"
{!../../../docs_src/query_params/tutorial005.py!}
```
-è¿\99é\87\8cç\9a\84æ\9f¥è¯¢å\8f\82æ\95° `needy` æ\98¯ç±»å\9e\8b为 `str` ç\9a\84å¿\85é\9c\80查询参数。
+è¿\99é\87\8cç\9a\84æ\9f¥è¯¢å\8f\82æ\95° `needy` æ\98¯ç±»å\9e\8b为 `str` ç\9a\84å¿\85é\80\89查询参数。
-å¦\82æ\9e\9cä½ å\9c¨æµ\8fè§\88å\99¨ä¸æ\89\93å¼\80ä¸\80个å\83\8fä¸\8bé\9d¢ç\9a\84 URL：
+å\9c¨æµ\8fè§\88å\99¨ä¸æ\89\93å¼\80å¦\82ä¸\8b URL：
```
http://127.0.0.1:8000/items/foo-item
```
-...å\9b 为没æ\9c\89æ·»å\8a å¿\85é\9c\80ç\9a\84å\8f\82æ\95° `needy`ï¼\8cä½ å°\86ç\9c\8bå\88°ç±»ä¼¼ä»¥ä¸\8bç\9a\84é\94\99误ï¼\9a
+â\80¦â\80¦å\9b 为路å¾\84ä¸æ²¡æ\9c\89å¿\85é\80\89å\8f\82æ\95° `needy`ï¼\8cè¿\94å\9b\9eç\9a\84å\93\8dåº\94ä¸ä¼\9aæ\98¾ç¤ºå¦\82ä¸\8bé\94\99误信æ\81¯ï¼\9a
```JSON
{
}
```
-由于 `needy` 是必需参数，因此你需要在 URL 中设置它的值：
+`needy` 是必选参数，因此要在 URL 中设置值：
```
http://127.0.0.1:8000/items/foo-item?needy=sooooneedy
```
-...这样就正常了：
+……这样就正常了：
```JSON
{
}
```
-当然，你也可以定义一些参数为必需的，一些具有默认值，而某些则完全是可选的：
+当然，把一些参数定义为必选，为另一些参数设置默认值，再把其它参数定义为可选，这些操作都是可以的：
-```Python hl_lines="7"
+```Python hl_lines="10"
{!../../../docs_src/query_params/tutorial006.py!}
```
-在这个例子中，有3个查询参数：
+本例中有 3 个查询参数：
+
+* `needy`，必选的 `str` 类型参数
+* `skip`，默认值为 `0` 的 `int` 类型参数
+* `limit`，可选的 `int` 类型参数
-* `needy`，一个必需的 `str` 类型参数。
-* `skip`，一个默认值为 `0` 的 `int` 类型参数。
-* `limit`，一个可选的 `int` 类型参数。
+!!! tip "提示"
-!!! tip
- 你还可以像在 [路径参数](path-params.md#predefined-values){.internal-link target=_blank} 中那样使用 `Enum`。
+ 还可以像在[路径参数](path-params.md#predefined-values){.internal-link target=_blank} 中那样使用 `Enum`。
projects / thirdparty / fastapi / fastapi.git / commitdiff
