mirror of
https://github.com/fastapi/fastapi.git
synced 2026-10-22 18:06:17 -04:00
🔧 Add pre-commit with first config and first formatting pass (#4888)
* 🔧 Add first pre-commit config * 🎨 Format YAML files with pre-commit * 🎨 Format Markdown with pre-commit * 🎨 Format SVGs, drawio, JS, HTML with pre-commit * ➕ Add pre-commit to dev dependencies * ⬇️ Extend pre-commit range to support Python 3.6
This commit is contained in:
Sebastián Ramírez authored and GitHub committed
1 parent
9cbd42b13e
commit
3d0f130ff3
119 files changed
+228
-221
No files matched your search
@@ -83,7 +83,7 @@
|
||||
{!../../../docs_src/bigger_applications/app/routers/users.py!}
|
||||
```
|
||||
|
||||
### 使用 `APIRouter` 的*路径操作*
|
||||
### 使用 `APIRouter` 的*路径操作*
|
||||
|
||||
然后你可以使用它来声明*路径操作*。
|
||||
|
||||
@@ -334,7 +334,7 @@ from app.routers import items, users
|
||||
```Python
|
||||
from .routers import items, users
|
||||
```
|
||||
|
||||
|
||||
第二个版本是「绝对导入」：
|
||||
|
||||
```Python
|
||||
|
||||
@@ -228,7 +228,7 @@ images: List[Image]
|
||||
但是 Pydantic 具有自动转换数据的功能。
|
||||
|
||||
这意味着，即使你的 API 客户端只能将字符串作为键发送，只要这些字符串内容仅包含整数，Pydantic 就会对其进行转换并校验。
|
||||
|
||||
|
||||
然后你接收的名为 `weights` 的 `dict` 实际上将具有 `int` 类型的键和 `float` 类型的值。
|
||||
|
||||
## 总结
|
||||
|
||||
@@ -37,11 +37,11 @@
|
||||
!!! Note "笔记"
|
||||
|
||||
`PATCH` 没有 `PUT` 知名，也怎么不常用。
|
||||
|
||||
|
||||
很多人甚至只用 `PUT` 实现部分更新。
|
||||
|
||||
|
||||
**FastAPI** 对此没有任何限制，可以**随意**互换使用这两种操作。
|
||||
|
||||
|
||||
但本指南也会分别介绍这两种操作各自的用途。
|
||||
|
||||
### 使用 Pydantic 的 `exclude_unset` 参数
|
||||
@@ -95,7 +95,7 @@
|
||||
!!! note "笔记"
|
||||
|
||||
注意，输入模型仍需验证。
|
||||
|
||||
|
||||
因此，如果希望接收的部分更新数据可以省略其他所有属性，则要把模型中所有的属性标记为可选（使用默认值或 `None`）。
|
||||
|
||||
|
||||
为了区分用于**更新**所有可选值的模型与用于**创建**包含必选值的模型，请参照[更多模型](extra-models.md){.internal-link target=_blank} 一节中的思路。
|
||||
@@ -23,15 +23,15 @@
|
||||
!!! tip "提示"
|
||||
|
||||
有些编辑器会检查代码中没使用过的函数参数，并显示错误提示。
|
||||
|
||||
|
||||
在*路径操作装饰器*中使用 `dependencies` 参数，可以确保在执行依赖项的同时，避免编辑器显示错误提示。
|
||||
|
||||
|
||||
使用路径装饰器依赖项还可以避免开发新人误会代码中包含无用的未使用参数。
|
||||
|
||||
!!! info "说明"
|
||||
|
||||
本例中，使用的是自定义响应头 `X-Key` 和 `X-Token`。
|
||||
|
||||
|
||||
但实际开发中，尤其是在实现安全措施时，最好使用 FastAPI 内置的[安全工具](../security/index.md){.internal-link target=_blank}（详见下一章）。
|
||||
|
||||
## 依赖项错误和返回值
|
||||
|
||||
@@ -15,4 +15,3 @@
|
||||
## 为一组路径操作定义依赖项
|
||||
|
||||
稍后，[大型应用 - 多文件](../../tutorial/bigger-applications.md){.internal-link target=_blank}一章中会介绍如何使用多个文件创建大型应用程序，在这一章中，您将了解到如何为一组*路径操作*声明单个 `dependencies` 参数。
|
||||
|
||||
@@ -101,7 +101,7 @@ common_parameters --> read_users
|
||||
!!! check "检查"
|
||||
|
||||
注意，无需创建专门的类，并将之传递给 **FastAPI** 以进行「注册」或执行类似的操作。
|
||||
|
||||
|
||||
只要把它传递给 `Depends`，**FastAPI** 就知道该如何执行后续操作。
|
||||
|
||||
## 要不要使用 `async`？
|
||||
@@ -209,4 +209,4 @@ paying_user --> pro_items
|
||||
|
||||
在声明需求时，所有这些依赖项还会把参数、验证等功能添加至路径操作。
|
||||
|
||||
**FastAPI** 负责把上述内容全部添加到 OpenAPI 概图，并显示在交互文档中。
|
||||
**FastAPI** 负责把上述内容全部添加到 OpenAPI 概图，并显示在交互文档中。
|
||||
@@ -44,7 +44,7 @@ FastAPI 支持创建含**子依赖项**的依赖项。
|
||||
!!! info "信息"
|
||||
|
||||
注意，这里在*路径操作函数*中只声明了一个依赖项，即 `query_or_cookie_extractor` 。
|
||||
|
||||
|
||||
但 **FastAPI** 必须先处理 `query_extractor`，以便在调用 `query_or_cookie_extractor` 时使用 `query_extractor` 返回的结果。
|
||||
|
||||
```mermaid
|
||||
@@ -82,7 +82,7 @@ async def needy_dependency(fresh_value: str = Depends(get_value, use_cache=False
|
||||
!!! tip "提示"
|
||||
|
||||
这些简单的例子现在看上去虽然没有什么实用价值，
|
||||
|
||||
|
||||
但在**安全**一章中，您会了解到这些例子的用途，
|
||||
|
||||
以及这些例子所能节省的代码量。
|
||||
|
||||
以及这些例子所能节省的代码量。
|
||||
@@ -22,7 +22,7 @@
|
||||
下面是一些你可以使用的其他数据类型:
|
||||
|
||||
* `UUID`:
|
||||
* 一种标准的 "通用唯一标识符" ，在许多数据库和系统中用作ID。
|
||||
* 一种标准的 "通用唯一标识符" ，在许多数据库和系统中用作ID。
|
||||
* 在请求和响应中将以 `str` 表示。
|
||||
* `datetime.datetime`:
|
||||
* 一个 Python `datetime.datetime`.
|
||||
|
||||
@@ -30,7 +30,7 @@ $ uvicorn main:app --reload
|
||||
* `main`：`main.py` 文件（一个 Python「模块」）。
|
||||
* `app`：在 `main.py` 文件中通过 `app = FastAPI()` 创建的对象。
|
||||
* `--reload`：让服务器在更新代码后重新启动。仅在开发时使用该选项。
|
||||
|
||||
|
||||
|
||||
在输出中，会有一行信息像下面这样：
|
||||
|
||||
|
||||
@@ -286,4 +286,4 @@ FastAPI 支持先对异常进行某些处理，然后再使用 **FastAPI** 中
|
||||
|
||||
虽然，本例只是输出了夸大其词的错误信息。
|
||||
|
||||
但也足以说明，可以在处理异常之后再复用默认的异常处理器。
|
||||
但也足以说明，可以在处理异常之后再复用默认的异常处理器。
|
||||
@@ -23,7 +23,7 @@
|
||||
!!! note "技术细节"
|
||||
|
||||
也可以使用 `from starlette import status` 导入状态码。
|
||||
|
||||
|
||||
**FastAPI** 的`fastapi.status` 和 `starlette.status` 一样，只是快捷方式。实际上，`fastapi.status` 直接继承自 Starlette。
|
||||
|
||||
## `tags` 参数
|
||||
@@ -75,7 +75,7 @@ OpenAPI 概图会自动添加标签，供 API 文档接口使用：
|
||||
!!! check "检查"
|
||||
|
||||
OpenAPI 规定每个*路径操作*都要有响应描述。
|
||||
|
||||
|
||||
如果没有定义响应描述，**FastAPI** 则自动生成内容为 "Successful response" 的响应描述。
|
||||
|
||||
<img src="/img/tutorial/path-operation-configuration/image03.png">
|
||||
|
||||
@@ -22,7 +22,7 @@
|
||||
|
||||
!!! note
|
||||
路径参数总是必需的，因为它必须是路径的一部分。
|
||||
|
||||
|
||||
所以，你应该在声明时使用 `...` 将其标记为必需参数。
|
||||
|
||||
然而，即使你使用 `None` 声明路径参数或设置一个其他默认值也不会有任何影响，它依然会是必需参数。
|
||||
|
||||
@@ -5,9 +5,9 @@
|
||||
!!! info "说明"
|
||||
|
||||
因为上传文件以「表单数据」形式发送。
|
||||
|
||||
|
||||
所以接收上传文件，要预先安装 <a href="https://andrew-d.github.io/python-multipart/" class="external-link" target="_blank">`python-multipart`</a>。
|
||||
|
||||
|
||||
例如： `pip install python-multipart`。
|
||||
|
||||
## 导入 `File`
|
||||
@@ -29,7 +29,7 @@
|
||||
!!! info "说明"
|
||||
|
||||
`File` 是直接继承自 `Form` 的类。
|
||||
|
||||
|
||||
注意，从 `fastapi` 导入的 `Query`、`Path`、`File` 等项，实际上是返回特定类的函数。
|
||||
|
||||
!!! tip "提示"
|
||||
@@ -109,15 +109,15 @@ contents = myfile.file.read()
|
||||
!!! note "技术细节"
|
||||
|
||||
不包含文件时，表单数据一般用 `application/x-www-form-urlencoded`「媒体类型」编码。
|
||||
|
||||
|
||||
但表单包含文件时，编码为 `multipart/form-data`。使用了 `File`，**FastAPI** 就知道要从请求体的正确位置获取文件。
|
||||
|
||||
|
||||
编码和表单字段详见 <a href="https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Methods/POST" class="external-link" target="_blank"><abbr title="Mozilla Developer Network">MDN</abbr> Web 文档的 <code>POST </code></a> 小节。
|
||||
|
||||
!!! warning "警告"
|
||||
|
||||
可在一个*路径操作*中声明多个 `File` 和 `Form` 参数，但不能同时声明要接收 JSON 的 `Body` 字段。因为此时请求体的编码是 `multipart/form-data`，不是 `application/json`。
|
||||
|
||||
|
||||
这不是 **FastAPI** 的问题，而是 HTTP 协议的规定。
|
||||
|
||||
## 多文件上传
|
||||
@@ -137,17 +137,17 @@ FastAPI 支持同时上传多个文件。
|
||||
!!! note "笔记"
|
||||
|
||||
注意，截至 2019 年 4 月 14 日，Swagger UI 不支持在同一个表单字段中上传多个文件。详见 <a href="https://github.com/swagger-api/swagger-ui/issues/4276" class="external-link" target="_blank">#4276</a> 和 <a href="https://github.com/swagger-api/swagger-ui/issues/3641" class="external-link" target="_blank">#3641</a>.
|
||||
|
||||
|
||||
不过，**FastAPI** 已通过 OpenAPI 标准与之兼容。
|
||||
|
||||
|
||||
因此，只要 Swagger UI 或任何其他支持 OpenAPI 的工具支持多文件上传，都将与 **FastAPI** 兼容。
|
||||
|
||||
!!! note "技术细节"
|
||||
|
||||
也可以使用 `from starlette.responses import HTMLResponse`。
|
||||
|
||||
|
||||
`fastapi.responses` 其实与 `starlette.responses` 相同，只是为了方便开发者调用。实际上，大多数 **FastAPI** 的响应都直接从 Starlette 调用。
|
||||
|
||||
## 小结
|
||||
|
||||
本节介绍了如何用 `File` 把上传文件声明为（表单数据的）输入参数。
|
||||
本节介绍了如何用 `File` 把上传文件声明为（表单数据的）输入参数。
|
||||
@@ -5,7 +5,7 @@ FastAPI 支持同时使用 `File` 和 `Form` 定义文件和表单字段。
|
||||
!!! info "说明"
|
||||
|
||||
接收上传文件或表单数据，要预先安装 <a href="https://andrew-d.github.io/python-multipart/" class="external-link" target="_blank">`python-multipart`</a>。
|
||||
|
||||
|
||||
例如，`pip install python-multipart`。
|
||||
|
||||
## 导入 `File` 与 `Form`
|
||||
@@ -29,10 +29,9 @@ FastAPI 支持同时使用 `File` 和 `Form` 定义文件和表单字段。
|
||||
!!! warning "警告"
|
||||
|
||||
可在一个*路径操作*中声明多个 `File` 与 `Form` 参数，但不能同时声明要接收 JSON 的 `Body` 字段。因为此时请求体的编码为 `multipart/form-data`，不是 `application/json`。
|
||||
|
||||
|
||||
这不是 **FastAPI** 的问题，而是 HTTP 协议的规定。
|
||||
|
||||
## 小结
|
||||
|
||||
在同一个请求中接收数据和文件时，应同时使用 `File` 和 `Form`。
|
||||
|
||||
@@ -5,7 +5,7 @@
|
||||
!!! info "说明"
|
||||
|
||||
要使用表单，需预先安装 <a href="https://andrew-d.github.io/python-multipart/" class="external-link" target="_blank">`python-multipart`</a>。
|
||||
|
||||
|
||||
例如，`pip install python-multipart`。
|
||||
|
||||
## 导入 `Form`
|
||||
@@ -47,17 +47,17 @@
|
||||
!!! note "技术细节"
|
||||
|
||||
表单数据的「媒体类型」编码一般为 `application/x-www-form-urlencoded`。
|
||||
|
||||
|
||||
但包含文件的表单编码为 `multipart/form-data`。文件处理详见下节。
|
||||
|
||||
|
||||
编码和表单字段详见 <a href="https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Methods/POST" class="external-link" target="_blank"><abbr title="Mozilla Developer Network">MDN</abbr> Web 文档的 <code>POST</code></a>小节。
|
||||
|
||||
!!! warning "警告"
|
||||
|
||||
可在一个*路径操作*中声明多个 `Form` 参数，但不能同时声明要接收 JSON 的 `Body` 字段。因为此时请求体的编码是 `application/x-www-form-urlencoded`，不是 `application/json`。
|
||||
|
||||
|
||||
这不是 **FastAPI** 的问题，而是 HTTP 协议的规定。
|
||||
|
||||
## 小结
|
||||
|
||||
本节介绍了如何使用 `Form` 声明表单数据输入参数。
|
||||
本节介绍了如何使用 `Form` 声明表单数据输入参数。
|
||||
@@ -31,7 +31,7 @@
|
||||
|
||||
你可以通过传递额外信息给 `Field` 同样的方式操作`Path`, `Query`, `Body`等。
|
||||
|
||||
比如，你可以将请求体的一个 `example` 传递给 `Body`:
|
||||
比如，你可以将请求体的一个 `example` 传递给 `Body`:
|
||||
|
||||
```Python hl_lines="21-26"
|
||||
{!../../../docs_src/schema_extra_example/tutorial003.py!}
|
||||
|
||||
@@ -98,4 +98,4 @@ FastAPI 在 `fastapi.security` 模块中为每个安全方案提供了几种工
|
||||
|
||||
在下一章中，你将看到如何使用 **FastAPI** 所提供的这些工具为你的 API 增加安全性。
|
||||
|
||||
而且你还将看到它如何自动地被集成到交互式文档系统中。
|
||||
而且你还将看到它如何自动地被集成到交互式文档系统中。
|
||||
@@ -263,4 +263,3 @@ OAuth2 具有「作用域」的概念。
|
||||
而且你可以用相对简单的方式使用和实现安全、标准的协议，比如 OAuth2。
|
||||
|
||||
你可以在**进阶用户指南**中了解更多关于如何使用 OAuth2 「作用域」的信息，以实现更精细的权限系统，并同样遵循这些标准。带有作用域的 OAuth2 是很多大的认证提供商使用的机制，比如 Facebook、Google、GitHub、微软、Twitter 等，授权第三方应用代表用户与他们的 API 进行交互。
|
||||
|
||||
Reference in new issue
Block a user