From ffb036b7d8e3a29d615d9d8f3c50f6dcd8247a77 Mon Sep 17 00:00:00 2001 From: jaystone776 Date: Mon, 1 Apr 2024 13:36:47 +0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=8C=90=20Update=20Chinese=20translation?= =?UTF-8?q?=20for=20`docs/zh/docs/tutorial/query-params.md`=20(#3480)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sebastián Ramírez Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> --- docs/zh/docs/tutorial/query-params.md | 102 ++++++++++++++------------ 1 file changed, 55 insertions(+), 47 deletions(-) diff --git a/docs/zh/docs/tutorial/query-params.md b/docs/zh/docs/tutorial/query-params.md index a0cc7fea3..308dd68a4 100644 --- a/docs/zh/docs/tutorial/query-params.md +++ b/docs/zh/docs/tutorial/query-params.md @@ -1,67 +1,67 @@ # 查询参数 -声明不属于路径参数的其他函数参数时，它们将被自动解释为"查询字符串"参数 +声明的参数不是路径参数时，路径操作函数会把该参数自动解释为**查询**参数。 ```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`：对应的值为 `0` -* `limit`：对应的值为 `10` +* `skip`：值为 `0` +* `limit`：值为 `10` -由于它们是 URL 的一部分，因此它们的"原始值"是字符串。 +这些值都是 URL 的组成部分，因此，它们的类型**本应**是字符串。 -但是，当你为它们声明了 Python 类型（在上面的示例中为 `int`）时，它们将转换为该类型并针对该类型进行校验。 +但声明 Python 类型（上例中为 `int`）之后，这些值就会转换为声明的类型，并进行类型校验。 -应用于路径参数的所有相同过程也适用于查询参数： +所有应用于路径参数的流程也适用于查询参数： -* （很明显的）编辑器支持 -* 数据"解析" +* （显而易见的）编辑器支持 +* 数据**解析** * 数据校验 -* 自动生成文档 +* 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+" @@ -76,20 +76,27 @@ http://127.0.0.1:8000/items/?skip=20 ``` -在这个例子中，函数参数 `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 @@ -119,42 +126,42 @@ http://127.0.0.1:8000/items/foo?short=on 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!} ``` -## 必需查询参数 +## 必选查询参数 -当你为非路径参数声明了默认值时（目前而言，我们所知道的仅有查询参数），则该参数不是必需的。 +为不是路径参数的参数声明默认值（至此，仅有查询参数），该参数就**不是必选**的了。 -如果你不想添加一个特定的值，而只是想使该参数成为可选的，则将默认值设置为 `None`。 +如果只想把参数设为**可选**，但又不想指定参数的值，则要把默认值设为 `None`。 -但当你想让一个查询参数成为必需的，不声明任何默认值就可以： +如果要把查询参数设置为**必选**，就不要声明默认值： ```Python hl_lines="6-7" {!../../../docs_src/query_params/tutorial005.py!} ``` -这里的查询参数 `needy` 是类型为 `str` 的必需查询参数。 +这里的查询参数 `needy` 是类型为 `str` 的必选查询参数。 -如果你在浏览器中打开一个像下面的 URL： +在浏览器中打开如下 URL： ``` http://127.0.0.1:8000/items/foo-item ``` -...因为没有添加必需的参数 `needy`，你将看到类似以下的错误： +……因为路径中没有必选参数 `needy`，返回的响应中会显示如下错误信息： ```JSON { @@ -171,13 +178,13 @@ http://127.0.0.1:8000/items/foo-item } ``` -由于 `needy` 是必需参数，因此你需要在 URL 中设置它的值： +`needy` 是必选参数，因此要在 URL 中设置值： ``` http://127.0.0.1:8000/items/foo-item?needy=sooooneedy ``` -...这样就正常了： +……这样就正常了： ```JSON { @@ -186,17 +193,18 @@ http://127.0.0.1:8000/items/foo-item?needy=sooooneedy } ``` -当然，你也可以定义一些参数为必需的，一些具有默认值，而某些则完全是可选的： +当然，把一些参数定义为必选，为另一些参数设置默认值，再把其它参数定义为可选，这些操作都是可以的： -```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`。