+
+## Combine predefined responses and custom ones
+
+You might want to have some predefined responses that apply to many *path operations*, but you want to combine them with custom responses needed by each *path operation*.
+
+For those cases, you can use the Python technique of "unpacking" a `dict` with `**dict_to_unpack`:
+
+```Python
+old_dict = {
+ "old key": "old value",
+ "second old key": "second old value",
+}
+new_dict = {**old_dict, "new key": "new value"}
+```
+
+Here, `new_dict` will contain all the key-value pairs from `old_dict` plus the new key-value pair:
+
+```Python
+{
+ "old key": "old value",
+ "second old key": "second old value",
+ "new key": "new value",
+}
+```
+
+You can use that technique to re-use some predefined responses in your *path operations* and combine them with additional custom ones.
+
+For example:
+
+```Python hl_lines="13-17 26"
+{!../../../docs_src/additional_responses/tutorial004.py!}
+```
+
+## More information about OpenAPI responses
+
+To see what exactly you can include in the responses, you can check these sections in the OpenAPI specification:
+
+* 
+
+## More info
+
+You can read more about 
+
+But if we access the docs UI at the "official" URL using the proxy with port `9999`, at `/api/v1/docs`, it works correctly! 🎉
+
+You can check it at 
+
+Right as we wanted it. ✔️
+
+This is because FastAPI uses this `root_path` to create the default `server` in OpenAPI with the URL provided by `root_path`.
+
+## Additional servers
+
+!!! warning
+ This is a more advanced use case. Feel free to skip it.
+
+By default, **FastAPI** will create a `server` in the OpenAPI schema with the URL for the `root_path`.
+
+But you can also provide other alternative `servers`, for example if you want *the same* docs UI to interact with a staging and production environments.
+
+If you pass a custom list of `servers` and there's a `root_path` (because your API lives behind a proxy), **FastAPI** will insert a "server" with this `root_path` at the beginning of the list.
+
+For example:
+
+```Python hl_lines="4-7"
+{!../../../docs_src/behind_a_proxy/tutorial003.py!}
+```
+
+Will generate an OpenAPI schema like:
+
+```JSON hl_lines="5-7"
+{
+ "openapi": "3.1.0",
+ // More stuff here
+ "servers": [
+ {
+ "url": "/api/v1"
+ },
+ {
+ "url": "https://stag.example.com",
+ "description": "Staging environment"
+ },
+ {
+ "url": "https://prod.example.com",
+ "description": "Production environment"
+ }
+ ],
+ "paths": {
+ // More stuff here
+ }
+}
+```
+
+!!! tip
+ Notice the auto-generated server with a `url` value of `/api/v1`, taken from the `root_path`.
+
+In the docs UI at 
+
+!!! tip
+ The docs UI will interact with the server that you select.
+
+### Disable automatic server from `root_path`
+
+If you don't want **FastAPI** to include an automatic server using the `root_path`, you can use the parameter `root_path_in_servers=False`:
+
+```Python hl_lines="9"
+{!../../../docs_src/behind_a_proxy/tutorial004.py!}
+```
+
+and then it won't include it in the OpenAPI schema.
+
+## Mounting a sub-application
+
+If you need to mount a sub-application (as described in [Sub Applications - Mounts](./sub-applications.md){.internal-link target=_blank}) while also using a proxy with `root_path`, you can do it normally, as you would expect.
+
+FastAPI will internally use the `root_path` smartly, so it will just work. ✨
diff --git a/docs/zh/docs/advanced/conditional-openapi.md b/docs/zh/docs/advanced/conditional-openapi.md
new file mode 100644
index 0000000000000..add16fbec519e
--- /dev/null
+++ b/docs/zh/docs/advanced/conditional-openapi.md
@@ -0,0 +1,58 @@
+# Conditional OpenAPI
+
+If you needed to, you could use settings and environment variables to configure OpenAPI conditionally depending on the environment, and even disable it entirely.
+
+## About security, APIs, and docs
+
+Hiding your documentation user interfaces in production *shouldn't* be the way to protect your API.
+
+That doesn't add any extra security to your API, the *path operations* will still be available where they are.
+
+If there's a security flaw in your code, it will still exist.
+
+Hiding the documentation just makes it more difficult to understand how to interact with your API, and could make it more difficult for you to debug it in production. It could be considered simply a form of 
+
+
+## Dataclasses in Nested Data Structures
+
+You can also combine `dataclasses` with other type annotations to make nested data structures.
+
+In some cases, you might still have to use Pydantic's version of `dataclasses`. For example, if you have errors with the automatically generated API documentation.
+
+In that case, you can simply swap the standard `dataclasses` with `pydantic.dataclasses`, which is a drop-in replacement:
+
+```{ .python .annotate hl_lines="1 5 8-11 14-17 23-25 28" }
+{!../../../docs_src/dataclasses/tutorial003.py!}
+```
+
+1. We still import `field` from standard `dataclasses`.
+
+2. `pydantic.dataclasses` is a drop-in replacement for `dataclasses`.
+
+3. The `Author` dataclass includes a list of `Item` dataclasses.
+
+4. The `Author` dataclass is used as the `response_model` parameter.
+
+5. You can use other standard type annotations with dataclasses as the request body.
+
+ In this case, it's a list of `Item` dataclasses.
+
+6. Here we are returning a dictionary that contains `items` which is a list of dataclasses.
+
+ FastAPI is still capable of serializing the data to JSON.
+
+7. Here the `response_model` is using a type annotation of a list of `Author` dataclasses.
+
+ Again, you can combine `dataclasses` with standard type annotations.
+
+8. Notice that this *path operation function* uses regular `def` instead of `async def`.
+
+ As always, in FastAPI you can combine `def` and `async def` as needed.
+
+ If you need a refresher about when to use which, check out the section _"In a hurry?"_ in the docs about 
+
+## Self-hosting JavaScript and CSS for docs
+
+The API docs use **Swagger UI** and **ReDoc**, and each of those need some JavaScript and CSS files.
+
+By default, those files are served from a CDN.
+
+But it's possible to customize it, you can set a specific CDN, or serve the files yourself.
+
+That's useful, for example, if you need your app to keep working even while offline, without open Internet access, or in a local network.
+
+Here you'll see how to serve those files yourself, in the same FastAPI app, and configure the docs to use them.
+
+### Project file structure
+
+Let's say your project file structure looks like this:
+
+```
+.
+├── app
+│ ├── __init__.py
+│ ├── main.py
+```
+
+Now create a directory to store those static files.
+
+Your new file structure could look like this:
+
+```
+.
+├── app
+│ ├── __init__.py
+│ ├── main.py
+└── static/
+```
+
+### Download the files
+
+Download the static files needed for the docs and put them on that `static/` directory.
+
+You can probably right-click each link and select an option similar to `Save link as...`.
+
+**Swagger UI** uses the files:
+
+* 
+
+But you can disable it by setting `syntaxHighlight` to `False`:
+
+```Python hl_lines="3"
+{!../../../docs_src/extending_openapi/tutorial003.py!}
+```
+
+...and then Swagger UI won't show the syntax highlighting anymore:
+
+
+
+### Change the Theme
+
+The same way you could set the syntax highlighting theme with the key `"syntaxHighlight.theme"` (notice that it has a dot in the middle):
+
+```Python hl_lines="3"
+{!../../../docs_src/extending_openapi/tutorial004.py!}
+```
+
+That configuration would change the syntax highlighting color theme:
+
+
+
+### Change Default Swagger UI Parameters
+
+FastAPI includes some default configuration parameters appropriate for most of the use cases.
+
+It includes these default configurations:
+
+```Python
+{!../../../fastapi/openapi/docs.py[ln:7-13]!}
+```
+
+You can override any of them by setting a different value in the argument `swagger_ui_parameters`.
+
+For example, to disable `deepLinking` you could pass these settings to `swagger_ui_parameters`:
+
+```Python hl_lines="3"
+{!../../../docs_src/extending_openapi/tutorial005.py!}
+```
+
+### Other Swagger UI Parameters
+
+To see all the other possible configurations you can use, read the official 
+
+You can see those schemas because they were declared with the models in the app.
+
+That information is available in the app's **OpenAPI schema**, and then shown in the API docs (by Swagger UI).
+
+And that same information from the models that is included in OpenAPI is what can be used to **generate the client code**.
+
+### Generate a TypeScript Client
+
+Now that we have the app with the models, we can generate the client code for the frontend.
+
+#### Install `openapi-typescript-codegen`
+
+You can install `openapi-typescript-codegen` in your frontend code with:
+
+
+
+You will also get autocompletion for the payload to send:
+
+
+
+!!! tip
+ Notice the autocompletion for `name` and `price`, that was defined in the FastAPI application, in the `Item` model.
+
+You will have inline errors for the data that you send:
+
+
+
+The response object will also have autocompletion:
+
+
+
+## FastAPI App with Tags
+
+In many cases your FastAPI app will be bigger, and you will probably use tags to separate different groups of *path operations*.
+
+For example, you could have a section for **items** and another section for **users**, and they could be separated by tags:
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="21 26 34"
+ {!> ../../../docs_src/generate_clients/tutorial002_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="23 28 36"
+ {!> ../../../docs_src/generate_clients/tutorial002.py!}
+ ```
+
+### Generate a TypeScript Client with Tags
+
+If you generate a client for a FastAPI app using tags, it will normally also separate the client code based on the tags.
+
+This way you will be able to have things ordered and grouped correctly for the client code:
+
+
+
+In this case you have:
+
+* `ItemsService`
+* `UsersService`
+
+### Client Method Names
+
+Right now the generated method names like `createItemItemsPost` don't look very clean:
+
+```TypeScript
+ItemsService.createItemItemsPost({name: "Plumbus", price: 5})
+```
+
+...that's because the client generator uses the OpenAPI internal **operation ID** for each *path operation*.
+
+OpenAPI requires that each operation ID is unique across all the *path operations*, so FastAPI uses the **function name**, the **path**, and the **HTTP method/operation** to generate that operation ID, because that way it can make sure that the operation IDs are unique.
+
+But I'll show you how to improve that next. 🤓
+
+## Custom Operation IDs and Better Method Names
+
+You can **modify** the way these operation IDs are **generated** to make them simpler and have **simpler method names** in the clients.
+
+In this case you will have to ensure that each operation ID is **unique** in some other way.
+
+For example, you could make sure that each *path operation* has a tag, and then generate the operation ID based on the **tag** and the *path operation* **name** (the function name).
+
+### Custom Generate Unique ID Function
+
+FastAPI uses a **unique ID** for each *path operation*, it is used for the **operation ID** and also for the names of any needed custom models, for requests or responses.
+
+You can customize that function. It takes an `APIRoute` and outputs a string.
+
+For example, here it is using the first tag (you will probably have only one tag) and the *path operation* name (the function name).
+
+You can then pass that custom function to **FastAPI** as the `generate_unique_id_function` parameter:
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="6-7 10"
+ {!> ../../../docs_src/generate_clients/tutorial003_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="8-9 12"
+ {!> ../../../docs_src/generate_clients/tutorial003.py!}
+ ```
+
+### Generate a TypeScript Client with Custom Operation IDs
+
+Now if you generate the client again, you will see that it has the improved method names:
+
+
+
+As you see, the method names now have the tag and then the function name, now they don't include information from the URL path and the HTTP operation.
+
+### Preprocess the OpenAPI Specification for the Client Generator
+
+The generated code still has some **duplicated information**.
+
+We already know that this method is related to the **items** because that word is in the `ItemsService` (taken from the tag), but we still have the tag name prefixed in the method name too. 😕
+
+We will probably still want to keep it for OpenAPI in general, as that will ensure that the operation IDs are **unique**.
+
+But for the generated client we could **modify** the OpenAPI operation IDs right before generating the clients, just to make those method names nicer and **cleaner**.
+
+We could download the OpenAPI JSON to a file `openapi.json` and then we could **remove that prefixed tag** with a script like this:
+
+```Python
+{!../../../docs_src/generate_clients/tutorial004.py!}
+```
+
+With that, the operation IDs would be renamed from things like `items-get_items` to just `get_items`, that way the client generator can generate simpler method names.
+
+### Generate a TypeScript Client with the Preprocessed OpenAPI
+
+Now as the end result is in a file `openapi.json`, you would modify the `package.json` to use that local file, for example:
+
+```JSON hl_lines="7"
+{
+ "name": "frontend-app",
+ "version": "1.0.0",
+ "description": "",
+ "main": "index.js",
+ "scripts": {
+ "generate-client": "openapi --input ./openapi.json --output ./src/client --client axios"
+ },
+ "author": "",
+ "license": "",
+ "devDependencies": {
+ "openapi-typescript-codegen": "^0.20.1",
+ "typescript": "^4.6.2"
+ }
+}
+```
+
+After generating the new client, you would now have **clean method names**, with all the **autocompletion**, **inline errors**, etc:
+
+
+
+## Benefits
+
+When using the automatically generated clients you would **autocompletion** for:
+
+* Methods.
+* Request payloads in the body, query parameters, etc.
+* Response payloads.
+
+You would also have **inline errors** for everything.
+
+And whenever you update the backend code, and **regenerate** the frontend, it would have any new *path operations* available as methods, the old ones removed, and any other change would be reflected on the generated code. 🤓
+
+This also means that if something changed it will be **reflected** on the client code automatically. And if you **build** the client it will error out if you have any **mismatch** in the data used.
+
+So, you would **detect many errors** very early in the development cycle instead of having to wait for the errors to show up to your final users in production and then trying to debug where the problem is. ✨
diff --git a/docs/zh/docs/advanced/graphql.md b/docs/zh/docs/advanced/graphql.md
new file mode 100644
index 0000000000000..1d2753fc4ce1b
--- /dev/null
+++ b/docs/zh/docs/advanced/graphql.md
@@ -0,0 +1,59 @@
+# GraphQL
+
+As **FastAPI** is based on the **ASGI** standard, it's very easy to integrate any **GraphQL** library also compatible with ASGI.
+
+You can combine normal FastAPI *path operations* with GraphQL on the same application.
+
+!!! tip
+ **GraphQL** solves some very specific use cases.
+
+ It has **advantages** and **disadvantages** when compared to common **web APIs**.
+
+ Make sure you evaluate if the **benefits** for your use case compensate the **drawbacks**. 🤓
+
+## GraphQL Libraries
+
+Here are some of the **GraphQL** libraries that have **ASGI** support. You could use them with **FastAPI**:
+
+* 
diff --git a/docs/zh/docs/advanced/openapi-webhooks.md b/docs/zh/docs/advanced/openapi-webhooks.md
new file mode 100644
index 0000000000000..a41f8c820490d
--- /dev/null
+++ b/docs/zh/docs/advanced/openapi-webhooks.md
@@ -0,0 +1,51 @@
+# OpenAPI Webhooks
+
+There are cases where you want to tell your API **users** that your app could call *their* app (sending a request) with some data, normally to **notify** of some type of **event**.
+
+This means that instead of the normal process of your users sending requests to your API, it's **your API** (or your app) that could **send requests to their system** (to their API, their app).
+
+This is normally called a **webhook**.
+
+## Webhooks steps
+
+The process normally is that **you define** in your code what is the message that you will send, the **body of the request**.
+
+You also define in some way at which **moments** your app will send those requests or events.
+
+And **your users** define in some way (for example in a web dashboard somewhere) the **URL** where your app should send those requests.
+
+All the **logic** about how to register the URLs for webhooks and the code to actually send those requests is up to you. You write it however you want to in **your own code**.
+
+## Documenting webhooks with **FastAPI** and OpenAPI
+
+With **FastAPI**, using OpenAPI, you can define the names of these webhooks, the types of HTTP operations that your app can send (e.g. `POST`, `PUT`, etc.) and the request **bodies** that your app would send.
+
+This can make it a lot easier for your users to **implement their APIs** to receive your **webhook** requests, they might even be able to autogenerate some of their own API code.
+
+!!! info
+ Webhooks are available in OpenAPI 3.1.0 and above, supported by FastAPI `0.99.0` and above.
+
+## An app with webhooks
+
+When you create a **FastAPI** application, there is a `webhooks` attribute that you can use to define *webhooks*, the same way you would define *path operations*, for example with `@app.webhooks.post()`.
+
+```Python hl_lines="9-13 36-53"
+{!../../../docs_src/openapi_webhooks/tutorial001.py!}
+```
+
+The webhooks that you define will end up in the **OpenAPI** schema and the automatic **docs UI**.
+
+!!! info
+ The `app.webhooks` object is actually just an `APIRouter`, the same type you would use when structuring your app with multiple files.
+
+Notice that with webhooks you are actually not declaring a *path* (like `/items/`), the text you pass there is just an **identifier** of the webhook (the name of the event), for example in `@app.webhooks.post("new-subscription")`, the webhook name is `new-subscription`.
+
+This is because it is expected that **your users** would define the actual **URL path** where they want to receive the webhook request in some other way (e.g. a web dashboard).
+
+### Check the docs
+
+Now you can start your app with Uvicorn and go to 
diff --git a/docs/zh/docs/advanced/path-operation-advanced-configuration.md b/docs/zh/docs/advanced/path-operation-advanced-configuration.md
index 7da9f251e30db..b9cbd79f35f9d 100644
--- a/docs/zh/docs/advanced/path-operation-advanced-configuration.md
+++ b/docs/zh/docs/advanced/path-operation-advanced-configuration.md
@@ -2,12 +2,12 @@
## OpenAPI 的 operationId
-!!! warning
+!!! !!! warning
如果你并非 OpenAPI 的「专家」，你可能不需要这部分内容。
你可以在路径操作中通过参数 `operation_id` 设置要使用的 OpenAPI `operationId`。
-务必确保每个操作路径的 `operation_id` 都是唯一的。
+You would have to make sure that it is unique for each operation.
```Python hl_lines="6"
{!../../../docs_src/path_operation_advanced_configuration/tutorial001.py!}
@@ -19,14 +19,14 @@
你应该在添加了所有 *路径操作* 之后执行此操作。
-```Python hl_lines="2 12 13 14 15 16 17 18 19 20 21 24"
+```Python hl_lines="2 12-21 24"
{!../../../docs_src/path_operation_advanced_configuration/tutorial002.py!}
```
-!!! tip
+!!! !!! tip
如果你手动调用 `app.openapi()`，你应该在此之前更新 `operationId`。
-!!! warning
+!!! !!! warning
如果你这样做，务必确保你的每个 *路径操作函数* 的名字唯一。
即使它们在不同的模块中（Python 文件）。
@@ -47,7 +47,146 @@
剩余部分不会出现在文档中，但是其他工具（比如 Sphinx）可以使用剩余部分。
-
-```Python hl_lines="19 20 21 22 23 24 25 26 27 28 29"
+```Python hl_lines="19-29"
{!../../../docs_src/path_operation_advanced_configuration/tutorial004.py!}
```
+
+## Additional Responses
+
+You probably have seen how to declare the `response_model` and `status_code` for a *path operation*.
+
+That defines the metadata about the main response of a *path operation*.
+
+You can also declare additional responses with their models, status codes, etc.
+
+There's a whole chapter here in the documentation about it, you can read it at [Additional Responses in OpenAPI](./additional-responses.md){.internal-link target=_blank}.
+
+## OpenAPI Extra
+
+When you declare a *path operation* in your application, **FastAPI** automatically generates the relevant metadata about that *path operation* to be included in the OpenAPI schema.
+
+!!! note "Technical details"
+ In the OpenAPI specification it is called the 
+
+And if you see the resulting OpenAPI (at `/openapi.json` in your API), you will see your extension as part of the specific *path operation* too:
+
+```JSON hl_lines="22"
+{
+ "openapi": "3.1.0",
+ "info": {
+ "title": "FastAPI",
+ "version": "0.1.0"
+ },
+ "paths": {
+ "/items/": {
+ "get": {
+ "summary": "Read Items",
+ "operationId": "read_items_items__get",
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {
+ "application/json": {
+ "schema": {}
+ }
+ }
+ }
+ },
+ "x-aperture-labs-portal": "blue"
+ }
+ }
+ }
+}
+```
+
+### Custom OpenAPI *path operation* schema
+
+The dictionary in `openapi_extra` will be deeply merged with the automatically generated OpenAPI schema for the *path operation*.
+
+So, you could add additional data to the automatically generated schema.
+
+For example, you could decide to read and validate the request with your own code, without using the automatic features of FastAPI with Pydantic, but you could still want to define the request in the OpenAPI schema.
+
+You could do that with `openapi_extra`:
+
+```Python hl_lines="20-37 39-40"
+{!../../../docs_src/path_operation_advanced_configuration/tutorial006.py!}
+```
+
+In this example, we didn't declare any Pydantic model. In fact, the request body is not even parsed as JSON, it is read directly as `bytes`, and the function `magic_data_reader()` would be in charge of parsing it in some way.
+
+Nevertheless, we can declare the expected schema for the request body.
+
+### Custom OpenAPI content type
+
+Using this same trick, you could use a Pydantic model to define the JSON Schema that is then included in the custom OpenAPI schema section for the *path operation*.
+
+And you could do this even if the data type in the request is not JSON.
+
+For example, in this application we don't use FastAPI's integrated functionality to extract the JSON Schema from Pydantic models nor the automatic validation for JSON. In fact, we are declaring the request content type as YAML, not JSON:
+
+=== "Pydantic v2"
+
+ ```Python hl_lines="17-22 24"
+ {!> ../../../docs_src/path_operation_advanced_configuration/tutorial007.py!}
+ ```
+
+=== "Pydantic v1"
+
+ ```Python hl_lines="17-22 24"
+ {!> ../../../docs_src/path_operation_advanced_configuration/tutorial007_pv1.py!}
+ ```
+
+!!! info
+ In Pydantic version 1 the method to get the JSON Schema for a model was called `Item.schema()`, in Pydantic version 2, the method is called `Item.model_schema_json()`.
+
+Nevertheless, although we are not using the default integrated functionality, we are still using a Pydantic model to manually generate the JSON Schema for the data that we want to receive in YAML.
+
+Then we use the request directly, and extract the body as `bytes`. This means that FastAPI won't even try to parse the request payload as JSON.
+
+And then in our code, we parse that YAML content directly, and then we are again using the same Pydantic model to validate the YAML content:
+
+=== "Pydantic v2"
+
+ ```Python hl_lines="26-33"
+ {!> ../../../docs_src/path_operation_advanced_configuration/tutorial007.py!}
+ ```
+
+=== "Pydantic v1"
+
+ ```Python hl_lines="26-33"
+ {!> ../../../docs_src/path_operation_advanced_configuration/tutorial007_pv1.py!}
+ ```
+
+!!! info
+ In Pydantic version 1 the method to parse and validate an object was `Item.parse_obj()`, in Pydantic version 2, the method is called `Item.model_validate()`.
+
+!!! tip
+ Here we re-use the same Pydantic model.
+
+ But the same way, we could have validated it in some other way.
diff --git a/docs/zh/docs/advanced/response-change-status-code.md b/docs/zh/docs/advanced/response-change-status-code.md
index a289cf20178f0..3bc41be37ad22 100644
--- a/docs/zh/docs/advanced/response-change-status-code.md
+++ b/docs/zh/docs/advanced/response-change-status-code.md
@@ -24,8 +24,10 @@
{!../../../docs_src/response_change_status_code/tutorial001.py!}
```
-然后你可以像平常一样返回任何你需要的对象（例如一个`dict`或者一个数据库模型）。如果你声明了一个`response_model`，它仍然会被用来过滤和转换你返回的对象。
+然后你可以像平常一样返回任何你需要的对象（例如一个`dict`或者一个数据库模型）。
+
+如果你声明了一个`response_model`，它仍然会被用来过滤和转换你返回的对象。
**FastAPI**将使用这个临时响应来提取状态码（也包括cookies和头部），并将它们放入包含你返回的值的最终响应中，该响应由任何`response_model`过滤。
-你也可以在依赖项中声明`Response`参数，并在其中设置状态码。但请注意，最后设置的状态码将会生效。
+你也可以在依赖项中声明`Response`参数，并在其中设置状态码。 但请注意，最后设置的状态码将会生效。
diff --git a/docs/zh/docs/advanced/response-cookies.md b/docs/zh/docs/advanced/response-cookies.md
index 3e53c53191a4c..810119ea8a6eb 100644
--- a/docs/zh/docs/advanced/response-cookies.md
+++ b/docs/zh/docs/advanced/response-cookies.md
@@ -4,6 +4,8 @@
你可以在 *路径函数* 中定义一个类型为 `Response`的参数，这样你就可以在这个临时响应对象中设置cookie了。
+And then you can set cookies in that *temporal* response object.
+
```Python hl_lines="1 8-9"
{!../../../docs_src/response_cookies/tutorial002.py!}
```
@@ -14,11 +16,11 @@
**FastAPI** 会使用这个 *临时* 响应对象去装在这些cookies信息 (同样还有headers和状态码等信息), 最终会将这些信息和通过`response_model`转化过的数据合并到最终的响应里。
-你也可以在depend中定义`Response`参数，并设置cookie和header。
+你还可以在直接响应`Response`时直接创建cookies。
## 直接响应 `Response`
-你还可以在直接响应`Response`时直接创建cookies。
+你也可以在depend中定义`Response`参数，并设置cookie和header。
你可以参考[Return a Response Directly](response-directly.md){.internal-link target=_blank}来创建response
@@ -28,20 +30,20 @@
{!../../../docs_src/response_cookies/tutorial001.py!}
```
-!!! tip
+!!! !!! tip
需要注意，如果你直接反馈一个response对象，而不是使用`Response`入参，FastAPI则会直接反馈你封装的response对象。
- 所以你需要确保你响应数据类型的正确性，如：你可以使用`JSONResponse`来兼容JSON的场景。
-
+ So, you will have to make sure your data is of the correct type. E.g. 所以你需要确保你响应数据类型的正确性，如：你可以使用`JSONResponse`来兼容JSON的场景。
+
同时，你也应当仅反馈通过`response_model`过滤过的数据。
### 更多信息
-!!! note "技术细节"
+!!! !!! note "技术细节"
你也可以使用`from starlette.responses import Response` 或者 `from starlette.responses import JSONResponse`。
- 为了方便开发者，**FastAPI** 封装了相同数据类型，如`starlette.responses` 和 `fastapi.responses`。不过大部分response对象都是直接引用自Starlette。
-
+ 为了方便开发者，**FastAPI** 封装了相同数据类型，如`starlette.responses` 和 `fastapi.responses`。 不过大部分response对象都是直接引用自Starlette。
+
因为`Response`对象可以非常便捷的设置headers和cookies，所以 **FastAPI** 同时也封装了`fastapi.Response`。
如果你想查看所有可用的参数和选项，可以参考 
+
+## Check the username
+
+Here's a more complete example.
+
+Use a dependency to check if the username and password are correct.
+
+For this, use the Python standard module 
+
+## JWT token with scopes
+
+Now, modify the token *path operation* to return the scopes requested.
+
+We are still using the same `OAuth2PasswordRequestForm`. It includes a property `scopes` with a `list` of `str`, with each scope it received in the request.
+
+And we return the scopes as part of the JWT token.
+
+!!! danger
+ For simplicity, here we are just adding the scopes received directly to the token.
+
+ But in your application, for security, you should make sure you only add the scopes that the user is actually able to have, or the ones you have predefined.
+
+=== "Python 3.10+"
+
+ ```Python hl_lines="155"
+ {!> ../../../docs_src/security/tutorial005_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="155"
+ {!> ../../../docs_src/security/tutorial005_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="156"
+ {!> ../../../docs_src/security/tutorial005_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="152"
+ {!> ../../../docs_src/security/tutorial005_py310.py!}
+ ```
+
+=== "Python 3.9+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="153"
+ {!> ../../../docs_src/security/tutorial005_py39.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="153"
+ {!> ../../../docs_src/security/tutorial005.py!}
+ ```
+
+## Declare scopes in *path operations* and dependencies
+
+Now we declare that the *path operation* for `/users/me/items/` requires the scope `items`.
+
+For this, we import and use `Security` from `fastapi`.
+
+You can use `Security` to declare dependencies (just like `Depends`), but `Security` also receives a parameter `scopes` with a list of scopes (strings).
+
+In this case, we pass a dependency function `get_current_active_user` to `Security` (the same way we would do with `Depends`).
+
+But we also pass a `list` of scopes, in this case with just one scope: `items` (it could have more).
+
+And the dependency function `get_current_active_user` can also declare sub-dependencies, not only with `Depends` but also with `Security`. Declaring its own sub-dependency function (`get_current_user`), and more scope requirements.
+
+In this case, it requires the scope `me` (it could require more than one scope).
+
+!!! note
+ You don't necessarily need to add different scopes in different places.
+
+ We are doing it here to demonstrate how **FastAPI** handles scopes declared at different levels.
+
+=== "Python 3.10+"
+
+ ```Python hl_lines="4 139 170"
+ {!> ../../../docs_src/security/tutorial005_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="4 139 170"
+ {!> ../../../docs_src/security/tutorial005_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="4 140 171"
+ {!> ../../../docs_src/security/tutorial005_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="3 138 165"
+ {!> ../../../docs_src/security/tutorial005_py310.py!}
+ ```
+
+=== "Python 3.9+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="4 139 166"
+ {!> ../../../docs_src/security/tutorial005_py39.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="4 139 166"
+ {!> ../../../docs_src/security/tutorial005.py!}
+ ```
+
+!!! info "Technical Details"
+ `Security` is actually a subclass of `Depends`, and it has just one extra parameter that we'll see later.
+
+ But by using `Security` instead of `Depends`, **FastAPI** will know that it can declare security scopes, use them internally, and document the API with OpenAPI.
+
+ But when you import `Query`, `Path`, `Depends`, `Security` and others from `fastapi`, those are actually functions that return special classes.
+
+## Use `SecurityScopes`
+
+Now update the dependency `get_current_user`.
+
+This is the one used by the dependencies above.
+
+Here's were we are using the same OAuth2 scheme we created before, declaring it as a dependency: `oauth2_scheme`.
+
+Because this dependency function doesn't have any scope requirements itself, we can use `Depends` with `oauth2_scheme`, we don't have to use `Security` when we don't need to specify security scopes.
+
+We also declare a special parameter of type `SecurityScopes`, imported from `fastapi.security`.
+
+This `SecurityScopes` class is similar to `Request` (`Request` was used to get the request object directly).
+
+=== "Python 3.10+"
+
+ ```Python hl_lines="8 105"
+ {!> ../../../docs_src/security/tutorial005_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="8 105"
+ {!> ../../../docs_src/security/tutorial005_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="8 106"
+ {!> ../../../docs_src/security/tutorial005_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="7 104"
+ {!> ../../../docs_src/security/tutorial005_py310.py!}
+ ```
+
+=== "Python 3.9+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="8 105"
+ {!> ../../../docs_src/security/tutorial005_py39.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="8 105"
+ {!> ../../../docs_src/security/tutorial005.py!}
+ ```
+
+## Use the `scopes`
+
+The parameter `security_scopes` will be of type `SecurityScopes`.
+
+It will have a property `scopes` with a list containing all the scopes required by itself and all the dependencies that use this as a sub-dependency. That means, all the "dependants"... this might sound confusing, it is explained again later below.
+
+The `security_scopes` object (of class `SecurityScopes`) also provides a `scope_str` attribute with a single string, containing those scopes separated by spaces (we are going to use it).
+
+We create an `HTTPException` that we can re-use (`raise`) later at several points.
+
+In this exception, we include the scopes required (if any) as a string separated by spaces (using `scope_str`). We put that string containing the scopes in the `WWW-Authenticate` header (this is part of the spec).
+
+=== "Python 3.10+"
+
+ ```Python hl_lines="105 107-115"
+ {!> ../../../docs_src/security/tutorial005_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="105 107-115"
+ {!> ../../../docs_src/security/tutorial005_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="106 108-116"
+ {!> ../../../docs_src/security/tutorial005_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="104 106-114"
+ {!> ../../../docs_src/security/tutorial005_py310.py!}
+ ```
+
+=== "Python 3.9+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="105 107-115"
+ {!> ../../../docs_src/security/tutorial005_py39.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="105 107-115"
+ {!> ../../../docs_src/security/tutorial005.py!}
+ ```
+
+## Verify the `username` and data shape
+
+We verify that we get a `username`, and extract the scopes.
+
+And then we validate that data with the Pydantic model (catching the `ValidationError` exception), and if we get an error reading the JWT token or validating the data with Pydantic, we raise the `HTTPException` we created before.
+
+For that, we update the Pydantic model `TokenData` with a new property `scopes`.
+
+By validating the data with Pydantic we can make sure that we have, for example, exactly a `list` of `str` with the scopes and a `str` with the `username`.
+
+Instead of, for example, a `dict`, or something else, as it could break the application at some point later, making it a security risk.
+
+We also verify that we have a user with that username, and if not, we raise that same exception we created before.
+
+=== "Python 3.10+"
+
+ ```Python hl_lines="46 116-127"
+ {!> ../../../docs_src/security/tutorial005_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="46 116-127"
+ {!> ../../../docs_src/security/tutorial005_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="47 117-128"
+ {!> ../../../docs_src/security/tutorial005_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="45 115-126"
+ {!> ../../../docs_src/security/tutorial005_py310.py!}
+ ```
+
+=== "Python 3.9+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="46 116-127"
+ {!> ../../../docs_src/security/tutorial005_py39.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="46 116-127"
+ {!> ../../../docs_src/security/tutorial005.py!}
+ ```
+
+## Verify the `scopes`
+
+We now verify that all the scopes required, by this dependency and all the dependants (including *path operations*), are included in the scopes provided in the token received, otherwise raise an `HTTPException`.
+
+For this, we use `security_scopes.scopes`, that contains a `list` with all these scopes as `str`.
+
+=== "Python 3.10+"
+
+ ```Python hl_lines="128-134"
+ {!> ../../../docs_src/security/tutorial005_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="128-134"
+ {!> ../../../docs_src/security/tutorial005_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="129-135"
+ {!> ../../../docs_src/security/tutorial005_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="127-133"
+ {!> ../../../docs_src/security/tutorial005_py310.py!}
+ ```
+
+=== "Python 3.9+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="128-134"
+ {!> ../../../docs_src/security/tutorial005_py39.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="128-134"
+ {!> ../../../docs_src/security/tutorial005.py!}
+ ```
+
+## Dependency tree and scopes
+
+Let's review again this dependency tree and the scopes.
+
+As the `get_current_active_user` dependency has as a sub-dependency on `get_current_user`, the scope `"me"` declared at `get_current_active_user` will be included in the list of required scopes in the `security_scopes.scopes` passed to `get_current_user`.
+
+The *path operation* itself also declares a scope, `"items"`, so this will also be in the list of `security_scopes.scopes` passed to `get_current_user`.
+
+Here's how the hierarchy of dependencies and scopes looks like:
+
+* The *path operation* `read_own_items` has:
+ * Required scopes `["items"]` with the dependency:
+ * `get_current_active_user`:
+ * The dependency function `get_current_active_user` has:
+ * Required scopes `["me"]` with the dependency:
+ * `get_current_user`:
+ * The dependency function `get_current_user` has:
+ * No scopes required by itself.
+ * A dependency using `oauth2_scheme`.
+ * A `security_scopes` parameter of type `SecurityScopes`:
+ * This `security_scopes` parameter has a property `scopes` with a `list` containing all these scopes declared above, so:
+ * `security_scopes.scopes` will contain `["me", "items"]` for the *path operation* `read_own_items`.
+ * `security_scopes.scopes` will contain `["me"]` for the *path operation* `read_users_me`, because it is declared in the dependency `get_current_active_user`.
+ * `security_scopes.scopes` will contain `[]` (nothing) for the *path operation* `read_system_status`, because it didn't declare any `Security` with `scopes`, and its dependency, `get_current_user`, doesn't declare any `scope` either.
+
+!!! tip
+ The important and "magic" thing here is that `get_current_user` will have a different list of `scopes` to check for each *path operation*.
+
+ All depending on the `scopes` declared in each *path operation* and each dependency in the dependency tree for that specific *path operation*.
+
+## More details about `SecurityScopes`
+
+You can use `SecurityScopes` at any point, and in multiple places, it doesn't have to be at the "root" dependency.
+
+It will always have the security scopes declared in the current `Security` dependencies and all the dependants for **that specific** *path operation* and **that specific** dependency tree.
+
+Because the `SecurityScopes` will have all the scopes declared by dependants, you can use it to verify that a token has the required scopes in a central dependency function, and then declare different scope requirements in different *path operations*.
+
+They will be checked independently for each *path operation*.
+
+## Check it
+
+If you open the API docs, you can authenticate and specify which scopes you want to authorize.
+
+
+
+And then, open the docs for the sub-application, at 
+
+If you try interacting with any of the two user interfaces, they will work correctly, because the browser will be able to talk to each specific app or sub-app.
+
+### Technical Details: `root_path`
+
+When you mount a sub-application as described above, FastAPI will take care of communicating the mount path for the sub-application using a mechanism from the ASGI specification called a `root_path`.
+
+That way, the sub-application will know to use that path prefix for the docs UI.
+
+And the sub-application could also have its own mounted sub-applications and everything would work correctly, because FastAPI handles all these `root_path`s automatically.
+
+You will learn more about the `root_path` and how to use it explicitly in the section about [Behind a Proxy](./behind-a-proxy.md){.internal-link target=_blank}.
diff --git a/docs/zh/docs/advanced/templates.md b/docs/zh/docs/advanced/templates.md
new file mode 100644
index 0000000000000..38618aeeb09cd
--- /dev/null
+++ b/docs/zh/docs/advanced/templates.md
@@ -0,0 +1,77 @@
+# Templates
+
+You can use any template engine you want with **FastAPI**.
+
+A common choice is Jinja2, the same one used by Flask and other tools.
+
+There are utilities to configure it easily that you can use directly in your **FastAPI** application (provided by Starlette).
+
+## Install dependencies
+
+Install `jinja2`:
+
+
+
+
+
+
+
+
+Then it's your turn, you place your order of 2 very fancy burgers for your crush and you. 🍔🍔
+
+
+
+The cashier says something to the cook in the kitchen so they know they have to prepare your burgers (even though they are currently preparing the ones for the previous clients).
+
+
+
+You pay. 💸
+
+The cashier gives you the number of your turn.
+
+
+
+While you are waiting, you go with your crush and pick a table, you sit and talk with your crush for a long time (as your burgers are very fancy and take some time to prepare).
+
+As you are sitting at the table with your crush, while you wait for the burgers, you can spend that time admiring how awesome, cute and smart your crush is ✨😍✨.
+
+
+
+While waiting and talking to your crush, from time to time, you check the number displayed on the counter to see if it's your turn already.
+
+Then at some point, it finally is your turn. You go to the counter, get your burgers and come back to the table.
+
+
+
+You and your crush eat the burgers and have a nice time. ✨
+
+
+
+!!! info
+ Beautiful illustrations by 
+
+Then it's finally your turn, you place your order of 2 very fancy burgers for your crush and you.
+
+You pay 💸.
+
+
+
+The cashier goes to the kitchen.
+
+You wait, standing in front of the counter 🕙, so that no one else takes your burgers before you do, as there are no numbers for turns.
+
+
+
+As you and your crush are busy not letting anyone get in front of you and take your burgers whenever they arrive, you cannot pay attention to your crush. 😞
+
+This is "synchronous" work, you are "synchronized" with the cashier/cook 👨🍳. You have to wait 🕙 and be there at the exact moment that the cashier/cook 👨🍳 finishes the burgers and gives them to you, or otherwise, someone else might take them.
+
+
+
+Then your cashier/cook 👨🍳 finally comes back with your burgers, after a long time waiting 🕙 there in front of the counter.
+
+
+
+You take your burgers and go to the table with your crush.
+
+You just eat them, and you are done. ⏹
+
+
+
+There was not much talk or flirting as most of the time was spent waiting 🕙 in front of the counter. 😞
+
+!!! info
+ Beautiful illustrations by 
+
+---
+
+Now that we know the difference between the terms **process** and **program**, let's continue talking about deployments.
+
+## Running on Startup
+
+In most cases, when you create a web API, you want it to be **always running**, uninterrupted, so that your clients can always access it. This is of course, unless you have a specific reason why you want it to run only in certain situations, but most of the time you want it constantly running and **available**.
+
+### In a Remote Server
+
+When you set up a remote server (a cloud server, a virtual machine, etc.) the simplest thing you can do is to run Uvicorn (or similar) manually, the same way you do when developing locally.
+
+And it will work and will be useful **during development**.
+
+But if your connection to the server is lost, the **running process** will probably die.
+
+And if the server is restarted (for example after updates, or migrations from the cloud provider) you probably **won't notice it**. And because of that, you won't even know that you have to restart the process manually. So, your API will just stay dead. 😱
+
+### Run Automatically on Startup
+
+In general, you will probably want the server program (e.g. Uvicorn) to be started automatically on server startup, and without needing any **human intervention**, to have a process always running with your API (e.g. Uvicorn running your FastAPI app).
+
+### Separate Program
+
+To achieve this, you will normally have a **separate program** that would make sure your application is run on startup. And in many cases, it would also make sure other components or applications are also run, for example, a database.
+
+### Example Tools to Run at Startup
+
+Some examples of the tools that can do this job are:
+
+* Docker
+* Kubernetes
+* Docker Compose
+* Docker in Swarm Mode
+* Systemd
+* Supervisor
+* Handled internally by a cloud provider as part of their services
+* Others...
+
+I'll give you more concrete examples in the next chapters.
+
+## Restarts
+
+Similar to making sure your application is run on startup, you probably also want to make sure it is **restarted** after failures.
+
+### We Make Mistakes
+
+We, as humans, make **mistakes**, all the time. Software almost *always* has **bugs** hidden in different places. 🐛
+
+And we as developers keep improving the code as we find those bugs and as we implement new features (possibly adding new bugs too 😅).
+
+### Small Errors Automatically Handled
+
+When building web APIs with FastAPI, if there's an error in our code, FastAPI will normally contain it to the single request that triggered the error. 🛡
+
+The client will get a **500 Internal Server Error** for that request, but the application will continue working for the next requests instead of just crashing completely.
+
+### Bigger Errors - Crashes
+
+Nevertheless, there might be cases where we write some code that **crashes the entire application** making Uvicorn and Python crash. 💥
+
+And still, you would probably not want the application to stay dead because there was an error in one place, you probably want it to **continue running** at least for the *path operations* that are not broken.
+
+### Restart After Crash
+
+But in those cases with really bad errors that crash the running **process**, you would want an external component that is in charge of **restarting** the process, at least a couple of times...
+
+!!! tip
+ ...Although if the whole application is just **crashing immediately** it probably doesn't make sense to keep restarting it forever. But in those cases, you will probably notice it during development, or at least right after deployment.
+
+ So let's focus on the main cases, where it could crash entirely in some particular cases **in the future**, and it still makes sense to restart it.
+
+You would probably want to have the thing in charge of restarting your application as an **external component**, because by that point, the same application with Uvicorn and Python already crashed, so there's nothing in the same code of the same app that could do anything about it.
+
+### Example Tools to Restart Automatically
+
+In most cases, the same tool that is used to **run the program on startup** is also used to handle automatic **restarts**.
+
+For example, this could be handled by:
+
+* Docker
+* Kubernetes
+* Docker Compose
+* Docker in Swarm Mode
+* Systemd
+* Supervisor
+* Handled internally by a cloud provider as part of their services
+* Others...
+
+## Replication - Processes and Memory
+
+With a FastAPI application, using a server program like Uvicorn, running it once in **one process** can serve multiple clients concurrently.
+
+But in many cases, you will want to run several worker processes at the same time.
+
+### Multiple Processes - Workers
+
+If you have more clients than what a single process can handle (for example if the virtual machine is not too big) and you have **multiple cores** in the server's CPU, then you could have **multiple processes** running with the same application at the same time, and distribute all the requests among them.
+
+When you run **multiple processes** of the same API program, they are commonly called **workers**.
+
+### Worker Processes and Ports
+
+Remember from the docs [About HTTPS](./https.md){.internal-link target=_blank} that only one process can be listening on one combination of port and IP address in a server?
+
+This is still true.
+
+So, to be able to have **multiple processes** at the same time, there has to be a **single process listening on a port** that then transmits the communication to each worker process in some way.
+
+### Memory per Process
+
+Now, when the program loads things in memory, for example, a machine learning model in a variable, or the contents of a large file in a variable, all that **consumes a bit of the memory (RAM)** of the server.
+
+And multiple processes normally **don't share any memory**. This means that each running process has its own things, variables, and memory. And if you are consuming a large amount of memory in your code, **each process** will consume an equivalent amount of memory.
+
+### Server Memory
+
+For example, if your code loads a Machine Learning model with **1 GB in size**, when you run one process with your API, it will consume at least 1 GB of RAM. And if you start **4 processes** (4 workers), each will consume 1 GB of RAM. So in total, your API will consume **4 GB of RAM**.
+
+And if your remote server or virtual machine only has 3 GB of RAM, trying to load more than 4 GB of RAM will cause problems. 🚨
+
+### Multiple Processes - An Example
+
+In this example, there's a **Manager Process** that starts and controls two **Worker Processes**.
+
+This Manager Process would probably be the one listening on the **port** in the IP. And it would transmit all the communication to the worker processes.
+
+Those worker processes would be the ones running your application, they would perform the main computations to receive a **request** and return a **response**, and they would load anything you put in variables in RAM.
+
+
+
+And of course, the same machine would probably have **other processes** running as well, apart from your application.
+
+An interesting detail is that the percentage of the **CPU used** by each process can **vary** a lot over time, but the **memory (RAM)** normally stays more or less **stable**.
+
+If you have an API that does a comparable amount of computations every time and you have a lot of clients, then the **CPU utilization** will probably *also be stable* (instead of constantly going up and down quickly).
+
+### Examples of Replication Tools and Strategies
+
+There can be several approaches to achieve this, and I'll tell you more about specific strategies in the next chapters, for example when talking about Docker and containers.
+
+The main constraint to consider is that there has to be a **single** component handling the **port** in the **public IP**. And then it has to have a way to **transmit** the communication to the replicated **processes/workers**.
+
+Here are some possible combinations and strategies:
+
+* **Gunicorn** managing **Uvicorn workers**
+ * Gunicorn would be the **process manager** listening on the **IP** and **port**, the replication would be by having **multiple Uvicorn worker processes**
+* **Uvicorn** managing **Uvicorn workers**
+ * One Uvicorn **process manager** would listen on the **IP** and **port**, and it would start **multiple Uvicorn worker processes**
+* **Kubernetes** and other distributed **container systems**
+ * Something in the **Kubernetes** layer would listen on the **IP** and **port**. The replication would be by having **multiple containers**, each with **one Uvicorn process** running
+* **Cloud services** that handle this for you
+ * The cloud service will probably **handle replication for you**. It would possibly let you define **a process to run**, or a **container image** to use, in any case, it would most probably be **a single Uvicorn process**, and the cloud service would be in charge of replicating it.
+
+!!! tip
+ Don't worry if some of these items about **containers**, Docker, or Kubernetes don't make a lot of sense yet.
+
+ I'll tell you more about container images, Docker, Kubernetes, etc. in a future chapter: [FastAPI in Containers - Docker](./docker.md){.internal-link target=_blank}.
+
+## Previous Steps Before Starting
+
+There are many cases where you want to perform some steps **before starting** your application.
+
+For example, you might want to run **database migrations**.
+
+But in most cases, you will want to perform these steps only **once**.
+
+So, you will want to have a **single process** to perform those **previous steps**, before starting the application.
+
+And you will have to make sure that it's a single process running those previous steps *even* if afterwards, you start **multiple processes** (multiple workers) for the application itself. If those steps were run by **multiple processes**, they would **duplicate** the work by running it on **parallel**, and if the steps were something delicate like a database migration, they could cause conflicts with each other.
+
+Of course, there are some cases where there's no problem in running the previous steps multiple times, in that case, it's a lot easier to handle.
+
+!!! tip
+ Also, have in mind that depending on your setup, in some cases you **might not even need any previous steps** before starting your application.
+
+ In that case, you wouldn't have to worry about any of this. 🤷
+
+### Examples of Previous Steps Strategies
+
+This will **depend heavily** on the way you **deploy your system**, and it would probably be connected to the way you start programs, handling restarts, etc.
+
+Here are some possible ideas:
+
+* An "Init Container" in Kubernetes that runs before your app container
+* A bash script that runs the previous steps and then starts your application
+ * You would still need a way to start/restart *that* bash script, detect errors, etc.
+
+!!! tip
+ I'll give you more concrete examples for doing this with containers in a future chapter: [FastAPI in Containers - Docker](./docker.md){.internal-link target=_blank}.
+
+## Resource Utilization
+
+Your server(s) is (are) a **resource**, you can consume or **utilize**, with your programs, the computation time on the CPUs, and the RAM memory available.
+
+How much of the system resources do you want to be consuming/utilizing? It might be easy to think "not much", but in reality, you will probably want to consume **as much as possible without crashing**.
+
+If you are paying for 3 servers but you are using only a little bit of their RAM and CPU, you are probably **wasting money** 💸, and probably **wasting server electric power** 🌎, etc.
+
+In that case, it could be better to have only 2 servers and use a higher percentage of their resources (CPU, memory, disk, network bandwidth, etc).
+
+On the other hand, if you have 2 servers and you are using **100% of their CPU and RAM**, at some point one process will ask for more memory, and the server will have to use the disk as "memory" (which can be thousands of times slower), or even **crash**. Or one process might need to do some computation and would have to wait until the CPU is free again.
+
+In this case, it would be better to get **one extra server** and run some processes on it so that they all have **enough RAM and CPU time**.
+
+There's also the chance that for some reason you have a **spike** of usage of your API. Maybe it went viral, or maybe some other services or bots start using it. And you might want to have extra resources to be safe in those cases.
+
+You could put an **arbitrary number** to target, for example, something **between 50% to 90%** of resource utilization. The point is that those are probably the main things you will want to measure and use to tweak your deployments.
+
+You can use simple tools like `htop` to see the CPU and RAM used in your server or the amount used by each process. Or you can use more complex monitoring tools, which may be distributed across servers, etc.
+
+## Recap
+
+You have been reading here some of the main concepts that you would probably need to have in mind when deciding how to deploy your application:
+
+* Security - HTTPS
+* Running on startup
+* Restarts
+* Replication (the number of processes running)
+* Memory
+* Previous steps before starting
+
+Understanding these ideas and how to apply them should give you the intuition necessary to take any decisions when configuring and tweaking your deployments. 🤓
+
+In the next sections, I'll give you more concrete examples of possible strategies you can follow. 🚀
diff --git a/docs/zh/docs/deployment/deta.md b/docs/zh/docs/deployment/deta.md
new file mode 100644
index 0000000000000..6b1b4690ecc8d
--- /dev/null
+++ b/docs/zh/docs/deployment/deta.md
@@ -0,0 +1,393 @@
+# Deploy FastAPI on Deta Space
+
+In this section you will learn how to easily deploy a **FastAPI** application on 
+
+Now run `space login` from the Space CLI. Upon pasting the token into the CLI prompt and pressing enter, you should see a confirmation message.
+
+
+
+Click on the new app called `fastapi-deta`, and it will open your API in a new browser tab on a URL like `https://fastapi-deta-gj7ka8.deta.app/`.
+
+You will get a JSON response from your FastAPI app:
+
+```JSON
+{
+ "Hello": "World"
+}
+```
+
+And now you can head over to the `/docs` of your API. For this example, it would be `https://fastapi-deta-gj7ka8.deta.app/docs`.
+
+
+
+## Enable public access
+
+Deta will handle authentication for your account using cookies. By default, every app or API that you `push` or install to your Space is personal - it's only accessible to you.
+
+But you can also make your API public using the `Spacefile` from earlier.
+
+With a `public_routes` parameter, you can specify which paths of your API should be available to the public.
+
+Set your `public_routes` to `"*"` to open every route of your API to the public:
+
+```yaml
+v: 0
+micros:
+ - name: fastapi-deta
+ src: .
+ engine: python3.9
+ public_routes:
+ - "/*"
+```
+
+Then run `space push` again to update your live API on Deta Space.
+
+Once it deploys, you can share your URL with anyone and they will be able to access your API. 🚀
+
+## HTTPS
+
+Congrats! You deployed your FastAPI app to Deta Space! 🎉 🍰
+
+Also, notice that Deta Space correctly handles HTTPS for you, so you don't have to take care of that and can be sure that your users will have a secure encrypted connection. ✅ 🔒
+
+## Create a release
+
+Space also allows you to publish your API. When you publish it, anyone else can install their own copy of your API, in their own Deta Space cloud.
+
+To do so, run `space release` in the Space CLI to create an **unlisted release**:
+
+
+
+## Learn more
+
+At some point, you will probably want to store some data for your app in a way that persists through time. For that you can use 
+
+### TLS Handshake Start
+
+The browser would then communicate with that IP address on **port 443** (the HTTPS port).
+
+The first part of the communication is just to establish the connection between the client and the server and to decide the cryptographic keys they will use, etc.
+
+
+
+This interaction between the client and the server to establish the TLS connection is called the **TLS handshake**.
+
+### TLS with SNI Extension
+
+**Only one process** in the server can be listening on a specific **port** in a specific **IP address**. There could be other processes listening on other ports in the same IP address, but only one for each combination of IP address and port.
+
+TLS (HTTPS) uses the specific port `443` by default. So that's the port we would need.
+
+As only one process can be listening on this port, the process that would do it would be the **TLS Termination Proxy**.
+
+The TLS Termination Proxy would have access to one or more **TLS certificates** (HTTPS certificates).
+
+Using the **SNI extension** discussed above, the TLS Termination Proxy would check which of the TLS (HTTPS) certificates available it should use for this connection, using the one that matches the domain expected by the client.
+
+In this case, it would use the certificate for `someapp.example.com`.
+
+
+
+The client already **trusts** the entity that generated that TLS certificate (in this case Let's Encrypt, but we'll see about that later), so it can **verify** that the certificate is valid.
+
+Then, using the certificate, the client and the TLS Termination Proxy **decide how to encrypt** the rest of the **TCP communication**. This completes the **TLS Handshake** part.
+
+After this, the client and the server have an **encrypted TCP connection**, this is what TLS provides. And then they can use that connection to start the actual **HTTP communication**.
+
+And that's what **HTTPS** is, it's just plain **HTTP** inside a **secure TLS connection** instead of a pure (unencrypted) TCP connection.
+
+!!! tip
+ Notice that the encryption of the communication happens at the **TCP level**, not at the HTTP level.
+
+### HTTPS Request
+
+Now that the client and server (specifically the browser and the TLS Termination Proxy) have an **encrypted TCP connection**, they can start the **HTTP communication**.
+
+So, the client sends an **HTTPS request**. This is just an HTTP request through an encrypted TLS connection.
+
+
+
+### Decrypt the Request
+
+The TLS Termination Proxy would use the encryption agreed to **decrypt the request**, and would transmit the **plain (decrypted) HTTP request** to the process running the application (for example a process with Uvicorn running the FastAPI application).
+
+
+
+### HTTP Response
+
+The application would process the request and send a **plain (unencrypted) HTTP response** to the TLS Termination Proxy.
+
+
+
+### HTTPS Response
+
+The TLS Termination Proxy would then **encrypt the response** using the cryptography agreed before (that started with the certificate for `someapp.example.com`), and send it back to the browser.
+
+Next, the browser would verify that the response is valid and encrypted with the right cryptographic key, etc. It would then **decrypt the response** and process it.
+
+
+
+The client (browser) will know that the response comes from the correct server because it is using the cryptography they agreed using the **HTTPS certificate** before.
+
+### Multiple Applications
+
+In the same server (or servers), there could be **multiple applications**, for example, other API programs or a database.
+
+Only one process can be handling the specific IP and port (the TLS Termination Proxy in our example) but the other applications/processes can be running on the server(s) too, as long as they don't try to use the same **combination of public IP and port**.
+
+
+
+That way, the TLS Termination Proxy could handle HTTPS and certificates for **multiple domains**, for multiple applications, and then transmit the requests to the right application in each case.
+
+### Certificate Renewal
+
+At some point in the future, each certificate would **expire** (about 3 months after acquiring it).
+
+And then, there would be another program (in some cases it's another program, in some cases it could be the same TLS Termination Proxy) that would talk to Let's Encrypt, and renew the certificate(s).
+
+
+
+The **TLS certificates** are **associated with a domain name**, not with an IP address.
+
+So, to renew the certificates, the renewal program needs to **prove** to the authority (Let's Encrypt) that it indeed **"owns" and controls that domain**.
+
+To do that, and to accommodate different application needs, there are several ways it can do it. Some popular ways are:
+
+* **Modify some DNS records**.
+ * For this, the renewal program needs to support the APIs of the DNS provider, so, depending on the DNS provider you are using, this might or might not be an option.
+* **Run as a server** (at least during the certificate acquisition process) on the public IP address associated with the domain.
+ * As we said above, only one process can be listening on a specific IP and port.
+ * This is one of the reasons why it's very useful when the same TLS Termination Proxy also takes care of the certificate renewal process.
+ * Otherwise, you might have to stop the TLS Termination Proxy momentarily, start the renewal program to acquire the certificates, then configure them with the TLS Termination Proxy, and then restart the TLS Termination Proxy. This is not ideal, as your app(s) will not be available during the time that the TLS Termination Proxy is off.
+
+All this renewal process, while still serving the app, is one of the main reasons why you would want to have a **separate system to handle HTTPS** with a TLS Termination Proxy instead of just using the TLS certificates with the application server directly (e.g. Uvicorn).
+
+## Recap
+
+Having **HTTPS** is very important, and quite **critical** in most cases. Most of the effort you as a developer have to put around HTTPS is just about **understanding these concepts** and how they work.
+
+But once you know the basic information of **HTTPS for developers** you can easily combine and configure different tools to help you manage everything in a simple way.
+
+In some of the next chapters, I'll show you several concrete examples of how to set up **HTTPS** for **FastAPI** applications. 🔒
diff --git a/docs/zh/docs/deployment/index.md b/docs/zh/docs/deployment/index.md
new file mode 100644
index 0000000000000..6c43d8abbe4db
--- /dev/null
+++ b/docs/zh/docs/deployment/index.md
@@ -0,0 +1,21 @@
+# Deployment
+
+Deploying a **FastAPI** application is relatively easy.
+
+## What Does Deployment Mean
+
+To **deploy** an application means to perform the necessary steps to make it **available to the users**.
+
+For a **web API**, it normally involves putting it in a **remote machine**, with a **server program** that provides good performance, stability, etc, so that your **users** can **access** the application efficiently and without interruptions or problems.
+
+This is in contrast to the **development** stages, where you are constantly changing the code, breaking it and fixing it, stopping and restarting the development server, etc.
+
+## Deployment Strategies
+
+There are several ways to do it depending on your specific use case and the tools that you use.
+
+You could **deploy a server** yourself using a combination of tools, you could use a **cloud service** that does part of the work for you, or other possible options.
+
+I will show you some of the main concepts you should probably have in mind when deploying a **FastAPI** application (although most of it applies to any other type of web application).
+
+You will see more details to have in mind and some of the techniques to do it in the next sections. ✨
diff --git a/docs/zh/docs/deployment/manually.md b/docs/zh/docs/deployment/manually.md
new file mode 100644
index 0000000000000..8238fa607ab30
--- /dev/null
+++ b/docs/zh/docs/deployment/manually.md
@@ -0,0 +1,141 @@
+# Run a Server Manually - Uvicorn
+
+The main thing you need to run a **FastAPI** application in a remote server machine is an ASGI server program like **Uvicorn**.
+
+There are 3 main alternatives:
+
+*
@@ -72,7 +72,7 @@ FastAPI 有一个非常棒的社区，它欢迎来自各个领域和背景的朋
这些用户 [创建了最多已被合并的 Pull Requests](help-fastapi.md#create-a-pull-request){.internal-link target=_blank}。
-他们贡献了源代码，文档，翻译等。 📦
+They have contributed source code, documentation, translations, etc. 📦
{% if people %}
-如果你正在开发一个在终端中运行的命令行应用而不是 web API，不妨试下 **Typer**。
+If you are building a CLI app to be used in the terminal instead of a web API, check out **Typer**.
-**Typer** 是 FastAPI 的小同胞。它想要成为**命令行中的 FastAPI**。 ⌨️ 🚀
+**Typer** is FastAPI's little sibling. And it's intended to be the **FastAPI of CLIs**. ⌨️ 🚀
-## 依赖
+## Requirements
-Python 3.6 及更高版本
+Python 3.7+
-FastAPI 站在以下巨人的肩膀之上：
+FastAPI stands on the shoulders of giants:
-* Starlette 负责 web 部分。
-* Pydantic 负责数据部分。
+* Starlette for the web parts.
+* Pydantic for the data parts.
-## 安装
+## Installation
+
-### 添加类型
+### Add types
-让我们来修改上面例子的一行代码。
+Let's modify a single line from the previous version.
-我们将把下面这段代码中的函数参数从：
+We will change exactly this fragment, the parameters of the function, from:
```Python
first_name, last_name
```
-改成：
+to:
```Python
first_name: str, last_name: str
```
-就是这样。
+That's it.
-这些就是"类型提示"：
+Those are the "type hints":
```Python hl_lines="1"
{!../../../docs_src/python_types/tutorial002.py!}
```
-这和声明默认值是不同的，例如：
+That is not the same as declaring default values like would be with:
```Python
first_name="john", last_name="doe"
```
-这两者不一样。
+It's a different thing.
-我们用的是冒号（`:`），不是等号（`=`）。
+We are using colons (`:`), not equals (`=`).
-而且添加类型提示一般不会改变原来的运行结果。
+And adding type hints normally doesn't change what happens from what would happen without them.
-现在假设我们又一次正在创建这个函数，这次添加了类型提示。
+But now, imagine you are again in the middle of creating that function, but with type hints.
-在同样的地方，通过 `Ctrl+Space` 触发自动补全，你会发现：
+At the same point, you try to trigger the autocomplete with `Ctrl+Space` and you see:
-
+
-这样，你可以滚动查看选项，直到你找到看起来眼熟的那个：
+With that, you can scroll, seeing the options, until you find the one that "rings a bell":
-
+
-## 更多动机
+## More motivation
-下面是一个已经有类型提示的函数：
+Check this function, it already has type hints:
```Python hl_lines="1"
{!../../../docs_src/python_types/tutorial003.py!}
```
-因为编辑器已经知道了这些变量的类型，所以不仅能对代码进行补全，还能检查其中的错误：
+Because the editor knows the types of the variables, you don't only get completion, you also get error checks:
-
+
-现在你知道了必须先修复这个问题，通过 `str(age)` 把 `age` 转换成字符串：
+Now you know that you have to fix it, convert `age` to a string with `str(age)`:
```Python hl_lines="2"
{!../../../docs_src/python_types/tutorial004.py!}
```
-## 声明类型
+## Declaring types
-你刚刚看到的就是声明类型提示的主要场景。用于函数的参数。
+You just saw the main place to declare type hints. As function parameters.
-这也是你将在 **FastAPI** 中使用它们的主要场景。
+This is also the main place you would use them with **FastAPI**.
-### 简单类型
+### Simple types
-不只是 `str`，你能够声明所有的标准 Python 类型。
+You can declare all the standard Python types, not only `str`.
-比如以下类型：
+You can use, for example:
* `int`
* `float`
@@ -144,143 +144,395 @@ John Doe
{!../../../docs_src/python_types/tutorial005.py!}
```
-### 嵌套类型
+### Generic types with type parameters
-有些容器数据结构可以包含其他的值，比如 `dict`、`list`、`set` 和 `tuple`。它们内部的值也会拥有自己的类型。
+There are some data structures that can contain other values, like `dict`, `list`, `set` and `tuple`. And the internal values can have their own type too.
-你可以使用 Python 的 `typing` 标准库来声明这些类型以及子类型。
+These types that have internal types are called "**generic**" types. And it's possible to declare them, even with their internal types.
-它专门用来支持这些类型提示。
+To declare those types and the internal types, you can use the standard Python module `typing`. It exists specifically to support these type hints.
-#### 列表
+#### Newer versions of Python
-例如，让我们来定义一个由 `str` 组成的 `list` 变量。
+The syntax using `typing` is **compatible** with all versions, from Python 3.6 to the latest ones, including Python 3.9, Python 3.10, etc.
-从 `typing` 模块导入 `List`（注意是大写的 `L`）：
+As Python advances, **newer versions** come with improved support for these type annotations and in many cases you won't even need to import and use the `typing` module to declare the type annotations.
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial006.py!}
-```
+If you can choose a more recent version of Python for your project, you will be able to take advantage of that extra simplicity.
-同样以冒号（`:`）来声明这个变量。
+In all the docs there are examples compatible with each version of Python (when there's a difference).
-输入 `List` 作为类型。
+For example "**Python 3.6+**" means it's compatible with Python 3.6 or above (including 3.7, 3.8, 3.9, 3.10, etc). And "**Python 3.9+**" means it's compatible with Python 3.9 or above (including 3.10, etc).
-由于列表是带有"子类型"的类型，所以我们把子类型放在方括号中：
+If you can use the **latest versions of Python**, use the examples for the latest version, those will have the **best and simplest syntax**, for example, "**Python 3.10+**".
-```Python hl_lines="4"
-{!../../../docs_src/python_types/tutorial006.py!}
-```
+#### List
+
+For example, let's define a variable to be a `list` of `str`.
+
+=== "Python 3.9+"
+
+ Declare the variable, with the same colon (`:`) syntax.
+
+ As the type, put `list`.
+
+ As the list is a type that contains some internal types, you put them in square brackets:
+
+ ```Python hl_lines="1"
+ {!> ../../../docs_src/python_types/tutorial006_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ From `typing`, import `List` (with a capital `L`):
+
+ ``` Python hl_lines="1"
+ {!> ../../../docs_src/python_types/tutorial006.py!}
+ ```
+
+
+ Declare the variable, with the same colon (`:`) syntax.
+
+ As the type, put the `List` that you imported from `typing`.
+
+ As the list is a type that contains some internal types, you put them in square brackets:
+
+ ```Python hl_lines="4"
+ {!> ../../../docs_src/python_types/tutorial006.py!}
+ ```
+
+!!! info
+ Those internal types in the square brackets are called "type parameters".
+
+ In this case, `str` is the type parameter passed to `List` (or `list` in Python 3.9 and above).
+
+That means: "the variable `items` is a `list`, and each of the items in this list is a `str`".
+
+!!! tip
+ If you use Python 3.9 or above, you don't have to import `List` from `typing`, you can use the same regular `list` type instead.
+
+By doing that, your editor can provide support even while processing items from the list:
+
+
+
+Without types, that's almost impossible to achieve.
+
+Notice that the variable `item` is one of the elements in the list `items`.
+
+And still, the editor knows it is a `str`, and provides support for that.
+
+#### Tuple and Set
+
+You would do the same to declare `tuple`s and `set`s:
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="1"
+ {!> ../../../docs_src/python_types/tutorial007_py39.py!}
+ ```
-这表示："变量 `items` 是一个 `list`，并且这个列表里的每一个元素都是 `str`"。
+=== "Python 3.6+"
-这样，即使在处理列表中的元素时，你的编辑器也可以提供支持。
+ ```Python hl_lines="1 4"
+ {!> ../../../docs_src/python_types/tutorial007.py!}
+ ```
-没有类型，几乎是不可能实现下面这样：
+This means:
-
+* The variable `items_t` is a `tuple` with 3 items, an `int`, another `int`, and a `str`.
+* The variable `items_s` is a `set`, and each of its items is of type `bytes`.
-注意，变量 `item` 是列表 `items` 中的元素之一。
+#### Dict
-而且，编辑器仍然知道它是一个 `str`，并为此提供了支持。
+To define a `dict`, you pass 2 type parameters, separated by commas.
-#### 元组和集合
+The first type parameter is for the keys of the `dict`.
-声明 `tuple` 和 `set` 的方法也是一样的：
+The second type parameter is for the values of the `dict`:
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="1"
+ {!> ../../../docs_src/python_types/tutorial008_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="1 4"
+ {!> ../../../docs_src/python_types/tutorial008.py!}
+ ```
+
+This means:
+
+* The variable `prices` is a `dict`:
+ * The keys of this `dict` are of type `str` (let's say, the name of each item).
+ * The values of this `dict` are of type `float` (let's say, the price of each item).
+
+#### Union
+
+You can declare that a variable can be any of **several types**, for example, an `int` or a `str`.
+
+In Python 3.6 and above (including Python 3.10) you can use the `Union` type from `typing` and put inside the square brackets the possible types to accept.
+
+In Python 3.10 there's also a **new syntax** where you can put the possible types separated by a vertical bar (`|`).
+
+=== "Python 3.10+"
+
+ ```Python hl_lines="1"
+ {!> ../../../docs_src/python_types/tutorial008b_py310.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="1 4"
+ {!> ../../../docs_src/python_types/tutorial008b.py!}
+ ```
+
+In both cases this means that `item` could be an `int` or a `str`.
+
+#### Possibly `None`
+
+You can declare that a value could have a type, like `str`, but that it could also be `None`.
+
+In Python 3.6 and above (including Python 3.10) you can declare it by importing and using `Optional` from the `typing` module.
```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial007.py!}
+{!../../../docs_src/python_types/tutorial009.py!}
```
-这表示：
+Using `Optional[str]` instead of just `str` will let the editor help you detecting errors where you could be assuming that a value is always a `str`, when it could actually be `None` too.
+
+`Optional[Something]` is actually a shortcut for `Union[Something, None]`, they are equivalent.
+
+This also means that in Python 3.10, you can use `Something | None`:
+
+=== "Python 3.10+"
+
+ ```Python hl_lines="1"
+ {!> ../../../docs_src/python_types/tutorial009_py310.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="1 4"
+ {!> ../../../docs_src/python_types/tutorial009.py!}
+ ```
+
+=== "Python 3.6+ alternative"
+
+ ```Python hl_lines="1 4"
+ {!> ../../../docs_src/python_types/tutorial009b.py!}
+ ```
+
+#### Using `Union` or `Optional`
-* 变量 `items_t` 是一个 `tuple`，其中的前两个元素都是 `int` 类型, 最后一个元素是 `str` 类型。
-* 变量 `items_s` 是一个 `set`，其中的每个元素都是 `bytes` 类型。
+If you are using a Python version below 3.10, here's a tip from my very **subjective** point of view:
-#### 字典
+* 🚨 Avoid using `Optional[SomeType]`
+* Instead ✨ **use `Union[SomeType, None]`** ✨.
-定义 `dict` 时，需要传入两个子类型，用逗号进行分隔。
+Both are equivalent and underneath they are the same, but I would recommend `Union` instead of `Optional` because the word "**optional**" would seem to imply that the value is optional, and it actually means "it can be `None`", even if it's not optional and is still required.
-第一个子类型声明 `dict` 的所有键。
+I think `Union[SomeType, None]` is more explicit about what it means.
-第二个子类型声明 `dict` 的所有值：
+It's just about the words and names. But those words can affect how you and your teammates think about the code.
+
+As an example, let's take this function:
+
+```Python hl_lines="1 4"
+{!../../../docs_src/python_types/tutorial009c.py!}
+```
+
+The parameter `name` is defined as `Optional[str]`, but it is **not optional**, you cannot call the function without the parameter:
+
+```Python
+say_hi() # Oh, no, this throws an error! 😱
+```
+
+The `name` parameter is **still required** (not *optional*) because it doesn't have a default value. Still, `name` accepts `None` as the value:
+
+```Python
+say_hi(name=None) # This works, None is valid 🎉
+```
+
+The good news is, once you are on Python 3.10 you won't have to worry about that, as you will be able to simply use `|` to define unions of types:
```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial008.py!}
+{!../../../docs_src/python_types/tutorial009c_py310.py!}
```
-这表示：
+And then you won't have to worry about names like `Optional` and `Union`. 😎
+
+#### Generic types
+
+These types that take type parameters in square brackets are called **Generic types** or **Generics**, for example:
+
+=== "Python 3.10+"
+
+ You can use the same builtin types as generics (with square brackets and types inside):
+
+ * `list`
+ * `tuple`
+ * `set`
+ * `dict`
+
+ And the same as with Python 3.6, from the `typing` module:
+
+ * `Union`
+ * `Optional` (the same as with Python 3.6)
+ * ...and others.
+
+ In Python 3.10, as an alternative to using the generics `Union` and `Optional`, you can use the vertical bar (`|`) to declare unions of types, that's a lot better and simpler.
+
+=== "Python 3.9+"
+
+ You can use the same builtin types as generics (with square brackets and types inside):
+
+ * `list`
+ * `tuple`
+ * `set`
+ * `dict`
+
+ And the same as with Python 3.6, from the `typing` module:
+
+ * `Union`
+ * `Optional`
+ * ...and others.
+
+=== "Python 3.6+"
-* 变量 `prices` 是一个 `dict`：
- * 这个 `dict` 的所有键为 `str` 类型（可以看作是字典内每个元素的名称）。
- * 这个 `dict` 的所有值为 `float` 类型（可以看作是字典内每个元素的价格）。
+ * `List`
+ * `Tuple`
+ * `Set`
+ * `Dict`
+ * `Union`
+ * `Optional`
+ * ...and others.
-### 类作为类型
+### Classes as types
-你也可以将类声明为变量的类型。
+You can also declare a class as the type of a variable.
-假设你有一个名为 `Person` 的类，拥有 name 属性：
+Let's say you have a class `Person`, with a name:
```Python hl_lines="1-3"
{!../../../docs_src/python_types/tutorial010.py!}
```
-接下来，你可以将一个变量声明为 `Person` 类型：
+Then you can declare a variable to be of type `Person`:
```Python hl_lines="6"
{!../../../docs_src/python_types/tutorial010.py!}
```
-然后，你将再次获得所有的编辑器支持：
+And then, again, you get all the editor support:
-
+
-## Pydantic 模型
+Notice that this means "`one_person` is an **instance** of the class `Person`".
-Pydantic 是一个用来用来执行数据校验的 Python 库。
+It doesn't mean "`one_person` is the **class** called `Person`".
-你可以将数据的"结构"声明为具有属性的类。
+## Pydantic models
-每个属性都拥有类型。
+Pydantic is a Python library to perform data validation.
-接着你用一些值来创建这个类的实例，这些值会被校验，并被转换为适当的类型（在需要的情况下），返回一个包含所有数据的对象。
+You declare the "shape" of the data as classes with attributes.
-然后，你将获得这个对象的所有编辑器支持。
+And each attribute has a type.
-下面的例子来自 Pydantic 官方文档：
+Then you create an instance of that class with some values and it will validate the values, convert them to the appropriate type (if that's the case) and give you an object with all the data.
-```Python
-{!../../../docs_src/python_types/tutorial010.py!}
-```
+And you get all the editor support with that resulting object.
+
+An example from the official Pydantic docs:
+
+=== "Python 3.10+"
+
+ ```Python
+ {!> ../../../docs_src/python_types/tutorial011_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python
+ {!> ../../../docs_src/python_types/tutorial011_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python
+ {!> ../../../docs_src/python_types/tutorial011.py!}
+ ```
!!! info
- 想进一步了解 Pydantic，请阅读其文档.
+ To learn more about Pydantic, check its docs.
+
+**FastAPI** is all based on Pydantic.
+
+You will see a lot more of all this in practice in the [Tutorial - User Guide](tutorial/index.md){.internal-link target=_blank}.
+
+!!! tip
+ Pydantic has a special behavior when you use `Optional` or `Union[Something, None]` without a default value, you can read more about it in the Pydantic docs about Required Optional fields.
+
+## Type Hints with Metadata Annotations
+
+Python also has a feature that allows putting **additional metadata** in these type hints using `Annotated`.
+
+=== "Python 3.9+"
+
+ In Python 3.9, `Annotated` is part of the standard library, so you can import it from `typing`.
+
+ ```Python hl_lines="1 4"
+ {!> ../../../docs_src/python_types/tutorial013_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ In versions below Python 3.9, you import `Annotated` from `typing_extensions`.
+
+ It will already be installed with **FastAPI**.
+
+ ```Python hl_lines="1 4"
+ {!> ../../../docs_src/python_types/tutorial013.py!}
+ ```
+
+Python itself doesn't do anything with this `Annotated`. And for editors and other tools, the type is still `str`.
+
+But you can use this space in `Annotated` to provide **FastAPI** with additional metadata about how you want your application to behave.
+
+The important thing to remember is that ***the first ***type parameter****** you pass to `Annotated` is the **actual type**. The rest, is just metadata for other tools.
+
+For now, you just need to know that `Annotated` exists, and that it's standard Python. 😎
+
+Later you will see how **powerful** it can be.
-整个 **FastAPI** 建立在 Pydantic 的基础之上。
+!!! tip
+ The fact that this is **standard Python** means that you will still get the **best possible developer experience** in your editor, with the tools you use to analyze and refactor your code, etc. ✨
-实际上你将在 [教程 - 用户指南](tutorial/index.md){.internal-link target=_blank} 看到很多这种情况。
+ And also that your code will be very compatible with many other Python tools and libraries. 🚀
-## **FastAPI** 中的类型提示
+## Type hints in **FastAPI**
-**FastAPI** 利用这些类型提示来做下面几件事。
+**FastAPI** takes advantage of these type hints to do several things.
-使用 **FastAPI** 时用类型提示声明参数可以获得：
+With **FastAPI** you declare parameters with type hints and you get:
-* **编辑器支持**。
-* **类型检查**。
+* **Editor support**.
+* **Type checks**.
-...并且 **FastAPI** 还会用这些类型声明来：
+...and **FastAPI** uses the same declarations to:
-* **定义参数要求**：声明对请求路径参数、查询参数、请求头、请求体、依赖等的要求。
-* **转换数据**：将来自请求的数据转换为需要的类型。
-* **校验数据**： 对于每一个请求：
- * 当数据校验失败时自动生成**错误信息**返回给客户端。
-* 使用 OpenAPI **记录** API：
- * 然后用于自动生成交互式文档的用户界面。
+* **Define requirements**: from request path parameters, query parameters, headers, bodies, dependencies, etc.
+* **Convert data**: from the request to the required type.
+* **Validate data**: coming from each request:
+ * Generating **automatic errors** returned to the client when the data is invalid.
+* **Document** the API using OpenAPI:
+ * which is then used by the automatic interactive documentation user interfaces.
-听上去有点抽象。不过不用担心。你将在 [教程 - 用户指南](tutorial/index.md){.internal-link target=_blank} 中看到所有的实战。
+This might all sound abstract. Don't worry. You'll see all this in action in the [Tutorial - User Guide](tutorial/index.md){.internal-link target=_blank}.
-最重要的是，通过使用标准的 Python 类型，只需要在一个地方声明（而不是添加更多的类、装饰器等），**FastAPI** 会为你完成很多的工作。
+The important thing is that by using standard Python types, in a single place (instead of adding more classes, decorators, etc), **FastAPI** will do a lot of the work for you.
!!! info
- 如果你已经阅读了所有教程，回过头来想了解有关类型的更多信息，来自 `mypy` 的"速查表"是不错的资源。
+ If you already went through all the tutorial and came back to see more about types, a good resource is the "cheat sheet" from `mypy`.
diff --git a/docs/zh/docs/tutorial/background-tasks.md b/docs/zh/docs/tutorial/background-tasks.md
new file mode 100644
index 0000000000000..1782971922ab2
--- /dev/null
+++ b/docs/zh/docs/tutorial/background-tasks.md
@@ -0,0 +1,126 @@
+# Background Tasks
+
+You can define background tasks to be run *after* returning a response.
+
+This is useful for operations that need to happen after a request, but that the client doesn't really have to be waiting for the operation to complete before receiving the response.
+
+This includes, for example:
+
+* Email notifications sent after performing an action:
+ * As connecting to an email server and sending an email tends to be "slow" (several seconds), you can return the response right away and send the email notification in the background.
+* Processing data:
+ * For example, let's say you receive a file that must go through a slow process, you can return a response of "Accepted" (HTTP 202) and process it in the background.
+
+## Using `BackgroundTasks`
+
+First, import `BackgroundTasks` and define a parameter in your *path operation function* with a type declaration of `BackgroundTasks`:
+
+```Python hl_lines="1 13"
+{!../../../docs_src/background_tasks/tutorial001.py!}
+```
+
+**FastAPI** will create the object of type `BackgroundTasks` for you and pass it as that parameter.
+
+## Create a task function
+
+Create a function to be run as the background task.
+
+It is just a standard function that can receive parameters.
+
+It can be an `async def` or normal `def` function, **FastAPI** will know how to handle it correctly.
+
+In this case, the task function will write to a file (simulating sending an email).
+
+And as the write operation doesn't use `async` and `await`, we define the function with normal `def`:
+
+```Python hl_lines="6-9"
+{!../../../docs_src/background_tasks/tutorial001.py!}
+```
+
+## Add the background task
+
+Inside of your *path operation function*, pass your task function to the *background tasks* object with the method `.add_task()`:
+
+```Python hl_lines="14"
+{!../../../docs_src/background_tasks/tutorial001.py!}
+```
+
+`.add_task()` receives as arguments:
+
+* A task function to be run in the background (`write_notification`).
+* Any sequence of arguments that should be passed to the task function in order (`email`).
+* Any keyword arguments that should be passed to the task function (`message="some notification"`).
+
+## Dependency Injection
+
+Using `BackgroundTasks` also works with the dependency injection system, you can declare a parameter of type `BackgroundTasks` at multiple levels: in a *path operation function*, in a dependency (dependable), in a sub-dependency, etc.
+
+**FastAPI** knows what to do in each case and how to re-use the same object, so that all the background tasks are merged together and are run in the background afterwards:
+
+=== "Python 3.10+"
+
+ ```Python hl_lines="13 15 22 25"
+ {!> ../../../docs_src/background_tasks/tutorial002_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="13 15 22 25"
+ {!> ../../../docs_src/background_tasks/tutorial002_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="14 16 23 26"
+ {!> ../../../docs_src/background_tasks/tutorial002_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="11 13 20 23"
+ {!> ../../../docs_src/background_tasks/tutorial002_py310.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="13 15 22 25"
+ {!> ../../../docs_src/background_tasks/tutorial002.py!}
+ ```
+
+In this example, the messages will be written to the `log.txt` file *after* the response is sent.
+
+If there was a query in the request, it will be written to the log in a background task.
+
+And then another background task generated at the *path operation function* will write a message using the `email` path parameter.
+
+## Technical Details
+
+The class `BackgroundTasks` comes directly from `starlette.background`.
+
+It is imported/included directly into FastAPI so that you can import it from `fastapi` and avoid accidentally importing the alternative `BackgroundTask` (without the `s` at the end) from `starlette.background`.
+
+By only using `BackgroundTasks` (and not `BackgroundTask`), it's then possible to use it as a *path operation function* parameter and have **FastAPI** handle the rest for you, just like when using the `Request` object directly.
+
+It's still possible to use `BackgroundTask` alone in FastAPI, but you have to create the object in your code and return a Starlette `Response` including it.
+
+You can see more details in Starlette's official docs for Background Tasks.
+
+## Caveat
+
+If you need to perform heavy background computation and you don't necessarily need it to be run by the same process (for example, you don't need to share memory, variables, etc), you might benefit from using other bigger tools like Celery.
+
+They tend to require more complex configurations, a message/job queue manager, like RabbitMQ or Redis, but they allow you to run background tasks in multiple processes, and especially, in multiple servers.
+
+To see an example, check the [Project Generators](../project-generation.md){.internal-link target=_blank}, they all include Celery already configured.
+
+But if you need to access variables and objects from the same **FastAPI** app, or you need to perform small background tasks (like sending an email notification), you can simply just use `BackgroundTasks`.
+
+## Recap
+
+Import and use `BackgroundTasks` with parameters in *path operation functions* and dependencies to add background tasks.
diff --git a/docs/zh/docs/tutorial/bigger-applications.md b/docs/zh/docs/tutorial/bigger-applications.md
index 9f0134f683c9e..0defc84810e53 100644
--- a/docs/zh/docs/tutorial/bigger-applications.md
+++ b/docs/zh/docs/tutorial/bigger-applications.md
@@ -4,7 +4,7 @@
**FastAPI** 提供了一个方便的工具，可以在保持所有灵活性的同时构建你的应用程序。
-!!! info
+!!! !!! info
如果你来自 Flask，那这将相当于 Flask 的 Blueprints。
## 一个文件结构示例
@@ -26,19 +26,19 @@
│ └── admin.py
```
-!!! tip
+!!! !!! tip
上面有几个 `__init__.py` 文件：每个目录或子目录中都有一个。
这就是能将代码从一个文件导入到另一个文件的原因。
-
+
例如，在 `app/main.py` 中，你可以有如下一行：
```
from app.routers import items
```
-* `app` 目录包含了所有内容。并且它有一个空文件 `app/__init__.py`，因此它是一个「Python 包」（「Python 模块」的集合）：`app`。
-* 它包含一个 `app/main.py` 文件。由于它位于一个 Python 包（一个包含 `__init__.py` 文件的目录）中，因此它是该包的一个「模块」：`app.main`。
+* `app` 目录包含了所有内容。 并且它有一个空文件 `app/__init__.py`，因此它是一个「Python 包」（「Python 模块」的集合）：`app`。
+* 它包含一个 `app/main.py` 文件。 由于它位于一个 Python 包（一个包含 `__init__.py` 文件的目录）中，因此它是该包的一个「模块」：`app.main`。
* 还有一个 `app/dependencies.py` 文件，就像 `app/main.py` 一样，它是一个「模块」：`app.dependencies`。
* 有一个子目录 `app/routers/` 包含另一个 `__init__.py` 文件，因此它是一个「Python 子包」：`app.routers`。
* 文件 `app/routers/items.py` 位于 `app/routers/` 包中，因此它是一个子模块：`app.routers.items`。
@@ -46,23 +46,23 @@
* 还有一个子目录 `app/internal/` 包含另一个 `__init__.py` 文件，因此它是又一个「Python 子包」：`app.internal`。
* `app/internal/admin.py` 是另一个子模块：`app.internal.admin`。
-
+
带有注释的同一文件结构：
```
.
-├── app # 「app」是一个 Python 包
-│ ├── __init__.py # 这个文件使「app」成为一个 Python 包
-│ ├── main.py # 「main」模块，例如 import app.main
-│ ├── dependencies.py # 「dependencies」模块，例如 import app.dependencies
-│ └── routers # 「routers」是一个「Python 子包」
-│ │ ├── __init__.py # 使「routers」成为一个「Python 子包」
-│ │ ├── items.py # 「items」子模块，例如 import app.routers.items
-│ │ └── users.py # 「users」子模块，例如 import app.routers.users
-│ └── internal # 「internal」是一个「Python 子包」
-│ ├── __init__.py # 使「internal」成为一个「Python 子包」
-│ └── admin.py # 「admin」子模块，例如 import app.internal.admin
+├── app # "app" is a Python package
+│ ├── __init__.py # this file makes "app" a "Python package"
+│ ├── main.py # "main" module, e.g. import app.main
+│ ├── dependencies.py # "dependencies" module, e.g. import app.dependencies
+│ └── routers # "routers" is a "Python subpackage"
+│ │ ├── __init__.py # makes "routers" a "Python subpackage"
+│ │ ├── items.py # "items" submodule, e.g. import app.routers.items
+│ │ └── users.py # "users" submodule, e.g. import app.routers.users
+│ └── internal # "internal" is a "Python subpackage"
+│ ├── __init__.py # makes "internal" a "Python subpackage"
+│ └── admin.py # "admin" submodule, e.g. import app.internal.admin
```
## `APIRouter`
@@ -99,7 +99,7 @@
所有相同的 `parameters`、`responses`、`dependencies`、`tags` 等等。
-!!! tip
+!!! !!! tip
在此示例中，该变量被命名为 `router`，但你可以根据你的想法自由命名。
我们将在主 `FastAPI` 应用中包含该 `APIRouter`，但首先，让我们来看看依赖项和另一个 `APIRouter`。
@@ -112,12 +112,51 @@
现在我们将使用一个简单的依赖项来读取一个自定义的 `X-Token` 请求首部：
-```Python hl_lines="1 4-6"
-{!../../../docs_src/bigger_applications/app/dependencies.py!}
-```
+=== "Python 3.9+"
+
+ ```Python hl_lines="3 6-8"
+ .
+├── app
+│ ├── __init__.py
+│ ├── main.py
+│ ├── dependencies.py
+│ └── routers
+│ │ ├── __init__.py
+│ │ ├── items.py
+│ │ └── users.py
+│ └── internal
+│ ├── __init__.py
+│ └── admin.py
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="1 5-7"
+ {!../../../docs_src/bigger_applications/app/dependencies.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="1 4-6"
+ .
+├── app # 「app」是一个 Python 包
+│ ├── __init__.py # 这个文件使「app」成为一个 Python 包
+│ ├── main.py # 「main」模块，例如 import app.main
+│ ├── dependencies.py # 「dependencies」模块，例如 import app.dependencies
+│ └── routers # 「routers」是一个「Python 子包」
+│ │ ├── __init__.py # 使「routers」成为一个「Python 子包」
+│ │ ├── items.py # 「items」子模块，例如 import app.routers.items
+│ │ └── users.py # 「users」子模块，例如 import app.routers.users
+│ └── internal # 「internal」是一个「Python 子包」
+│ ├── __init__.py # 使「internal」成为一个「Python 子包」
+│ └── admin.py # 「admin」子模块，例如 import app.internal.admin
+ ```
!!! tip
- 我们正在使用虚构的请求首部来简化此示例。
+ We are using an invented header to simplify this example.
但在实际情况下，使用集成的[安全性实用工具](./security/index.md){.internal-link target=_blank}会得到更好的效果。
@@ -141,7 +180,8 @@
* 额外的 `responses`。
* `dependencies`：它们都需要我们创建的 `X-Token` 依赖项。
-因此，我们可以将其添加到 `APIRouter` 中，而不是将其添加到每个路径操作中。
+!!! note "技术细节"
+ 实际上，它将在内部为声明在 `APIRouter` 中的每个*路径操作*创建一个*路径操作*。
```Python hl_lines="5-10 16 21"
{!../../../docs_src/bigger_applications/app/routers/items.py!}
@@ -163,7 +203,7 @@ async def read_item(item_id: str):
我们可以添加一个 `dependencies` 列表，这些依赖项将被添加到路由器中的所有*路径操作*中，并将针对向它们发起的每个请求执行/解决。
-!!! tip
+!!! !!! tip
请注意，和[*路径操作装饰器*中的依赖项](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}很类似，没有值会被传递给你的*路径操作函数*。
最终结果是项目相关的路径现在为：
@@ -181,10 +221,10 @@ async def read_item(item_id: str):
* 路由器的依赖项最先执行，然后是[装饰器中的 `dependencies`](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}，再然后是普通的参数依赖项。
* 你还可以添加[具有 `scopes` 的 `Security` 依赖项](../advanced/security/oauth2-scopes.md){.internal-link target=_blank}。
-!!! tip
- 在 `APIRouter`中具有 `dependencies` 可以用来，例如，对一整组的*路径操作*要求身份认证。即使这些依赖项并没有分别添加到每个路径操作中。
+!!! !!! tip
+ 在 `APIRouter`中具有 `dependencies` 可以用来，例如，对一整组的*路径操作*要求身份认证。 即使这些依赖项并没有分别添加到每个路径操作中。
-!!! check
+!!! !!! check
`prefix`、`tags`、`responses` 以及 `dependencies` 参数只是（和其他很多情况一样）**FastAPI** 的一个用于帮助你避免代码重复的功能。
### 导入依赖项
@@ -201,7 +241,7 @@ async def read_item(item_id: str):
#### 相对导入如何工作
-!!! tip
+!!! !!! tip
如果你完全了解导入的工作原理，请从下面的下一部分继续。
一个单点 `.`，例如：
@@ -220,7 +260,7 @@ from .dependencies import get_token_header
请记住我们的程序/文件结构是怎样的：
-
+
---
@@ -230,14 +270,14 @@ from .dependencies import get_token_header
from ..dependencies import get_token_header
```
-表示：
+那将意味着：
* 从该模块（`app/routers/items.py` 文件）所在的同一个包（`app/routers/` 目录）开始...
* 跳转到其父包（`app/` 目录）...
* 在该父包中，找到 `dependencies` 模块（位于 `app/dependencies.py` 的文件）...
* 然后从中导入函数 `get_token_header`。
-正常工作了！🎉
+正常工作了！ 🎉
---
@@ -247,7 +287,7 @@ from ..dependencies import get_token_header
from ...dependencies import get_token_header
```
-那将意味着：
+that would mean:
* 从该模块（`app/routers/items.py` 文件）所在的同一个包（`app/routers/` 目录）开始...
* 跳转到其父包（`app/` 目录）...
@@ -255,9 +295,9 @@ from ...dependencies import get_token_header
* 在该父包中，找到 `dependencies` 模块（位于 `app/` 更上一级目录中的 `dependencies.py` 文件）...
* 然后从中导入函数 `get_token_header`。
-这将引用 `app/` 的往上一级，带有其自己的 `__init __.py` 等文件的某个包。但是我们并没有这个包。因此，这将在我们的示例中引发错误。🚨
+这将引用 `app/` 的往上一级，带有其自己的 `__init __.py` 等文件的某个包。 但是我们并没有这个包。 因此，这将在我们的示例中引发错误。 🚨
-但是现在你知道了它的工作原理，因此无论它们多么复杂，你都可以在自己的应用程序中使用相对导入。🤓
+但是现在你知道了它的工作原理，因此无论它们多么复杂，你都可以在自己的应用程序中使用相对导入。 🤓
### 添加一些自定义的 `tags`、`responses` 和 `dependencies`
@@ -269,7 +309,7 @@ from ...dependencies import get_token_header
{!../../../docs_src/bigger_applications/app/routers/items.py!}
```
-!!! tip
+!!! !!! tip
最后的这个路径操作将包含标签的组合：`["items"，"custom"]`。
并且在文档中也会有两个响应，一个用于 `404`，一个用于 `403`。
@@ -278,7 +318,7 @@ from ...dependencies import get_token_header
现在，让我们来看看位于 `app/main.py` 的模块。
-在这里你导入并使用 `FastAPI` 类。
+你可以像平常一样导入并创建一个 `FastAPI` 类。
这将是你的应用程序中将所有内容联结在一起的主文件。
@@ -286,7 +326,7 @@ from ...dependencies import get_token_header
### 导入 `FastAPI`
-你可以像平常一样导入并创建一个 `FastAPI` 类。
+在这里你导入并使用 `FastAPI` 类。
我们甚至可以声明[全局依赖项](dependencies/global-dependencies.md){.internal-link target=_blank}，它会和每个 `APIRouter` 的依赖项组合在一起：
@@ -302,11 +342,11 @@ from ...dependencies import get_token_header
{!../../../docs_src/bigger_applications/app/main.py!}
```
-由于文件 `app/routers/users.py` 和 `app/routers/items.py` 是同一 Python 包 `app` 一个部分的子模块，因此我们可以使用单个点 ` .` 通过「相对导入」来导入它们。
+由于文件 `app/routers/users.py` 和 `app/routers/items.py` 是同一 Python 包 `app` 一个部分的子模块，因此我们可以使用单个点 `.` 通过「相对导入」来导入它们。
### 导入是如何工作的
-这段代码：
+The section:
```Python
from .routers import items, users
@@ -318,7 +358,7 @@ from .routers import items, users
* 寻找 `routers` 子包（位于 `app/routers/` 的目录）...
* 从该包中，导入子模块 `items` (位于 `app/routers/items.py` 的文件) 以及 `users` (位于 `app/routers/users.py` 的文件)...
-`items` 模块将具有一个 `router` 变量（`items.router`）。这与我们在 `app/routers/items.py` 文件中创建的变量相同，它是一个 `APIRouter` 对象。
+`items` 模块将具有一个 `router` 变量（`items.router`）。 这与我们在 `app/routers/items.py` 文件中创建的变量相同，它是一个 `APIRouter` 对象。
然后我们对 `users` 模块进行相同的操作。
@@ -328,19 +368,21 @@ from .routers import items, users
from app.routers import items, users
```
-!!! info
+!!! !!! info
第一个版本是「相对导入」：
```Python
from .routers import items, users
```
+
第二个版本是「绝对导入」：
```Python
from app.routers import items, users
```
+
要了解有关 Python 包和模块的更多信息，请查阅关于 Modules 的 Python 官方文档。
### 避免名称冲突
@@ -372,7 +414,7 @@ from .routers.users import router
{!../../../docs_src/bigger_applications/app/main.py!}
```
-!!! info
+!!! !!! info
`users.router` 包含了 `app/routers/users.py` 文件中的 `APIRouter`。
`items.router` 包含了 `app/routers/items.py` 文件中的 `APIRouter`。
@@ -381,17 +423,17 @@ from .routers.users import router
它将包含来自该路由器的所有路由作为其一部分。
-!!! note "技术细节"
- 实际上，它将在内部为声明在 `APIRouter` 中的每个*路径操作*创建一个*路径操作*。
+!!! note "Technical Details"
+ It will actually internally create a *path operation* for each *path operation* that was declared in the `APIRouter`.
所以，在幕后，它实际上会像所有的东西都是同一个应用程序一样工作。
-!!! check
+!!! !!! check
包含路由器时，你不必担心性能问题。
这将花费几微秒时间，并且只会在启动时发生。
-
- 因此，它不会影响性能。⚡
+
+ 因此，它不会影响性能。 ⚡
### 包含一个有自定义 `prefix`、`tags`、`responses` 和 `dependencies` 的 `APIRouter`
@@ -399,7 +441,7 @@ from .routers.users import router
它包含一个带有一些由你的组织在多个项目之间共享的管理员*路径操作*的 `APIRouter`。
-对于此示例，它将非常简单。但是假设由于它是与组织中的其他项目所共享的，因此我们无法对其进行修改，以及直接在 `APIRouter` 中添加 `prefix`、`dependencies`、`tags` 等：
+对于此示例，它将非常简单。 但是假设由于它是与组织中的其他项目所共享的，因此我们无法对其进行修改，以及直接在 `APIRouter` 中添加 `prefix`、`dependencies`、`tags` 等：
```Python hl_lines="3"
{!../../../docs_src/bigger_applications/app/internal/admin.py!}
@@ -407,7 +449,7 @@ from .routers.users import router
但是我们仍然希望在包含 `APIRouter` 时设置一个自定义的 `prefix`，以便其所有*路径操作*以 `/admin` 开头，我们希望使用本项目已经有的 `dependencies` 保护它，并且我们希望它包含自定义的 `tags` 和 `responses`。
-我们可以通过将这些参数传递给 `app.include_router()` 来完成所有的声明，而不必修改原始的 `APIRouter`：
+但这只会影响我们应用中的 `APIRouter`，而不会影响使用它的任何其他代码。
```Python hl_lines="14-17"
{!../../../docs_src/bigger_applications/app/main.py!}
@@ -422,7 +464,7 @@ from .routers.users import router
* `get_token_header` 依赖项。
* `418` 响应。 🍵
-但这只会影响我们应用中的 `APIRouter`，而不会影响使用它的任何其他代码。
+因此，我们可以将其添加到 `APIRouter` 中，而不是将其添加到每个路径操作中。
因此，举例来说，其他项目能够以不同的身份认证方法使用相同的 `APIRouter`。
@@ -438,15 +480,15 @@ from .routers.users import router
它将与通过 `app.include_router()` 添加的所有其他*路径操作*一起正常运行。
-!!! info "特别的技术细节"
+!!! !!! info "特别的技术细节"
**注意**：这是一个非常技术性的细节，你也许可以**直接跳过**。
---
-
+
`APIRouter` 没有被「挂载」，它们与应用程序的其余部分没有隔离。
-
+
这是因为我们想要在 OpenAPI 模式和用户界面中包含它们的*路径操作*。
-
+
由于我们不能仅仅隔离它们并独立于其余部分来「挂载」它们，因此*路径操作*是被「克隆的」（重新创建），而不是直接包含。
## 查看自动化的 API 文档
@@ -467,7 +509,7 @@ $ uvicorn app.main:app --reload
你将看到使用了正确路径（和前缀）和正确标签的自动化 API 文档，包括了来自所有子模块的路径：
-
+
## 多次使用不同的 `prefix` 包含同一个路由器
diff --git a/docs/zh/docs/tutorial/body-fields.md b/docs/zh/docs/tutorial/body-fields.md
index 053cae71c7c6f..da96baaecfbc0 100644
--- a/docs/zh/docs/tutorial/body-fields.md
+++ b/docs/zh/docs/tutorial/body-fields.md
@@ -1,4 +1,4 @@
-# 请求体 - 字段
+# Body - Fields
与使用 `Query`、`Path` 和 `Body` 在*路径操作函数*中声明额外的校验和元数据的方式相同，你可以使用 Pydantic 的 `Field` 在 Pydantic 模型内部声明校验和元数据。
@@ -6,42 +6,118 @@
首先，你必须导入它：
-```Python hl_lines="2"
-{!../../../docs_src/body_fields/tutorial001.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="4"
+ {!> ../../../docs_src/body_fields/tutorial001_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="4"
+ {!> ../../../docs_src/body_fields/tutorial001_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="4"
+ !!! note "技术细节"
+ 实际上，
+
如果你直接使用 `dict` 而不是 Pydantic 模型，那你将无法获得这种编辑器支持。
@@ -218,27 +358,38 @@ images: List[Image]
在下面的例子中，你将接受任意键为 `int` 类型并且值为 `float` 类型的 `dict`：
-```Python hl_lines="15"
-{!../../../docs_src/body_nested_models/tutorial009.py!}
-```
+=== "Python 3.9+"
+
+ ```Python hl_lines="7"
+ https://fastapi.tiangolo.com/img/tutorial/body-nested-models/image01.png
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="9"
+ !!! info
+ 请注意 
+
而且还将在每一个需要它们的*路径操作*的 API 文档中使用：
-
+
## 编辑器支持
在你的编辑器中，你会在函数内部的任意地方得到类型提示和代码补全（如果你接收的是一个 `dict` 而不是 Pydantic 模型，则不会发生这种情况）：
-
+
你还会获得对不正确的类型操作的错误检查：
-
+
这并非偶然，整个框架都是围绕该设计而构建。
@@ -106,15 +134,34 @@ Pydantic 本身甚至也进行了一些更改以支持此功能。
但是在 PyCharm 和绝大多数其他 Python 编辑器中你也会获得同样的编辑器支持：
-
+
+
+!!! tip
+ If you use PyCharm as your editor, you can use the Pydantic PyCharm Plugin.
+
+ It improves editor support for Pydantic models, with:
+
+ * auto-completion
+ * type checks
+ * refactoring
+ * searching
+ * inspections
## 使用模型
在函数内部，你可以直接访问模型对象的所有属性：
-```Python hl_lines="19"
-{!../../../docs_src/body/tutorial002.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="19"
+ https://fastapi.tiangolo.com/img/tutorial/body/image01.png
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="21"
+ {!../../../docs_src/body/tutorial002.py!}
+ ```
## 请求体 + 路径参数
@@ -122,9 +169,17 @@ Pydantic 本身甚至也进行了一些更改以支持此功能。
**FastAPI** 将识别出与路径参数匹配的函数参数应**从路径中获取**，而声明为 Pydantic 模型的函数参数应**从请求体中获取**。
-```Python hl_lines="15-16"
-{!../../../docs_src/body/tutorial003.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="15-16"
+ https://fastapi.tiangolo.com/img/tutorial/body/image04.png
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="17-18"
+ {!../../../docs_src/body/tutorial003.py!}
+ ```
## 请求体 + 路径参数 + 查询参数
@@ -132,9 +187,17 @@ Pydantic 本身甚至也进行了一些更改以支持此功能。
**FastAPI** 会识别它们中的每一个，并从正确的位置获取数据。
-```Python hl_lines="16"
-{!../../../docs_src/body/tutorial004.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="16"
+ https://fastapi.tiangolo.com/img/tutorial/body/image02.png
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="18"
+ {!../../../docs_src/body/tutorial004.py!}
+ ```
函数参数将依次按如下规则进行识别：
@@ -142,6 +205,11 @@ Pydantic 本身甚至也进行了一些更改以支持此功能。
* 如果参数属于**单一类型**（比如 `int`、`float`、`str`、`bool` 等）它将被解释为**查询**参数。
* 如果参数的类型被声明为一个 **Pydantic 模型**，它将被解释为**请求体**。
+!!! note
+ FastAPI will know that the value of `q` is not required because of the default value `= None`.
+
+ The `Union` in `Union[str, None]` is not used by FastAPI, but will allow your editor to give you better support and detect errors.
+
## 不使用 Pydantic
-如果你不想使用 Pydantic 模型，你还可以使用 **Body** 参数。请参阅文档 [请求体 - 多个参数：请求体中的单一值](body-multiple-params.md#singular-values-in-body){.internal-link target=_blank}。
+如果你不想使用 Pydantic 模型，你还可以使用 **Body** 参数。 请参阅文档 [请求体 - 多个参数：请求体中的单一值](body-multiple-params.md#singular-values-in-body){.internal-link target=_blank}。
diff --git a/docs/zh/docs/tutorial/cookie-params.md b/docs/zh/docs/tutorial/cookie-params.md
index d67daf0f9051e..5e9a59af732f5 100644
--- a/docs/zh/docs/tutorial/cookie-params.md
+++ b/docs/zh/docs/tutorial/cookie-params.md
@@ -6,9 +6,44 @@
首先，导入 `Cookie`:
-```Python hl_lines="3"
-{!../../../docs_src/cookie_params/tutorial001.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="3"
+ {!> ../../../docs_src/cookie_params/tutorial001_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="3"
+ {!> ../../../docs_src/cookie_params/tutorial001_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="3"
+ {!> ../../../docs_src/cookie_params/tutorial001_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="1"
+ {!../../../docs_src/cookie_params/tutorial001.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="3"
+ !!! info
+ 你需要使用 
+
---
如果使用 Pycharm，你可以：
* 打开「运行」菜单。
-* 选中「调试...」。
+* Select the option "Debug...".
* 然后出现一个上下文菜单。
* 选择要调试的文件（本例中的 `main.py`）。
@@ -105,4 +109,4 @@ from myapp import app
看起来可能是这样：
-
+
diff --git a/docs/zh/docs/tutorial/dependencies/classes-as-dependencies.md b/docs/zh/docs/tutorial/dependencies/classes-as-dependencies.md
index f404820df0119..7da62b650bca0 100644
--- a/docs/zh/docs/tutorial/dependencies/classes-as-dependencies.md
+++ b/docs/zh/docs/tutorial/dependencies/classes-as-dependencies.md
@@ -8,13 +8,37 @@
=== "Python 3.10+"
+ ```Python hl_lines="9"
+ {!> ../../../docs_src/dependencies/tutorial001_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="11"
+ {!> ../../../docs_src/dependencies/tutorial001_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="12"
+ {!> ../../../docs_src/dependencies/tutorial001_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
```Python hl_lines="7"
{!> ../../../docs_src/dependencies/tutorial001_py310.py!}
```
-=== "Python 3.6+"
+=== "Python 3.6+ non-Annotated"
- ```Python hl_lines="9"
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="11"
{!> ../../../docs_src/dependencies/tutorial001.py!}
```
@@ -30,7 +54,7 @@
但这并不是声明依赖项的唯一方法(尽管它可能是更常见的方法)。
-关键因素是依赖项应该是 "可调用对象"。
+The key factor is that a dependency should be a "callable".
Python 中的 "**可调用对象**" 是指任何 Python 可以像函数一样 "调用" 的对象。
@@ -46,7 +70,7 @@ something()
something(some_argument, some_keyword_argument="foo")
```
-这就是 "可调用对象"。
+then it is a "callable".
## 类作为依赖项
@@ -73,19 +97,43 @@ fluffy = Cat(name="Mr Fluffy")
实际上 FastAPI 检查的是它是一个 "可调用对象"（函数，类或其他任何类型）以及定义的参数。
-如果您在 **FastAPI** 中传递一个 "可调用对象" 作为依赖项，它将分析该 "可调用对象" 的参数，并以处理路径操作函数的参数的方式来处理它们。包括子依赖项。
+如果您在 **FastAPI** 中传递一个 "可调用对象" 作为依赖项，它将分析该 "可调用对象" 的参数，并以处理路径操作函数的参数的方式来处理它们。 包括子依赖项。
-这也适用于完全没有参数的可调用对象。这与不带参数的路径操作函数一样。
+这也适用于完全没有参数的可调用对象。 这与不带参数的路径操作函数一样。
所以，我们可以将上面的依赖项 "可依赖对象" `common_parameters` 更改为类 `CommonQueryParams`:
=== "Python 3.10+"
+ ```Python hl_lines="11-15"
+ {!> ../../../docs_src/dependencies/tutorial002_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="11-15"
+ {!> ../../../docs_src/dependencies/tutorial002_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="12-16"
+ {!> ../../../docs_src/dependencies/tutorial002_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
```Python hl_lines="9-13"
{!> ../../../docs_src/dependencies/tutorial002_py310.py!}
```
-=== "Python 3.6+"
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
```Python hl_lines="11-15"
{!> ../../../docs_src/dependencies/tutorial002.py!}
@@ -95,11 +143,35 @@ fluffy = Cat(name="Mr Fluffy")
=== "Python 3.10+"
+ ```Python hl_lines="12"
+ {!> ../../../docs_src/dependencies/tutorial002_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="12"
+ {!> ../../../docs_src/dependencies/tutorial002_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="13"
+ {!> ../../../docs_src/dependencies/tutorial002_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
```Python hl_lines="10"
{!> ../../../docs_src/dependencies/tutorial002_py310.py!}
```
-=== "Python 3.6+"
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
```Python hl_lines="12"
{!> ../../../docs_src/dependencies/tutorial002.py!}
@@ -109,11 +181,35 @@ fluffy = Cat(name="Mr Fluffy")
=== "Python 3.10+"
+ ```Python hl_lines="8"
+ {!> ../../../docs_src/dependencies/tutorial001_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="9"
+ {!> ../../../docs_src/dependencies/tutorial001_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="10"
+ {!> ../../../docs_src/dependencies/tutorial001_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
```Python hl_lines="6"
{!> ../../../docs_src/dependencies/tutorial001_py310.py!}
```
-=== "Python 3.6+"
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
```Python hl_lines="9"
{!> ../../../docs_src/dependencies/tutorial001.py!}
@@ -135,30 +231,65 @@ fluffy = Cat(name="Mr Fluffy")
=== "Python 3.10+"
+ ```Python hl_lines="19"
+ {!> ../../../docs_src/dependencies/tutorial002_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="19"
+ {!> ../../../docs_src/dependencies/tutorial002_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="20"
+ {!> ../../../docs_src/dependencies/tutorial002_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
```Python hl_lines="17"
{!> ../../../docs_src/dependencies/tutorial002_py310.py!}
```
-=== "Python 3.6+"
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
```Python hl_lines="19"
{!> ../../../docs_src/dependencies/tutorial002.py!}
```
-**FastAPI** 调用 `CommonQueryParams` 类。这将创建该类的一个 "实例"，该实例将作为参数 `commons` 被传递给你的函数。
+**FastAPI** 调用 `CommonQueryParams` 类。 这将创建该类的一个 "实例"，该实例将作为参数 `commons` 被传递给你的函数。
## 类型注解 vs `Depends`
注意，我们在上面的代码中编写了两次`CommonQueryParams`：
-```Python
-commons: CommonQueryParams = Depends(CommonQueryParams)
-```
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python
+ commons: CommonQueryParams = Depends(CommonQueryParams)
+ ```
+
+=== "Python 3.6+"
+
+ ```Python
+ ... = Depends(CommonQueryParams)
+ ```
最后的 `CommonQueryParams`:
```Python
-... = Depends(CommonQueryParams)
+... Depends(CommonQueryParams)
```
...实际上是 **Fastapi** 用来知道依赖项是什么的。
@@ -169,27 +300,74 @@ FastAPI 将从依赖项中提取声明的参数，这才是 FastAPI 实际调用
在本例中，第一个 `CommonQueryParams` ：
-```Python
-commons: CommonQueryParams ...
-```
+=== "Python 3.6+"
+
+ ```Python
+ 这就是 "可调用对象"。
+ ```
-...对于 **FastAPI** 没有任何特殊的意义。FastAPI 不会使用它进行数据转换、验证等 (因为对于这，它使用 `= Depends(CommonQueryParams)`)。
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python
+ commons: CommonQueryParams ...
+ ```
+
+...对于 **FastAPI** 没有任何特殊的意义。 FastAPI 不会使用它进行数据转换、验证等 (因为对于这，它使用 `= Depends(CommonQueryParams)`)。
你实际上可以只这样编写:
-```Python
-commons = Depends(CommonQueryParams)
-```
+=== "Python 3.6+"
+
+ ```Python
+ !!! tip
+ 如果这看起来更加混乱而不是更加有帮助，那么请忽略它，你不需要它。
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python
+ commons = Depends(CommonQueryParams)
+ ```
..就像:
=== "Python 3.10+"
+ ```Python hl_lines="19"
+ {!> ../../../docs_src/dependencies/tutorial003_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="19"
+ {!> ../../../docs_src/dependencies/tutorial003_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="20"
+ {!> ../../../docs_src/dependencies/tutorial003_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
```Python hl_lines="17"
{!> ../../../docs_src/dependencies/tutorial003_py310.py!}
```
-=== "Python 3.6+"
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
```Python hl_lines="19"
{!> ../../../docs_src/dependencies/tutorial003.py!}
@@ -197,15 +375,26 @@ commons = Depends(CommonQueryParams)
但是声明类型是被鼓励的，因为那样你的编辑器就会知道将传递什么作为参数 `commons` ，然后它可以帮助你完成代码，类型检查，等等：
-
+
## 快捷方式
但是您可以看到，我们在这里有一些代码重复了，编写了`CommonQueryParams`两次：
-```Python
-commons: CommonQueryParams = Depends(CommonQueryParams)
-```
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python
+ commons: CommonQueryParams = Depends(CommonQueryParams)
+ ```
+
+=== "Python 3.6+"
+
+ ```Python
+ commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
+ ```
**FastAPI** 为这些情况提供了一个快捷方式，在这些情况下，依赖项 *明确地* 是一个类，**FastAPI** 将 "调用" 它来创建类本身的一个实例。
@@ -213,15 +402,37 @@ commons: CommonQueryParams = Depends(CommonQueryParams)
不是写成这样：
-```Python
-commons: CommonQueryParams = Depends(CommonQueryParams)
-```
+=== "Python 3.6+"
+
+ ```Python
+ commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python
+ commons: CommonQueryParams = Depends(CommonQueryParams)
+ ```
...而是这样写:
-```Python
-commons: CommonQueryParams = Depends()
-```
+=== "Python 3.6+"
+
+ ```Python
+ 关键因素是依赖项应该是 "可调用对象"。
+ ```
+
+=== "Python 3.6 non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python
+ commons: CommonQueryParams = Depends()
+ ```
您声明依赖项作为参数的类型，并使用 `Depends()` 作为该函数的参数的 "默认" 值(在 `=` 之后)，而在 `Depends()` 中没有任何参数，而不是在 `Depends(CommonQueryParams)` 编写完整的类。
@@ -229,11 +440,35 @@ commons: CommonQueryParams = Depends()
=== "Python 3.10+"
+ ```Python hl_lines="19"
+ {!> ../../../docs_src/dependencies/tutorial004_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="19"
+ {!> ../../../docs_src/dependencies/tutorial004_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="20"
+ {!> ../../../docs_src/dependencies/tutorial004_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
```Python hl_lines="17"
{!> ../../../docs_src/dependencies/tutorial004_py310.py!}
```
-=== "Python 3.6+"
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
```Python hl_lines="19"
{!> ../../../docs_src/dependencies/tutorial004.py!}
@@ -242,6 +477,6 @@ commons: CommonQueryParams = Depends()
... **FastAPI** 会知道怎么处理。
!!! tip
- 如果这看起来更加混乱而不是更加有帮助，那么请忽略它，你不*需要*它。
+ If that seems more confusing than helpful, disregard it, you don't *need* it.
- 这只是一个快捷方式。因为 **FastAPI** 关心的是帮助您减少代码重复。
+ 这只是一个快捷方式。 因为 **FastAPI** 关心的是帮助您减少代码重复。
diff --git a/docs/zh/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md b/docs/zh/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md
index 61ea371e5453e..f7961ad050a95 100644
--- a/docs/zh/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md
+++ b/docs/zh/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md
@@ -4,7 +4,7 @@
或者说，有些依赖项不返回值。
-但仍要执行或解析该依赖项。
+But you still need it to be executed/solved.
对于这种情况，不必在声明*路径操作函数*的参数时使用 `Depends`，而是可以在*路径操作装饰器*中添加一个由 `dependencies` 组成的 `list`。
@@ -14,23 +14,36 @@
该参数的值是由 `Depends()` 组成的 `list`：
-```Python hl_lines="17"
-{!../../../docs_src/dependencies/tutorial006.py!}
-```
+=== "Python 3.9+"
-路径操作装饰器依赖项（以下简称为**“路径装饰器依赖项”**）的执行或解析方式和普通依赖项一样，但就算这些依赖项会返回值，它们的值也不会传递给*路径操作函数*。
+ ```Python hl_lines="19"
+ {!> ../../../docs_src/dependencies/tutorial006_an_py39.py!}
+ ```
-!!! tip "提示"
+=== "Python 3.6+"
- 有些编辑器会检查代码中没使用过的函数参数，并显示错误提示。
+ ```Python hl_lines="18"
+ !!! tip "提示"
+ ```
- 在*路径操作装饰器*中使用 `dependencies` 参数，可以确保在执行依赖项的同时，避免编辑器显示错误提示。
+=== "Python 3.6 non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="17"
+ {!../../../docs_src/dependencies/tutorial006.py!}
+ ```
- 使用路径装饰器依赖项还可以避免开发新人误会代码中包含无用的未使用参数。
+These dependencies will be executed/solved the same way normal dependencies. But their value (if they return any) won't be passed to your *path operation function*.
-!!! info "说明"
+!!! 有些编辑器会检查代码中没使用过的函数参数，并显示错误提示。
- 本例中，使用的是自定义响应头 `X-Key` 和 `X-Token`。
+ 在*路径操作装饰器*中使用 `dependencies` 参数，可以确保在执行依赖项的同时，避免编辑器显示错误提示。
+
+ It might also help avoid confusion for new developers that see an unused parameter in your code and could think it's unnecessary.
+
+!!! 本例中，使用的是自定义响应头 `X-Key` 和 `X-Token`。
但实际开发中，尤其是在实现安全措施时，最好使用 FastAPI 内置的[安全工具](../security/index.md){.internal-link target=_blank}（详见下一章）。
@@ -42,27 +55,78 @@
路径装饰器依赖项可以声明请求的需求项（比如响应头）或其他子依赖项：
-```Python hl_lines="6 11"
-{!../../../docs_src/dependencies/tutorial006.py!}
-```
+=== "Python 3.9+"
+
+ ```Python hl_lines="8 13"
+ {!> ../../../docs_src/dependencies/tutorial006_an_py39.py!}
+ ```
-### 触发异常
+=== "Python 3.6+"
+
+ ```Python hl_lines="7 12"
+ !!! info "说明"
+ ```
+
+=== "Python 3.6 non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="6 11"
+ {!../../../docs_src/dependencies/tutorial006.py!}
+ ```
+
+### Raise exceptions
路径装饰器依赖项与正常的依赖项一样，可以 `raise` 异常：
-```Python hl_lines="8 13"
-{!../../../docs_src/dependencies/tutorial006.py!}
-```
+=== "Python 3.9+"
+
+ ```Python hl_lines="10 15"
+ 但仍要执行或解析该依赖项。
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="9 14"
+ 无论路径装饰器依赖项是否返回值，路径操作都不会使用这些值。
+ ```
+
+=== "Python 3.6 non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="8 13"
+ {!../../../docs_src/dependencies/tutorial006.py!}
+ ```
### 返回值
-无论路径装饰器依赖项是否返回值，路径操作都不会使用这些值。
+And they can return values or not, the values won't be used.
因此，可以复用在其他位置使用过的、（能返回值的）普通依赖项，即使没有使用这个值，也会执行该依赖项：
-```Python hl_lines="9 14"
-{!../../../docs_src/dependencies/tutorial006.py!}
-```
+=== "Python 3.9+"
+
+ ```Python hl_lines="11 16"
+ 路径操作装饰器依赖项（以下简称为“路径装饰器依赖项”）的执行或解析方式和普通依赖项一样，但就算这些依赖项会返回值，它们的值也不会传递给路径操作函数。
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="10 15"
+ 触发异常
+ ```
+
+=== "Python 3.6 non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="9 14"
+ {!../../../docs_src/dependencies/tutorial006.py!}
+ ```
## 为一组路径操作定义依赖项
diff --git a/docs/zh/docs/tutorial/dependencies/dependencies-with-yield.md b/docs/zh/docs/tutorial/dependencies/dependencies-with-yield.md
new file mode 100644
index 0000000000000..c0883364aff4c
--- /dev/null
+++ b/docs/zh/docs/tutorial/dependencies/dependencies-with-yield.md
@@ -0,0 +1,252 @@
+# Dependencies with yield
+
+FastAPI supports dependencies that do some extra steps after finishing.
+
+To do this, use `yield` instead of `return`, and write the extra steps after.
+
+!!! tip
+ Make sure to use `yield` one single time.
+
+!!! note "Technical Details"
+ Any function that is valid to use with:
+
+ * `@contextlib.contextmanager` or
+ * `@contextlib.asynccontextmanager`
+
+ would be valid to use as a **FastAPI** dependency.
+
+ In fact, FastAPI uses those two decorators internally.
+
+## A database dependency with `yield`
+
+For example, you could use this to create a database session and close it after finishing.
+
+Only the code prior to and including the `yield` statement is executed before sending a response:
+
+```Python hl_lines="2-4"
+{!../../../docs_src/dependencies/tutorial007.py!}
+```
+
+The yielded value is what is injected into *path operations* and other dependencies:
+
+```Python hl_lines="4"
+{!../../../docs_src/dependencies/tutorial007.py!}
+```
+
+The code following the `yield` statement is executed after the response has been delivered:
+
+```Python hl_lines="5-6"
+{!../../../docs_src/dependencies/tutorial007.py!}
+```
+
+!!! tip
+ You can use `async` or normal functions.
+
+ **FastAPI** will do the right thing with each, the same as with normal dependencies.
+
+## A dependency with `yield` and `try`
+
+If you use a `try` block in a dependency with `yield`, you'll receive any exception that was thrown when using the dependency.
+
+For example, if some code at some point in the middle, in another dependency or in a *path operation*, made a database transaction "rollback" or create any other error, you will receive the exception in your dependency.
+
+So, you can look for that specific exception inside the dependency with `except SomeException`.
+
+In the same way, you can use `finally` to make sure the exit steps are executed, no matter if there was an exception or not.
+
+```Python hl_lines="3 5"
+{!../../../docs_src/dependencies/tutorial007.py!}
+```
+
+## Sub-dependencies with `yield`
+
+You can have sub-dependencies and "trees" of sub-dependencies of any size and shape, and any or all of them can use `yield`.
+
+**FastAPI** will make sure that the "exit code" in each dependency with `yield` is run in the correct order.
+
+For example, `dependency_c` can have a dependency on `dependency_b`, and `dependency_b` on `dependency_a`:
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="6 14 22"
+ {!> ../../../docs_src/dependencies/tutorial008_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="5 13 21"
+ {!> ../../../docs_src/dependencies/tutorial008_an.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="4 12 20"
+ {!> ../../../docs_src/dependencies/tutorial008.py!}
+ ```
+
+And all of them can use `yield`.
+
+In this case `dependency_c`, to execute its exit code, needs the value from `dependency_b` (here named `dep_b`) to still be available.
+
+And, in turn, `dependency_b` needs the value from `dependency_a` (here named `dep_a`) to be available for its exit code.
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="18-19 26-27"
+ {!> ../../../docs_src/dependencies/tutorial008_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="17-18 25-26"
+ {!> ../../../docs_src/dependencies/tutorial008_an.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="16-17 24-25"
+ {!> ../../../docs_src/dependencies/tutorial008.py!}
+ ```
+
+The same way, you could have dependencies with `yield` and `return` mixed.
+
+And you could have a single dependency that requires several other dependencies with `yield`, etc.
+
+You can have any combinations of dependencies that you want.
+
+**FastAPI** will make sure everything is run in the correct order.
+
+!!! note "Technical Details"
+ This works thanks to Python's Context Managers.
+
+ **FastAPI** uses them internally to achieve this.
+
+## Dependencies with `yield` and `HTTPException`
+
+You saw that you can use dependencies with `yield` and have `try` blocks that catch exceptions.
+
+It might be tempting to raise an `HTTPException` or similar in the exit code, after the `yield`. But **it won't work**.
+
+The exit code in dependencies with `yield` is executed *after* the response is sent, so [Exception Handlers](../handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank} will have already run. There's nothing catching exceptions thrown by your dependencies in the exit code (after the `yield`).
+
+So, if you raise an `HTTPException` after the `yield`, the default (or any custom) exception handler that catches `HTTPException`s and returns an HTTP 400 response won't be there to catch that exception anymore.
+
+This is what allows anything set in the dependency (e.g. a DB session) to, for example, be used by background tasks.
+
+Background tasks are run *after* the response has been sent. So there's no way to raise an `HTTPException` because there's not even a way to change the response that is *already sent*.
+
+But if a background task creates a DB error, at least you can rollback or cleanly close the session in the dependency with `yield`, and maybe log the error or report it to a remote tracking system.
+
+If you have some code that you know could raise an exception, do the most normal/"Pythonic" thing and add a `try` block in that section of the code.
+
+If you have custom exceptions that you would like to handle *before* returning the response and possibly modifying the response, maybe even raising an `HTTPException`, create a [Custom Exception Handler](../handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank}.
+
+!!! tip
+ You can still raise exceptions including `HTTPException` *before* the `yield`. But not after.
+
+The sequence of execution is more or less like this diagram. Time flows from top to bottom. And each column is one of the parts interacting or executing code.
+
+```mermaid
+sequenceDiagram
+
+participant client as Client
+participant handler as Exception handler
+participant dep as Dep with yield
+participant operation as Path Operation
+participant tasks as Background tasks
+
+ Note over client,tasks: Can raise exception for dependency, handled after response is sent
+ Note over client,operation: Can raise HTTPException and can change the response
+ client ->> dep: Start request
+ Note over dep: Run code up to yield
+ opt raise
+ dep -->> handler: Raise HTTPException
+ handler -->> client: HTTP error response
+ dep -->> dep: Raise other exception
+ end
+ dep ->> operation: Run dependency, e.g. DB session
+ opt raise
+ operation -->> dep: Raise HTTPException
+ dep -->> handler: Auto forward exception
+ handler -->> client: HTTP error response
+ operation -->> dep: Raise other exception
+ dep -->> handler: Auto forward exception
+ end
+ operation ->> client: Return response to client
+ Note over client,operation: Response is already sent, can't change it anymore
+ opt Tasks
+ operation -->> tasks: Send background tasks
+ end
+ opt Raise other exception
+ tasks -->> dep: Raise other exception
+ end
+ Note over dep: After yield
+ opt Handle other exception
+ dep -->> dep: Handle exception, can't change response. E.g. close DB session.
+ end
+```
+
+!!! info
+ Only **one response** will be sent to the client. It might be one of the error responses or it will be the response from the *path operation*.
+
+ After one of those responses is sent, no other response can be sent.
+
+!!! tip
+ This diagram shows `HTTPException`, but you could also raise any other exception for which you create a [Custom Exception Handler](../handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank}.
+
+ If you raise any exception, it will be passed to the dependencies with yield, including `HTTPException`, and then **again** to the exception handlers. If there's no exception handler for that exception, it will then be handled by the default internal `ServerErrorMiddleware`, returning a 500 HTTP status code, to let the client know that there was an error in the server.
+
+## Context Managers
+
+### What are "Context Managers"
+
+"Context Managers" are any of those Python objects that you can use in a `with` statement.
+
+For example, you can use `with` to read a file:
+
+```Python
+with open("./somefile.txt") as f:
+ contents = f.read()
+ print(contents)
+```
+
+Underneath, the `open("./somefile.txt")` creates an object that is a called a "Context Manager".
+
+When the `with` block finishes, it makes sure to close the file, even if there were exceptions.
+
+When you create a dependency with `yield`, **FastAPI** will internally convert it to a context manager, and combine it with some other related tools.
+
+### Using context managers in dependencies with `yield`
+
+!!! warning
+ This is, more or less, an "advanced" idea.
+
+ If you are just starting with **FastAPI** you might want to skip it for now.
+
+In Python, you can create Context Managers by creating a class with two methods: `__enter__()` and `__exit__()`.
+
+You can also use them inside of **FastAPI** dependencies with `yield` by using `with` or `async with` statements inside of the dependency function:
+
+```Python hl_lines="1-9 13"
+{!../../../docs_src/dependencies/tutorial010.py!}
+```
+
+!!! tip
+ Another way to create a context manager is with:
+
+ * `@contextlib.contextmanager` or
+ * `@contextlib.asynccontextmanager`
+
+ using them to decorate a function with a single `yield`.
+
+ That's what **FastAPI** uses internally for dependencies with `yield`.
+
+ But you don't have to use the decorators for FastAPI dependencies (and you shouldn't).
+
+ FastAPI will do it for you internally.
diff --git a/docs/zh/docs/tutorial/dependencies/global-dependencies.md b/docs/zh/docs/tutorial/dependencies/global-dependencies.md
index 3f7afa32cd1b3..33e768bbe2f9d 100644
--- a/docs/zh/docs/tutorial/dependencies/global-dependencies.md
+++ b/docs/zh/docs/tutorial/dependencies/global-dependencies.md
@@ -1,17 +1,34 @@
# 全局依赖项
-有时，我们要为整个应用添加依赖项。
+For some types of applications you might want to add dependencies to the whole application.
通过与定义[*路径装饰器依赖项*](dependencies-in-path-operation-decorators.md){.internal-link target=_blank} 类似的方式，可以把依赖项添加至整个 `FastAPI` 应用。
这样一来，就可以为所有*路径操作*应用该依赖项：
-```Python hl_lines="15"
-{!../../../docs_src/dependencies/tutorial012.py!}
-```
+=== "Python 3.9+"
+
+ ```Python hl_lines="16"
+ 有时，我们要为整个应用添加依赖项。
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="16"
+ 为一组路径操作定义依赖项
+ ```
+
+=== "Python 3.6 non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="15"
+ {!../../../docs_src/dependencies/tutorial012.py!}
+ ```
[*路径装饰器依赖项*](dependencies-in-path-operation-decorators.md){.internal-link target=_blank} 一章的思路均适用于全局依赖项， 在本例中，这些依赖项可以用于应用中的所有*路径操作*。
-## 为一组路径操作定义依赖项
+## Dependencies for groups of *path operations*
稍后，[大型应用 - 多文件](../../tutorial/bigger-applications.md){.internal-link target=_blank}一章中会介绍如何使用多个文件创建大型应用程序，在这一章中，您将了解到如何为一组*路径操作*声明单个 `dependencies` 参数。
diff --git a/docs/zh/docs/tutorial/dependencies/index.md b/docs/zh/docs/tutorial/dependencies/index.md
index 7a133061de797..18a301d8e46b0 100644
--- a/docs/zh/docs/tutorial/dependencies/index.md
+++ b/docs/zh/docs/tutorial/dependencies/index.md
@@ -10,18 +10,18 @@ FastAPI 提供了简单易用，但功能强大的** ../../../docs_src/dependencies/tutorial001_py310.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="3"
+ {!../../../docs_src/dependencies/tutorial001.py!}
+ ```
+
+### Declare the dependency, in the "dependant"
与在*路径操作函数*参数中使用 `Body`、`Query` 的方式相同，声明依赖项需要使用 `Depends` 和一个新的参数：
-```Python hl_lines="15 20"
-{!../../../docs_src/dependencies/tutorial001.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="13 18"
+ 外部支持库
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="15 20"
+ 声明依赖项
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="16 21"
+ !!! tip "提示"
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="11 16"
+ {!> ../../../docs_src/dependencies/tutorial001_py310.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="15 20"
+ !!! note "笔记"
+ ```
虽然，在路径操作函数的参数中使用 `Depends` 的方式与 `Body`、`Query` 相同，但 `Depends` 的工作方式略有不同。
-这里只能传给 Depends 一个参数。
+You only give `Depends` a single parameter.
且该参数必须是可调用对象，比如函数。
+上述场景均可以使用**依赖注入**，将代码重复最小化。
+
该函数接收的参数和*路径操作函数*的参数一样。
-!!! tip "提示"
-
- 下一章介绍，除了函数还有哪些「对象」可以用作依赖项。
+!!! tip
+ You'll see what other "things", apart from functions, can be used as dependencies in the next chapter.
接收到新的请求时，**FastAPI** 执行如下操作：
@@ -98,12 +202,49 @@ common_parameters --> read_users
这样，只编写一次代码，**FastAPI** 就可以为多个*路径操作*共享这段代码 。
-!!! check "检查"
-
- 注意，无需创建专门的类，并将之传递给 **FastAPI** 以进行「注册」或执行类似的操作。
+!!! 注意，无需创建专门的类，并将之传递给 **FastAPI** 以进行「注册」或执行类似的操作。
只要把它传递给 `Depends`，**FastAPI** 就知道该如何执行后续操作。
+## Share `Annotated` dependencies
+
+接下来，我们学习一个非常简单的例子，尽管它过于简单，不是很实用。
+
+When you need to use the `common_parameters()` dependency, you have to write the whole parameter with the type annotation and `Depends()`:
+
+```Python
+commons: Annotated[dict, Depends(common_parameters)]
+```
+
+But because we are using `Annotated`, we can store that `Annotated` value in a variable and use it in multiple places:
+
+=== "Python 3.10+"
+
+ ```Python hl_lines="12 16 21"
+ 开发人员可以使用依赖项及其子依赖项为这些路径操作添加不同的权限：
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="14 18 23"
+ 等……
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="15 19 24"
+ 依赖项可以返回各种内容。
+ ```
+
+!!! tip
+ This is just standard Python, it's called a "type alias", it's actually not specific to **FastAPI**.
+
+ But because **FastAPI** is based on the Python standards, including `Annotated`, you can use this trick in your code. 😎
+
+The dependencies will keep working as expected, and the **best part** is that the **type information will be preserved**, which means that your editor will be able to keep providing you with **autocompletion**, **inline errors**, etc. The same for other tools like `mypy`.
+
+上述这些操作都是可行的，**FastAPI** 知道该怎么处理。
+
## 要不要使用 `async`？
**FastAPI** 调用依赖项的方式与*路径操作函数*一样，因此，定义依赖项函数，也要应用与路径操作函数相同的规则。
@@ -112,11 +253,10 @@ common_parameters --> read_users
在普通的 `def` *路径操作函数*中，可以声明异步的 `async def` 依赖项；也可以在异步的 `async def` *路径操作函数*中声明普通的 `def` 依赖项。
-上述这些操作都是可行的，**FastAPI** 知道该怎么处理。
-
-!!! note "笔记"
+It doesn't matter. 然后，**FastAPI** 会用正确的参数调用函数，并提取请求中的数据。
- 如里不了解异步，请参阅[异步：*“着急了？”*](../../async.md){.internal-link target=_blank} 一章中 `async` 和 `await` 的内容。
+!!! note
+ If you don't know, check the [Async: *"In a hurry?"*](../../async.md){.internal-link target=_blank} section about `async` and `await` in the docs.
## 与 OpenAPI 集成
@@ -124,15 +264,15 @@ common_parameters --> read_users
所以，交互文档里也会显示依赖项的所有信息：
-
+
## 简单用法
-观察一下就会发现，只要*路径* 和*操作*匹配，就可以使用声明的路径操作函数。然后，**FastAPI** 会用正确的参数调用函数，并提取请求中的数据。
+开发人员永远都不需要直接调用这些函数，这些函数是由框架（在此为 **FastAPI** ）调用的。
实际上，所有（或大多数）网络框架的工作方式都是这样的。
-开发人员永远都不需要直接调用这些函数，这些函数是由框架（在此为 **FastAPI** ）调用的。
+You never call those functions directly. They are called by your framework (in this case, **FastAPI**).
通过依赖注入系统，只要告诉 **FastAPI** *路径操作函数* 还要「依赖」其他在*路径操作函数*之前执行的内容，**FastAPI** 就会执行函数代码，并「注入」函数返回的结果。
@@ -144,21 +284,21 @@ common_parameters --> read_users
* 可注入（Injectable）
* 组件（Component）
-## **FastAPI** 插件
+## **FastAPI** 兼容性
-**依赖注入**系统支持构建集成和「插件」。但实际上，FastAPI 根本**不需要创建「插件」**，因为使用依赖项可以声明不限数量的、可用于*路径操作函数*的集成与交互。
+**依赖注入**系统支持构建集成和「插件」。 但实际上，FastAPI 根本**不需要创建「插件」**，因为使用依赖项可以声明不限数量的、可用于*路径操作函数*的集成与交互。
-创建依赖项非常简单、直观，并且还支持导入 Python 包。毫不夸张地说，只要几行代码就可以把需要的 Python 包与 API 函数集成在一起。
+创建依赖项非常简单、直观，并且还支持导入 Python 包。 毫不夸张地说，只要几行代码就可以把需要的 Python 包与 API 函数集成在一起。
下一章将详细介绍在关系型数据库、NoSQL 数据库、安全等方面使用依赖项的例子。
-## **FastAPI** 兼容性
+## **FastAPI** 插件
依赖注入系统如此简洁的特性，让 **FastAPI** 可以与下列系统兼容：
* 关系型数据库
* NoSQL 数据库
-* 外部支持库
+* external packages
* 外部 API
* 认证和鉴权系统
* API 使用监控系统
@@ -180,7 +320,7 @@ common_parameters --> read_users
* `/users/{user_id}/activate`
* `/items/pro/`
-开发人员可以使用依赖项及其子依赖项为这些路径操作添加不同的权限：
+then you could add different permission requirements for each of them just with dependencies and sub-dependencies:
```mermaid
graph TB
diff --git a/docs/zh/docs/tutorial/dependencies/sub-dependencies.md b/docs/zh/docs/tutorial/dependencies/sub-dependencies.md
index 58377bbfecd8d..fa61d94fa0bb3 100644
--- a/docs/zh/docs/tutorial/dependencies/sub-dependencies.md
+++ b/docs/zh/docs/tutorial/dependencies/sub-dependencies.md
@@ -6,25 +6,89 @@ FastAPI 支持创建含**子依赖项**的依赖项。
**FastAPI** 负责处理解析不同深度的子依赖项。
-### 第一层依赖项
+## 第一层依赖项
-下列代码创建了第一层依赖项：
+You could create a first dependency ("dependable") like:
-```Python hl_lines="8-9"
-{!../../../docs_src/dependencies/tutorial005.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="8-9"
+ 这个函数很简单（不过也没什么用），但却有助于让我们专注于了解子依赖项的工作方式。
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="8-9"
+ 小结
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="9-10"
+ !!! tip "提示"
+ ```
+
+=== "Python 3.10 non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="6-7"
+ {!../../../docs_src/dependencies/tutorial005.py!}
+ ```
+
+=== "Python 3.6 non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="8-9"
+ {!> ../../../docs_src/dependencies/tutorial005.py!}
+ ```
这段代码声明了类型为 `str` 的可选查询参数 `q`，然后返回这个查询参数。
-这个函数很简单（不过也没什么用），但却有助于让我们专注于了解子依赖项的工作方式。
+This is quite simple (not very useful), but will help us focus on how the sub-dependencies work.
-### 第二层依赖项
+## Second dependency, "dependable" and "dependant"
接下来，创建另一个依赖项函数，并同时用该依赖项自身再声明一个依赖项（所以这也是一个「依赖项」）：
-```Python hl_lines="13"
-{!../../../docs_src/dependencies/tutorial005.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="13"
+ {!> ../../../docs_src/dependencies/tutorial005_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="13"
+ 下列代码创建了第一层依赖项：
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="14"
+ {!> ../../../docs_src/dependencies/tutorial005_an.py!}
+ ```
+
+=== "Python 3.10 non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="11"
+ {!> ../../../docs_src/dependencies/tutorial005_py310.py!}
+ ```
+
+=== "Python 3.6 non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="13"
+ {!../../../docs_src/dependencies/tutorial005.py!}
+ ```
这里重点说明一下声明的参数：
@@ -33,17 +97,47 @@ FastAPI 支持创建含**子依赖项**的依赖项。
* 同时，该函数还声明了类型是 `str` 的可选 cookie（`last_query`）
* 用户未提供查询参数 `q` 时，则使用上次使用后保存在 cookie 中的查询
-### 使用依赖项
+## 使用依赖项
接下来，就可以使用依赖项：
-```Python hl_lines="22"
-{!../../../docs_src/dependencies/tutorial005.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="23"
+ {!> ../../../docs_src/dependencies/tutorial005_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="23"
+ 第二层依赖项
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="24"
+ !!! info "信息"
+ ```
+
+=== "Python 3.10 non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="19"
+ {!> ../../../docs_src/dependencies/tutorial005_py310.py!}
+ ```
+
+=== "Python 3.6 non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
-!!! info "信息"
+ ```Python hl_lines="22"
+ {!../../../docs_src/dependencies/tutorial005.py!}
+ ```
- 注意，这里在*路径操作函数*中只声明了一个依赖项，即 `query_or_cookie_extractor` 。
+!!! 注意，这里在*路径操作函数*中只声明了一个依赖项，即 `query_or_cookie_extractor` 。
但 **FastAPI** 必须先处理 `query_extractor`，以便在调用 `query_or_cookie_extractor` 时使用 `query_extractor` 返回的结果。
@@ -66,12 +160,27 @@ FastAPI 不会为同一个请求多次调用同一个依赖项，而是把依赖
在高级使用场景中，如果不想使用「缓存」值，而是为需要在同一请求的每一步操作（多次）中都实际调用依赖项，可以把 `Depends` 的参数 `use_cache` 的值设置为 `False` :
-```Python hl_lines="1"
-async def needy_dependency(fresh_value: str = Depends(get_value, use_cache=False)):
+=== "Python 3.6+"
+
+ ```Python hl_lines="1"
+ 这些简单的例子现在看上去虽然没有什么实用价值，
+
+但在**安全**一章中，您会了解到这些例子的用途，
+
+以及这些例子所能节省的代码量。
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="1"
+ async def needy_dependency(fresh_value: str = Depends(get_value, use_cache=False)):
return {"fresh_value": fresh_value}
-```
+ ```
-## 小结
+## Recap
千万别被本章里这些花里胡哨的词藻吓倒了，其实**依赖注入**系统非常简单。
@@ -79,10 +188,9 @@ async def needy_dependency(fresh_value: str = Depends(get_value, use_cache=False
但它依然非常强大，能够声明任意嵌套深度的「图」或树状的依赖结构。
-!!! tip "提示"
-
- 这些简单的例子现在看上去虽然没有什么实用价值，
-
- 但在**安全**一章中，您会了解到这些例子的用途，
+!!! tip
+ All this might not seem as useful with these simple examples.
- 以及这些例子所能节省的代码量。
+ But you will see how useful it is in the chapters about **security**.
+
+ And you will also see the amounts of code it will save you.
diff --git a/docs/zh/docs/tutorial/encoder.md b/docs/zh/docs/tutorial/encoder.md
index 76ed846ce35e4..3c0b9152fc1dd 100644
--- a/docs/zh/docs/tutorial/encoder.md
+++ b/docs/zh/docs/tutorial/encoder.md
@@ -36,7 +36,7 @@
调用它的结果后就可以使用Python标准编码中的`json.dumps()`。
-这个操作不会返回一个包含JSON格式（作为字符串）数据的庞大的`str`。它将返回一个Python标准数据结构（例如`dict`），其值和子值都与JSON兼容。
+这个操作不会返回一个包含JSON格式（作为字符串）数据的庞大的`str`。 它将返回一个Python标准数据结构（例如`dict`），其值和子值都与JSON兼容。
-!!! note
- `jsonable_encoder`实际上是FastAPI内部用来转换数据的。但是它在许多其他场景中也很有用。
+!!! !!! note
+ `jsonable_encoder`实际上是FastAPI内部用来转换数据的。 但是它在许多其他场景中也很有用。
diff --git a/docs/zh/docs/tutorial/extra-data-types.md b/docs/zh/docs/tutorial/extra-data-types.md
index ac3e076545f48..60fc4c3bc68df 100644
--- a/docs/zh/docs/tutorial/extra-data-types.md
+++ b/docs/zh/docs/tutorial/extra-data-types.md
@@ -55,12 +55,76 @@
下面是一个*路径操作*的示例，其中的参数使用了上面的一些类型。
-```Python hl_lines="1 3 12-16"
-{!../../../docs_src/extra_data_types/tutorial001.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="1 3 12-16"
+ {!> ../../../docs_src/extra_data_types/tutorial001_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="1 3 12-16"
+ {!> ../../../docs_src/extra_data_types/tutorial001_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="1 3 13-17"
+ {!> ../../../docs_src/extra_data_types/tutorial001_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="1 2 11-15"
+ {!../../../docs_src/extra_data_types/tutorial001.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="1 2 12-16"
+ {!../../../docs_src/extra_data_types/tutorial001.py!}
+ ```
注意，函数内的参数有原生的数据类型，你可以，例如，执行正常的日期操作，如:
-```Python hl_lines="18-19"
-{!../../../docs_src/extra_data_types/tutorial001.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="18-19"
+ {!> ../../../docs_src/extra_data_types/tutorial001_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="18-19"
+ {!> ../../../docs_src/extra_data_types/tutorial001_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="19-20"
+ {!> ../../../docs_src/extra_data_types/tutorial001_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="17-18"
+ {!> ../../../docs_src/extra_data_types/tutorial001_py310.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="18-19"
+ {!> ../../../docs_src/extra_data_types/tutorial001.py!}
+ ```
diff --git a/docs/zh/docs/tutorial/extra-models.md b/docs/zh/docs/tutorial/extra-models.md
index 1fbe77be8de70..1a1f3c3354ca8 100644
--- a/docs/zh/docs/tutorial/extra-models.md
+++ b/docs/zh/docs/tutorial/extra-models.md
@@ -8,8 +8,8 @@
* **输出模型**不应该包含密码。
* **数据库模型**很可能需要保存密码的哈希值。
-!!! danger
- 永远不要存储用户的明文密码。始终存储一个可以用于验证的「安全哈希值」。
+!!! !!! danger
+ 永远不要存储用户的明文密码。 始终存储一个可以用于验证的「安全哈希值」。
如果你尚未了解该知识，你可以在[安全章节](security/simple-oauth2.md#password-hashing){.internal-link target=_blank}中学习何为「密码哈希值」。
@@ -17,9 +17,17 @@
下面是应该如何根据它们的密码字段以及使用位置去定义模型的大概思路：
-```Python hl_lines="9 11 16 22 24 29-30 33-35 40-41"
-{!../../../docs_src/extra_models/tutorial001.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="7 9 14 20 22 27-28 31-33 38-39"
+ {!> ../../../docs_src/extra_models/tutorial001_py310.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="9 11 16 22 24 29-30 33-35 40-41"
+ {!../../../docs_src/extra_models/tutorial001.py!}
+ ```
### 关于 `**user_in.dict()`
@@ -62,7 +70,7 @@ print(user_dict)
#### 解包 `dict`
-如果我们将 `user_dict` 这样的 `dict` 以 `**user_dict` 形式传递给一个函数（或类），Python将对其进行「解包」。它会将 `user_dict` 的键和值作为关键字参数直接传递。
+如果我们将 `user_dict` 这样的 `dict` 以 `**user_dict` 形式传递给一个函数（或类），Python将对其进行「解包」。 它会将 `user_dict` 的键和值作为关键字参数直接传递。
因此，从上面的 `user_dict` 继续，编写：
@@ -94,7 +102,7 @@ UserInDB(
#### 来自于其他模型内容的 Pydantic 模型
-如上例所示，我们从 `user_in.dict（）` 中获得了 `user_dict`，此代码：
+...因为 `user_in.dict()` 是一个 `dict`，然后我们通过以`**`开头传递给 `UserInDB` 来使 Python「解包」它。
```Python
user_dict = user_in.dict()
@@ -107,7 +115,7 @@ UserInDB(**user_dict)
UserInDB(**user_in.dict())
```
-...因为 `user_in.dict()` 是一个 `dict`，然后我们通过以`**`开头传递给 `UserInDB` 来使 Python「解包」它。
+如上例所示，我们从 `user_in.dict（）` 中获得了 `user_dict`，此代码：
这样，我们获得了一个来自于其他 Pydantic 模型中的数据的 Pydantic 模型。
@@ -132,7 +140,7 @@ UserInDB(
```
!!! warning
- 辅助性的额外函数只是为了演示可能的数据流，但它们显然不能提供任何真正的安全性。
+ The supporting additional functions are just to demo a possible flow of the data, but they of course are not providing any real security.
## 减少重复
@@ -144,15 +152,23 @@ UserInDB(
我们可以做得更好。
-我们可以声明一个 `UserBase` 模型作为其他模型的基类。然后我们可以创建继承该模型属性（类型声明，校验等）的子类。
+我们可以声明一个 `UserBase` 模型作为其他模型的基类。 然后我们可以创建继承该模型属性（类型声明，校验等）的子类。
所有的数据转换、校验、文档生成等仍将正常运行。
这样，我们可以仅声明模型之间的差异部分（具有明文的 `password`、具有 `hashed_password` 以及不包括密码）。
-```Python hl_lines="9 15-16 19-20 23-24"
-{!../../../docs_src/extra_models/tutorial002.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="7 13-14 17-18 21-22"
+ {!> ../../../docs_src/extra_models/tutorial002_py310.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="9 15-16 19-20 23-24"
+ {!../../../docs_src/extra_models/tutorial002.py!}
+ ```
## `Union` 或者 `anyOf`
@@ -162,23 +178,53 @@ UserInDB(
为此，请使用标准的 Python 类型提示 `typing.Union`：
+!!! !!! note
+ 定义一个 `Union` 类型时，首先包括最详细的类型，然后是不太详细的类型。 在下面的示例中，更详细的 `PlaneItem` 位于 `Union[PlaneItem，CarItem]` 中的 `CarItem` 之前。
+
+=== "Python 3.10+"
+
+ ```Python hl_lines="1 14-15 18-20 33"
+ {!> ../../../docs_src/extra_models/tutorial003_py310.py!}
+ ```
+
+=== "Python 3.6+"
-!!! note
- 定义一个 `Union` 类型时，首先包括最详细的类型，然后是不太详细的类型。在下面的示例中，更详细的 `PlaneItem` 位于 `Union[PlaneItem，CarItem]` 中的 `CarItem` 之前。
+ ```Python hl_lines="1 14-15 18-20 33"
+ {!../../../docs_src/extra_models/tutorial003.py!}
+ ```
-```Python hl_lines="1 14-15 18-20 33"
-{!../../../docs_src/extra_models/tutorial003.py!}
+### `Union` in Python 3.10
+
+In this example we pass `Union[PlaneItem, CarItem]` as the value of the argument `response_model`.
+
+Because we are passing it as a **value to an argument** instead of putting it in a **type annotation**, we have to use `Union` even in Python 3.10.
+
+If it was in a type annotation we could have used the vertical bar, as:
+
+```Python
+some_variable: PlaneItem | CarItem
```
+But if we put that in `response_model=PlaneItem | CarItem` we would get an error, because Python would try to perform an **invalid operation** between `PlaneItem` and `CarItem` instead of interpreting that as a type annotation.
+
## 模型列表
你可以用同样的方式声明由对象列表构成的响应。
为此，请使用标准的 Python `typing.List`：
-```Python hl_lines="1 20"
-{!../../../docs_src/extra_models/tutorial004.py!}
-```
+=== "Python 3.9+"
+
+ ```Python hl_lines="18"
+ !!! warning
+ 辅助性的额外函数只是为了演示可能的数据流，但它们显然不能提供任何真正的安全性。
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="1 20"
+ {!../../../docs_src/extra_models/tutorial004.py!}
+ ```
## 任意 `dict` 构成的响应
@@ -188,12 +234,20 @@ UserInDB(
在这种情况下，你可以使用 `typing.Dict`：
-```Python hl_lines="1 8"
-{!../../../docs_src/extra_models/tutorial005.py!}
-```
+=== "Python 3.9+"
+
+ ```Python hl_lines="6"
+ 总结
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="1 8"
+ {!../../../docs_src/extra_models/tutorial005.py!}
+ ```
-## 总结
+## Recap
使用多个 Pydantic 模型，并针对不同场景自由地继承。
-如果一个实体必须能够具有不同的「状态」，你无需为每个状态的实体定义单独的数据模型。以用户「实体」为例，其状态有包含 `password`、包含 `password_hash` 以及不含密码。
+如果一个实体必须能够具有不同的「状态」，你无需为每个状态的实体定义单独的数据模型。 以用户「实体」为例，其状态有包含 `password`、包含 `password_hash` 以及不含密码。
diff --git a/docs/zh/docs/tutorial/first-steps.md b/docs/zh/docs/tutorial/first-steps.md
index 30fae99cf8fc2..597e8e6f89acf 100644
--- a/docs/zh/docs/tutorial/first-steps.md
+++ b/docs/zh/docs/tutorial/first-steps.md
@@ -21,16 +21,17 @@ $ uvicorn main:app --reload
INFO: Waiting for application startup.
INFO: Application startup complete.
```
+INFO: Application startup complete.
+```
-!!! note
+!!! !!! note
`uvicorn main:app` 命令含义如下:
* `main`：`main.py` 文件（一个 Python「模块」）。
* `app`：在 `main.py` 文件中通过 `app = FastAPI()` 创建的对象。
- * `--reload`：让服务器在更新代码后重新启动。仅在开发时使用该选项。
-
+ * `--reload`：让服务器在更新代码后重新启动。 仅在开发时使用该选项。
在输出中，会有一行信息像下面这样：
@@ -38,7 +39,6 @@ $ uvicorn main:app --reload
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
-
该行显示了你的应用在本机所提供服务的 URL 地址。
### 查看
@@ -73,23 +73,23 @@ INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
#### 「模式」
-「模式」是对事物的一种定义或描述。它并非具体的实现代码，而只是抽象的描述。
+「模式」是对事物的一种定义或描述。 它并非具体的实现代码，而只是抽象的描述。
#### API「模式」
-在这种场景下，OpenAPI 是一种规定如何定义 API 模式的规范。
+In this case, OpenAPI is a specification that dictates how to define a schema of your API.
定义的 OpenAPI 模式将包括你的 API 路径，以及它们可能使用的参数等等。
#### 数据「模式」
-「模式」这个术语也可能指的是某些数据比如 JSON 的结构。
+The term "schema" might also refer to the shape of some data, like a JSON content.
在这种情况下，它可以表示 JSON 的属性及其具有的数据类型，等等。
#### OpenAPI 和 JSON Schema
-OpenAPI 为你的 API 定义 API 模式。该模式中包含了你的 API 发送和接收的数据的定义（或称为「模式」），这些定义通过 JSON 数据模式标准 **JSON Schema** 所生成。
+OpenAPI 为你的 API 定义 API 模式。 该模式中包含了你的 API 发送和接收的数据的定义（或称为「模式」），这些定义通过 JSON 数据模式标准 **JSON Schema** 所生成。
#### 查看 `openapi.json`
@@ -122,13 +122,13 @@ OpenAPI 为你的 API 定义 API 模式。该模式中包含了你的 API 发送
#### OpenAPI 的用途
-驱动 FastAPI 内置的 2 个交互式文档系统的正是 OpenAPI 模式。
+The OpenAPI schema is what powers the two interactive documentation systems included.
-并且还有数十种替代方案，它们全部都基于 OpenAPI。你可以轻松地将这些替代方案中的任何一种添加到使用 **FastAPI** 构建的应用程序中。
+并且还有数十种替代方案，它们全部都基于 OpenAPI。 你可以轻松地将这些替代方案中的任何一种添加到使用 **FastAPI** 构建的应用程序中。
-你还可以使用它自动生成与你的 API 进行通信的客户端代码。例如 web 前端，移动端或物联网嵌入程序。
+你还可以使用它自动生成与你的 API 进行通信的客户端代码。 例如 web 前端，移动端或物联网嵌入程序。
-## 分步概括
+## Recap, step by step
### 步骤 1：导入 `FastAPI`
@@ -138,7 +138,7 @@ OpenAPI 为你的 API 定义 API 模式。该模式中包含了你的 API 发送
`FastAPI` 是一个为你的 API 提供了所有功能的 Python 类。
-!!! note "技术细节"
+!!! !!! note "技术细节"
`FastAPI` 是直接从 `Starlette` 继承的类。
你可以通过 `FastAPI` 使用所有的 Starlette 的功能。
@@ -201,7 +201,7 @@ https://example.com/items/foo
/items/foo
```
-!!! info
+!!! !!! info
「路径」也通常被称为「端点」或「路由」。
开发 API 时，「路径」是用来分离「关注点」和「资源」的主要手段。
@@ -239,7 +239,7 @@ https://example.com/items/foo
因此，在 OpenAPI 中，每一个 HTTP 方法都被称为「操作」。
-我们也打算称呼它们为「操作」。
+We are going to call them "**operations**" too.
#### 定义一个*路径操作装饰器*
@@ -252,15 +252,14 @@ https://example.com/items/foo
* 请求路径为 `/`
* 使用
@@ -84,7 +84,7 @@ FastAPI 有一个非常棒的社区，它欢迎来自各个领域和背景的朋
{% endif %}
-还有很多其他贡献者（超过100个），你可以在 FastAPI GitHub 贡献者页面 中看到他们。👷
+以下是 **赞助商** 。 😎
## 杰出审核者
@@ -92,7 +92,7 @@ FastAPI 有一个非常棒的社区，它欢迎来自各个领域和背景的朋
### 翻译审核
-我只会说少数几种语言（而且还不是很流利 😅）。所以，具备[能力去批准文档翻译](contributing.md#translations){.internal-link target=_blank} 是这些评审者们。如果没有它们，就不会有多语言文档。
+我只会说少数几种语言（而且还不是很流利 😅）。 所以，具备[能力去批准文档翻译](contributing.md#translations){.internal-link target=_blank} 是这些评审者们。 如果没有它们，就不会有多语言文档。
---
@@ -110,7 +110,7 @@ FastAPI 有一个非常棒的社区，它欢迎来自各个领域和背景的朋
## 赞助商
-以下是 **赞助商** 。😎
+These are the **Sponsors**. 😎
他们主要通过GitHub Sponsors支持我在 **FastAPI** (和其他项目)的工作。
diff --git a/docs/zh/docs/features.md b/docs/zh/docs/features.md
index 2db7f852a9e83..b1a214a1224e6 100644
--- a/docs/zh/docs/features.md
+++ b/docs/zh/docs/features.md
@@ -6,15 +6,14 @@
### 基于开放标准
-
* 用于创建 API 的 OpenAPI 包含了路径操作，请求参数，请求体，安全性等的声明。
* 使用 JSON Schema (因为 OpenAPI 本身就是基于 JSON Schema 的)自动生成数据模型文档。
-* 经过了缜密的研究后围绕这些标准而设计。并非狗尾续貂。
+* 经过了缜密的研究后围绕这些标准而设计。 并非狗尾续貂。
* 这也允许了在很多语言中自动**生成客户端代码**。
### 自动生成文档
-交互式 API 文档以及具探索性 web 界面。因为该框架是基于 OpenAPI，所以有很多可选项，FastAPI 默认自带两个交互式 API 文档。
+交互式 API 文档以及具探索性 web 界面。 因为该框架是基于 OpenAPI，所以有很多可选项，FastAPI 默认自带两个交互式 API 文档。
* Swagger UI，可交互式操作，能在浏览器中直接调用和测试你的 API 。
@@ -26,7 +25,7 @@
### 更主流的 Python
-全部都基于标准的 **Python 3.6 类型**声明（感谢 Pydantic ）。没有新的语法需要学习。只需要标准的 Python 。
+全部都基于标准的 **Python 3.6 类型**声明（感谢 Pydantic ）。 没有新的语法需要学习。 只需要标准的 Python 。
如果你需要2分钟来学习如何使用 Python 类型（即使你不使用 FastAPI ），看看这个简短的教程：[Python Types](python-types.md){.internal-link target=_blank}。
@@ -64,8 +63,7 @@ second_user_data = {
my_second_user: User = User(**second_user_data)
```
-
-!!! info
+!!! !!! info
`**second_user_data` 意思是:
直接将`second_user_data`字典的键和值直接作为key-value参数传递，等同于：`User(id=4, name="Mary", joined="2018-11-30")`
@@ -76,7 +74,7 @@ my_second_user: User = User(**second_user_data)
在最近的 Python 开发者调查中，我们能看到 被使用最多的功能是"自动补全"。
-整个 **FastAPI** 框架就是基于这一点的。任何地方都可以进行自动补全。
+整个 **FastAPI** 框架就是基于这一点的。 任何地方都可以进行自动补全。
你几乎不需要经常回来看文档。
@@ -90,21 +88,19 @@ my_second_user: User = User(**second_user_data)
-你将能进行代码补全，这是在之前你可能曾认为不可能的事。例如，在来自请求 JSON 体（可能是嵌套的）中的键 `price`。
+你将能进行代码补全，这是在之前你可能曾认为不可能的事。 例如，在来自请求 JSON 体（可能是嵌套的）中的键 `price`。
不会再输错键名，来回翻看文档，或者来回滚动寻找你最后使用的 `username` 或者 `user_name` 。
+### Short
-
-### 简洁
-
-任何类型都有合理的**默认值**，任何和地方都有可选配置。所有的参数被微调，来满足你的需求，定义成你需要的 API。
+任何类型都有合理的**默认值**，任何和地方都有可选配置。 所有的参数被微调，来满足你的需求，定义成你需要的 API。
但是默认情况下，一切都能**“顺利工作”**。
### 验证
-* 校验大部分（甚至所有？）的 Python **数据类型**，包括：
+* Validation for most (or all?) 校验大部分（甚至所有？）的 Python **数据类型**，包括：
* JSON 对象 (`dict`).
* JSON 数组 (`list`) 定义成员类型。
* 字符串 (`str`) 字段, 定义最小或最大长度。
@@ -120,14 +116,14 @@ my_second_user: User = User(**second_user_data)
### 安全性及身份验证
-集成了安全性和身份认证。杜绝数据库或者数据模型的渗透风险。
+集成了安全性和身份认证。 杜绝数据库或者数据模型的渗透风险。
OpenAPI 中定义的安全模式，包括：
* HTTP 基本认证。
-* **OAuth2** (也使用 **JWT tokens**)。在 [OAuth2 with JWT](tutorial/security/oauth2-jwt.md){.internal-link target=_blank}查看教程。
+* **OAuth2** (也使用 **JWT tokens**)。 在 [OAuth2 with JWT](tutorial/security/oauth2-jwt.md){.internal-link target=_blank}查看教程。
* API 密钥，在:
- * 请求头。
+ * Headers.
* 查询参数。
* Cookies, 等等。
@@ -135,8 +131,6 @@ OpenAPI 中定义的安全模式，包括：
所有的这些都是可复用的工具和组件，可以轻松与你的系统，数据仓库，关系型以及 NoSQL 数据库等等集成。
-
-
### 依赖注入
FastAPI 有一个使用非常简单，但是非常强大的依赖注入系统。
@@ -162,13 +156,14 @@ FastAPI 有一个使用非常简单，但是非常强大的Pydantic 完全兼容(并基于)。所以，你有的其他的 Pydantic 代码也能正常工作。
+**FastAPI** 和 Starlette 完全兼容(并基于)。 So, any additional Pydantic code you have, will also work.
兼容包括基于 Pydantic 的外部库， 例如用与数据库的 ORMs, ODMs。
-这也意味着在很多情况下，你可以将从请求中获得的相同对象**直接传到数据库**，因为所有的验证都是自动的。
-
反之亦然，在很多情况下，你也可以将从数据库中获取的对象**直接传到客户端**。
+这也意味着在很多情况下，你可以将从请求中获得的相同对象**直接传到数据库**，因为所有的验证都是自动的。
+
通过 **FastAPI** 你可以获得所有 **Pydantic** (FastAPI 基于 Pydantic 做了所有的数据处理)：
* **更简单**：
@@ -194,8 +189,6 @@ FastAPI 有一个使用非常简单，但是非常强大的Tweet about **FastAPI** 让我和大家知道您为什么喜欢 FastAPI。🎉
+Tweet about **FastAPI** 让我和大家知道您为什么喜欢 FastAPI。 🎉
知道有人使用 **FastAPI**，我会很开心，我也想知道您为什么喜欢 FastAPI，以及您在什么项目/哪些公司使用 FastAPI，等等。
## 为 FastAPI 投票
-* 在 Slant 上为 **FastAPI** 投票
-* 在 AlternativeTo 上为 **FastAPI** 投票
+* Vote for **FastAPI** in Slant.
+* Vote for **FastAPI** in AlternativeTo.
+* Say you use **FastAPI** on StackShare.
## 在 GitHub 上帮助其他人解决问题
-您可以查看现有 issues，并尝试帮助其他人解决问题，说不定您能解决这些问题呢。🤓
+You can try and help others with their questions in:
-如果帮助很多人解决了问题，您就有可能成为 [FastAPI 的官方专家](fastapi-people.md#experts){.internal-link target=_blank}。🎉
+* GitHub Discussions
+* GitHub Issues
+
+如果帮助很多人解决了问题，您就有可能成为 [FastAPI 的官方专家](fastapi-people.md#experts){.internal-link target=_blank}。 🎉
+
+**注意**：如果您创建 Issue，我会要求您也要帮助别的用户。 😉
+
+Just remember, the most important point is: try to be kind. People come with their frustrations and in many cases don't ask in the best way, but try as best as you can to be kind. 🤗
+
+The idea is for the **FastAPI** community to be kind and welcoming. At the same time, don't accept bullying or disrespectful behavior towards others. We have to take care of each other.
+
+---
+
+Here's how to help others with questions (in discussions or issues):
+
+### Understand the question
+
+* **Star** 以后，其它用户就能更容易找到 FastAPI，并了解到已经有其他用户在使用它了。
+
+* 如果您选择 "Watching" 而不是 "Releases only"，有人创建新 Issue 时，您会接收到通知。
+
+* In many cases the question asked is about an imaginary solution from the user, but there might be a **better** one. If you can understand the problem and use case better, you might be able to suggest a better **alternative solution**.
+
+* contributing.md#translations
+
+### 创建 Issue
+
+For most of the cases and most of the questions there's something related to the person's **original code**.
+
+In many cases they will only copy a fragment of the code, but that's not enough to **reproduce the problem**.
+
+* You can ask them to provide a minimal, reproducible, example, that you can **copy-paste** and run locally to see the same error or behavior they are seeing, or to understand their use case better.
+
+* If you are feeling too generous, you can try to **create an example** like that yourself, just based on the description of the problem. Just have in mind that this might take a lot of time and it might be better to ask them to clarify the problem first.
+
+### Suggest solutions
+
+* 给我买杯咖啡 ☕️ 以示感谢 😄
+
+* In many cases, it's better to understand their **underlying problem or use case**, because there might be a better way to solve it than what they are trying to do.
+
+### Ask to close
+
+另一方面，聊天室里有成千上万的用户，在这里，您有很大可能遇到聊得来的人。 😄
+
+* Now, if that solved their problem, you can ask them to:
+
+ * 在 **Twitter** 上关注我
+ * 在 **GitHub** 上关注我
## 监听 GitHub 资源库
-您可以在 GitHub 上「监听」FastAPI（点击右上角的 "watch" 按钮）： https://github.com/tiangolo/fastapi. 👀
+您还可以在 GitHub 上 **Watch** FastAPI，（点击右上角的 **Watch** 按钮）https://github.com/tiangolo/fastapi。 👀
-如果您选择 "Watching" 而不是 "Releases only"，有人创建新 Issue 时，您会接收到通知。
+If you select "Watching" instead of "Releases only" you will receive notifications when someone creates a new issue or question. You can also specify that you only want to be notified about new issues, or discussions, or PRs, etc.
然后您就可以尝试并帮助他们解决问题。
-## 创建 Issue
+## Ask Questions
您可以在 GitHub 资源库中创建 Issue，例如：
* 提出**问题**或**意见**
* 提出新**特性**建议
-**注意**：如果您创建 Issue，我会要求您也要帮助别的用户。😉
+当然您也可以成为 FastAPI 的金牌或银牌赞助商。 🏅🎉
+
+## Review Pull Requests
+
+You can help me review pull requests from others.
+
+谢谢！ 🚀
+
+---
-## 创建 PR
+Here's what to have in mind and how to review a pull request:
+
+### Understand the problem
+
+* First, make sure you **understand the problem** that the pull request is trying to solve. It might have a longer discussion in a GitHub Discussion or issue.
+
+* There's also a good chance that the pull request is not actually needed because the problem can be solved in a **different way**. Then you can suggest or ask about that.
+
+### Don't worry about style
+
+* Don't worry too much about things like commit message styles, I will squash and merge customizing the commit manually.
+
+* Also don't worry about style rules, there are already automatized tools checking that.
+
+And if there's any other style or consistency need, I'll ask directly for that, or I'll add commits on top with the needed changes.
+
+### Check the code
+
+* 您可以选择只关注发布（**Releases only**）。
+
+* Then **comment** saying that you did that, that's how I will know you really checked it.
+
+!!! info
+ Unfortunately, I can't simply trust PRs that just have several approvals.
+
+ Several times it has happened that there are PRs with 3, 5 or more approvals, probably because the description is appealing, but when I check the PRs, they are actually broken, have a bug, or don't solve the problem they claim to solve. 😅
+
+ So, it's really important that you actually read and run the code, and let me know in the comments that you did. 🤓
+
+* If the PR can be simplified in a way, you can ask for that, but there's no need to be too picky, there might be a lot of subjective points of view (and I will have my own as well 🙈), so it's better if you can focus on the fundamental things.
+
+### Tests
+
+* 创建 PR
+
+* Check that the tests **fail** before the PR. 🚨
+
+* Then check that the tests **pass** after the PR. ✅
+
+* Many PRs don't have tests, you can **remind** them to add tests, or you can even **suggest** some tests yourself. That's one of the things that consume most time and you can help a lot with that.
+
+* Then also comment what you tried, that way I'll know that you checked it. 🤓
+
+## Create a Pull Request
您可以创建 PR 为源代码做[贡献](contributing.md){.internal-link target=_blank}，例如：
-* 修改文档错别字
+* To fix a typo you found on the documentation.
* 编辑这个文件，分享 FastAPI 的文章、视频、博客，不论是您自己的，还是您看到的都成
* 注意，添加的链接要放在对应区块的开头
* [翻译文档](contributing.md#translations){.internal-link target=_blank}
- * 审阅别人翻译的文档
-* 添加新的文档内容
+ * You can also help to review the translations created by others.
+* To propose new documentation sections.
* 修复现有问题/Bug
+ * Make sure to add tests.
* 添加新功能
+ * Make sure to add tests.
+ * Make sure to add documentation if it's relevant.
+
+## 在 AlternativeTo 上为 **FastAPI** 投票
+
+Help me maintain **FastAPI**! 🤓
+
+There's a lot of work to do, and for most of it, **YOU** can do it.
+
+The main tasks that you can do right now are:
+
+* [Help others with questions in GitHub](#help-others-with-questions-in-github){.internal-link target=_blank} (see the section above).
+* [Review Pull Requests](#review-pull-requests){.internal-link target=_blank} (see the section above).
+
+Those two tasks are what **consume time the most**. That's the main work of maintaining FastAPI.
+
+If you can help me with that, **you are helping me maintain FastAPI** and making sure it keeps **advancing faster and better**. 🚀
## 加入聊天
快加入 👥 Discord 聊天服务器 👥 和 FastAPI 社区里的小伙伴一起哈皮吧。
-!!! tip "提示"
-
- 如有问题，请在 GitHub Issues 里提问，在这里更容易得到 [FastAPI 专家](fastapi-people.md#experts){.internal-link target=_blank}的帮助。
+!!! 如有问题，请在 {\[--lt--]}a href="https://github.com/tiangolo/fastapi/issues/new/choose" class="external-link" target="_blank">GitHub Issues</a> 里提问，在这里更容易得到 [FastAPI 专家\](fastapi-people.md#experts){.internal-link target=_blank}的帮助。
- 聊天室仅供闲聊。
+ Use the chat only for other general conversations.
我们之前还使用过 Gitter chat，但它不支持频道等高级功能，聊天也比较麻烦，所以现在推荐使用 Discord。
@@ -120,19 +236,19 @@
注意，聊天室更倾向于“闲聊”，经常有人会提出一些笼统得让人难以回答的问题，所以在这里提问一般没人回答。
-GitHub Issues 里提供了模板，指引您提出正确的问题，有利于获得优质的回答，甚至可能解决您还没有想到的问题。而且就算答疑解惑要耗费不少时间，我还是会尽量在 GitHub 里回答问题。但在聊天室里，我就没功夫这么做了。😅
+GitHub Issues 里提供了模板，指引您提出正确的问题，有利于获得优质的回答，甚至可能解决您还没有想到的问题。 而且就算答疑解惑要耗费不少时间，我还是会尽量在 GitHub 里回答问题。 但在聊天室里，我就没功夫这么做了。 😅
-聊天室里的聊天内容也不如 GitHub 里好搜索，聊天里的问答很容易就找不到了。只有在 GitHub Issues 里的问答才能帮助您成为 [FastAPI 专家](fastapi-people.md#experts){.internal-link target=_blank}，在 GitHub Issues 中为您带来更多关注。
+聊天室里的聊天内容也不如 GitHub 里好搜索，聊天里的问答很容易就找不到了。 只有在 GitHub Issues 里的问答才能帮助您成为 [FastAPI 专家](fastapi-people.md#experts){.internal-link target=_blank}，在 GitHub Issues 中为您带来更多关注。
-另一方面，聊天室里有成千上万的用户，在这里，您有很大可能遇到聊得来的人。😄
+On the other side, there are thousands of users in the chat systems, so there's a high chance you'll find someone to talk to there, almost all the time. 😄
## 赞助作者
您还可以通过 GitHub 赞助商资助本项目的作者（就是我）。
-给我买杯咖啡 ☕️ 以示感谢 😄
+There you could buy me a coffee ☕️ to say thanks. 😄
-当然您也可以成为 FastAPI 的金牌或银牌赞助商。🏅🎉
+And you can also become a Silver or Gold sponsor for FastAPI. 🏅🎉
## 赞助 FastAPI 使用的工具
@@ -145,4 +261,4 @@ GitHub Issues 里提供了模板，指引您提出正确的问题，有利于获
---
-谢谢！🚀
+Thanks! 🚀
diff --git a/docs/zh/docs/history-design-future.md b/docs/zh/docs/history-design-future.md
new file mode 100644
index 0000000000000..ef6ea883213c2
--- /dev/null
+++ b/docs/zh/docs/history-design-future.md
@@ -0,0 +1,76 @@
+# History, Design and Future
+
+Some time ago, a **FastAPI** user asked:
+
+> What’s the history of this project? It seems to have come from nowhere to awesome in a few weeks [...]
+
+Here's a little bit of that history.
+
+## Alternatives
+
+I have been creating APIs with complex requirements for several years (Machine Learning, distributed systems, asynchronous jobs, NoSQL databases, etc), leading several teams of developers.
+
+As part of that, I needed to investigate, test and use many alternatives.
+
+The history of **FastAPI** is in great part the history of its predecessors.
+
+As said in the section [Alternatives](alternatives.md){.internal-link target=_blank}:
++ **FastAPI** wouldn't exist if not for the previous work of others. + + There have been many tools created before that have helped inspire its creation. + + I have been avoiding the creation of a new framework for several years. First I tried to solve all the features covered by **FastAPI** using many different frameworks, plug-ins, and tools. + + But at some point, there was no other option than creating something that provided all these features, taking the best ideas from previous tools, and combining them in the best way possible, using language features that weren't even available before (Python 3.6+ type hints). ++ +## Investigation + +By using all the previous alternatives I had the chance to learn from all of them, take ideas, and combine them in the best way I could find for myself and the teams of developers I have worked with. + +For example, it was clear that ideally it should be based on standard Python type hints. + +Also, the best approach was to use already existing standards. + +So, before even starting to code **FastAPI**, I spent several months studying the specs for OpenAPI, JSON Schema, OAuth2, etc. Understanding their relationship, overlap, and differences. + +## Design + +Then I spent some time designing the developer "API" I wanted to have as a user (as a developer using FastAPI). + +I tested several ideas in the most popular Python editors: PyCharm, VS Code, Jedi based editors. + +By the last Python Developer Survey, that covers about 80% of the users. + +It means that **FastAPI** was specifically tested with the editors used by 80% of the Python developers. And as most of the other editors tend to work similarly, all its benefits should work for virtually all editors. + +That way I could find the best ways to reduce code duplication as much as possible, to have completion everywhere, type and error checks, etc. + +All in a way that provided the best development experience for all the developers. + +## Requirements + +After testing several alternatives, I decided that I was going to use **Pydantic** for its advantages. + +Then I contributed to it, to make it fully compliant with JSON Schema, to support different ways to define constraint declarations, and to improve editor support (type checks, autocompletion) based on the tests in several editors. + +During the development, I also contributed to **Starlette**, the other key requirement. + +## Development + +By the time I started creating **FastAPI** itself, most of the pieces were already in place, the design was defined, the requirements and tools were ready, and the knowledge about the standards and specifications was clear and fresh. + +## Future + +By this point, it's already clear that **FastAPI** with its ideas is being useful for many people. + +It is being chosen over previous alternatives for suiting many use cases better. + +Many developers and teams already depend on **FastAPI** for their projects (including me and my team). + +But still, there are many improvements and features to come. + +**FastAPI** has a great future ahead. + +And [your help](help-fastapi.md){.internal-link target=_blank} is greatly appreciated. diff --git a/docs/zh/docs/index.md b/docs/zh/docs/index.md index 1de2a8d36d09a..ebd74bc8f00d2 100644 --- a/docs/zh/docs/index.md +++ b/docs/zh/docs/index.md @@ -2,43 +2,45 @@
- FastAPI 框架，高性能，易于学习，高效编码，生产可用 + FastAPI framework, high performance, easy to learn, fast to code, ready for production
--- -**文档**： https://fastapi.tiangolo.com +**Documentation**: https://fastapi.tiangolo.com -**源码**： https://github.com/tiangolo/fastapi +**Source Code**: https://github.com/tiangolo/fastapi --- -FastAPI 是一个用于构建 API 的现代、快速（高性能）的 web 框架，使用 Python 3.6+ 并基于标准的 Python 类型提示。 +FastAPI is a modern, fast (high-performance), web framework for building APIs with Python 3.7+ based on standard Python type hints. -关键特性: +The key features are: -* **快速**：可与 **NodeJS** 和 **Go** 并肩的极高性能（归功于 Starlette 和 Pydantic）。[最快的 Python web 框架之一](#_11)。 +* **Fast**: Very high performance, on par with **NodeJS** and **Go** (thanks to Starlette and Pydantic). [One of the fastest Python frameworks available](#performance). +* **Fast to code**: Increase the speed to develop features by about 200% to 300%. * +* **Fewer bugs**: Reduce about 40% of human (developer) induced errors. * +* **Intuitive**: Great editor support. Completion everywhere. Less time debugging. +* **Easy**: Designed to be easy to use and learn. Less time reading docs. +* **Short**: Minimize code duplication. Multiple features from each parameter declaration. Fewer bugs. +* **Robust**: Get production-ready code. With automatic interactive documentation. +* **Standards-based**: Based on (and fully compatible with) the open standards for APIs: OpenAPI (previously known as Swagger) and JSON Schema. -* **高效编码**：提高功能开发速度约 200％ 至 300％。* -* **更少 bug**：减少约 40％ 的人为（开发者）导致错误。* -* **智能**：极佳的编辑器支持。处处皆可自动补全，减少调试时间。 -* **简单**：设计的易于使用和学习，阅读文档的时间更短。 -* **简短**：使代码重复最小化。通过不同的参数声明实现丰富功能。bug 更少。 -* **健壮**：生产可用级别的代码。还有自动生成的交互式文档。 -* **标准化**：基于（并完全兼容）API 的相关开放标准：OpenAPI (以前被称为 Swagger) 和 JSON Schema。 - -* 根据对某个构建线上应用的内部开发团队所进行的测试估算得出。 +* estimation based on tests on an internal development team, building production applications. ## Sponsors @@ -57,64 +59,70 @@ FastAPI 是一个用于构建 API 的现代、快速（高性能）的 web 框 Other sponsors -## 评价 +## Opinions -「_[...] 最近我一直在使用 **FastAPI**。[...] 实际上我正在计划将其用于我所在的**微软**团队的所有**机器学习服务**。其中一些服务正被集成进核心 **Windows** 产品和一些 **Office** 产品。_」 +"_[...] I'm using **FastAPI** a ton these days. [...] I'm actually planning to use it for all of my team's **ML services at Microsoft**. Some of them are getting integrated into the core **Windows** product and some **Office** products._" -
+
+
+Kabir Khan - 微软 (ref)
+Kabir Khan - Microsoft (ref)
---
-「_我们选择了 **FastAPI** 来创建用于获取**预测结果**的 **REST** 服务。[用于 Ludwig]_」
+"_We adopted the **FastAPI** library to spawn a **REST** server that can be queried to obtain **predictions**. [for Ludwig]_"
-Piero Molino，Yaroslav Dudin 和 Sai Sumanth Miryala - Uber (ref)
+Piero Molino, Yaroslav Dudin, and Sai Sumanth Miryala - Uber (ref)
---
-「_**Netflix** 非常高兴地宣布，正式开源我们的**危机管理**编排框架：**Dispatch**！[使用 **FastAPI** 构建]_」
+"_**Netflix** is pleased to announce the open-source release of our **crisis management** orchestration framework: **Dispatch**! [built with **FastAPI**]_"
-Kevin Glisson，Marc Vilanova，Forest Monsen - Netflix (ref)
+Kevin Glisson, Marc Vilanova, Forest Monsen - Netflix (ref)
---
-「_**FastAPI** 让我兴奋的欣喜若狂。它太棒了！_」
+"_I’m over the moon excited about **FastAPI**. It’s so fun!_"
-Brian Okken - Python Bytes 播客主持人 (ref)
+Brian Okken - Python Bytes podcast host (ref)
---
-「_老实说，你的作品看起来非常可靠和优美。在很多方面，这就是我想让 **Hug** 成为的样子 - 看到有人实现了它真的很鼓舞人心。_」
+"_Honestly, what you've built looks super solid and polished. In many ways, it's what I wanted **Hug** to be - it's really inspiring to see someone build that._"
-
+
---
-「_如果你正打算学习一个**现代框架**用来构建 REST API，来看下 **FastAPI** [...] 它快速、易用且易于学习 [...]_」
+"_If you're looking to learn one **modern framework** for building REST APIs, check out **FastAPI** [...] It's fast, easy to use and easy to learn [...]_"
+
+"_We've switched over to **FastAPI** for our **APIs** [...] I think you'll like it [...]_"
+
+
+
+---
-「_我们已经将 **API** 服务切换到了 **FastAPI** [...] 我认为你会喜欢它的 [...]_」
+"_If anyone is looking to build a production Python API, I would highly recommend **FastAPI**. It is **beautifully designed**, **simple to use** and **highly scalable**, it has become a **key component** in our API first development strategy and is driving many automations and services such as our Virtual TAC Engineer._"
-
+Deon Pillsbury - Cisco (ref)
---
-## **Typer**，命令行中的 FastAPI
+## **Typer**, the FastAPI of CLIs
-如果你正在开发一个在终端中运行的命令行应用而不是 web API，不妨试下 **Typer**。
+If you are building a CLI app to be used in the terminal instead of a web API, check out **Typer**.
-**Typer** 是 FastAPI 的小同胞。它想要成为**命令行中的 FastAPI**。 ⌨️ 🚀
+**Typer** is FastAPI's little sibling. And it's intended to be the **FastAPI of CLIs**. ⌨️ 🚀
-## 依赖
+## Requirements
-Python 3.6 及更高版本
+Python 3.7+
-FastAPI 站在以下巨人的肩膀之上：
+FastAPI stands on the shoulders of giants:
-* Starlette 负责 web 部分。
-* Pydantic 负责数据部分。
+* Starlette for the web parts.
+* Pydantic for the data parts.
-## 安装
+## Installation
@@ -126,7 +134,7 @@ $ pip install fastapi
-你还会需要一个 ASGI 服务器，生产环境可以使用 Uvicorn 或者 Hypercorn。
+You will also need an ASGI server, for production such as Uvicorn or Hypercorn.
@@ -138,11 +146,11 @@ $ pip install "uvicorn[standard]"
-## 示例
+## Example
-### 创建
+### Create it
-* 创建一个 `main.py` 文件并写入以下内容:
+* Create a file `main.py` with:
```Python
from typing import Union
@@ -163,9 +171,9 @@ def read_item(item_id: int, q: Union[str, None] = None):
```
-或者使用
+Or use
-如果你的代码里会出现 `async` / `await`，请使用 `async def`：
+If your code uses `async` / `await`, use `async def`:
```Python hl_lines="9 14"
from typing import Union
@@ -187,13 +195,13 @@ async def read_item(item_id: int, q: Union[str, None] = None):
**Note**:
-如果你不知道是否会用到，可以查看文档的 _"In a hurry?"_ 章节中 关于 `async` 和 `await` 的部分。
+If you don't know, check the _"In a hurry?"_ section about `async` and `await` in the docs.
-### 运行
+### Run it
-通过以下命令运行服务器：
+Run the server with:
或者使用 async def...
+Or use async def...
-如果你的代码里会出现 `async` / `await`，请使用 `async def`：
+If your code uses `async` / `await`, use `async def`:
```Python hl_lines="9 14"
from typing import Union
@@ -187,13 +195,13 @@ async def read_item(item_id: int, q: Union[str, None] = None):
**Note**:
-如果你不知道是否会用到，可以查看文档的 _"In a hurry?"_ 章节中 关于 `async` 和 `await` 的部分。
+If you don't know, check the _"In a hurry?"_ section about `async` and `await` in the docs.
@@ -210,54 +218,54 @@ INFO: Application startup complete.
-关于
+About the command
- `uvicorn main:app` 命令含义如下:
+The command `uvicorn main:app` refers to:
-* `main`：`main.py` 文件（一个 Python "模块"）。
-* `app`：在 `main.py` 文件中通过 `app = FastAPI()` 创建的对象。
-* `--reload`：让服务器在更新代码后重新启动。仅在开发时使用该选项。
+* `main`: the file `main.py` (the Python "module").
+* `app`: the object created inside of `main.py` with the line `app = FastAPI()`.
+* `--reload`: make the server restart after code changes. Only do this for development.
-### 检查
+### Check it
-使用浏览器访问 http://127.0.0.1:8000/items/5?q=somequery。
+Open your browser at http://127.0.0.1:8000/items/5?q=somequery.
-你将会看到如下 JSON 响应：
+You will see the JSON response as:
```JSON
{"item_id": 5, "q": "somequery"}
```
-你已经创建了一个具有以下功能的 API：
+You already created an API that:
-* 通过 _路径_ `/` 和 `/items/{item_id}` 接受 HTTP 请求。
-* 以上 _路径_ 都接受 `GET` 操作（也被称为 HTTP _方法_）。
-* `/items/{item_id}` _路径_ 有一个 _路径参数_ `item_id` 并且应该为 `int` 类型。
-* `/items/{item_id}` _路径_ 有一个可选的 `str` 类型的 _查询参数_ `q`。
+* Receives HTTP requests in the _paths_ `/` and `/items/{item_id}`.
+* Both _paths_ take `GET` operations (also known as HTTP _methods_).
+* The _path_ `/items/{item_id}` has a _path parameter_ `item_id` that should be an `int`.
+* The _path_ `/items/{item_id}` has an optional `str` _query parameter_ `q`.
-### 交互式 API 文档
+### Interactive API docs
-现在访问 http://127.0.0.1:8000/docs。
+Now go to http://127.0.0.1:8000/docs.
-你会看到自动生成的交互式 API 文档（由 Swagger UI生成）：
+You will see the automatic interactive API documentation (provided by Swagger UI):
-### 可选的 API 文档
+### Alternative API docs
-访问 http://127.0.0.1:8000/redoc。
+And now, go to http://127.0.0.1:8000/redoc.
-你会看到另一个自动生成的文档（由 ReDoc 生成）：
+You will see the alternative automatic documentation (provided by ReDoc):
-## 示例升级
+## Example upgrade
-现在修改 `main.py` 文件来从 `PUT` 请求中接收请求体。
+Now modify the file `main.py` to receive a body from a `PUT` request.
-我们借助 Pydantic 来使用标准的 Python 类型声明请求体。
+Declare the body using standard Python types, thanks to Pydantic.
```Python hl_lines="4 9-12 25-27"
from typing import Union
@@ -289,173 +297,174 @@ def update_item(item_id: int, item: Item):
return {"item_name": item.name, "item_id": item_id}
```
-服务器将会自动重载（因为在上面的步骤中你向 `uvicorn` 命令添加了 `--reload` 选项）。
+The server should reload automatically (because you added `--reload` to the `uvicorn` command above).
-### 交互式 API 文档升级
+### Interactive API docs upgrade
-访问 http://127.0.0.1:8000/docs。
+Now go to http://127.0.0.1:8000/docs.
-* 交互式 API 文档将会自动更新，并加入新的请求体：
+* The interactive API documentation will be automatically updated, including the new body:
-* 点击「Try it out」按钮，之后你可以填写参数并直接调用 API：
+* Click on the button "Try it out", it allows you to fill the parameters and directly interact with the API:
-* 然后点击「Execute」按钮，用户界面将会和 API 进行通信，发送参数，获取结果并在屏幕上展示：
+* Then click on the "Execute" button, the user interface will communicate with your API, send the parameters, get the results and show them on the screen:
-### 可选文档升级
+### Alternative API docs upgrade
-访问 http://127.0.0.1:8000/redoc。
+And now, go to http://127.0.0.1:8000/redoc.
-* 可选文档同样会体现新加入的请求参数和请求体：
+* The alternative documentation will also reflect the new query parameter and body:
-### 总结
+### Recap
-总的来说，你就像声明函数的参数类型一样只声明了**一次**请求参数、请求体等的类型。
+In summary, you declare **once** the types of parameters, body, etc. as function parameters.
-你使用了标准的现代 Python 类型来完成声明。
+You do that with standard modern Python types.
-你不需要去学习新的语法、了解特定库的方法或类，等等。
+You don't have to learn a new syntax, the methods or classes of a specific library, etc.
-只需要使用标准的 **Python 3.6 及更高版本**。
+Just standard **Python 3.7+**.
-举个例子，比如声明 `int` 类型：
+For example, for an `int`:
```Python
item_id: int
```
-或者一个更复杂的 `Item` 模型：
+or for a more complex `Item` model:
```Python
item: Item
```
-......在进行一次声明之后，你将获得：
-
-* 编辑器支持，包括：
- * 自动补全
- * 类型检查
-* 数据校验：
- * 在校验失败时自动生成清晰的错误信息
- * 对多层嵌套的 JSON 对象依然执行校验
-* 转换 来自网络请求的输入数据为 Python 数据类型。包括以下数据：
- * JSON
- * 路径参数
- * 查询参数
- * Cookies
- * 请求头
- * 表单
- * 文件
-* 转换 输出的数据：转换 Python 数据类型为供网络传输的 JSON 数据：
- * 转换 Python 基础类型 （`str`、 `int`、 `float`、 `bool`、 `list` 等）
- * `datetime` 对象
- * `UUID` 对象
- * 数据库模型
- * ......以及更多其他类型
-* 自动生成的交互式 API 文档，包括两种可选的用户界面：
- * Swagger UI
- * ReDoc
+...and with that single declaration you get:
+
+* Editor support, including:
+ * Completion.
+ * Type checks.
+* Validation of data:
+ * Automatic and clear errors when the data is invalid.
+ * Validation even for deeply nested JSON objects.
+* Conversion of input data: coming from the network to Python data and types. Reading from:
+ * JSON.
+ * Path parameters.
+ * Query parameters.
+ * Cookies.
+ * Headers.
+ * Forms.
+ * Files.
+* Conversion of output data: converting from Python data and types to network data (as JSON):
+ * Convert Python types (`str`, `int`, `float`, `bool`, `list`, etc).
+ * `datetime` objects.
+ * `UUID` objects.
+ * Database models.
+ * ...and many more.
+* Automatic interactive API documentation, including 2 alternative user interfaces:
+ * Swagger UI.
+ * ReDoc.
---
-回到前面的代码示例，**FastAPI** 将会：
-
-* 校验 `GET` 和 `PUT` 请求的路径中是否含有 `item_id`。
-* 校验 `GET` 和 `PUT` 请求中的 `item_id` 是否为 `int` 类型。
- * 如果不是，客户端将会收到清晰有用的错误信息。
-* 检查 `GET` 请求中是否有命名为 `q` 的可选查询参数（比如 `http://127.0.0.1:8000/items/foo?q=somequery`）。
- * 因为 `q` 被声明为 `= None`，所以它是可选的。
- * 如果没有 `None` 它将会是必需的 (如 `PUT` 例子中的请求体)。
-* 对于访问 `/items/{item_id}` 的 `PUT` 请求，将请求体读取为 JSON 并：
- * 检查是否有必需属性 `name` 并且值为 `str` 类型 。
- * 检查是否有必需属性 `price` 并且值为 `float` 类型。
- * 检查是否有可选属性 `is_offer`， 如果有的话值应该为 `bool` 类型。
- * 以上过程对于多层嵌套的 JSON 对象同样也会执行
-* 自动对 JSON 进行转换或转换成 JSON。
-* 通过 OpenAPI 文档来记录所有内容，可被用于：
- * 交互式文档系统
- * 许多编程语言的客户端代码自动生成系统
-* 直接提供 2 种交互式文档 web 界面。
+Coming back to the previous code example, **FastAPI** will:
+
+* Validate that there is an `item_id` in the path for `GET` and `PUT` requests.
+* Validate that the `item_id` is of type `int` for `GET` and `PUT` requests.
+ * If it is not, the client will see a useful, clear error.
+* Check if there is an optional query parameter named `q` (as in `http://127.0.0.1:8000/items/foo?q=somequery`) for `GET` requests.
+ * As the `q` parameter is declared with `= None`, it is optional.
+ * Without the `None` it would be required (as is the body in the case with `PUT`).
+* For `PUT` requests to `/items/{item_id}`, Read the body as JSON:
+ * Check that it has a required attribute `name` that should be a `str`.
+ * Check that it has a required attribute `price` that has to be a `float`.
+ * Check that it has an optional attribute `is_offer`, that should be a `bool`, if present.
+ * All this would also work for deeply nested JSON objects.
+* Convert from and to JSON automatically.
+* Document everything with OpenAPI, that can be used by:
+ * Interactive documentation systems.
+ * Automatic client code generation systems, for many languages.
+* Provide 2 interactive documentation web interfaces directly.
---
-虽然我们才刚刚开始，但其实你已经了解了这一切是如何工作的。
+We just scratched the surface, but you already get the idea of how it all works.
-尝试更改下面这行代码：
+Try changing the line with:
```Python
return {"item_name": item.name, "item_id": item_id}
```
-......从：
+...from:
```Python
... "item_name": item.name ...
```
-......改为：
+...to:
```Python
... "item_price": item.price ...
```
-......注意观察编辑器是如何自动补全属性并且还知道它们的类型：
+...and see how your editor will auto-complete the attributes and know their types:
-教程 - 用户指南 中有包含更多特性的更完整示例。
+For a more complete example including more features, see the Tutorial - User Guide.
-**剧透警告**： 教程 - 用户指南中的内容有：
+**Spoiler alert**: the tutorial - user guide includes:
-* 对来自不同地方的参数进行声明，如：**请求头**、**cookies**、**form 表单**以及**上传的文件**。
-* 如何设置**校验约束**如 `maximum_length` 或者 `regex`。
-* 一个强大并易于使用的 **依赖注入** 系统。
-* 安全性和身份验证，包括通过 **JWT 令牌**和 **HTTP 基本身份认证**来支持 **OAuth2**。
-* 更进阶（但同样简单）的技巧来声明 **多层嵌套 JSON 模型** （借助 Pydantic）。
-* 许多额外功能（归功于 Starlette）比如：
+* Declaration of **parameters** from other different places as: **headers**, **cookies**, **form fields** and **files**.
+* How to set **validation constraints** as `maximum_length` or `regex`.
+* A very powerful and easy to use **Dependency Injection** system.
+* Security and authentication, including support for **OAuth2** with **JWT tokens** and **HTTP Basic** auth.
+* More advanced (but equally easy) techniques for declaring **deeply nested JSON models** (thanks to Pydantic).
+* **GraphQL** integration with Strawberry and other libraries.
+* Many extra features (thanks to Starlette) as:
* **WebSockets**
- * **GraphQL**
- * 基于 HTTPX 和 `pytest` 的极其简单的测试
+ * extremely easy tests based on HTTPX and `pytest`
* **CORS**
* **Cookie Sessions**
- * ......以及更多
+ * ...and more.
-## 性能
+## Performance
-独立机构 TechEmpower 所作的基准测试结果显示，基于 Uvicorn 运行的 **FastAPI** 程序是 最快的 Python web 框架之一，仅次于 Starlette 和 Uvicorn 本身（FastAPI 内部使用了它们）。(*)
+Independent TechEmpower benchmarks show **FastAPI** applications running under Uvicorn as one of the fastest Python frameworks available, only below Starlette and Uvicorn themselves (used internally by FastAPI). (*)
-想了解更多，请查阅 基准测试 章节。
+To understand more about it, see the section Benchmarks.
-## 可选依赖
+## Optional Dependencies
-用于 Pydantic：
+Used by Pydantic:
-* 关于 uvicorn main:app --reload 命令......
+About the command uvicorn main:app --reload...
- `uvicorn main:app` 命令含义如下:
+The command `uvicorn main:app` refers to:
-* `main`：`main.py` 文件（一个 Python "模块"）。
-* `app`：在 `main.py` 文件中通过 `app = FastAPI()` 创建的对象。
-* `--reload`：让服务器在更新代码后重新启动。仅在开发时使用该选项。
+* `main`: the file `main.py` (the Python "module").
+* `app`: the object created inside of `main.py` with the line `app = FastAPI()`.
+* `--reload`: make the server restart after code changes. Only do this for development.
email_validator - 用于 email 校验。
+* email_validator - for email validation.
+* pydantic-settings - for settings management.
+* pydantic-extra-types - for extra types to be used with Pydantic.
-用于 Starlette：
+Used by Starlette:
-* httpx - 使用 `TestClient` 时安装。
-* jinja2 - 使用默认模板配置时安装。
-* python-multipart - 需要通过 `request.form()` 对表单进行「解析」时安装。
-* itsdangerous - 需要 `SessionMiddleware` 支持时安装。
-* pyyaml - 使用 Starlette 提供的 `SchemaGenerator` 时安装（有 FastAPI 你可能并不需要它）。
-* graphene - 需要 `GraphQLApp` 支持时安装。
-* ujson - 使用 `UJSONResponse` 时安装。
+* httpx - Required if you want to use the `TestClient`.
+* jinja2 - Required if you want to use the default template configuration.
+* python-multipart - Required if you want to support form "parsing", with `request.form()`.
+* itsdangerous - Required for `SessionMiddleware` support.
+* pyyaml - Required for Starlette's `SchemaGenerator` support (you probably don't need it with FastAPI).
+* ujson - Required if you want to use `UJSONResponse`.
-用于 FastAPI / Starlette：
+Used by FastAPI / Starlette:
-* uvicorn - 用于加载和运行你的应用程序的服务器。
-* orjson - 使用 `ORJSONResponse` 时安装。
+* uvicorn - for the server that loads and serves your application.
+* orjson - Required if you want to use `ORJSONResponse`.
-你可以通过 `pip install fastapi[all]` 命令来安装以上所有依赖。
+You can install all of these with `pip install "fastapi[all]"`.
-## 许可协议
+## License
-该项目遵循 MIT 许可协议。
+This project is licensed under the terms of the MIT license.
diff --git a/docs/zh/docs/newsletter.md b/docs/zh/docs/newsletter.md
new file mode 100644
index 0000000000000..782db1353c8d0
--- /dev/null
+++ b/docs/zh/docs/newsletter.md
@@ -0,0 +1,5 @@
+# FastAPI and friends newsletter
+
+
+
+
diff --git a/docs/zh/docs/project-generation.md b/docs/zh/docs/project-generation.md
new file mode 100644
index 0000000000000..8ba34fa11200d
--- /dev/null
+++ b/docs/zh/docs/project-generation.md
@@ -0,0 +1,84 @@
+# Project Generation - Template
+
+You can use a project generator to get started, as it includes a lot of the initial set up, security, database and some API endpoints already done for you.
+
+A project generator will always have a very opinionated setup that you should update and adapt for your own needs, but it might be a good starting point for your project.
+
+## Full Stack FastAPI PostgreSQL
+
+GitHub: https://github.com/tiangolo/full-stack-fastapi-postgresql
+
+### Full Stack FastAPI PostgreSQL - Features
+
+* Full **Docker** integration (Docker based).
+* Docker Swarm Mode deployment.
+* **Docker Compose** integration and optimization for local development.
+* **Production ready** Python web server using Uvicorn and Gunicorn.
+* Python **FastAPI** backend:
+ * **Fast**: Very high performance, on par with **NodeJS** and **Go** (thanks to Starlette and Pydantic).
+ * **Intuitive**: Great editor support. Completion everywhere. Less time debugging.
+ * **Easy**: Designed to be easy to use and learn. Less time reading docs.
+ * **Short**: Minimize code duplication. Multiple features from each parameter declaration.
+ * **Robust**: Get production-ready code. With automatic interactive documentation.
+ * **Standards-based**: Based on (and fully compatible with) the open standards for APIs: OpenAPI and JSON Schema.
+ * **Many other features** including automatic validation, serialization, interactive documentation, authentication with OAuth2 JWT tokens, etc.
+* **Secure password** hashing by default.
+* **JWT token** authentication.
+* **SQLAlchemy** models (independent of Flask extensions, so they can be used with Celery workers directly).
+* Basic starting models for users (modify and remove as you need).
+* **Alembic** migrations.
+* **CORS** (Cross Origin Resource Sharing).
+* **Celery** worker that can import and use models and code from the rest of the backend selectively.
+* REST backend tests based on **Pytest**, integrated with Docker, so you can test the full API interaction, independent on the database. As it runs in Docker, it can build a new data store from scratch each time (so you can use ElasticSearch, MongoDB, CouchDB, or whatever you want, and just test that the API works).
+* Easy Python integration with **Jupyter Kernels** for remote or in-Docker development with extensions like Atom Hydrogen or Visual Studio Code Jupyter.
+* **Vue** frontend:
+ * Generated with Vue CLI.
+ * **JWT Authentication** handling.
+ * Login view.
+ * After login, main dashboard view.
+ * Main dashboard with user creation and edition.
+ * Self user edition.
+ * **Vuex**.
+ * **Vue-router**.
+ * **Vuetify** for beautiful material design components.
+ * **TypeScript**.
+ * Docker server based on **Nginx** (configured to play nicely with Vue-router).
+ * Docker multi-stage building, so you don't need to save or commit compiled code.
+ * Frontend tests ran at build time (can be disabled too).
+ * Made as modular as possible, so it works out of the box, but you can re-generate with Vue CLI or create it as you need, and re-use what you want.
+* **PGAdmin** for PostgreSQL database, you can modify it to use PHPMyAdmin and MySQL easily.
+* **Flower** for Celery jobs monitoring.
+* Load balancing between frontend and backend with **Traefik**, so you can have both under the same domain, separated by path, but served by different containers.
+* Traefik integration, including Let's Encrypt **HTTPS** certificates automatic generation.
+* GitLab **CI** (continuous integration), including frontend and backend testing.
+
+## Full Stack FastAPI Couchbase
+
+GitHub: https://github.com/tiangolo/full-stack-fastapi-couchbase
+
+⚠️ **WARNING** ⚠️
+
+If you are starting a new project from scratch, check the alternatives here.
+
+For example, the project generator Full Stack FastAPI PostgreSQL might be a better alternative, as it is actively maintained and used. And it includes all the new features and improvements.
+
+You are still free to use the Couchbase-based generator if you want to, it should probably still work fine, and if you already have a project generated with it that's fine as well (and you probably already updated it to suit your needs).
+
+You can read more about it in the docs for the repo.
+
+## Full Stack FastAPI MongoDB
+
+...might come later, depending on my time availability and other factors. 😅 🎉
+
+## Machine Learning models with spaCy and FastAPI
+
+GitHub: https://github.com/microsoft/cookiecutter-spacy-fastapi
+
+### Machine Learning models with spaCy and FastAPI - Features
+
+* **spaCy** NER model integration.
+* **Azure Cognitive Search** request format built in.
+* **Production ready** Python web server using Uvicorn and Gunicorn.
+* **Azure DevOps** Kubernetes (AKS) CI/CD deployment built in.
+* **Multilingual** Easily choose one of spaCy's built in languages during project setup.
+* **Easily extensible** to other model frameworks (Pytorch, Tensorflow), not just spaCy.
diff --git a/docs/zh/docs/python-types.md b/docs/zh/docs/python-types.md
index 6cdb4b58838d7..34350d70befba 100644
--- a/docs/zh/docs/python-types.md
+++ b/docs/zh/docs/python-types.md
@@ -1,139 +1,139 @@
-# Python 类型提示简介
+# Python Types Intro
-**Python 3.6+ 版本**加入了对"类型提示"的支持。
+Python has support for optional "type hints" (also called "type annotations").
-这些**"类型提示"**是一种新的语法（在 Python 3.6 版本加入）用来声明一个变量的类型。
+These **"type hints"** or annotations are a special syntax that allow declaring the type of a variable.
-通过声明变量的类型，编辑器和一些工具能给你提供更好的支持。
+By declaring types for your variables, editors and tools can give you better support.
-这只是一个关于 Python 类型提示的**快速入门 / 复习**。它仅涵盖与 **FastAPI** 一起使用所需的最少部分...实际上只有很少一点。
+This is just a **quick tutorial / refresher** about Python type hints. It covers only the minimum necessary to use them with **FastAPI**... which is actually very little.
-整个 **FastAPI** 都基于这些类型提示构建，它们带来了许多优点和好处。
+**FastAPI** is all based on these type hints, they give it many advantages and benefits.
-但即使你不会用到 **FastAPI**，了解一下类型提示也会让你从中受益。
+But even if you never use **FastAPI**, you would benefit from learning a bit about them.
!!! note
- 如果你已经精通 Python，并且了解关于类型提示的一切知识，直接跳到下一章节吧。
+ If you are a Python expert, and you already know everything about type hints, skip to the next chapter.
-## 动机
+## Motivation
-让我们从一个简单的例子开始：
+Let's start with a simple example:
```Python
{!../../../docs_src/python_types/tutorial001.py!}
```
-运行这段程序将输出：
+Calling this program outputs:
```
John Doe
```
-这个函数做了下面这些事情：
+The function does the following:
-* 接收 `first_name` 和 `last_name` 参数。
-* 通过 `title()` 将每个参数的第一个字母转换为大写形式。
-* 中间用一个空格来拼接它们。
+* Takes a `first_name` and `last_name`.
+* Converts the first letter of each one to upper case with `title()`.
+* Concatenates them with a space in the middle.
```Python hl_lines="2"
{!../../../docs_src/python_types/tutorial001.py!}
```
-### 修改示例
+### Edit it
-这是一个非常简单的程序。
+It's a very simple program.
-现在假设你将从头开始编写这段程序。
+But now imagine that you were writing it from scratch.
-在某一时刻，你开始定义函数，并且准备好了参数...。
+At some point you would have started the definition of the function, you had the parameters ready...
-现在你需要调用一个"将第一个字母转换为大写形式的方法"。
+But then you have to call "that method that converts the first letter to upper case".
-等等，那个方法是什么来着？`upper`？还是 `uppercase`？`first_uppercase`？`capitalize`？
+Was it `upper`? Was it `uppercase`? `first_uppercase`? `capitalize`?
-然后你尝试向程序员老手的朋友——编辑器自动补全寻求帮助。
+Then, you try with the old programmer's friend, editor autocompletion.
-输入函数的第一个参数 `first_name`，输入点号（`.`）然后敲下 `Ctrl+Space` 来触发代码补全。
+You type the first parameter of the function, `first_name`, then a dot (`.`) and then hit `Ctrl+Space` to trigger the completion.
-但遗憾的是并没有起什么作用：
+But, sadly, you get nothing useful:
-
+
-### 添加类型
+### Add types
-让我们来修改上面例子的一行代码。
+Let's modify a single line from the previous version.
-我们将把下面这段代码中的函数参数从：
+We will change exactly this fragment, the parameters of the function, from:
```Python
first_name, last_name
```
-改成：
+to:
```Python
first_name: str, last_name: str
```
-就是这样。
+That's it.
-这些就是"类型提示"：
+Those are the "type hints":
```Python hl_lines="1"
{!../../../docs_src/python_types/tutorial002.py!}
```
-这和声明默认值是不同的，例如：
+That is not the same as declaring default values like would be with:
```Python
first_name="john", last_name="doe"
```
-这两者不一样。
+It's a different thing.
-我们用的是冒号（`:`），不是等号（`=`）。
+We are using colons (`:`), not equals (`=`).
-而且添加类型提示一般不会改变原来的运行结果。
+And adding type hints normally doesn't change what happens from what would happen without them.
-现在假设我们又一次正在创建这个函数，这次添加了类型提示。
+But now, imagine you are again in the middle of creating that function, but with type hints.
-在同样的地方，通过 `Ctrl+Space` 触发自动补全，你会发现：
+At the same point, you try to trigger the autocomplete with `Ctrl+Space` and you see:
-
+
-这样，你可以滚动查看选项，直到你找到看起来眼熟的那个：
+With that, you can scroll, seeing the options, until you find the one that "rings a bell":
-
+
-## 更多动机
+## More motivation
-下面是一个已经有类型提示的函数：
+Check this function, it already has type hints:
```Python hl_lines="1"
{!../../../docs_src/python_types/tutorial003.py!}
```
-因为编辑器已经知道了这些变量的类型，所以不仅能对代码进行补全，还能检查其中的错误：
+Because the editor knows the types of the variables, you don't only get completion, you also get error checks:
-
+
-现在你知道了必须先修复这个问题，通过 `str(age)` 把 `age` 转换成字符串：
+Now you know that you have to fix it, convert `age` to a string with `str(age)`:
```Python hl_lines="2"
{!../../../docs_src/python_types/tutorial004.py!}
```
-## 声明类型
+## Declaring types
-你刚刚看到的就是声明类型提示的主要场景。用于函数的参数。
+You just saw the main place to declare type hints. As function parameters.
-这也是你将在 **FastAPI** 中使用它们的主要场景。
+This is also the main place you would use them with **FastAPI**.
-### 简单类型
+### Simple types
-不只是 `str`，你能够声明所有的标准 Python 类型。
+You can declare all the standard Python types, not only `str`.
-比如以下类型：
+You can use, for example:
* `int`
* `float`
@@ -144,143 +144,395 @@ John Doe
{!../../../docs_src/python_types/tutorial005.py!}
```
-### 嵌套类型
+### Generic types with type parameters
-有些容器数据结构可以包含其他的值，比如 `dict`、`list`、`set` 和 `tuple`。它们内部的值也会拥有自己的类型。
+There are some data structures that can contain other values, like `dict`, `list`, `set` and `tuple`. And the internal values can have their own type too.
-你可以使用 Python 的 `typing` 标准库来声明这些类型以及子类型。
+These types that have internal types are called "**generic**" types. And it's possible to declare them, even with their internal types.
-它专门用来支持这些类型提示。
+To declare those types and the internal types, you can use the standard Python module `typing`. It exists specifically to support these type hints.
-#### 列表
+#### Newer versions of Python
-例如，让我们来定义一个由 `str` 组成的 `list` 变量。
+The syntax using `typing` is **compatible** with all versions, from Python 3.6 to the latest ones, including Python 3.9, Python 3.10, etc.
-从 `typing` 模块导入 `List`（注意是大写的 `L`）：
+As Python advances, **newer versions** come with improved support for these type annotations and in many cases you won't even need to import and use the `typing` module to declare the type annotations.
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial006.py!}
-```
+If you can choose a more recent version of Python for your project, you will be able to take advantage of that extra simplicity.
-同样以冒号（`:`）来声明这个变量。
+In all the docs there are examples compatible with each version of Python (when there's a difference).
-输入 `List` 作为类型。
+For example "**Python 3.6+**" means it's compatible with Python 3.6 or above (including 3.7, 3.8, 3.9, 3.10, etc). And "**Python 3.9+**" means it's compatible with Python 3.9 or above (including 3.10, etc).
-由于列表是带有"子类型"的类型，所以我们把子类型放在方括号中：
+If you can use the **latest versions of Python**, use the examples for the latest version, those will have the **best and simplest syntax**, for example, "**Python 3.10+**".
-```Python hl_lines="4"
-{!../../../docs_src/python_types/tutorial006.py!}
-```
+#### List
+
+For example, let's define a variable to be a `list` of `str`.
+
+=== "Python 3.9+"
+
+ Declare the variable, with the same colon (`:`) syntax.
+
+ As the type, put `list`.
+
+ As the list is a type that contains some internal types, you put them in square brackets:
+
+ ```Python hl_lines="1"
+ {!> ../../../docs_src/python_types/tutorial006_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ From `typing`, import `List` (with a capital `L`):
+
+ ``` Python hl_lines="1"
+ {!> ../../../docs_src/python_types/tutorial006.py!}
+ ```
+
+
+ Declare the variable, with the same colon (`:`) syntax.
+
+ As the type, put the `List` that you imported from `typing`.
+
+ As the list is a type that contains some internal types, you put them in square brackets:
+
+ ```Python hl_lines="4"
+ {!> ../../../docs_src/python_types/tutorial006.py!}
+ ```
+
+!!! info
+ Those internal types in the square brackets are called "type parameters".
+
+ In this case, `str` is the type parameter passed to `List` (or `list` in Python 3.9 and above).
+
+That means: "the variable `items` is a `list`, and each of the items in this list is a `str`".
+
+!!! tip
+ If you use Python 3.9 or above, you don't have to import `List` from `typing`, you can use the same regular `list` type instead.
+
+By doing that, your editor can provide support even while processing items from the list:
+
+
+
+Without types, that's almost impossible to achieve.
+
+Notice that the variable `item` is one of the elements in the list `items`.
+
+And still, the editor knows it is a `str`, and provides support for that.
+
+#### Tuple and Set
+
+You would do the same to declare `tuple`s and `set`s:
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="1"
+ {!> ../../../docs_src/python_types/tutorial007_py39.py!}
+ ```
-这表示："变量 `items` 是一个 `list`，并且这个列表里的每一个元素都是 `str`"。
+=== "Python 3.6+"
-这样，即使在处理列表中的元素时，你的编辑器也可以提供支持。
+ ```Python hl_lines="1 4"
+ {!> ../../../docs_src/python_types/tutorial007.py!}
+ ```
-没有类型，几乎是不可能实现下面这样：
+This means:
-
+* The variable `items_t` is a `tuple` with 3 items, an `int`, another `int`, and a `str`.
+* The variable `items_s` is a `set`, and each of its items is of type `bytes`.
-注意，变量 `item` 是列表 `items` 中的元素之一。
+#### Dict
-而且，编辑器仍然知道它是一个 `str`，并为此提供了支持。
+To define a `dict`, you pass 2 type parameters, separated by commas.
-#### 元组和集合
+The first type parameter is for the keys of the `dict`.
-声明 `tuple` 和 `set` 的方法也是一样的：
+The second type parameter is for the values of the `dict`:
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="1"
+ {!> ../../../docs_src/python_types/tutorial008_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="1 4"
+ {!> ../../../docs_src/python_types/tutorial008.py!}
+ ```
+
+This means:
+
+* The variable `prices` is a `dict`:
+ * The keys of this `dict` are of type `str` (let's say, the name of each item).
+ * The values of this `dict` are of type `float` (let's say, the price of each item).
+
+#### Union
+
+You can declare that a variable can be any of **several types**, for example, an `int` or a `str`.
+
+In Python 3.6 and above (including Python 3.10) you can use the `Union` type from `typing` and put inside the square brackets the possible types to accept.
+
+In Python 3.10 there's also a **new syntax** where you can put the possible types separated by a vertical bar (`|`).
+
+=== "Python 3.10+"
+
+ ```Python hl_lines="1"
+ {!> ../../../docs_src/python_types/tutorial008b_py310.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="1 4"
+ {!> ../../../docs_src/python_types/tutorial008b.py!}
+ ```
+
+In both cases this means that `item` could be an `int` or a `str`.
+
+#### Possibly `None`
+
+You can declare that a value could have a type, like `str`, but that it could also be `None`.
+
+In Python 3.6 and above (including Python 3.10) you can declare it by importing and using `Optional` from the `typing` module.
```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial007.py!}
+{!../../../docs_src/python_types/tutorial009.py!}
```
-这表示：
+Using `Optional[str]` instead of just `str` will let the editor help you detecting errors where you could be assuming that a value is always a `str`, when it could actually be `None` too.
+
+`Optional[Something]` is actually a shortcut for `Union[Something, None]`, they are equivalent.
+
+This also means that in Python 3.10, you can use `Something | None`:
+
+=== "Python 3.10+"
+
+ ```Python hl_lines="1"
+ {!> ../../../docs_src/python_types/tutorial009_py310.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="1 4"
+ {!> ../../../docs_src/python_types/tutorial009.py!}
+ ```
+
+=== "Python 3.6+ alternative"
+
+ ```Python hl_lines="1 4"
+ {!> ../../../docs_src/python_types/tutorial009b.py!}
+ ```
+
+#### Using `Union` or `Optional`
-* 变量 `items_t` 是一个 `tuple`，其中的前两个元素都是 `int` 类型, 最后一个元素是 `str` 类型。
-* 变量 `items_s` 是一个 `set`，其中的每个元素都是 `bytes` 类型。
+If you are using a Python version below 3.10, here's a tip from my very **subjective** point of view:
-#### 字典
+* 🚨 Avoid using `Optional[SomeType]`
+* Instead ✨ **use `Union[SomeType, None]`** ✨.
-定义 `dict` 时，需要传入两个子类型，用逗号进行分隔。
+Both are equivalent and underneath they are the same, but I would recommend `Union` instead of `Optional` because the word "**optional**" would seem to imply that the value is optional, and it actually means "it can be `None`", even if it's not optional and is still required.
-第一个子类型声明 `dict` 的所有键。
+I think `Union[SomeType, None]` is more explicit about what it means.
-第二个子类型声明 `dict` 的所有值：
+It's just about the words and names. But those words can affect how you and your teammates think about the code.
+
+As an example, let's take this function:
+
+```Python hl_lines="1 4"
+{!../../../docs_src/python_types/tutorial009c.py!}
+```
+
+The parameter `name` is defined as `Optional[str]`, but it is **not optional**, you cannot call the function without the parameter:
+
+```Python
+say_hi() # Oh, no, this throws an error! 😱
+```
+
+The `name` parameter is **still required** (not *optional*) because it doesn't have a default value. Still, `name` accepts `None` as the value:
+
+```Python
+say_hi(name=None) # This works, None is valid 🎉
+```
+
+The good news is, once you are on Python 3.10 you won't have to worry about that, as you will be able to simply use `|` to define unions of types:
```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial008.py!}
+{!../../../docs_src/python_types/tutorial009c_py310.py!}
```
-这表示：
+And then you won't have to worry about names like `Optional` and `Union`. 😎
+
+#### Generic types
+
+These types that take type parameters in square brackets are called **Generic types** or **Generics**, for example:
+
+=== "Python 3.10+"
+
+ You can use the same builtin types as generics (with square brackets and types inside):
+
+ * `list`
+ * `tuple`
+ * `set`
+ * `dict`
+
+ And the same as with Python 3.6, from the `typing` module:
+
+ * `Union`
+ * `Optional` (the same as with Python 3.6)
+ * ...and others.
+
+ In Python 3.10, as an alternative to using the generics `Union` and `Optional`, you can use the vertical bar (`|`) to declare unions of types, that's a lot better and simpler.
+
+=== "Python 3.9+"
+
+ You can use the same builtin types as generics (with square brackets and types inside):
+
+ * `list`
+ * `tuple`
+ * `set`
+ * `dict`
+
+ And the same as with Python 3.6, from the `typing` module:
+
+ * `Union`
+ * `Optional`
+ * ...and others.
+
+=== "Python 3.6+"
-* 变量 `prices` 是一个 `dict`：
- * 这个 `dict` 的所有键为 `str` 类型（可以看作是字典内每个元素的名称）。
- * 这个 `dict` 的所有值为 `float` 类型（可以看作是字典内每个元素的价格）。
+ * `List`
+ * `Tuple`
+ * `Set`
+ * `Dict`
+ * `Union`
+ * `Optional`
+ * ...and others.
-### 类作为类型
+### Classes as types
-你也可以将类声明为变量的类型。
+You can also declare a class as the type of a variable.
-假设你有一个名为 `Person` 的类，拥有 name 属性：
+Let's say you have a class `Person`, with a name:
```Python hl_lines="1-3"
{!../../../docs_src/python_types/tutorial010.py!}
```
-接下来，你可以将一个变量声明为 `Person` 类型：
+Then you can declare a variable to be of type `Person`:
```Python hl_lines="6"
{!../../../docs_src/python_types/tutorial010.py!}
```
-然后，你将再次获得所有的编辑器支持：
+And then, again, you get all the editor support:
-
+
-## Pydantic 模型
+Notice that this means "`one_person` is an **instance** of the class `Person`".
-Pydantic 是一个用来用来执行数据校验的 Python 库。
+It doesn't mean "`one_person` is the **class** called `Person`".
-你可以将数据的"结构"声明为具有属性的类。
+## Pydantic models
-每个属性都拥有类型。
+Pydantic is a Python library to perform data validation.
-接着你用一些值来创建这个类的实例，这些值会被校验，并被转换为适当的类型（在需要的情况下），返回一个包含所有数据的对象。
+You declare the "shape" of the data as classes with attributes.
-然后，你将获得这个对象的所有编辑器支持。
+And each attribute has a type.
-下面的例子来自 Pydantic 官方文档：
+Then you create an instance of that class with some values and it will validate the values, convert them to the appropriate type (if that's the case) and give you an object with all the data.
-```Python
-{!../../../docs_src/python_types/tutorial010.py!}
-```
+And you get all the editor support with that resulting object.
+
+An example from the official Pydantic docs:
+
+=== "Python 3.10+"
+
+ ```Python
+ {!> ../../../docs_src/python_types/tutorial011_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python
+ {!> ../../../docs_src/python_types/tutorial011_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python
+ {!> ../../../docs_src/python_types/tutorial011.py!}
+ ```
!!! info
- 想进一步了解 Pydantic，请阅读其文档.
+ To learn more about Pydantic, check its docs.
+
+**FastAPI** is all based on Pydantic.
+
+You will see a lot more of all this in practice in the [Tutorial - User Guide](tutorial/index.md){.internal-link target=_blank}.
+
+!!! tip
+ Pydantic has a special behavior when you use `Optional` or `Union[Something, None]` without a default value, you can read more about it in the Pydantic docs about Required Optional fields.
+
+## Type Hints with Metadata Annotations
+
+Python also has a feature that allows putting **additional metadata** in these type hints using `Annotated`.
+
+=== "Python 3.9+"
+
+ In Python 3.9, `Annotated` is part of the standard library, so you can import it from `typing`.
+
+ ```Python hl_lines="1 4"
+ {!> ../../../docs_src/python_types/tutorial013_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ In versions below Python 3.9, you import `Annotated` from `typing_extensions`.
+
+ It will already be installed with **FastAPI**.
+
+ ```Python hl_lines="1 4"
+ {!> ../../../docs_src/python_types/tutorial013.py!}
+ ```
+
+Python itself doesn't do anything with this `Annotated`. And for editors and other tools, the type is still `str`.
+
+But you can use this space in `Annotated` to provide **FastAPI** with additional metadata about how you want your application to behave.
+
+The important thing to remember is that ***the first ***type parameter****** you pass to `Annotated` is the **actual type**. The rest, is just metadata for other tools.
+
+For now, you just need to know that `Annotated` exists, and that it's standard Python. 😎
+
+Later you will see how **powerful** it can be.
-整个 **FastAPI** 建立在 Pydantic 的基础之上。
+!!! tip
+ The fact that this is **standard Python** means that you will still get the **best possible developer experience** in your editor, with the tools you use to analyze and refactor your code, etc. ✨
-实际上你将在 [教程 - 用户指南](tutorial/index.md){.internal-link target=_blank} 看到很多这种情况。
+ And also that your code will be very compatible with many other Python tools and libraries. 🚀
-## **FastAPI** 中的类型提示
+## Type hints in **FastAPI**
-**FastAPI** 利用这些类型提示来做下面几件事。
+**FastAPI** takes advantage of these type hints to do several things.
-使用 **FastAPI** 时用类型提示声明参数可以获得：
+With **FastAPI** you declare parameters with type hints and you get:
-* **编辑器支持**。
-* **类型检查**。
+* **Editor support**.
+* **Type checks**.
-...并且 **FastAPI** 还会用这些类型声明来：
+...and **FastAPI** uses the same declarations to:
-* **定义参数要求**：声明对请求路径参数、查询参数、请求头、请求体、依赖等的要求。
-* **转换数据**：将来自请求的数据转换为需要的类型。
-* **校验数据**： 对于每一个请求：
- * 当数据校验失败时自动生成**错误信息**返回给客户端。
-* 使用 OpenAPI **记录** API：
- * 然后用于自动生成交互式文档的用户界面。
+* **Define requirements**: from request path parameters, query parameters, headers, bodies, dependencies, etc.
+* **Convert data**: from the request to the required type.
+* **Validate data**: coming from each request:
+ * Generating **automatic errors** returned to the client when the data is invalid.
+* **Document** the API using OpenAPI:
+ * which is then used by the automatic interactive documentation user interfaces.
-听上去有点抽象。不过不用担心。你将在 [教程 - 用户指南](tutorial/index.md){.internal-link target=_blank} 中看到所有的实战。
+This might all sound abstract. Don't worry. You'll see all this in action in the [Tutorial - User Guide](tutorial/index.md){.internal-link target=_blank}.
-最重要的是，通过使用标准的 Python 类型，只需要在一个地方声明（而不是添加更多的类、装饰器等），**FastAPI** 会为你完成很多的工作。
+The important thing is that by using standard Python types, in a single place (instead of adding more classes, decorators, etc), **FastAPI** will do a lot of the work for you.
!!! info
- 如果你已经阅读了所有教程，回过头来想了解有关类型的更多信息，来自 `mypy` 的"速查表"是不错的资源。
+ If you already went through all the tutorial and came back to see more about types, a good resource is the "cheat sheet" from `mypy`.
diff --git a/docs/zh/docs/tutorial/background-tasks.md b/docs/zh/docs/tutorial/background-tasks.md
new file mode 100644
index 0000000000000..1782971922ab2
--- /dev/null
+++ b/docs/zh/docs/tutorial/background-tasks.md
@@ -0,0 +1,126 @@
+# Background Tasks
+
+You can define background tasks to be run *after* returning a response.
+
+This is useful for operations that need to happen after a request, but that the client doesn't really have to be waiting for the operation to complete before receiving the response.
+
+This includes, for example:
+
+* Email notifications sent after performing an action:
+ * As connecting to an email server and sending an email tends to be "slow" (several seconds), you can return the response right away and send the email notification in the background.
+* Processing data:
+ * For example, let's say you receive a file that must go through a slow process, you can return a response of "Accepted" (HTTP 202) and process it in the background.
+
+## Using `BackgroundTasks`
+
+First, import `BackgroundTasks` and define a parameter in your *path operation function* with a type declaration of `BackgroundTasks`:
+
+```Python hl_lines="1 13"
+{!../../../docs_src/background_tasks/tutorial001.py!}
+```
+
+**FastAPI** will create the object of type `BackgroundTasks` for you and pass it as that parameter.
+
+## Create a task function
+
+Create a function to be run as the background task.
+
+It is just a standard function that can receive parameters.
+
+It can be an `async def` or normal `def` function, **FastAPI** will know how to handle it correctly.
+
+In this case, the task function will write to a file (simulating sending an email).
+
+And as the write operation doesn't use `async` and `await`, we define the function with normal `def`:
+
+```Python hl_lines="6-9"
+{!../../../docs_src/background_tasks/tutorial001.py!}
+```
+
+## Add the background task
+
+Inside of your *path operation function*, pass your task function to the *background tasks* object with the method `.add_task()`:
+
+```Python hl_lines="14"
+{!../../../docs_src/background_tasks/tutorial001.py!}
+```
+
+`.add_task()` receives as arguments:
+
+* A task function to be run in the background (`write_notification`).
+* Any sequence of arguments that should be passed to the task function in order (`email`).
+* Any keyword arguments that should be passed to the task function (`message="some notification"`).
+
+## Dependency Injection
+
+Using `BackgroundTasks` also works with the dependency injection system, you can declare a parameter of type `BackgroundTasks` at multiple levels: in a *path operation function*, in a dependency (dependable), in a sub-dependency, etc.
+
+**FastAPI** knows what to do in each case and how to re-use the same object, so that all the background tasks are merged together and are run in the background afterwards:
+
+=== "Python 3.10+"
+
+ ```Python hl_lines="13 15 22 25"
+ {!> ../../../docs_src/background_tasks/tutorial002_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="13 15 22 25"
+ {!> ../../../docs_src/background_tasks/tutorial002_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="14 16 23 26"
+ {!> ../../../docs_src/background_tasks/tutorial002_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="11 13 20 23"
+ {!> ../../../docs_src/background_tasks/tutorial002_py310.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="13 15 22 25"
+ {!> ../../../docs_src/background_tasks/tutorial002.py!}
+ ```
+
+In this example, the messages will be written to the `log.txt` file *after* the response is sent.
+
+If there was a query in the request, it will be written to the log in a background task.
+
+And then another background task generated at the *path operation function* will write a message using the `email` path parameter.
+
+## Technical Details
+
+The class `BackgroundTasks` comes directly from `starlette.background`.
+
+It is imported/included directly into FastAPI so that you can import it from `fastapi` and avoid accidentally importing the alternative `BackgroundTask` (without the `s` at the end) from `starlette.background`.
+
+By only using `BackgroundTasks` (and not `BackgroundTask`), it's then possible to use it as a *path operation function* parameter and have **FastAPI** handle the rest for you, just like when using the `Request` object directly.
+
+It's still possible to use `BackgroundTask` alone in FastAPI, but you have to create the object in your code and return a Starlette `Response` including it.
+
+You can see more details in Starlette's official docs for Background Tasks.
+
+## Caveat
+
+If you need to perform heavy background computation and you don't necessarily need it to be run by the same process (for example, you don't need to share memory, variables, etc), you might benefit from using other bigger tools like Celery.
+
+They tend to require more complex configurations, a message/job queue manager, like RabbitMQ or Redis, but they allow you to run background tasks in multiple processes, and especially, in multiple servers.
+
+To see an example, check the [Project Generators](../project-generation.md){.internal-link target=_blank}, they all include Celery already configured.
+
+But if you need to access variables and objects from the same **FastAPI** app, or you need to perform small background tasks (like sending an email notification), you can simply just use `BackgroundTasks`.
+
+## Recap
+
+Import and use `BackgroundTasks` with parameters in *path operation functions* and dependencies to add background tasks.
diff --git a/docs/zh/docs/tutorial/bigger-applications.md b/docs/zh/docs/tutorial/bigger-applications.md
index 9f0134f683c9e..0defc84810e53 100644
--- a/docs/zh/docs/tutorial/bigger-applications.md
+++ b/docs/zh/docs/tutorial/bigger-applications.md
@@ -4,7 +4,7 @@
**FastAPI** 提供了一个方便的工具，可以在保持所有灵活性的同时构建你的应用程序。
-!!! info
+!!! !!! info
如果你来自 Flask，那这将相当于 Flask 的 Blueprints。
## 一个文件结构示例
@@ -26,19 +26,19 @@
│ └── admin.py
```
-!!! tip
+!!! !!! tip
上面有几个 `__init__.py` 文件：每个目录或子目录中都有一个。
这就是能将代码从一个文件导入到另一个文件的原因。
-
+
例如，在 `app/main.py` 中，你可以有如下一行：
```
from app.routers import items
```
-* `app` 目录包含了所有内容。并且它有一个空文件 `app/__init__.py`，因此它是一个「Python 包」（「Python 模块」的集合）：`app`。
-* 它包含一个 `app/main.py` 文件。由于它位于一个 Python 包（一个包含 `__init__.py` 文件的目录）中，因此它是该包的一个「模块」：`app.main`。
+* `app` 目录包含了所有内容。 并且它有一个空文件 `app/__init__.py`，因此它是一个「Python 包」（「Python 模块」的集合）：`app`。
+* 它包含一个 `app/main.py` 文件。 由于它位于一个 Python 包（一个包含 `__init__.py` 文件的目录）中，因此它是该包的一个「模块」：`app.main`。
* 还有一个 `app/dependencies.py` 文件，就像 `app/main.py` 一样，它是一个「模块」：`app.dependencies`。
* 有一个子目录 `app/routers/` 包含另一个 `__init__.py` 文件，因此它是一个「Python 子包」：`app.routers`。
* 文件 `app/routers/items.py` 位于 `app/routers/` 包中，因此它是一个子模块：`app.routers.items`。
@@ -46,23 +46,23 @@
* 还有一个子目录 `app/internal/` 包含另一个 `__init__.py` 文件，因此它是又一个「Python 子包」：`app.internal`。
* `app/internal/admin.py` 是另一个子模块：`app.internal.admin`。
-
+
带有注释的同一文件结构：
```
.
-├── app # 「app」是一个 Python 包
-│ ├── __init__.py # 这个文件使「app」成为一个 Python 包
-│ ├── main.py # 「main」模块，例如 import app.main
-│ ├── dependencies.py # 「dependencies」模块，例如 import app.dependencies
-│ └── routers # 「routers」是一个「Python 子包」
-│ │ ├── __init__.py # 使「routers」成为一个「Python 子包」
-│ │ ├── items.py # 「items」子模块，例如 import app.routers.items
-│ │ └── users.py # 「users」子模块，例如 import app.routers.users
-│ └── internal # 「internal」是一个「Python 子包」
-│ ├── __init__.py # 使「internal」成为一个「Python 子包」
-│ └── admin.py # 「admin」子模块，例如 import app.internal.admin
+├── app # "app" is a Python package
+│ ├── __init__.py # this file makes "app" a "Python package"
+│ ├── main.py # "main" module, e.g. import app.main
+│ ├── dependencies.py # "dependencies" module, e.g. import app.dependencies
+│ └── routers # "routers" is a "Python subpackage"
+│ │ ├── __init__.py # makes "routers" a "Python subpackage"
+│ │ ├── items.py # "items" submodule, e.g. import app.routers.items
+│ │ └── users.py # "users" submodule, e.g. import app.routers.users
+│ └── internal # "internal" is a "Python subpackage"
+│ ├── __init__.py # makes "internal" a "Python subpackage"
+│ └── admin.py # "admin" submodule, e.g. import app.internal.admin
```
## `APIRouter`
@@ -99,7 +99,7 @@
所有相同的 `parameters`、`responses`、`dependencies`、`tags` 等等。
-!!! tip
+!!! !!! tip
在此示例中，该变量被命名为 `router`，但你可以根据你的想法自由命名。
我们将在主 `FastAPI` 应用中包含该 `APIRouter`，但首先，让我们来看看依赖项和另一个 `APIRouter`。
@@ -112,12 +112,51 @@
现在我们将使用一个简单的依赖项来读取一个自定义的 `X-Token` 请求首部：
-```Python hl_lines="1 4-6"
-{!../../../docs_src/bigger_applications/app/dependencies.py!}
-```
+=== "Python 3.9+"
+
+ ```Python hl_lines="3 6-8"
+ .
+├── app
+│ ├── __init__.py
+│ ├── main.py
+│ ├── dependencies.py
+│ └── routers
+│ │ ├── __init__.py
+│ │ ├── items.py
+│ │ └── users.py
+│ └── internal
+│ ├── __init__.py
+│ └── admin.py
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="1 5-7"
+ {!../../../docs_src/bigger_applications/app/dependencies.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="1 4-6"
+ .
+├── app # 「app」是一个 Python 包
+│ ├── __init__.py # 这个文件使「app」成为一个 Python 包
+│ ├── main.py # 「main」模块，例如 import app.main
+│ ├── dependencies.py # 「dependencies」模块，例如 import app.dependencies
+│ └── routers # 「routers」是一个「Python 子包」
+│ │ ├── __init__.py # 使「routers」成为一个「Python 子包」
+│ │ ├── items.py # 「items」子模块，例如 import app.routers.items
+│ │ └── users.py # 「users」子模块，例如 import app.routers.users
+│ └── internal # 「internal」是一个「Python 子包」
+│ ├── __init__.py # 使「internal」成为一个「Python 子包」
+│ └── admin.py # 「admin」子模块，例如 import app.internal.admin
+ ```
!!! tip
- 我们正在使用虚构的请求首部来简化此示例。
+ We are using an invented header to simplify this example.
但在实际情况下，使用集成的[安全性实用工具](./security/index.md){.internal-link target=_blank}会得到更好的效果。
@@ -141,7 +180,8 @@
* 额外的 `responses`。
* `dependencies`：它们都需要我们创建的 `X-Token` 依赖项。
-因此，我们可以将其添加到 `APIRouter` 中，而不是将其添加到每个路径操作中。
+!!! note "技术细节"
+ 实际上，它将在内部为声明在 `APIRouter` 中的每个*路径操作*创建一个*路径操作*。
```Python hl_lines="5-10 16 21"
{!../../../docs_src/bigger_applications/app/routers/items.py!}
@@ -163,7 +203,7 @@ async def read_item(item_id: str):
我们可以添加一个 `dependencies` 列表，这些依赖项将被添加到路由器中的所有*路径操作*中，并将针对向它们发起的每个请求执行/解决。
-!!! tip
+!!! !!! tip
请注意，和[*路径操作装饰器*中的依赖项](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}很类似，没有值会被传递给你的*路径操作函数*。
最终结果是项目相关的路径现在为：
@@ -181,10 +221,10 @@ async def read_item(item_id: str):
* 路由器的依赖项最先执行，然后是[装饰器中的 `dependencies`](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}，再然后是普通的参数依赖项。
* 你还可以添加[具有 `scopes` 的 `Security` 依赖项](../advanced/security/oauth2-scopes.md){.internal-link target=_blank}。
-!!! tip
- 在 `APIRouter`中具有 `dependencies` 可以用来，例如，对一整组的*路径操作*要求身份认证。即使这些依赖项并没有分别添加到每个路径操作中。
+!!! !!! tip
+ 在 `APIRouter`中具有 `dependencies` 可以用来，例如，对一整组的*路径操作*要求身份认证。 即使这些依赖项并没有分别添加到每个路径操作中。
-!!! check
+!!! !!! check
`prefix`、`tags`、`responses` 以及 `dependencies` 参数只是（和其他很多情况一样）**FastAPI** 的一个用于帮助你避免代码重复的功能。
### 导入依赖项
@@ -201,7 +241,7 @@ async def read_item(item_id: str):
#### 相对导入如何工作
-!!! tip
+!!! !!! tip
如果你完全了解导入的工作原理，请从下面的下一部分继续。
一个单点 `.`，例如：
@@ -220,7 +260,7 @@ from .dependencies import get_token_header
请记住我们的程序/文件结构是怎样的：
-
+
---
@@ -230,14 +270,14 @@ from .dependencies import get_token_header
from ..dependencies import get_token_header
```
-表示：
+那将意味着：
* 从该模块（`app/routers/items.py` 文件）所在的同一个包（`app/routers/` 目录）开始...
* 跳转到其父包（`app/` 目录）...
* 在该父包中，找到 `dependencies` 模块（位于 `app/dependencies.py` 的文件）...
* 然后从中导入函数 `get_token_header`。
-正常工作了！🎉
+正常工作了！ 🎉
---
@@ -247,7 +287,7 @@ from ..dependencies import get_token_header
from ...dependencies import get_token_header
```
-那将意味着：
+that would mean:
* 从该模块（`app/routers/items.py` 文件）所在的同一个包（`app/routers/` 目录）开始...
* 跳转到其父包（`app/` 目录）...
@@ -255,9 +295,9 @@ from ...dependencies import get_token_header
* 在该父包中，找到 `dependencies` 模块（位于 `app/` 更上一级目录中的 `dependencies.py` 文件）...
* 然后从中导入函数 `get_token_header`。
-这将引用 `app/` 的往上一级，带有其自己的 `__init __.py` 等文件的某个包。但是我们并没有这个包。因此，这将在我们的示例中引发错误。🚨
+这将引用 `app/` 的往上一级，带有其自己的 `__init __.py` 等文件的某个包。 但是我们并没有这个包。 因此，这将在我们的示例中引发错误。 🚨
-但是现在你知道了它的工作原理，因此无论它们多么复杂，你都可以在自己的应用程序中使用相对导入。🤓
+但是现在你知道了它的工作原理，因此无论它们多么复杂，你都可以在自己的应用程序中使用相对导入。 🤓
### 添加一些自定义的 `tags`、`responses` 和 `dependencies`
@@ -269,7 +309,7 @@ from ...dependencies import get_token_header
{!../../../docs_src/bigger_applications/app/routers/items.py!}
```
-!!! tip
+!!! !!! tip
最后的这个路径操作将包含标签的组合：`["items"，"custom"]`。
并且在文档中也会有两个响应，一个用于 `404`，一个用于 `403`。
@@ -278,7 +318,7 @@ from ...dependencies import get_token_header
现在，让我们来看看位于 `app/main.py` 的模块。
-在这里你导入并使用 `FastAPI` 类。
+你可以像平常一样导入并创建一个 `FastAPI` 类。
这将是你的应用程序中将所有内容联结在一起的主文件。
@@ -286,7 +326,7 @@ from ...dependencies import get_token_header
### 导入 `FastAPI`
-你可以像平常一样导入并创建一个 `FastAPI` 类。
+在这里你导入并使用 `FastAPI` 类。
我们甚至可以声明[全局依赖项](dependencies/global-dependencies.md){.internal-link target=_blank}，它会和每个 `APIRouter` 的依赖项组合在一起：
@@ -302,11 +342,11 @@ from ...dependencies import get_token_header
{!../../../docs_src/bigger_applications/app/main.py!}
```
-由于文件 `app/routers/users.py` 和 `app/routers/items.py` 是同一 Python 包 `app` 一个部分的子模块，因此我们可以使用单个点 ` .` 通过「相对导入」来导入它们。
+由于文件 `app/routers/users.py` 和 `app/routers/items.py` 是同一 Python 包 `app` 一个部分的子模块，因此我们可以使用单个点 `.` 通过「相对导入」来导入它们。
### 导入是如何工作的
-这段代码：
+The section:
```Python
from .routers import items, users
@@ -318,7 +358,7 @@ from .routers import items, users
* 寻找 `routers` 子包（位于 `app/routers/` 的目录）...
* 从该包中，导入子模块 `items` (位于 `app/routers/items.py` 的文件) 以及 `users` (位于 `app/routers/users.py` 的文件)...
-`items` 模块将具有一个 `router` 变量（`items.router`）。这与我们在 `app/routers/items.py` 文件中创建的变量相同，它是一个 `APIRouter` 对象。
+`items` 模块将具有一个 `router` 变量（`items.router`）。 这与我们在 `app/routers/items.py` 文件中创建的变量相同，它是一个 `APIRouter` 对象。
然后我们对 `users` 模块进行相同的操作。
@@ -328,19 +368,21 @@ from .routers import items, users
from app.routers import items, users
```
-!!! info
+!!! !!! info
第一个版本是「相对导入」：
```Python
from .routers import items, users
```
+
第二个版本是「绝对导入」：
```Python
from app.routers import items, users
```
+
要了解有关 Python 包和模块的更多信息，请查阅关于 Modules 的 Python 官方文档。
### 避免名称冲突
@@ -372,7 +414,7 @@ from .routers.users import router
{!../../../docs_src/bigger_applications/app/main.py!}
```
-!!! info
+!!! !!! info
`users.router` 包含了 `app/routers/users.py` 文件中的 `APIRouter`。
`items.router` 包含了 `app/routers/items.py` 文件中的 `APIRouter`。
@@ -381,17 +423,17 @@ from .routers.users import router
它将包含来自该路由器的所有路由作为其一部分。
-!!! note "技术细节"
- 实际上，它将在内部为声明在 `APIRouter` 中的每个*路径操作*创建一个*路径操作*。
+!!! note "Technical Details"
+ It will actually internally create a *path operation* for each *path operation* that was declared in the `APIRouter`.
所以，在幕后，它实际上会像所有的东西都是同一个应用程序一样工作。
-!!! check
+!!! !!! check
包含路由器时，你不必担心性能问题。
这将花费几微秒时间，并且只会在启动时发生。
-
- 因此，它不会影响性能。⚡
+
+ 因此，它不会影响性能。 ⚡
### 包含一个有自定义 `prefix`、`tags`、`responses` 和 `dependencies` 的 `APIRouter`
@@ -399,7 +441,7 @@ from .routers.users import router
它包含一个带有一些由你的组织在多个项目之间共享的管理员*路径操作*的 `APIRouter`。
-对于此示例，它将非常简单。但是假设由于它是与组织中的其他项目所共享的，因此我们无法对其进行修改，以及直接在 `APIRouter` 中添加 `prefix`、`dependencies`、`tags` 等：
+对于此示例，它将非常简单。 但是假设由于它是与组织中的其他项目所共享的，因此我们无法对其进行修改，以及直接在 `APIRouter` 中添加 `prefix`、`dependencies`、`tags` 等：
```Python hl_lines="3"
{!../../../docs_src/bigger_applications/app/internal/admin.py!}
@@ -407,7 +449,7 @@ from .routers.users import router
但是我们仍然希望在包含 `APIRouter` 时设置一个自定义的 `prefix`，以便其所有*路径操作*以 `/admin` 开头，我们希望使用本项目已经有的 `dependencies` 保护它，并且我们希望它包含自定义的 `tags` 和 `responses`。
-我们可以通过将这些参数传递给 `app.include_router()` 来完成所有的声明，而不必修改原始的 `APIRouter`：
+但这只会影响我们应用中的 `APIRouter`，而不会影响使用它的任何其他代码。
```Python hl_lines="14-17"
{!../../../docs_src/bigger_applications/app/main.py!}
@@ -422,7 +464,7 @@ from .routers.users import router
* `get_token_header` 依赖项。
* `418` 响应。 🍵
-但这只会影响我们应用中的 `APIRouter`，而不会影响使用它的任何其他代码。
+因此，我们可以将其添加到 `APIRouter` 中，而不是将其添加到每个路径操作中。
因此，举例来说，其他项目能够以不同的身份认证方法使用相同的 `APIRouter`。
@@ -438,15 +480,15 @@ from .routers.users import router
它将与通过 `app.include_router()` 添加的所有其他*路径操作*一起正常运行。
-!!! info "特别的技术细节"
+!!! !!! info "特别的技术细节"
**注意**：这是一个非常技术性的细节，你也许可以**直接跳过**。
---
-
+
`APIRouter` 没有被「挂载」，它们与应用程序的其余部分没有隔离。
-
+
这是因为我们想要在 OpenAPI 模式和用户界面中包含它们的*路径操作*。
-
+
由于我们不能仅仅隔离它们并独立于其余部分来「挂载」它们，因此*路径操作*是被「克隆的」（重新创建），而不是直接包含。
## 查看自动化的 API 文档
@@ -467,7 +509,7 @@ $ uvicorn app.main:app --reload
你将看到使用了正确路径（和前缀）和正确标签的自动化 API 文档，包括了来自所有子模块的路径：
-
+
## 多次使用不同的 `prefix` 包含同一个路由器
diff --git a/docs/zh/docs/tutorial/body-fields.md b/docs/zh/docs/tutorial/body-fields.md
index 053cae71c7c6f..da96baaecfbc0 100644
--- a/docs/zh/docs/tutorial/body-fields.md
+++ b/docs/zh/docs/tutorial/body-fields.md
@@ -1,4 +1,4 @@
-# 请求体 - 字段
+# Body - Fields
与使用 `Query`、`Path` 和 `Body` 在*路径操作函数*中声明额外的校验和元数据的方式相同，你可以使用 Pydantic 的 `Field` 在 Pydantic 模型内部声明校验和元数据。
@@ -6,42 +6,118 @@
首先，你必须导入它：
-```Python hl_lines="2"
-{!../../../docs_src/body_fields/tutorial001.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="4"
+ {!> ../../../docs_src/body_fields/tutorial001_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="4"
+ {!> ../../../docs_src/body_fields/tutorial001_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="4"
+ !!! note "技术细节"
+ 实际上，Query、Path 和其他你将在之后看到的类，创建的是由一个共同的 Params 类派生的子类的对象，该共同类本身又是 Pydantic 的 FieldInfo 类的子类。
+ ```
+、Path 和其他你将在之后看到的类，创建的是由一个共同的 Params 类派生的子类的对象，该共同类本身又是 Pydantic 的 FieldInfo 类的子类。
+
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="2"
+ {!../../../docs_src/body_fields/tutorial001.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="4"
+ !!! tip
+ 注意每个模型属性如何使用类型、默认值和 Field 在代码结构上和路径操作函数的参数是相同的，区别是用 Field 替换Path、Query 和 Body。
+ ```
+ 在代码结构上和*路径操作函数*的参数是相同的，区别是用 Field 替换Path、Query 和 Body。
+
!!! warning
- 注意，`Field` 是直接从 `pydantic` 导入的，而不是像其他的（`Query`，`Path`，`Body` 等）都从 `fastapi` 导入。
+ Notice that `Field` is imported directly from `pydantic`, not from `fastapi` as are all the rest (`Query`, `Path`, `Body`, etc).
## 声明模型属性
然后，你可以对模型属性使用 `Field`：
-```Python hl_lines="9-10"
-{!../../../docs_src/body_fields/tutorial001.py!}
-```
+=== "Python 3.10+"
-`Field` 的工作方式和 `Query`、`Path` 和 `Body` 相同，包括它们的参数等等也完全相同。
+ ```Python hl_lines="11-14"
+ 总结
+ ```
-!!! note "技术细节"
- 实际上，`Query`、`Path` 和其他你将在之后看到的类，创建的是由一个共同的 `Params` 类派生的子类的对象，该共同类本身又是 Pydantic 的 `FieldInfo` 类的子类。
+=== "Python 3.9+"
- Pydantic 的 `Field` 也会返回一个 `FieldInfo` 的实例。
+ ```Python hl_lines="11-14"
+ {!> ../../../docs_src/body_fields/tutorial001_an_py39.py!}
+ ```
- `Body` 也直接返回 `FieldInfo` 的一个子类的对象。还有其他一些你之后会看到的类是 `Body` 类的子类。
+=== "Python 3.6+"
+ ```Python hl_lines="12-15"
+ 请求体 - 字段
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="9-12"
+ {!../../../docs_src/body_fields/tutorial001.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="11-14"
+ !!! warning
+ 注意，Field 是直接从 pydantic 导入的，而不是像其他的（Query，Path，Body 等）都从 fastapi 导入。
+ ```
+ 是直接从 pydantic 导入的，而不是像其他的（Query，Path，Body 等）都从 fastapi 导入。
+
+
+`Field` 的工作方式和 `Query`、`Path` 和 `Body` 相同，包括它们的参数等等也完全相同。
+
+!!! note "Technical Details"
+ Actually, `Query`, `Path` and others you'll see next create objects of subclasses of a common `Param` class, which is itself a subclass of Pydantic's `FieldInfo` class.
+
+ Pydantic 的 `Field` 也会返回一个 `FieldInfo` 的实例。
+
+ `Body` 也直接返回 `FieldInfo` 的一个子类的对象。 还有其他一些你之后会看到的类是 `Body` 类的子类。
+
请记住当你从 `fastapi` 导入 `Query`、`Path` 等对象时，他们实际上是返回特殊类的函数。
!!! tip
- 注意每个模型属性如何使用类型、默认值和 `Field` 在代码结构上和*路径操作函数*的参数是相同的，区别是用 `Field` 替换`Path`、`Query` 和 `Body`。
+ Notice how each model's attribute with a type, default value and `Field` has the same structure as a *path operation function's* parameter, with `Field` instead of `Path`, `Query` and `Body`.
## 添加额外信息
-你可以在 `Field`、`Query`、`Body` 中声明额外的信息。这些信息将包含在生成的 JSON Schema 中。
+你可以在 `Field`、`Query`、`Body` 中声明额外的信息。 这些信息将包含在生成的 JSON Schema 中。
你将在文档的后面部分学习声明示例时，了解到更多有关添加额外信息的知识。
-## 总结
+!!! warning
+ Extra keys passed to `Field` will also be present in the resulting OpenAPI schema for your application. As these keys may not necessarily be part of the OpenAPI specification, some OpenAPI tools, for example [the OpenAPI validator](https://validator.swagger.io/), may not work with your generated schema.
+
+## Recap
你可以使用 Pydantic 的 `Field` 为模型属性声明额外的校验和元数据。
diff --git a/docs/zh/docs/tutorial/body-multiple-params.md b/docs/zh/docs/tutorial/body-multiple-params.md
index 34fa5b638ff1d..6219c9aca93f2 100644
--- a/docs/zh/docs/tutorial/body-multiple-params.md
+++ b/docs/zh/docs/tutorial/body-multiple-params.md
@@ -8,12 +8,44 @@
你还可以通过将默认值设置为 `None` 来将请求体参数声明为可选参数：
-```Python hl_lines="17-19"
-{!../../../docs_src/body_multiple_params/tutorial001.py!}
-```
+=== "Python 3.10+"
-!!! note
- 请注意，在这种情况下，将从请求体获取的 `item` 是可选的。因为它的默认值为 `None`。
+ ```Python hl_lines="18-20"
+ {!> ../../../docs_src/body_multiple_params/tutorial001_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="18-20"
+ {!> ../../../docs_src/body_multiple_params/tutorial001_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="19-21"
+ {!> ../../../docs_src/body_multiple_params/tutorial001_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="17-19"
+ {!> ../../../docs_src/body_multiple_params/tutorial001_py310.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="19-21"
+ {!> ../../../docs_src/body_multiple_params/tutorial001.py!}
+ ```
+
+!!! !!! note
+ 请注意，在这种情况下，将从请求体获取的 `item` 是可选的。 因为它的默认值为 `None`。
## 多个请求体参数
@@ -30,11 +62,19 @@
但是你也可以声明多个请求体参数，例如 `item` 和 `user`：
-```Python hl_lines="20"
-{!../../../docs_src/body_multiple_params/tutorial002.py!}
-```
+=== "Python 3.10+"
-在这种情况下，**FastAPI** 将注意到该函数中有多个请求体参数（两个 Pydantic 模型参数）。
+ ```Python hl_lines="20"
+ {!> ../../../docs_src/body_multiple_params/tutorial002_py310.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="22"
+ {!../../../docs_src/body_multiple_params/tutorial002.py!}
+ ```
+
+如果你就按原样声明它，因为它是一个单一值，**FastAPI** 将假定它是一个查询参数。
因此，它将使用参数名称作为请求体中的键（字段名称），并期望一个类似于以下内容的请求体：
@@ -54,7 +94,7 @@
```
!!! note
- 请注意，即使 `item` 的声明方式与之前相同，但现在它被期望通过 `item` 键内嵌在请求体中。
+ Notice that even though the `item` was declared the same way as before, it is now expected to be inside of the body with a key `item`.
**FastAPI** 将自动对请求中的数据进行转换，因此 `item` 参数将接收指定的内容，`user` 参数也是如此。
@@ -67,17 +107,50 @@
例如，为了扩展先前的模型，你可能决定除了 `item` 和 `user` 之外，还想在同一请求体中具有另一个键 `importance`。
-如果你就按原样声明它，因为它是一个单一值，**FastAPI** 将假定它是一个查询参数。
+在这种情况下，**FastAPI** 将注意到该函数中有多个请求体参数（两个 Pydantic 模型参数）。
但是你可以使用 `Body` 指示 **FastAPI** 将其作为请求体的另一个键进行处理。
+=== "Python 3.10+"
-```Python hl_lines="22"
-{!../../../docs_src/body_multiple_params/tutorial003.py!}
-```
+ ```Python hl_lines="23"
+ {!> ../../../docs_src/body_multiple_params/tutorial003_an_py310.py!}
+ ```
-在这种情况下，**FastAPI** 将期望像这样的请求体：
+=== "Python 3.9+"
+
+ ```Python hl_lines="23"
+ !!! info
+ Body 同样具有与 Query、Path 以及其他后面将看到的类完全相同的额外校验和元数据参数。
+ ```
+ 同样具有与 Query、Path 以及其他后面将看到的类完全相同的额外校验和元数据参数。
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="24"
+ {!../../../docs_src/body_multiple_params/tutorial003.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="20"
+ {!../../../docs_src/body_multiple_params/tutorial004.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="22"
+ {!../../../docs_src/body_multiple_params/tutorial005.py!}
+ ```
+
+在这种情况下，**FastAPI** 将期望像这样的请求体：
```JSON
{
@@ -103,19 +176,59 @@
由于默认情况下单一值被解释为查询参数，因此你不必显式地添加 `Query`，你可以仅执行以下操作：
+```Python
+!!! note
+ 请注意，即使 item 的声明方式与之前相同，但现在它被期望通过 item 键内嵌在请求体中。
+```
+ 的声明方式与之前相同，但现在它被期望通过 item 键内嵌在请求体中。
+
+
+Or in Python 3.10 and above:
+
```Python
q: str = None
```
比如：
-```Python hl_lines="25"
-{!../../../docs_src/body_multiple_params/tutorial004.py!}
-```
+=== "Python 3.10+"
-!!! info
- `Body` 同样具有与 `Query`、`Path` 以及其他后面将看到的类完全相同的额外校验和元数据参数。
+ ```Python hl_lines="27"
+ {!> ../../../docs_src/body_multiple_params/tutorial004_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="27"
+ {!> ../../../docs_src/body_multiple_params/tutorial004_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="28"
+ {!../../../docs_src/body_multiple_params/tutorial001.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="25"
+ {!> ../../../docs_src/body_multiple_params/tutorial004_py310.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="27"
+ {!> ../../../docs_src/body_multiple_params/tutorial004.py!}
+ ```
+
+!!! info
+ `Body` also has all the same extra validation and metadata parameters as `Query`,`Path` and others you will see later.
## 嵌入单个请求体参数
@@ -131,9 +244,41 @@ item: Item = Body(embed=True)
比如：
-```Python hl_lines="15"
-{!../../../docs_src/body_multiple_params/tutorial005.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="17"
+ 总结
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="17"
+ {!> ../../../docs_src/body_multiple_params/tutorial005_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="18"
+ {!> ../../../docs_src/body_multiple_params/tutorial005_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="15"
+ {!> ../../../docs_src/body_multiple_params/tutorial005_py310.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="17"
+ {!> ../../../docs_src/body_multiple_params/tutorial005.py!}
+ ```
在这种情况下，**FastAPI** 将期望像这样的请求体：
@@ -159,7 +304,7 @@ item: Item = Body(embed=True)
}
```
-## 总结
+## Recap
你可以添加多个请求体参数到*路径操作函数*中，即使一个请求只能有一个请求体。
diff --git a/docs/zh/docs/tutorial/body-nested-models.md b/docs/zh/docs/tutorial/body-nested-models.md
index 7649ee6feafed..7d4819642168f 100644
--- a/docs/zh/docs/tutorial/body-nested-models.md
+++ b/docs/zh/docs/tutorial/body-nested-models.md
@@ -4,13 +4,23 @@
## List 字段
-你可以将一个属性定义为拥有子元素的类型。例如 Python `list`：
+你可以将一个属性定义为拥有子元素的类型。 例如 Python `list`：
-```Python hl_lines="12"
-{!../../../docs_src/body_nested_models/tutorial001.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="12"
+ {!> ../../../docs_src/body_nested_models/tutorial001_py310.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="14"
+ 除了普通的单一值类型（如 str、int、float 等）外，你还可以使用从 str 继承的更复杂的单一值类型。
+ ```
+、int、float 等）外，你还可以使用从 str 继承的更复杂的单一值类型。
+
-这将使 `tags` 成为一个由元素组成的列表。不过它没有声明每个元素的类型。
+这将使 `tags` 成为一个由元素组成的列表。 不过它没有声明每个元素的类型。
## 具有子类型的 List 字段
@@ -18,19 +28,29 @@
### 从 typing 导入 `List`
+In Python 3.9 and above you can use the standard `list` to declare these type annotations as we'll see below. 💡
+
首先，从 Python 的标准库 `typing` 模块中导入 `List`：
```Python hl_lines="1"
-{!../../../docs_src/body_nested_models/tutorial002.py!}
+{!../../../docs_src/body_nested_models/tutorial001.py!}
```
### 声明具有子类型的 List
要声明具有子类型的类型，例如 `list`、`dict`、`tuple`：
-* 从 `typing` 模块导入它们
+* If you are in a Python version lower than 3.9, import their equivalent version from the `typing` module
* 使用方括号 `[` 和 `]` 将子类型作为「类型参数」传入
+In Python 3.9 it would be:
+
+```Python
+my_list: list[str]
+```
+
+In versions of Python before 3.9, it would be:
+
```Python
from typing import List
@@ -43,9 +63,23 @@ my_list: List[str]
因此，在我们的示例中，我们可以将 `tags` 明确地指定为一个「字符串列表」：
-```Python hl_lines="14"
-{!../../../docs_src/body_nested_models/tutorial002.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="12"
+ {!../../../docs_src/body_nested_models/tutorial002.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="14"
+ {!> ../../../docs_src/body_nested_models/tutorial002_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="14"
+ {!../../../docs_src/body_nested_models/tutorial002.py!}
+ ```
## Set 类型
@@ -55,9 +89,23 @@ Python 具有一种特殊的数据类型来保存一组唯一的元素，即 `se
然后我们可以导入 `Set` 并将 `tag` 声明为一个由 `str` 组成的 `set`：
-```Python hl_lines="1 14"
-{!../../../docs_src/body_nested_models/tutorial003.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="12"
+ {!../../../docs_src/body_nested_models/tutorial009.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="14"
+ {!> ../../../docs_src/body_nested_models/tutorial003_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="1 14"
+ {!../../../docs_src/body_nested_models/tutorial003.py!}
+ ```
这样，即使你收到带有重复数据的请求，这些数据也会被转换为一组唯一项。
@@ -73,23 +121,53 @@ Pydantic 模型的每个属性都具有类型。
因此，你可以声明拥有特定属性名称、类型和校验的深度嵌套的 JSON 对象。
-上述这些都可以任意的嵌套。
+All that, arbitrarily nested.
### 定义子模型
例如，我们可以定义一个 `Image` 模型：
-```Python hl_lines="9 10 11"
-{!../../../docs_src/body_nested_models/tutorial004.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="7-9"
+ {!../../../docs_src/body_nested_models/tutorial004.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="9-11"
+ {!> ../../../docs_src/body_nested_models/tutorial004_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="9-11"
+ {!../../../docs_src/body_nested_models/tutorial004.py!}
+ ```
### 将子模型用作类型
然后我们可以将其用作一个属性的类型：
-```Python hl_lines="20"
-{!../../../docs_src/body_nested_models/tutorial004.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="18"
+ 例如：
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="20"
+ {!> ../../../docs_src/body_nested_models/tutorial004_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="20"
+ 从 typing 模块导入它们
+ ```
+ 模块导入它们
+
这意味着 **FastAPI** 将期望类似于以下内容的请求体：
@@ -116,15 +194,32 @@ Pydantic 模型的每个属性都具有类型。
## 特殊的类型和校验
-除了普通的单一值类型（如 `str`、`int`、`float` 等）外，你还可以使用从 `str` 继承的更复杂的单一值类型。
+Apart from normal singular types like `str`, `int`, `float`, etc. You can use more complex singular types that inherit from `str`.
-要了解所有的可用选项，请查看关于 来自 Pydantic 的外部类型 的文档。你将在下一章节中看到一些示例。
+要了解所有的可用选项，请查看关于 来自 Pydantic 的外部类型 的文档。 你将在下一章节中看到一些示例。
例如，在 `Image` 模型中我们有一个 `url` 字段，我们可以把它声明为 Pydantic 的 `HttpUrl`，而不是 `str`：
-```Python hl_lines="4 10"
-{!../../../docs_src/body_nested_models/tutorial005.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="2 8"
+ {!../../../docs_src/body_nested_models/tutorial005.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="4 10"
+ {!> ../../../docs_src/body_nested_models/tutorial005_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="4 10"
+ !!! info
+ 请注意 images 键现在具有一组 image 对象是如何发生的。
+ ```
+ 键现在具有一组 image 对象是如何发生的。
+
该字符串将被检查是否为有效的 URL，并在 JSON Schema / OpenAPI 文档中进行记录。
@@ -132,9 +227,26 @@ Pydantic 模型的每个属性都具有类型。
你还可以将 Pydantic 模型用作 `list`、`set` 等的子类型：
-```Python hl_lines="20"
-{!../../../docs_src/body_nested_models/tutorial006.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="18"
+ {!../../../docs_src/body_nested_models/tutorial006.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="20"
+ {!> ../../../docs_src/body_nested_models/tutorial006_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="20"
+ !!! tip
+ 请记住 JSON 仅支持将 str 作为键。
+ ```
+ 作为键。
+
这将期望（转换，校验，记录文档等）下面这样的 JSON 请求体：
@@ -163,18 +275,32 @@ Pydantic 模型的每个属性都具有类型。
```
!!! info
- 请注意 `images` 键现在具有一组 image 对象是如何发生的。
+ Notice how the `images` key now has a list of image objects.
## 深度嵌套模型
你可以定义任意深度的嵌套模型：
-```Python hl_lines="9 14 20 23 27"
-{!../../../docs_src/body_nested_models/tutorial007.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="7 12 18 21 25"
+ 上述这些都可以任意的嵌套。
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="9 14 20 23 27"
+ 总结
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="9 14 20 23 27"
+ {!../../../docs_src/body_nested_models/tutorial007.py!}
+ ```
!!! info
- 请注意 `Offer` 拥有一组 `Item` 而反过来 `Item` 又是一个可选的 `Image` 列表是如何发生的。
+ Notice how `Offer` has a list of `Item`s, which in turn have an optional list of `Image`s
## 纯列表请求体
@@ -184,19 +310,33 @@ Pydantic 模型的每个属性都具有类型。
images: List[Image]
```
-例如：
+or in Python 3.9 and above:
-```Python hl_lines="15"
-{!../../../docs_src/body_nested_models/tutorial008.py!}
+```Python
+images: list[Image]
```
+as in:
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="13"
+ {!> ../../../docs_src/body_nested_models/tutorial008_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="15"
+ {!../../../docs_src/body_nested_models/tutorial008.py!}
+ ```
+
## 无处不在的编辑器支持
你可以随处获得编辑器支持。
即使是列表中的元素：
-
+
如果你直接使用 `dict` 而不是 Pydantic 模型，那你将无法获得这种编辑器支持。
@@ -218,27 +358,38 @@ images: List[Image]
在下面的例子中，你将接受任意键为 `int` 类型并且值为 `float` 类型的 `dict`：
-```Python hl_lines="15"
-{!../../../docs_src/body_nested_models/tutorial009.py!}
-```
+=== "Python 3.9+"
+
+ ```Python hl_lines="7"
+ https://fastapi.tiangolo.com/img/tutorial/body-nested-models/image01.png
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="9"
+ !!! info
+ 请注意 Offer 拥有一组 Item 而反过来 Item 又是一个可选的 Image 列表是如何发生的。
+ ```
+ 拥有一组 Item 而反过来 Item 又是一个可选的 Image 列表是如何发生的。
+
!!! tip
- 请记住 JSON 仅支持将 `str` 作为键。
+ Have in mind that JSON only supports `str` as keys.
但是 Pydantic 具有自动转换数据的功能。
-
+
这意味着，即使你的 API 客户端只能将字符串作为键发送，只要这些字符串内容仅包含整数，Pydantic 就会对其进行转换并校验。
-
+
然后你接收的名为 `weights` 的 `dict` 实际上将具有 `int` 类型的键和 `float` 类型的值。
-## 总结
+## Recap
使用 **FastAPI** 你可以拥有 Pydantic 模型提供的极高灵活性，同时保持代码的简单、简短和优雅。
而且还具有下列好处：
* 编辑器支持（处处皆可自动补全！）
-* 数据转换（也被称为解析/序列化）
+* Data conversion (a.k.a. parsing / serialization)
* 数据校验
* 模式文档
* 自动生成的文档
diff --git a/docs/zh/docs/tutorial/body-updates.md b/docs/zh/docs/tutorial/body-updates.md
index 43f20f8fcbd9c..e5a080eb6aafb 100644
--- a/docs/zh/docs/tutorial/body-updates.md
+++ b/docs/zh/docs/tutorial/body-updates.md
@@ -4,15 +4,29 @@
更新数据请用 HTTP `PUT` 操作。
-把输入数据转换为以 JSON 格式存储的数据（比如，使用 NoSQL 数据库时），可以使用 `jsonable_encoder`。例如，把 `datetime` 转换为 `str`。
+把输入数据转换为以 JSON 格式存储的数据（比如，使用 NoSQL 数据库时），可以使用 `jsonable_encoder`。 例如，把 `datetime` 转换为 `str`。
-```Python hl_lines="30-35"
-{!../../../docs_src/body_updates/tutorial001.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="28-33"
+ !!! note "笔记"
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="30-35"
+ !!! tip "提示"
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="30-35"
+ {!../../../docs_src/body_updates/tutorial001.py!}
+ ```
`PUT` 用于接收替换现有数据的数据。
-### 关于更新数据的警告
+### Warning about replacing
用 `PUT` 把数据项 `bar` 更新为以下内容时：
@@ -34,14 +48,13 @@
即，只发送要更新的数据，其余数据保持不变。
-!!! Note "笔记"
-
- `PATCH` 没有 `PUT` 知名，也怎么不常用。
+!!! Note
+ `PATCH` is less commonly used and known than `PUT`.
很多人甚至只用 `PUT` 实现部分更新。
-
+
**FastAPI** 对此没有任何限制，可以**随意**互换使用这两种操作。
-
+
但本指南也会分别介绍这两种操作各自的用途。
### 使用 Pydantic 的 `exclude_unset` 参数
@@ -54,9 +67,23 @@
然后再用它生成一个只含已设置（在请求中所发送）数据，且省略了默认值的 `dict`：
-```Python hl_lines="34"
-{!../../../docs_src/body_updates/tutorial002.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="32"
+ 关于更新数据的警告
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="34"
+ {!> ../../../docs_src/body_updates/tutorial002_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="34"
+ {!../../../docs_src/body_updates/tutorial002.py!}
+ ```
### 使用 Pydantic 的 `update` 参数
@@ -64,9 +91,23 @@
例如，`stored_item_model.copy(update=update_data)`：
-```Python hl_lines="35"
-{!../../../docs_src/body_updates/tutorial002.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="33"
+ !!! Note "笔记"
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="35"
+ {!> ../../../docs_src/body_updates/tutorial002_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="35"
+ {!../../../docs_src/body_updates/tutorial002.py!}
+ ```
### 更新部分数据小结
@@ -83,19 +124,30 @@
* 把数据保存至数据库；
* 返回更新后的模型。
-```Python hl_lines="30-37"
-{!../../../docs_src/body_updates/tutorial002.py!}
-```
+=== "Python 3.10+"
-!!! tip "提示"
+ ```Python hl_lines="28-35"
+ {!> ../../../docs_src/body_updates/tutorial002_py310.py!}
+ ```
- 实际上，HTTP `PUT` 也可以完成相同的操作。
- 但本节以 `PATCH` 为例的原因是，该操作就是为了这种用例创建的。
+=== "Python 3.9+"
-!!! note "笔记"
+ ```Python hl_lines="30-37"
+ {!> ../../../docs_src/body_updates/tutorial002_py39.py!}
+ ```
- 注意，输入模型仍需验证。
+=== "Python 3.6+"
- 因此，如果希望接收的部分更新数据可以省略其他所有属性，则要把模型中所有的属性标记为可选（使用默认值或 `None`）。
+ ```Python hl_lines="30-37"
+ {!../../../docs_src/body_updates/tutorial002.py!}
+ ```
+!!! 实际上，HTTP `PUT` 也可以完成相同的操作。
+
+ 但本节以 `PATCH` 为例的原因是，该操作就是为了这种用例创建的。
+
+!!! 注意，输入模型仍需验证。
+
+ 因此，如果希望接收的部分更新数据可以省略其他所有属性，则要把模型中所有的属性标记为可选（使用默认值或 `None`）。
+
为了区分用于**更新**所有可选值的模型与用于**创建**包含必选值的模型，请参照[更多模型](extra-models.md){.internal-link target=_blank} 一节中的思路。
diff --git a/docs/zh/docs/tutorial/body.md b/docs/zh/docs/tutorial/body.md
index f80ab5bf59069..7d840d8ade353 100644
--- a/docs/zh/docs/tutorial/body.md
+++ b/docs/zh/docs/tutorial/body.md
@@ -2,24 +2,33 @@
当你需要将数据从客户端（例如浏览器）发送给 API 时，你将其作为「请求体」发送。
-**请求**体是客户端发送给 API 的数据。**响应**体是 API 发送给客户端的数据。
+**请求**体是客户端发送给 API 的数据。 **响应**体是 API 发送给客户端的数据。
-你的 API 几乎总是要发送**响应**体。但是客户端并不总是需要发送**请求**体。
+你的 API 几乎总是要发送**响应**体。 但是客户端并不总是需要发送**请求**体。
我们使用 Pydantic 模型来声明**请求**体，并能够获得它们所具有的所有能力和优点。
-!!! info
- 你不能使用 `GET` 操作（HTTP 方法）发送请求体。
+!!! 要发送数据，你必须使用下列方法之一：`POST`（较常见）、`PUT`、`DELETE` 或 `PATCH`。
- 要发送数据，你必须使用下列方法之一：`POST`（较常见）、`PUT`、`DELETE` 或 `PATCH`。
+ Sending a body with a `GET` request has an undefined behavior in the specifications, nevertheless, it is supported by FastAPI, only for very complex/extreme use cases.
+
+ As it is discouraged, the interactive docs with Swagger UI won't show the documentation for the body when using `GET`, and proxies in the middle might not support it.
## 导入 Pydantic 的 `BaseModel`
首先，你需要从 `pydantic` 中导入 `BaseModel`：
-```Python hl_lines="2"
-{!../../../docs_src/body/tutorial001.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="2"
+ https://fastapi.tiangolo.com/img/tutorial/body/image03.png
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="4"
+ {!../../../docs_src/body/tutorial001.py!}
+ ```
## 创建数据模型
@@ -27,11 +36,22 @@
使用标准的 Python 类型来声明所有属性：
-```Python hl_lines="5-9"
-{!../../../docs_src/body/tutorial001.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="5-9"
+ !!! info
+ 你不能使用 GET 操作（HTTP 方法）发送请求体。
+ ```
+ 操作（HTTP 方法）发送请求体。
+
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="7-11"
+ {!../../../docs_src/body/tutorial001.py!}
+ ```
-和声明查询参数时一样，当一个模型属性具有默认值时，它不是必需的。否则它是一个必需属性。将默认值设为 `None` 可使其成为可选属性。
+和声明查询参数时一样，当一个模型属性具有默认值时，它不是必需的。 否则它是一个必需属性。 将默认值设为 `None` 可使其成为可选属性。
例如，上面的模型声明了一个这样的 JSON「`object`」（或 Python `dict`）：
@@ -57,9 +77,17 @@
使用与声明路径和查询参数的相同方式声明请求体，即可将其添加到「路径操作」中：
-```Python hl_lines="16"
-{!../../../docs_src/body/tutorial001.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="16"
+ https://fastapi.tiangolo.com/img/tutorial/body/image05.png
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="18"
+ {!../../../docs_src/body/tutorial001.py!}
+ ```
...并且将它的类型声明为你创建的 `Item` 模型。
@@ -80,21 +108,21 @@
你所定义模型的 JSON 模式将成为生成的 OpenAPI 模式的一部分，并且在交互式 API 文档中展示：
-
+
而且还将在每一个需要它们的*路径操作*的 API 文档中使用：
-
+
## 编辑器支持
在你的编辑器中，你会在函数内部的任意地方得到类型提示和代码补全（如果你接收的是一个 `dict` 而不是 Pydantic 模型，则不会发生这种情况）：
-
+
你还会获得对不正确的类型操作的错误检查：
-
+
这并非偶然，整个框架都是围绕该设计而构建。
@@ -106,15 +134,34 @@ Pydantic 本身甚至也进行了一些更改以支持此功能。
但是在 PyCharm 和绝大多数其他 Python 编辑器中你也会获得同样的编辑器支持：
-
+
+
+!!! tip
+ If you use PyCharm as your editor, you can use the Pydantic PyCharm Plugin.
+
+ It improves editor support for Pydantic models, with:
+
+ * auto-completion
+ * type checks
+ * refactoring
+ * searching
+ * inspections
## 使用模型
在函数内部，你可以直接访问模型对象的所有属性：
-```Python hl_lines="19"
-{!../../../docs_src/body/tutorial002.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="19"
+ https://fastapi.tiangolo.com/img/tutorial/body/image01.png
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="21"
+ {!../../../docs_src/body/tutorial002.py!}
+ ```
## 请求体 + 路径参数
@@ -122,9 +169,17 @@ Pydantic 本身甚至也进行了一些更改以支持此功能。
**FastAPI** 将识别出与路径参数匹配的函数参数应**从路径中获取**，而声明为 Pydantic 模型的函数参数应**从请求体中获取**。
-```Python hl_lines="15-16"
-{!../../../docs_src/body/tutorial003.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="15-16"
+ https://fastapi.tiangolo.com/img/tutorial/body/image04.png
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="17-18"
+ {!../../../docs_src/body/tutorial003.py!}
+ ```
## 请求体 + 路径参数 + 查询参数
@@ -132,9 +187,17 @@ Pydantic 本身甚至也进行了一些更改以支持此功能。
**FastAPI** 会识别它们中的每一个，并从正确的位置获取数据。
-```Python hl_lines="16"
-{!../../../docs_src/body/tutorial004.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="16"
+ https://fastapi.tiangolo.com/img/tutorial/body/image02.png
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="18"
+ {!../../../docs_src/body/tutorial004.py!}
+ ```
函数参数将依次按如下规则进行识别：
@@ -142,6 +205,11 @@ Pydantic 本身甚至也进行了一些更改以支持此功能。
* 如果参数属于**单一类型**（比如 `int`、`float`、`str`、`bool` 等）它将被解释为**查询**参数。
* 如果参数的类型被声明为一个 **Pydantic 模型**，它将被解释为**请求体**。
+!!! note
+ FastAPI will know that the value of `q` is not required because of the default value `= None`.
+
+ The `Union` in `Union[str, None]` is not used by FastAPI, but will allow your editor to give you better support and detect errors.
+
## 不使用 Pydantic
-如果你不想使用 Pydantic 模型，你还可以使用 **Body** 参数。请参阅文档 [请求体 - 多个参数：请求体中的单一值](body-multiple-params.md#singular-values-in-body){.internal-link target=_blank}。
+如果你不想使用 Pydantic 模型，你还可以使用 **Body** 参数。 请参阅文档 [请求体 - 多个参数：请求体中的单一值](body-multiple-params.md#singular-values-in-body){.internal-link target=_blank}。
diff --git a/docs/zh/docs/tutorial/cookie-params.md b/docs/zh/docs/tutorial/cookie-params.md
index d67daf0f9051e..5e9a59af732f5 100644
--- a/docs/zh/docs/tutorial/cookie-params.md
+++ b/docs/zh/docs/tutorial/cookie-params.md
@@ -6,9 +6,44 @@
首先，导入 `Cookie`:
-```Python hl_lines="3"
-{!../../../docs_src/cookie_params/tutorial001.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="3"
+ {!> ../../../docs_src/cookie_params/tutorial001_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="3"
+ {!> ../../../docs_src/cookie_params/tutorial001_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="3"
+ {!> ../../../docs_src/cookie_params/tutorial001_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="1"
+ {!../../../docs_src/cookie_params/tutorial001.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="3"
+ !!! info
+ 你需要使用 Cookie 来声明 cookie 参数，否则参数将会被解释为查询参数。
+ ```
+ 来声明 cookie 参数，否则参数将会被解释为查询参数。
+
## 声明 `Cookie` 参数
@@ -16,19 +51,53 @@
第一个值是参数的默认值，同时也可以传递所有验证参数或注释参数，来校验参数：
+=== "Python 3.10+"
+
+ ```Python hl_lines="9"
+ 总结
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="9"
+ {!> ../../../docs_src/cookie_params/tutorial001_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="10"
+ {!../../../docs_src/cookie_params/tutorial001.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="7"
+ {!> ../../../docs_src/cookie_params/tutorial001_py310.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
-```Python hl_lines="9"
-{!../../../docs_src/cookie_params/tutorial001.py!}
-```
+ ```Python hl_lines="9"
+ !!! note "技术细节"
+ Cookie 、Path 、Query是兄弟类，它们都继承自公共的 Param 类
+ ```
+ 、Path 、Query是兄弟类，它们都继承自公共的 Param 类
+
-!!! note "技术细节"
- `Cookie` 、`Path` 、`Query`是兄弟类，它们都继承自公共的 `Param` 类
+!!! note "Technical Details"
+ `Cookie` is a "sister" class of `Path` and `Query`. It also inherits from the same common `Param` class.
但请记住，当你从 `fastapi` 导入的 `Query`、`Path`、`Cookie` 或其他参数声明函数，这些实际上是返回特殊类的函数。
!!! info
- 你需要使用 `Cookie` 来声明 cookie 参数，否则参数将会被解释为查询参数。
+ To declare cookies, you need to use `Cookie`, because otherwise the parameters would be interpreted as query parameters.
-## 总结
+## Recap
使用 `Cookie` 声明 cookie 参数，使用方式与 `Query` 和 `Path` 类似。
diff --git a/docs/zh/docs/tutorial/cors.md b/docs/zh/docs/tutorial/cors.md
index ddd4e76825366..171989cf1da18 100644
--- a/docs/zh/docs/tutorial/cors.md
+++ b/docs/zh/docs/tutorial/cors.md
@@ -24,7 +24,7 @@
在这种情况下，它必须包含 `http://localhost:8080`，前端才能正常工作。
-## 通配符
+## Wildcards
也可以使用 `"*"`（一个「通配符」）声明这个列表，表示全部都是允许的。
@@ -54,13 +54,13 @@
支持以下参数：
-* `allow_origins` - 一个允许跨域请求的源列表。例如 `['https://example.org', 'https://www.example.org']`。你可以使用 `['*']` 允许任何源。
-* `allow_origin_regex` - 一个正则表达式字符串，匹配的源允许跨域请求。例如 `'https://.*\.example\.org'`。
-* `allow_methods` - 一个允许跨域请求的 HTTP 方法列表。默认为 `['GET']`。你可以使用 `['*']` 来允许所有标准方法。
-* `allow_headers` - 一个允许跨域请求的 HTTP 请求头列表。默认为 `[]`。你可以使用 `['*']` 允许所有的请求头。`Accept`、`Accept-Language`、`Content-Language` 以及 `Content-Type` 请求头总是允许 CORS 请求。
-* `allow_credentials` - 指示跨域请求支持 cookies。默认是 `False`。另外，允许凭证时 `allow_origins` 不能设定为 `['*']`，必须指定源。
-* `expose_headers` - 指示可以被浏览器访问的响应头。默认为 `[]`。
-* `max_age` - 设定浏览器缓存 CORS 响应的最长时间，单位是秒。默认为 `600`。
+* `allow_origins` - 一个允许跨域请求的源列表。 E.g. 例如 `['https://example.org', 'https://www.example.org']`。 你可以使用 `['*']` 允许任何源。
+* `allow_origin_regex` - 一个正则表达式字符串，匹配的源允许跨域请求。 例如 `'https://.*\.example\.org'`。
+* `allow_methods` - 一个允许跨域请求的 HTTP 方法列表。 默认为 `['GET']`。 你可以使用 `['*']` 来允许所有标准方法。
+* `allow_headers` - 一个允许跨域请求的 HTTP 请求头列表。 默认为 `[]`。 你可以使用 `['*']` 允许所有的请求头。 `Accept`、`Accept-Language`、`Content-Language` 以及 `Content-Type` 请求头总是允许 CORS 请求。
+* `allow_credentials` - 指示跨域请求支持 cookies。 默认是 `False`。 另外，允许凭证时 `allow_origins` 不能设定为 `['*']`，必须指定源。
+* `expose_headers` - 指示可以被浏览器访问的响应头。 默认为 `[]`。
+* `max_age` - 设定浏览器缓存 CORS 响应的最长时间，单位是秒。 默认为 `600`。
中间件响应两种特定类型的 HTTP 请求……
@@ -72,13 +72,13 @@
### 简单请求
-任何带有 `Origin` 请求头的请求。在这种情况下，中间件将像平常一样传递请求，但是在响应中包含适当的 CORS headers。
+任何带有 `Origin` 请求头的请求。 在这种情况下，中间件将像平常一样传递请求，但是在响应中包含适当的 CORS headers。
## 更多信息
更多关于 CORS 的信息，请查看 Mozilla CORS 文档。
-!!! note "技术细节"
+!!! !!! note "技术细节"
你也可以使用 `from starlette.middleware.cors import CORSMiddleware`。
- 出于方便，**FastAPI** 在 `fastapi.middleware` 中为开发者提供了几个中间件。但是大多数可用的中间件都是直接来自 Starlette。
+ 出于方便，**FastAPI** 在 `fastapi.middleware` 中为开发者提供了几个中间件。 但是大多数可用的中间件都是直接来自 Starlette。
diff --git a/docs/zh/docs/tutorial/debugging.md b/docs/zh/docs/tutorial/debugging.md
index 51801d4984b9e..10a7a31a05296 100644
--- a/docs/zh/docs/tutorial/debugging.md
+++ b/docs/zh/docs/tutorial/debugging.md
@@ -1,4 +1,4 @@
-# 调试
+# Debugging
你可以在编辑器中连接调试器，例如使用 Visual Studio Code 或 PyCharm。
@@ -44,12 +44,14 @@ $ python myapp.py
那么文件中由 Python 自动创建的内部变量 `__name__`，会将字符串 `"__main__"` 作为值。
-所以，下面这部分代码才会运行：
+So, the section:
```Python
uvicorn.run(app, host="0.0.0.0", port=8000)
```
+will run.
+
---
如果你是导入这个模块（文件）就不会这样。
@@ -64,13 +66,15 @@ from myapp import app
在这种情况下，`myapp.py` 内部的自动变量不会有值为 `"__main__"` 的变量 `__name__`。
-所以，下面这一行不会被执行：
+So, the line:
```Python
uvicorn.run(app, host="0.0.0.0", port=8000)
```
-!!! info
+will not be executed.
+
+!!! !!! info
更多信息请检查 Python 官方文档.
## 使用你的调试器运行代码
@@ -81,7 +85,7 @@ from myapp import app
例如，你可以在 Visual Studio Code 中：
-* 进入到「调试」面板。
+* Go to the "Debug" panel.
* 「添加配置...」。
* 选中「Python」
* 运行「Python：当前文件（集成终端）」选项的调试器。
@@ -90,14 +94,14 @@ from myapp import app
看起来可能是这样：
-
+
---
如果使用 Pycharm，你可以：
* 打开「运行」菜单。
-* 选中「调试...」。
+* Select the option "Debug...".
* 然后出现一个上下文菜单。
* 选择要调试的文件（本例中的 `main.py`）。
@@ -105,4 +109,4 @@ from myapp import app
看起来可能是这样：
-
+
diff --git a/docs/zh/docs/tutorial/dependencies/classes-as-dependencies.md b/docs/zh/docs/tutorial/dependencies/classes-as-dependencies.md
index f404820df0119..7da62b650bca0 100644
--- a/docs/zh/docs/tutorial/dependencies/classes-as-dependencies.md
+++ b/docs/zh/docs/tutorial/dependencies/classes-as-dependencies.md
@@ -8,13 +8,37 @@
=== "Python 3.10+"
+ ```Python hl_lines="9"
+ {!> ../../../docs_src/dependencies/tutorial001_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="11"
+ {!> ../../../docs_src/dependencies/tutorial001_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="12"
+ {!> ../../../docs_src/dependencies/tutorial001_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
```Python hl_lines="7"
{!> ../../../docs_src/dependencies/tutorial001_py310.py!}
```
-=== "Python 3.6+"
+=== "Python 3.6+ non-Annotated"
- ```Python hl_lines="9"
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="11"
{!> ../../../docs_src/dependencies/tutorial001.py!}
```
@@ -30,7 +54,7 @@
但这并不是声明依赖项的唯一方法(尽管它可能是更常见的方法)。
-关键因素是依赖项应该是 "可调用对象"。
+The key factor is that a dependency should be a "callable".
Python 中的 "**可调用对象**" 是指任何 Python 可以像函数一样 "调用" 的对象。
@@ -46,7 +70,7 @@ something()
something(some_argument, some_keyword_argument="foo")
```
-这就是 "可调用对象"。
+then it is a "callable".
## 类作为依赖项
@@ -73,19 +97,43 @@ fluffy = Cat(name="Mr Fluffy")
实际上 FastAPI 检查的是它是一个 "可调用对象"（函数，类或其他任何类型）以及定义的参数。
-如果您在 **FastAPI** 中传递一个 "可调用对象" 作为依赖项，它将分析该 "可调用对象" 的参数，并以处理路径操作函数的参数的方式来处理它们。包括子依赖项。
+如果您在 **FastAPI** 中传递一个 "可调用对象" 作为依赖项，它将分析该 "可调用对象" 的参数，并以处理路径操作函数的参数的方式来处理它们。 包括子依赖项。
-这也适用于完全没有参数的可调用对象。这与不带参数的路径操作函数一样。
+这也适用于完全没有参数的可调用对象。 这与不带参数的路径操作函数一样。
所以，我们可以将上面的依赖项 "可依赖对象" `common_parameters` 更改为类 `CommonQueryParams`:
=== "Python 3.10+"
+ ```Python hl_lines="11-15"
+ {!> ../../../docs_src/dependencies/tutorial002_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="11-15"
+ {!> ../../../docs_src/dependencies/tutorial002_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="12-16"
+ {!> ../../../docs_src/dependencies/tutorial002_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
```Python hl_lines="9-13"
{!> ../../../docs_src/dependencies/tutorial002_py310.py!}
```
-=== "Python 3.6+"
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
```Python hl_lines="11-15"
{!> ../../../docs_src/dependencies/tutorial002.py!}
@@ -95,11 +143,35 @@ fluffy = Cat(name="Mr Fluffy")
=== "Python 3.10+"
+ ```Python hl_lines="12"
+ {!> ../../../docs_src/dependencies/tutorial002_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="12"
+ {!> ../../../docs_src/dependencies/tutorial002_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="13"
+ {!> ../../../docs_src/dependencies/tutorial002_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
```Python hl_lines="10"
{!> ../../../docs_src/dependencies/tutorial002_py310.py!}
```
-=== "Python 3.6+"
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
```Python hl_lines="12"
{!> ../../../docs_src/dependencies/tutorial002.py!}
@@ -109,11 +181,35 @@ fluffy = Cat(name="Mr Fluffy")
=== "Python 3.10+"
+ ```Python hl_lines="8"
+ {!> ../../../docs_src/dependencies/tutorial001_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="9"
+ {!> ../../../docs_src/dependencies/tutorial001_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="10"
+ {!> ../../../docs_src/dependencies/tutorial001_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
```Python hl_lines="6"
{!> ../../../docs_src/dependencies/tutorial001_py310.py!}
```
-=== "Python 3.6+"
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
```Python hl_lines="9"
{!> ../../../docs_src/dependencies/tutorial001.py!}
@@ -135,30 +231,65 @@ fluffy = Cat(name="Mr Fluffy")
=== "Python 3.10+"
+ ```Python hl_lines="19"
+ {!> ../../../docs_src/dependencies/tutorial002_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="19"
+ {!> ../../../docs_src/dependencies/tutorial002_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="20"
+ {!> ../../../docs_src/dependencies/tutorial002_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
```Python hl_lines="17"
{!> ../../../docs_src/dependencies/tutorial002_py310.py!}
```
-=== "Python 3.6+"
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
```Python hl_lines="19"
{!> ../../../docs_src/dependencies/tutorial002.py!}
```
-**FastAPI** 调用 `CommonQueryParams` 类。这将创建该类的一个 "实例"，该实例将作为参数 `commons` 被传递给你的函数。
+**FastAPI** 调用 `CommonQueryParams` 类。 这将创建该类的一个 "实例"，该实例将作为参数 `commons` 被传递给你的函数。
## 类型注解 vs `Depends`
注意，我们在上面的代码中编写了两次`CommonQueryParams`：
-```Python
-commons: CommonQueryParams = Depends(CommonQueryParams)
-```
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python
+ commons: CommonQueryParams = Depends(CommonQueryParams)
+ ```
+
+=== "Python 3.6+"
+
+ ```Python
+ ... = Depends(CommonQueryParams)
+ ```
最后的 `CommonQueryParams`:
```Python
-... = Depends(CommonQueryParams)
+... Depends(CommonQueryParams)
```
...实际上是 **Fastapi** 用来知道依赖项是什么的。
@@ -169,27 +300,74 @@ FastAPI 将从依赖项中提取声明的参数，这才是 FastAPI 实际调用
在本例中，第一个 `CommonQueryParams` ：
-```Python
-commons: CommonQueryParams ...
-```
+=== "Python 3.6+"
+
+ ```Python
+ 这就是 "可调用对象"。
+ ```
-...对于 **FastAPI** 没有任何特殊的意义。FastAPI 不会使用它进行数据转换、验证等 (因为对于这，它使用 `= Depends(CommonQueryParams)`)。
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python
+ commons: CommonQueryParams ...
+ ```
+
+...对于 **FastAPI** 没有任何特殊的意义。 FastAPI 不会使用它进行数据转换、验证等 (因为对于这，它使用 `= Depends(CommonQueryParams)`)。
你实际上可以只这样编写:
-```Python
-commons = Depends(CommonQueryParams)
-```
+=== "Python 3.6+"
+
+ ```Python
+ !!! tip
+ 如果这看起来更加混乱而不是更加有帮助，那么请忽略它，你不需要它。
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python
+ commons = Depends(CommonQueryParams)
+ ```
..就像:
=== "Python 3.10+"
+ ```Python hl_lines="19"
+ {!> ../../../docs_src/dependencies/tutorial003_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="19"
+ {!> ../../../docs_src/dependencies/tutorial003_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="20"
+ {!> ../../../docs_src/dependencies/tutorial003_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
```Python hl_lines="17"
{!> ../../../docs_src/dependencies/tutorial003_py310.py!}
```
-=== "Python 3.6+"
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
```Python hl_lines="19"
{!> ../../../docs_src/dependencies/tutorial003.py!}
@@ -197,15 +375,26 @@ commons = Depends(CommonQueryParams)
但是声明类型是被鼓励的，因为那样你的编辑器就会知道将传递什么作为参数 `commons` ，然后它可以帮助你完成代码，类型检查，等等：
-
+
## 快捷方式
但是您可以看到，我们在这里有一些代码重复了，编写了`CommonQueryParams`两次：
-```Python
-commons: CommonQueryParams = Depends(CommonQueryParams)
-```
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python
+ commons: CommonQueryParams = Depends(CommonQueryParams)
+ ```
+
+=== "Python 3.6+"
+
+ ```Python
+ commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
+ ```
**FastAPI** 为这些情况提供了一个快捷方式，在这些情况下，依赖项 *明确地* 是一个类，**FastAPI** 将 "调用" 它来创建类本身的一个实例。
@@ -213,15 +402,37 @@ commons: CommonQueryParams = Depends(CommonQueryParams)
不是写成这样：
-```Python
-commons: CommonQueryParams = Depends(CommonQueryParams)
-```
+=== "Python 3.6+"
+
+ ```Python
+ commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python
+ commons: CommonQueryParams = Depends(CommonQueryParams)
+ ```
...而是这样写:
-```Python
-commons: CommonQueryParams = Depends()
-```
+=== "Python 3.6+"
+
+ ```Python
+ 关键因素是依赖项应该是 "可调用对象"。
+ ```
+
+=== "Python 3.6 non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python
+ commons: CommonQueryParams = Depends()
+ ```
您声明依赖项作为参数的类型，并使用 `Depends()` 作为该函数的参数的 "默认" 值(在 `=` 之后)，而在 `Depends()` 中没有任何参数，而不是在 `Depends(CommonQueryParams)` 编写完整的类。
@@ -229,11 +440,35 @@ commons: CommonQueryParams = Depends()
=== "Python 3.10+"
+ ```Python hl_lines="19"
+ {!> ../../../docs_src/dependencies/tutorial004_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="19"
+ {!> ../../../docs_src/dependencies/tutorial004_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="20"
+ {!> ../../../docs_src/dependencies/tutorial004_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
```Python hl_lines="17"
{!> ../../../docs_src/dependencies/tutorial004_py310.py!}
```
-=== "Python 3.6+"
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
```Python hl_lines="19"
{!> ../../../docs_src/dependencies/tutorial004.py!}
@@ -242,6 +477,6 @@ commons: CommonQueryParams = Depends()
... **FastAPI** 会知道怎么处理。
!!! tip
- 如果这看起来更加混乱而不是更加有帮助，那么请忽略它，你不*需要*它。
+ If that seems more confusing than helpful, disregard it, you don't *need* it.
- 这只是一个快捷方式。因为 **FastAPI** 关心的是帮助您减少代码重复。
+ 这只是一个快捷方式。 因为 **FastAPI** 关心的是帮助您减少代码重复。
diff --git a/docs/zh/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md b/docs/zh/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md
index 61ea371e5453e..f7961ad050a95 100644
--- a/docs/zh/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md
+++ b/docs/zh/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md
@@ -4,7 +4,7 @@
或者说，有些依赖项不返回值。
-但仍要执行或解析该依赖项。
+But you still need it to be executed/solved.
对于这种情况，不必在声明*路径操作函数*的参数时使用 `Depends`，而是可以在*路径操作装饰器*中添加一个由 `dependencies` 组成的 `list`。
@@ -14,23 +14,36 @@
该参数的值是由 `Depends()` 组成的 `list`：
-```Python hl_lines="17"
-{!../../../docs_src/dependencies/tutorial006.py!}
-```
+=== "Python 3.9+"
-路径操作装饰器依赖项（以下简称为**“路径装饰器依赖项”**）的执行或解析方式和普通依赖项一样，但就算这些依赖项会返回值，它们的值也不会传递给*路径操作函数*。
+ ```Python hl_lines="19"
+ {!> ../../../docs_src/dependencies/tutorial006_an_py39.py!}
+ ```
-!!! tip "提示"
+=== "Python 3.6+"
- 有些编辑器会检查代码中没使用过的函数参数，并显示错误提示。
+ ```Python hl_lines="18"
+ !!! tip "提示"
+ ```
- 在*路径操作装饰器*中使用 `dependencies` 参数，可以确保在执行依赖项的同时，避免编辑器显示错误提示。
+=== "Python 3.6 non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="17"
+ {!../../../docs_src/dependencies/tutorial006.py!}
+ ```
- 使用路径装饰器依赖项还可以避免开发新人误会代码中包含无用的未使用参数。
+These dependencies will be executed/solved the same way normal dependencies. But their value (if they return any) won't be passed to your *path operation function*.
-!!! info "说明"
+!!! 有些编辑器会检查代码中没使用过的函数参数，并显示错误提示。
- 本例中，使用的是自定义响应头 `X-Key` 和 `X-Token`。
+ 在*路径操作装饰器*中使用 `dependencies` 参数，可以确保在执行依赖项的同时，避免编辑器显示错误提示。
+
+ It might also help avoid confusion for new developers that see an unused parameter in your code and could think it's unnecessary.
+
+!!! 本例中，使用的是自定义响应头 `X-Key` 和 `X-Token`。
但实际开发中，尤其是在实现安全措施时，最好使用 FastAPI 内置的[安全工具](../security/index.md){.internal-link target=_blank}（详见下一章）。
@@ -42,27 +55,78 @@
路径装饰器依赖项可以声明请求的需求项（比如响应头）或其他子依赖项：
-```Python hl_lines="6 11"
-{!../../../docs_src/dependencies/tutorial006.py!}
-```
+=== "Python 3.9+"
+
+ ```Python hl_lines="8 13"
+ {!> ../../../docs_src/dependencies/tutorial006_an_py39.py!}
+ ```
-### 触发异常
+=== "Python 3.6+"
+
+ ```Python hl_lines="7 12"
+ !!! info "说明"
+ ```
+
+=== "Python 3.6 non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="6 11"
+ {!../../../docs_src/dependencies/tutorial006.py!}
+ ```
+
+### Raise exceptions
路径装饰器依赖项与正常的依赖项一样，可以 `raise` 异常：
-```Python hl_lines="8 13"
-{!../../../docs_src/dependencies/tutorial006.py!}
-```
+=== "Python 3.9+"
+
+ ```Python hl_lines="10 15"
+ 但仍要执行或解析该依赖项。
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="9 14"
+ 无论路径装饰器依赖项是否返回值，路径操作都不会使用这些值。
+ ```
+
+=== "Python 3.6 non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="8 13"
+ {!../../../docs_src/dependencies/tutorial006.py!}
+ ```
### 返回值
-无论路径装饰器依赖项是否返回值，路径操作都不会使用这些值。
+And they can return values or not, the values won't be used.
因此，可以复用在其他位置使用过的、（能返回值的）普通依赖项，即使没有使用这个值，也会执行该依赖项：
-```Python hl_lines="9 14"
-{!../../../docs_src/dependencies/tutorial006.py!}
-```
+=== "Python 3.9+"
+
+ ```Python hl_lines="11 16"
+ 路径操作装饰器依赖项（以下简称为“路径装饰器依赖项”）的执行或解析方式和普通依赖项一样，但就算这些依赖项会返回值，它们的值也不会传递给路径操作函数。
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="10 15"
+ 触发异常
+ ```
+
+=== "Python 3.6 non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="9 14"
+ {!../../../docs_src/dependencies/tutorial006.py!}
+ ```
## 为一组路径操作定义依赖项
diff --git a/docs/zh/docs/tutorial/dependencies/dependencies-with-yield.md b/docs/zh/docs/tutorial/dependencies/dependencies-with-yield.md
new file mode 100644
index 0000000000000..c0883364aff4c
--- /dev/null
+++ b/docs/zh/docs/tutorial/dependencies/dependencies-with-yield.md
@@ -0,0 +1,252 @@
+# Dependencies with yield
+
+FastAPI supports dependencies that do some extra steps after finishing.
+
+To do this, use `yield` instead of `return`, and write the extra steps after.
+
+!!! tip
+ Make sure to use `yield` one single time.
+
+!!! note "Technical Details"
+ Any function that is valid to use with:
+
+ * `@contextlib.contextmanager` or
+ * `@contextlib.asynccontextmanager`
+
+ would be valid to use as a **FastAPI** dependency.
+
+ In fact, FastAPI uses those two decorators internally.
+
+## A database dependency with `yield`
+
+For example, you could use this to create a database session and close it after finishing.
+
+Only the code prior to and including the `yield` statement is executed before sending a response:
+
+```Python hl_lines="2-4"
+{!../../../docs_src/dependencies/tutorial007.py!}
+```
+
+The yielded value is what is injected into *path operations* and other dependencies:
+
+```Python hl_lines="4"
+{!../../../docs_src/dependencies/tutorial007.py!}
+```
+
+The code following the `yield` statement is executed after the response has been delivered:
+
+```Python hl_lines="5-6"
+{!../../../docs_src/dependencies/tutorial007.py!}
+```
+
+!!! tip
+ You can use `async` or normal functions.
+
+ **FastAPI** will do the right thing with each, the same as with normal dependencies.
+
+## A dependency with `yield` and `try`
+
+If you use a `try` block in a dependency with `yield`, you'll receive any exception that was thrown when using the dependency.
+
+For example, if some code at some point in the middle, in another dependency or in a *path operation*, made a database transaction "rollback" or create any other error, you will receive the exception in your dependency.
+
+So, you can look for that specific exception inside the dependency with `except SomeException`.
+
+In the same way, you can use `finally` to make sure the exit steps are executed, no matter if there was an exception or not.
+
+```Python hl_lines="3 5"
+{!../../../docs_src/dependencies/tutorial007.py!}
+```
+
+## Sub-dependencies with `yield`
+
+You can have sub-dependencies and "trees" of sub-dependencies of any size and shape, and any or all of them can use `yield`.
+
+**FastAPI** will make sure that the "exit code" in each dependency with `yield` is run in the correct order.
+
+For example, `dependency_c` can have a dependency on `dependency_b`, and `dependency_b` on `dependency_a`:
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="6 14 22"
+ {!> ../../../docs_src/dependencies/tutorial008_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="5 13 21"
+ {!> ../../../docs_src/dependencies/tutorial008_an.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="4 12 20"
+ {!> ../../../docs_src/dependencies/tutorial008.py!}
+ ```
+
+And all of them can use `yield`.
+
+In this case `dependency_c`, to execute its exit code, needs the value from `dependency_b` (here named `dep_b`) to still be available.
+
+And, in turn, `dependency_b` needs the value from `dependency_a` (here named `dep_a`) to be available for its exit code.
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="18-19 26-27"
+ {!> ../../../docs_src/dependencies/tutorial008_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="17-18 25-26"
+ {!> ../../../docs_src/dependencies/tutorial008_an.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="16-17 24-25"
+ {!> ../../../docs_src/dependencies/tutorial008.py!}
+ ```
+
+The same way, you could have dependencies with `yield` and `return` mixed.
+
+And you could have a single dependency that requires several other dependencies with `yield`, etc.
+
+You can have any combinations of dependencies that you want.
+
+**FastAPI** will make sure everything is run in the correct order.
+
+!!! note "Technical Details"
+ This works thanks to Python's Context Managers.
+
+ **FastAPI** uses them internally to achieve this.
+
+## Dependencies with `yield` and `HTTPException`
+
+You saw that you can use dependencies with `yield` and have `try` blocks that catch exceptions.
+
+It might be tempting to raise an `HTTPException` or similar in the exit code, after the `yield`. But **it won't work**.
+
+The exit code in dependencies with `yield` is executed *after* the response is sent, so [Exception Handlers](../handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank} will have already run. There's nothing catching exceptions thrown by your dependencies in the exit code (after the `yield`).
+
+So, if you raise an `HTTPException` after the `yield`, the default (or any custom) exception handler that catches `HTTPException`s and returns an HTTP 400 response won't be there to catch that exception anymore.
+
+This is what allows anything set in the dependency (e.g. a DB session) to, for example, be used by background tasks.
+
+Background tasks are run *after* the response has been sent. So there's no way to raise an `HTTPException` because there's not even a way to change the response that is *already sent*.
+
+But if a background task creates a DB error, at least you can rollback or cleanly close the session in the dependency with `yield`, and maybe log the error or report it to a remote tracking system.
+
+If you have some code that you know could raise an exception, do the most normal/"Pythonic" thing and add a `try` block in that section of the code.
+
+If you have custom exceptions that you would like to handle *before* returning the response and possibly modifying the response, maybe even raising an `HTTPException`, create a [Custom Exception Handler](../handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank}.
+
+!!! tip
+ You can still raise exceptions including `HTTPException` *before* the `yield`. But not after.
+
+The sequence of execution is more or less like this diagram. Time flows from top to bottom. And each column is one of the parts interacting or executing code.
+
+```mermaid
+sequenceDiagram
+
+participant client as Client
+participant handler as Exception handler
+participant dep as Dep with yield
+participant operation as Path Operation
+participant tasks as Background tasks
+
+ Note over client,tasks: Can raise exception for dependency, handled after response is sent
+ Note over client,operation: Can raise HTTPException and can change the response
+ client ->> dep: Start request
+ Note over dep: Run code up to yield
+ opt raise
+ dep -->> handler: Raise HTTPException
+ handler -->> client: HTTP error response
+ dep -->> dep: Raise other exception
+ end
+ dep ->> operation: Run dependency, e.g. DB session
+ opt raise
+ operation -->> dep: Raise HTTPException
+ dep -->> handler: Auto forward exception
+ handler -->> client: HTTP error response
+ operation -->> dep: Raise other exception
+ dep -->> handler: Auto forward exception
+ end
+ operation ->> client: Return response to client
+ Note over client,operation: Response is already sent, can't change it anymore
+ opt Tasks
+ operation -->> tasks: Send background tasks
+ end
+ opt Raise other exception
+ tasks -->> dep: Raise other exception
+ end
+ Note over dep: After yield
+ opt Handle other exception
+ dep -->> dep: Handle exception, can't change response. E.g. close DB session.
+ end
+```
+
+!!! info
+ Only **one response** will be sent to the client. It might be one of the error responses or it will be the response from the *path operation*.
+
+ After one of those responses is sent, no other response can be sent.
+
+!!! tip
+ This diagram shows `HTTPException`, but you could also raise any other exception for which you create a [Custom Exception Handler](../handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank}.
+
+ If you raise any exception, it will be passed to the dependencies with yield, including `HTTPException`, and then **again** to the exception handlers. If there's no exception handler for that exception, it will then be handled by the default internal `ServerErrorMiddleware`, returning a 500 HTTP status code, to let the client know that there was an error in the server.
+
+## Context Managers
+
+### What are "Context Managers"
+
+"Context Managers" are any of those Python objects that you can use in a `with` statement.
+
+For example, you can use `with` to read a file:
+
+```Python
+with open("./somefile.txt") as f:
+ contents = f.read()
+ print(contents)
+```
+
+Underneath, the `open("./somefile.txt")` creates an object that is a called a "Context Manager".
+
+When the `with` block finishes, it makes sure to close the file, even if there were exceptions.
+
+When you create a dependency with `yield`, **FastAPI** will internally convert it to a context manager, and combine it with some other related tools.
+
+### Using context managers in dependencies with `yield`
+
+!!! warning
+ This is, more or less, an "advanced" idea.
+
+ If you are just starting with **FastAPI** you might want to skip it for now.
+
+In Python, you can create Context Managers by creating a class with two methods: `__enter__()` and `__exit__()`.
+
+You can also use them inside of **FastAPI** dependencies with `yield` by using `with` or `async with` statements inside of the dependency function:
+
+```Python hl_lines="1-9 13"
+{!../../../docs_src/dependencies/tutorial010.py!}
+```
+
+!!! tip
+ Another way to create a context manager is with:
+
+ * `@contextlib.contextmanager` or
+ * `@contextlib.asynccontextmanager`
+
+ using them to decorate a function with a single `yield`.
+
+ That's what **FastAPI** uses internally for dependencies with `yield`.
+
+ But you don't have to use the decorators for FastAPI dependencies (and you shouldn't).
+
+ FastAPI will do it for you internally.
diff --git a/docs/zh/docs/tutorial/dependencies/global-dependencies.md b/docs/zh/docs/tutorial/dependencies/global-dependencies.md
index 3f7afa32cd1b3..33e768bbe2f9d 100644
--- a/docs/zh/docs/tutorial/dependencies/global-dependencies.md
+++ b/docs/zh/docs/tutorial/dependencies/global-dependencies.md
@@ -1,17 +1,34 @@
# 全局依赖项
-有时，我们要为整个应用添加依赖项。
+For some types of applications you might want to add dependencies to the whole application.
通过与定义[*路径装饰器依赖项*](dependencies-in-path-operation-decorators.md){.internal-link target=_blank} 类似的方式，可以把依赖项添加至整个 `FastAPI` 应用。
这样一来，就可以为所有*路径操作*应用该依赖项：
-```Python hl_lines="15"
-{!../../../docs_src/dependencies/tutorial012.py!}
-```
+=== "Python 3.9+"
+
+ ```Python hl_lines="16"
+ 有时，我们要为整个应用添加依赖项。
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="16"
+ 为一组路径操作定义依赖项
+ ```
+
+=== "Python 3.6 non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="15"
+ {!../../../docs_src/dependencies/tutorial012.py!}
+ ```
[*路径装饰器依赖项*](dependencies-in-path-operation-decorators.md){.internal-link target=_blank} 一章的思路均适用于全局依赖项， 在本例中，这些依赖项可以用于应用中的所有*路径操作*。
-## 为一组路径操作定义依赖项
+## Dependencies for groups of *path operations*
稍后，[大型应用 - 多文件](../../tutorial/bigger-applications.md){.internal-link target=_blank}一章中会介绍如何使用多个文件创建大型应用程序，在这一章中，您将了解到如何为一组*路径操作*声明单个 `dependencies` 参数。
diff --git a/docs/zh/docs/tutorial/dependencies/index.md b/docs/zh/docs/tutorial/dependencies/index.md
index 7a133061de797..18a301d8e46b0 100644
--- a/docs/zh/docs/tutorial/dependencies/index.md
+++ b/docs/zh/docs/tutorial/dependencies/index.md
@@ -10,18 +10,18 @@ FastAPI 提供了简单易用，但功能强大的** ../../../docs_src/dependencies/tutorial001_py310.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="3"
+ {!../../../docs_src/dependencies/tutorial001.py!}
+ ```
+
+### Declare the dependency, in the "dependant"
与在*路径操作函数*参数中使用 `Body`、`Query` 的方式相同，声明依赖项需要使用 `Depends` 和一个新的参数：
-```Python hl_lines="15 20"
-{!../../../docs_src/dependencies/tutorial001.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="13 18"
+ 外部支持库
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="15 20"
+ 声明依赖项
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="16 21"
+ !!! tip "提示"
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="11 16"
+ {!> ../../../docs_src/dependencies/tutorial001_py310.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="15 20"
+ !!! note "笔记"
+ ```
虽然，在路径操作函数的参数中使用 `Depends` 的方式与 `Body`、`Query` 相同，但 `Depends` 的工作方式略有不同。
-这里只能传给 Depends 一个参数。
+You only give `Depends` a single parameter.
且该参数必须是可调用对象，比如函数。
+上述场景均可以使用**依赖注入**，将代码重复最小化。
+
该函数接收的参数和*路径操作函数*的参数一样。
-!!! tip "提示"
-
- 下一章介绍，除了函数还有哪些「对象」可以用作依赖项。
+!!! tip
+ You'll see what other "things", apart from functions, can be used as dependencies in the next chapter.
接收到新的请求时，**FastAPI** 执行如下操作：
@@ -98,12 +202,49 @@ common_parameters --> read_users
这样，只编写一次代码，**FastAPI** 就可以为多个*路径操作*共享这段代码 。
-!!! check "检查"
-
- 注意，无需创建专门的类，并将之传递给 **FastAPI** 以进行「注册」或执行类似的操作。
+!!! 注意，无需创建专门的类，并将之传递给 **FastAPI** 以进行「注册」或执行类似的操作。
只要把它传递给 `Depends`，**FastAPI** 就知道该如何执行后续操作。
+## Share `Annotated` dependencies
+
+接下来，我们学习一个非常简单的例子，尽管它过于简单，不是很实用。
+
+When you need to use the `common_parameters()` dependency, you have to write the whole parameter with the type annotation and `Depends()`:
+
+```Python
+commons: Annotated[dict, Depends(common_parameters)]
+```
+
+But because we are using `Annotated`, we can store that `Annotated` value in a variable and use it in multiple places:
+
+=== "Python 3.10+"
+
+ ```Python hl_lines="12 16 21"
+ 开发人员可以使用依赖项及其子依赖项为这些路径操作添加不同的权限：
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="14 18 23"
+ 等……
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="15 19 24"
+ 依赖项可以返回各种内容。
+ ```
+
+!!! tip
+ This is just standard Python, it's called a "type alias", it's actually not specific to **FastAPI**.
+
+ But because **FastAPI** is based on the Python standards, including `Annotated`, you can use this trick in your code. 😎
+
+The dependencies will keep working as expected, and the **best part** is that the **type information will be preserved**, which means that your editor will be able to keep providing you with **autocompletion**, **inline errors**, etc. The same for other tools like `mypy`.
+
+上述这些操作都是可行的，**FastAPI** 知道该怎么处理。
+
## 要不要使用 `async`？
**FastAPI** 调用依赖项的方式与*路径操作函数*一样，因此，定义依赖项函数，也要应用与路径操作函数相同的规则。
@@ -112,11 +253,10 @@ common_parameters --> read_users
在普通的 `def` *路径操作函数*中，可以声明异步的 `async def` 依赖项；也可以在异步的 `async def` *路径操作函数*中声明普通的 `def` 依赖项。
-上述这些操作都是可行的，**FastAPI** 知道该怎么处理。
-
-!!! note "笔记"
+It doesn't matter. 然后，**FastAPI** 会用正确的参数调用函数，并提取请求中的数据。
- 如里不了解异步，请参阅[异步：*“着急了？”*](../../async.md){.internal-link target=_blank} 一章中 `async` 和 `await` 的内容。
+!!! note
+ If you don't know, check the [Async: *"In a hurry?"*](../../async.md){.internal-link target=_blank} section about `async` and `await` in the docs.
## 与 OpenAPI 集成
@@ -124,15 +264,15 @@ common_parameters --> read_users
所以，交互文档里也会显示依赖项的所有信息：
-
+
## 简单用法
-观察一下就会发现，只要*路径* 和*操作*匹配，就可以使用声明的路径操作函数。然后，**FastAPI** 会用正确的参数调用函数，并提取请求中的数据。
+开发人员永远都不需要直接调用这些函数，这些函数是由框架（在此为 **FastAPI** ）调用的。
实际上，所有（或大多数）网络框架的工作方式都是这样的。
-开发人员永远都不需要直接调用这些函数，这些函数是由框架（在此为 **FastAPI** ）调用的。
+You never call those functions directly. They are called by your framework (in this case, **FastAPI**).
通过依赖注入系统，只要告诉 **FastAPI** *路径操作函数* 还要「依赖」其他在*路径操作函数*之前执行的内容，**FastAPI** 就会执行函数代码，并「注入」函数返回的结果。
@@ -144,21 +284,21 @@ common_parameters --> read_users
* 可注入（Injectable）
* 组件（Component）
-## **FastAPI** 插件
+## **FastAPI** 兼容性
-**依赖注入**系统支持构建集成和「插件」。但实际上，FastAPI 根本**不需要创建「插件」**，因为使用依赖项可以声明不限数量的、可用于*路径操作函数*的集成与交互。
+**依赖注入**系统支持构建集成和「插件」。 但实际上，FastAPI 根本**不需要创建「插件」**，因为使用依赖项可以声明不限数量的、可用于*路径操作函数*的集成与交互。
-创建依赖项非常简单、直观，并且还支持导入 Python 包。毫不夸张地说，只要几行代码就可以把需要的 Python 包与 API 函数集成在一起。
+创建依赖项非常简单、直观，并且还支持导入 Python 包。 毫不夸张地说，只要几行代码就可以把需要的 Python 包与 API 函数集成在一起。
下一章将详细介绍在关系型数据库、NoSQL 数据库、安全等方面使用依赖项的例子。
-## **FastAPI** 兼容性
+## **FastAPI** 插件
依赖注入系统如此简洁的特性，让 **FastAPI** 可以与下列系统兼容：
* 关系型数据库
* NoSQL 数据库
-* 外部支持库
+* external packages
* 外部 API
* 认证和鉴权系统
* API 使用监控系统
@@ -180,7 +320,7 @@ common_parameters --> read_users
* `/users/{user_id}/activate`
* `/items/pro/`
-开发人员可以使用依赖项及其子依赖项为这些路径操作添加不同的权限：
+then you could add different permission requirements for each of them just with dependencies and sub-dependencies:
```mermaid
graph TB
diff --git a/docs/zh/docs/tutorial/dependencies/sub-dependencies.md b/docs/zh/docs/tutorial/dependencies/sub-dependencies.md
index 58377bbfecd8d..fa61d94fa0bb3 100644
--- a/docs/zh/docs/tutorial/dependencies/sub-dependencies.md
+++ b/docs/zh/docs/tutorial/dependencies/sub-dependencies.md
@@ -6,25 +6,89 @@ FastAPI 支持创建含**子依赖项**的依赖项。
**FastAPI** 负责处理解析不同深度的子依赖项。
-### 第一层依赖项
+## 第一层依赖项
-下列代码创建了第一层依赖项：
+You could create a first dependency ("dependable") like:
-```Python hl_lines="8-9"
-{!../../../docs_src/dependencies/tutorial005.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="8-9"
+ 这个函数很简单（不过也没什么用），但却有助于让我们专注于了解子依赖项的工作方式。
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="8-9"
+ 小结
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="9-10"
+ !!! tip "提示"
+ ```
+
+=== "Python 3.10 non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="6-7"
+ {!../../../docs_src/dependencies/tutorial005.py!}
+ ```
+
+=== "Python 3.6 non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="8-9"
+ {!> ../../../docs_src/dependencies/tutorial005.py!}
+ ```
这段代码声明了类型为 `str` 的可选查询参数 `q`，然后返回这个查询参数。
-这个函数很简单（不过也没什么用），但却有助于让我们专注于了解子依赖项的工作方式。
+This is quite simple (not very useful), but will help us focus on how the sub-dependencies work.
-### 第二层依赖项
+## Second dependency, "dependable" and "dependant"
接下来，创建另一个依赖项函数，并同时用该依赖项自身再声明一个依赖项（所以这也是一个「依赖项」）：
-```Python hl_lines="13"
-{!../../../docs_src/dependencies/tutorial005.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="13"
+ {!> ../../../docs_src/dependencies/tutorial005_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="13"
+ 下列代码创建了第一层依赖项：
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="14"
+ {!> ../../../docs_src/dependencies/tutorial005_an.py!}
+ ```
+
+=== "Python 3.10 non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="11"
+ {!> ../../../docs_src/dependencies/tutorial005_py310.py!}
+ ```
+
+=== "Python 3.6 non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="13"
+ {!../../../docs_src/dependencies/tutorial005.py!}
+ ```
这里重点说明一下声明的参数：
@@ -33,17 +97,47 @@ FastAPI 支持创建含**子依赖项**的依赖项。
* 同时，该函数还声明了类型是 `str` 的可选 cookie（`last_query`）
* 用户未提供查询参数 `q` 时，则使用上次使用后保存在 cookie 中的查询
-### 使用依赖项
+## 使用依赖项
接下来，就可以使用依赖项：
-```Python hl_lines="22"
-{!../../../docs_src/dependencies/tutorial005.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="23"
+ {!> ../../../docs_src/dependencies/tutorial005_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="23"
+ 第二层依赖项
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="24"
+ !!! info "信息"
+ ```
+
+=== "Python 3.10 non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="19"
+ {!> ../../../docs_src/dependencies/tutorial005_py310.py!}
+ ```
+
+=== "Python 3.6 non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
-!!! info "信息"
+ ```Python hl_lines="22"
+ {!../../../docs_src/dependencies/tutorial005.py!}
+ ```
- 注意，这里在*路径操作函数*中只声明了一个依赖项，即 `query_or_cookie_extractor` 。
+!!! 注意，这里在*路径操作函数*中只声明了一个依赖项，即 `query_or_cookie_extractor` 。
但 **FastAPI** 必须先处理 `query_extractor`，以便在调用 `query_or_cookie_extractor` 时使用 `query_extractor` 返回的结果。
@@ -66,12 +160,27 @@ FastAPI 不会为同一个请求多次调用同一个依赖项，而是把依赖
在高级使用场景中，如果不想使用「缓存」值，而是为需要在同一请求的每一步操作（多次）中都实际调用依赖项，可以把 `Depends` 的参数 `use_cache` 的值设置为 `False` :
-```Python hl_lines="1"
-async def needy_dependency(fresh_value: str = Depends(get_value, use_cache=False)):
+=== "Python 3.6+"
+
+ ```Python hl_lines="1"
+ 这些简单的例子现在看上去虽然没有什么实用价值，
+
+但在**安全**一章中，您会了解到这些例子的用途，
+
+以及这些例子所能节省的代码量。
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="1"
+ async def needy_dependency(fresh_value: str = Depends(get_value, use_cache=False)):
return {"fresh_value": fresh_value}
-```
+ ```
-## 小结
+## Recap
千万别被本章里这些花里胡哨的词藻吓倒了，其实**依赖注入**系统非常简单。
@@ -79,10 +188,9 @@ async def needy_dependency(fresh_value: str = Depends(get_value, use_cache=False
但它依然非常强大，能够声明任意嵌套深度的「图」或树状的依赖结构。
-!!! tip "提示"
-
- 这些简单的例子现在看上去虽然没有什么实用价值，
-
- 但在**安全**一章中，您会了解到这些例子的用途，
+!!! tip
+ All this might not seem as useful with these simple examples.
- 以及这些例子所能节省的代码量。
+ But you will see how useful it is in the chapters about **security**.
+
+ And you will also see the amounts of code it will save you.
diff --git a/docs/zh/docs/tutorial/encoder.md b/docs/zh/docs/tutorial/encoder.md
index 76ed846ce35e4..3c0b9152fc1dd 100644
--- a/docs/zh/docs/tutorial/encoder.md
+++ b/docs/zh/docs/tutorial/encoder.md
@@ -36,7 +36,7 @@
调用它的结果后就可以使用Python标准编码中的`json.dumps()`。
-这个操作不会返回一个包含JSON格式（作为字符串）数据的庞大的`str`。它将返回一个Python标准数据结构（例如`dict`），其值和子值都与JSON兼容。
+这个操作不会返回一个包含JSON格式（作为字符串）数据的庞大的`str`。 它将返回一个Python标准数据结构（例如`dict`），其值和子值都与JSON兼容。
-!!! note
- `jsonable_encoder`实际上是FastAPI内部用来转换数据的。但是它在许多其他场景中也很有用。
+!!! !!! note
+ `jsonable_encoder`实际上是FastAPI内部用来转换数据的。 但是它在许多其他场景中也很有用。
diff --git a/docs/zh/docs/tutorial/extra-data-types.md b/docs/zh/docs/tutorial/extra-data-types.md
index ac3e076545f48..60fc4c3bc68df 100644
--- a/docs/zh/docs/tutorial/extra-data-types.md
+++ b/docs/zh/docs/tutorial/extra-data-types.md
@@ -55,12 +55,76 @@
下面是一个*路径操作*的示例，其中的参数使用了上面的一些类型。
-```Python hl_lines="1 3 12-16"
-{!../../../docs_src/extra_data_types/tutorial001.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="1 3 12-16"
+ {!> ../../../docs_src/extra_data_types/tutorial001_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="1 3 12-16"
+ {!> ../../../docs_src/extra_data_types/tutorial001_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="1 3 13-17"
+ {!> ../../../docs_src/extra_data_types/tutorial001_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="1 2 11-15"
+ {!../../../docs_src/extra_data_types/tutorial001.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="1 2 12-16"
+ {!../../../docs_src/extra_data_types/tutorial001.py!}
+ ```
注意，函数内的参数有原生的数据类型，你可以，例如，执行正常的日期操作，如:
-```Python hl_lines="18-19"
-{!../../../docs_src/extra_data_types/tutorial001.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="18-19"
+ {!> ../../../docs_src/extra_data_types/tutorial001_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="18-19"
+ {!> ../../../docs_src/extra_data_types/tutorial001_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="19-20"
+ {!> ../../../docs_src/extra_data_types/tutorial001_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="17-18"
+ {!> ../../../docs_src/extra_data_types/tutorial001_py310.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="18-19"
+ {!> ../../../docs_src/extra_data_types/tutorial001.py!}
+ ```
diff --git a/docs/zh/docs/tutorial/extra-models.md b/docs/zh/docs/tutorial/extra-models.md
index 1fbe77be8de70..1a1f3c3354ca8 100644
--- a/docs/zh/docs/tutorial/extra-models.md
+++ b/docs/zh/docs/tutorial/extra-models.md
@@ -8,8 +8,8 @@
* **输出模型**不应该包含密码。
* **数据库模型**很可能需要保存密码的哈希值。
-!!! danger
- 永远不要存储用户的明文密码。始终存储一个可以用于验证的「安全哈希值」。
+!!! !!! danger
+ 永远不要存储用户的明文密码。 始终存储一个可以用于验证的「安全哈希值」。
如果你尚未了解该知识，你可以在[安全章节](security/simple-oauth2.md#password-hashing){.internal-link target=_blank}中学习何为「密码哈希值」。
@@ -17,9 +17,17 @@
下面是应该如何根据它们的密码字段以及使用位置去定义模型的大概思路：
-```Python hl_lines="9 11 16 22 24 29-30 33-35 40-41"
-{!../../../docs_src/extra_models/tutorial001.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="7 9 14 20 22 27-28 31-33 38-39"
+ {!> ../../../docs_src/extra_models/tutorial001_py310.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="9 11 16 22 24 29-30 33-35 40-41"
+ {!../../../docs_src/extra_models/tutorial001.py!}
+ ```
### 关于 `**user_in.dict()`
@@ -62,7 +70,7 @@ print(user_dict)
#### 解包 `dict`
-如果我们将 `user_dict` 这样的 `dict` 以 `**user_dict` 形式传递给一个函数（或类），Python将对其进行「解包」。它会将 `user_dict` 的键和值作为关键字参数直接传递。
+如果我们将 `user_dict` 这样的 `dict` 以 `**user_dict` 形式传递给一个函数（或类），Python将对其进行「解包」。 它会将 `user_dict` 的键和值作为关键字参数直接传递。
因此，从上面的 `user_dict` 继续，编写：
@@ -94,7 +102,7 @@ UserInDB(
#### 来自于其他模型内容的 Pydantic 模型
-如上例所示，我们从 `user_in.dict（）` 中获得了 `user_dict`，此代码：
+...因为 `user_in.dict()` 是一个 `dict`，然后我们通过以`**`开头传递给 `UserInDB` 来使 Python「解包」它。
```Python
user_dict = user_in.dict()
@@ -107,7 +115,7 @@ UserInDB(**user_dict)
UserInDB(**user_in.dict())
```
-...因为 `user_in.dict()` 是一个 `dict`，然后我们通过以`**`开头传递给 `UserInDB` 来使 Python「解包」它。
+如上例所示，我们从 `user_in.dict（）` 中获得了 `user_dict`，此代码：
这样，我们获得了一个来自于其他 Pydantic 模型中的数据的 Pydantic 模型。
@@ -132,7 +140,7 @@ UserInDB(
```
!!! warning
- 辅助性的额外函数只是为了演示可能的数据流，但它们显然不能提供任何真正的安全性。
+ The supporting additional functions are just to demo a possible flow of the data, but they of course are not providing any real security.
## 减少重复
@@ -144,15 +152,23 @@ UserInDB(
我们可以做得更好。
-我们可以声明一个 `UserBase` 模型作为其他模型的基类。然后我们可以创建继承该模型属性（类型声明，校验等）的子类。
+我们可以声明一个 `UserBase` 模型作为其他模型的基类。 然后我们可以创建继承该模型属性（类型声明，校验等）的子类。
所有的数据转换、校验、文档生成等仍将正常运行。
这样，我们可以仅声明模型之间的差异部分（具有明文的 `password`、具有 `hashed_password` 以及不包括密码）。
-```Python hl_lines="9 15-16 19-20 23-24"
-{!../../../docs_src/extra_models/tutorial002.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="7 13-14 17-18 21-22"
+ {!> ../../../docs_src/extra_models/tutorial002_py310.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="9 15-16 19-20 23-24"
+ {!../../../docs_src/extra_models/tutorial002.py!}
+ ```
## `Union` 或者 `anyOf`
@@ -162,23 +178,53 @@ UserInDB(
为此，请使用标准的 Python 类型提示 `typing.Union`：
+!!! !!! note
+ 定义一个 `Union` 类型时，首先包括最详细的类型，然后是不太详细的类型。 在下面的示例中，更详细的 `PlaneItem` 位于 `Union[PlaneItem，CarItem]` 中的 `CarItem` 之前。
+
+=== "Python 3.10+"
+
+ ```Python hl_lines="1 14-15 18-20 33"
+ {!> ../../../docs_src/extra_models/tutorial003_py310.py!}
+ ```
+
+=== "Python 3.6+"
-!!! note
- 定义一个 `Union` 类型时，首先包括最详细的类型，然后是不太详细的类型。在下面的示例中，更详细的 `PlaneItem` 位于 `Union[PlaneItem，CarItem]` 中的 `CarItem` 之前。
+ ```Python hl_lines="1 14-15 18-20 33"
+ {!../../../docs_src/extra_models/tutorial003.py!}
+ ```
-```Python hl_lines="1 14-15 18-20 33"
-{!../../../docs_src/extra_models/tutorial003.py!}
+### `Union` in Python 3.10
+
+In this example we pass `Union[PlaneItem, CarItem]` as the value of the argument `response_model`.
+
+Because we are passing it as a **value to an argument** instead of putting it in a **type annotation**, we have to use `Union` even in Python 3.10.
+
+If it was in a type annotation we could have used the vertical bar, as:
+
+```Python
+some_variable: PlaneItem | CarItem
```
+But if we put that in `response_model=PlaneItem | CarItem` we would get an error, because Python would try to perform an **invalid operation** between `PlaneItem` and `CarItem` instead of interpreting that as a type annotation.
+
## 模型列表
你可以用同样的方式声明由对象列表构成的响应。
为此，请使用标准的 Python `typing.List`：
-```Python hl_lines="1 20"
-{!../../../docs_src/extra_models/tutorial004.py!}
-```
+=== "Python 3.9+"
+
+ ```Python hl_lines="18"
+ !!! warning
+ 辅助性的额外函数只是为了演示可能的数据流，但它们显然不能提供任何真正的安全性。
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="1 20"
+ {!../../../docs_src/extra_models/tutorial004.py!}
+ ```
## 任意 `dict` 构成的响应
@@ -188,12 +234,20 @@ UserInDB(
在这种情况下，你可以使用 `typing.Dict`：
-```Python hl_lines="1 8"
-{!../../../docs_src/extra_models/tutorial005.py!}
-```
+=== "Python 3.9+"
+
+ ```Python hl_lines="6"
+ 总结
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="1 8"
+ {!../../../docs_src/extra_models/tutorial005.py!}
+ ```
-## 总结
+## Recap
使用多个 Pydantic 模型，并针对不同场景自由地继承。
-如果一个实体必须能够具有不同的「状态」，你无需为每个状态的实体定义单独的数据模型。以用户「实体」为例，其状态有包含 `password`、包含 `password_hash` 以及不含密码。
+如果一个实体必须能够具有不同的「状态」，你无需为每个状态的实体定义单独的数据模型。 以用户「实体」为例，其状态有包含 `password`、包含 `password_hash` 以及不含密码。
diff --git a/docs/zh/docs/tutorial/first-steps.md b/docs/zh/docs/tutorial/first-steps.md
index 30fae99cf8fc2..597e8e6f89acf 100644
--- a/docs/zh/docs/tutorial/first-steps.md
+++ b/docs/zh/docs/tutorial/first-steps.md
@@ -21,16 +21,17 @@ $ uvicorn main:app --reload
INFO: Waiting for application startup.
INFO: Application startup complete.
```
+INFO: Application startup complete.
+```
get 操作
-!!! info "`@decorator` Info"
- `@something` 语法在 Python 中被称为「装饰器」。
-
- 像一顶漂亮的装饰帽一样，将它放在一个函数的上方（我猜测这个术语的命名就是这么来的）。
+!!! !!! info "`@decorator` Info" `@something` 语法在 Python 中被称为「装饰器」。
+ You put it on top of a function. 像一顶漂亮的装饰帽一样，将它放在一个函数的上方（我猜测这个术语的命名就是这么来的）。
+
装饰器接收位于其下方的函数并且用它完成一些工作。
-
+
在我们的例子中，这个装饰器告诉 **FastAPI** 位于其下方的函数对应着**路径** `/` 加上 `get` **操作**。
-
+
它是一个「**路径操作装饰器**」。
你也可以使用其他的操作：
@@ -276,13 +275,13 @@ https://example.com/items/foo
* `@app.patch()`
* `@app.trace()`
-!!! tip
+!!! !!! tip
您可以随意使用任何一个操作（HTTP方法）。
**FastAPI** 没有强制要求操作有任何特定的含义。
-
+
此处提供的信息仅作为指导，而不是要求。
-
+
比如，当使用 GraphQL 时通常你所有的动作都通过 `post` 一种方法执行。
### 步骤 4：定义**路径操作函数**
@@ -311,7 +310,7 @@ https://example.com/items/foo
{!../../../docs_src/first_steps/tutorial003.py!}
```
-!!! note
+!!! !!! note
如果你不知道两者的区别，请查阅 [Async: *"In a hurry?"*](https://fastapi.tiangolo.com/async/#in-a-hurry){.internal-link target=_blank}。
### 步骤 5：返回内容
@@ -324,9 +323,9 @@ https://example.com/items/foo
你还可以返回 Pydantic 模型（稍后你将了解更多）。
-还有许多其他将会自动转换为 JSON 的对象和模型（包括 ORM 对象等）。尝试下使用你最喜欢的一种，它很有可能已经被支持。
+还有许多其他将会自动转换为 JSON 的对象和模型（包括 ORM 对象等）。 尝试下使用你最喜欢的一种，它很有可能已经被支持。
-## 总结
+## Recap
* 导入 `FastAPI`。
* 创建一个 `app` 实例。
diff --git a/docs/zh/docs/tutorial/handling-errors.md b/docs/zh/docs/tutorial/handling-errors.md
index 9b066bc2cee65..46a31245ea790 100644
--- a/docs/zh/docs/tutorial/handling-errors.md
+++ b/docs/zh/docs/tutorial/handling-errors.md
@@ -4,18 +4,18 @@
这里所谓的客户端包括前端浏览器、其他应用程序、物联网设备等。
-需要向客户端返回错误提示的场景主要如下：
+You could need to tell the client that:
-- 客户端没有执行操作的权限
-- 客户端没有访问资源的权限
-- 客户端要访问的项目不存在
-- 等等 ...
+* 客户端没有执行操作的权限
+* 客户端没有访问资源的权限
+* 客户端要访问的项目不存在
+* etc.
遇到这些情况时，通常要返回 **4XX**（400 至 499）**HTTP 状态码**。
-**4XX** 状态码与表示请求成功的 **2XX**（200 至 299） HTTP 状态码类似。
+This is similar to the 200 HTTP status codes (from 200 to 299). Those "200" status codes mean that somehow there was a "success" in the request.
-只不过，**4XX** 状态码表示客户端发生的错误。
+The status codes in the 400 range mean that there was an error from the client.
大家都知道**「404 Not Found」**错误，还有调侃这个错误的笑话吧？
@@ -27,7 +27,6 @@
```Python hl_lines="1"
{!../../../docs_src/handling_errors/tutorial001.py!}
-
```
### 触发 `HTTPException`
@@ -44,7 +43,6 @@
```Python hl_lines="11"
{!../../../docs_src/handling_errors/tutorial001.py!}
-
```
### 响应结果
@@ -55,7 +53,6 @@
{
"item": "The Foo Wrestlers"
}
-
```
但如果客户端请求 `http://example.com/items/bar`（`item_id` `「bar」` 不存在时），则会接收到 HTTP 状态码 - 404（「未找到」错误）及如下 JSON 响应结果：
@@ -64,21 +61,15 @@
{
"detail": "Item not found"
}
-
```
-!!! tip "提示"
-
- 触发 `HTTPException` 时，可以用参数 `detail` 传递任何能转换为 JSON 的值，不仅限于 `str`。
-
- 还支持传递 `dict`、`list` 等数据结构。
-
- **FastAPI** 能自动处理这些数据，并将之转换为 JSON。
+!!! 触发 `HTTPException` 时，可以用参数 `detail` 传递任何能转换为 JSON 的值，不仅限于 `str`。
+ 还支持传递 `dict`、`list` 等数据结构。 **FastAPI** 能自动处理这些数据，并将之转换为 JSON。
## 添加自定义响应头
-有些场景下要为 HTTP 错误添加自定义响应头。例如，出于某些方面的安全需要。
+有些场景下要为 HTTP 错误添加自定义响应头。 例如，出于某些方面的安全需要。
一般情况下可能不会需要在代码中直接使用响应头。
@@ -86,7 +77,6 @@
```Python hl_lines="14"
{!../../../docs_src/handling_errors/tutorial002.py!}
-
```
## 安装自定义异常处理器
@@ -101,7 +91,6 @@
```Python hl_lines="5-7 13-18 24"
{!../../../docs_src/handling_errors/tutorial003.py!}
-
```
请求 `/unicorns/yolo` 时，路径操作会触发 `UnicornException`。
@@ -111,30 +100,27 @@
接收到的错误信息清晰明了，HTTP 状态码为 `418`，JSON 内容如下：
```JSON
-{"message": "Oops! yolo did something. There goes a rainbow..."}
-
+{"message": "Oops! yolo did something. {"message": "Oops! yolo did something. There goes a rainbow..."}
```
-!!! note "技术细节"
-
- `from starlette.requests import Request` 和 `from starlette.responses import JSONResponse` 也可以用于导入 `Request` 和 `JSONResponse`。
+!!! note "Technical Details"
+ You could also use `from starlette.requests import Request` and `from starlette.responses import JSONResponse`.
- **FastAPI** 提供了与 `starlette.responses` 相同的 `fastapi.responses` 作为快捷方式，但大部分响应操作都可以直接从 Starlette 导入。同理，`Request` 也是如此。
+ `from starlette.requests import Request` 和 `from starlette.responses import JSONResponse` 也可以用于导入 `Request` 和 `JSONResponse`。 **FastAPI** 提供了与 `starlette.responses` 相同的 `fastapi.responses` 作为快捷方式，但大部分响应操作都可以直接从 Starlette 导入。 同理，`Request` 也是如此。
-
-## 覆盖默认异常处理器
+## Override the default exception handlers
**FastAPI** 自带了一些默认异常处理器。
触发 `HTTPException` 或请求无效数据时，这些处理器返回默认的 JSON 响应结果。
-不过，也可以使用自定义处理器覆盖默认异常处理器。
+You can override these exception handlers with your own.
### 覆盖请求验证异常
请求中包含无效数据时，**FastAPI** 内部会触发 `RequestValidationError`。
-该异常也内置了默认异常处理器。
+And it also includes a default exception handler for it.
覆盖默认异常处理器时需要导入 `RequestValidationError`，并用 `@app.excption_handler(RequestValidationError)` 装饰异常处理器。
@@ -142,7 +128,6 @@
```Python hl_lines="2 14-16"
{!../../../docs_src/handling_errors/tutorial004.py!}
-
```
访问 `/items/foo`，可以看到以下内容替换了默认 JSON 错误信息：
@@ -160,30 +145,26 @@
}
]
}
-
```
-以下是文本格式的错误信息：
+you will get a text version, with:
```
1 validation error
path -> item_id
value is not a valid integer (type=type_error.integer)
-
```
-### `RequestValidationError` vs `ValidationError`
-
-!!! warning "警告"
-
- 如果您觉得现在还用不到以下技术细节，可以先跳过下面的内容。
+#### `RequestValidationError` vs `ValidationError`
+!!! warning
+ These are technical details that you might skip if it's not important for you now.
`RequestValidationError` 是 Pydantic 的 `ValidationError` 的子类。
**FastAPI** 调用的就是 `RequestValidationError` 类，因此，如果在 `response_model` 中使用 Pydantic 模型，且数据有错误时，在日志中就会看到这个错误。
-但客户端或用户看不到这个错误。反之，客户端接收到的是 HTTP 状态码为 `500` 的「内部服务器错误」。
+但客户端或用户看不到这个错误。 反之，客户端接收到的是 HTTP 状态码为 `500` 的「内部服务器错误」。
这是因为在*响应*或代码（不是在客户端的请求里）中出现的 Pydantic `ValidationError` 是代码的 bug。
@@ -197,15 +178,12 @@ path -> item_id
```Python hl_lines="3-4 9-11 22"
{!../../../docs_src/handling_errors/tutorial004.py!}
-
```
-!!! note "技术细节"
-
- 还可以使用 `from starlette.responses import PlainTextResponse`。
-
- **FastAPI** 提供了与 `starlette.responses` 相同的 `fastapi.responses` 作为快捷方式，但大部分响应都可以直接从 Starlette 导入。
+!!! note "Technical Details"
+ You could also use `from starlette.responses import PlainTextResponse`.
+ 还可以使用 `from starlette.responses import PlainTextResponse`。 **FastAPI** 提供了与 `starlette.responses` 相同的 `fastapi.responses` 作为快捷方式，但大部分响应都可以直接从 Starlette 导入。
### 使用 `RequestValidationError` 的请求体
@@ -215,7 +193,6 @@ path -> item_id
```Python hl_lines="14"
{!../../../docs_src/handling_errors/tutorial005.py!}
-
```
现在试着发送一个无效的 `item`，例如：
@@ -225,7 +202,6 @@ path -> item_id
"title": "towel",
"size": "XL"
}
-
```
收到的响应包含 `body` 信息，并说明数据是无效的：
@@ -247,10 +223,9 @@ path -> item_id
"size": "XL"
}
}
-
```
-### FastAPI `HTTPException` vs Starlette `HTTPException`
+#### FastAPI `HTTPException` vs Starlette `HTTPException`
**FastAPI** 也提供了自有的 `HTTPException`。
@@ -270,20 +245,14 @@ OAuth 2.0 等安全工具需要在内部调用这些响应头。
```Python
from starlette.exceptions import HTTPException as StarletteHTTPException
-
```
### 复用 **FastAPI** 异常处理器
FastAPI 支持先对异常进行某些处理，然后再使用 **FastAPI** 中处理该异常的默认异常处理器。
-从 `fastapi.exception_handlers` 中导入要复用的默认异常处理器：
-
```Python hl_lines="2-5 15 21"
{!../../../docs_src/handling_errors/tutorial006.py!}
-
```
-虽然，本例只是输出了夸大其词的错误信息。
-
-但也足以说明，可以在处理异常之后再复用默认的异常处理器。
+In this example you are just `print`ing the error with a very expressive message, but you get the idea. You can use the exception and then just re-use the default exception handlers.
diff --git a/docs/zh/docs/tutorial/header-params.md b/docs/zh/docs/tutorial/header-params.md
index c4b1c38ceecc8..945345f38ef25 100644
--- a/docs/zh/docs/tutorial/header-params.md
+++ b/docs/zh/docs/tutorial/header-params.md
@@ -6,9 +6,41 @@
首先导入 `Header`:
-```Python hl_lines="3"
-{!../../../docs_src/header_params/tutorial001.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="3"
+ {!> ../../../docs_src/header_params/tutorial001_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="3"
+ {!> ../../../docs_src/header_params/tutorial001_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="3"
+ {!> ../../../docs_src/header_params/tutorial001_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="1"
+ {!../../../docs_src/header_params/tutorial001.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="3"
+ {!../../../docs_src/header_params/tutorial002.py!}
+ ```
## 声明 `Header` 参数
@@ -16,17 +48,49 @@
第一个值是默认值，你可以传递所有的额外验证或注释参数：
-```Python hl_lines="9"
-{!../../../docs_src/header_params/tutorial001.py!}
-```
+=== "Python 3.10+"
-!!! note "技术细节"
- `Header` 是 `Path`, `Query` 和 `Cookie` 的兄弟类型。它也继承自通用的 `Param` 类.
+ ```Python hl_lines="9"
+ {!> ../../../docs_src/header_params/tutorial001_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="9"
+ {!> ../../../docs_src/header_params/tutorial001_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="10"
+ {!> ../../../docs_src/header_params/tutorial001_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="7"
+ {!> ../../../docs_src/header_params/tutorial001_py310.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="9"
+ {!> ../../../docs_src/header_params/tutorial001.py!}
+ ```
+
+!!! !!! note "技术细节"
+ `Header` 是 `Path`, `Query` 和 `Cookie` 的兄弟类型。 它也继承自通用的 `Param` 类.
但是请记得，当你从`fastapi`导入 `Query`, `Path`, `Header`, 或其他时，实际上导入的是返回特定类型的函数。
!!! info
- 为了声明headers， 你需要使用`Header`, 因为否则参数将被解释为查询参数。
+ To declare headers, you need to use `Header`, because otherwise the parameters would be interpreted as query parameters.
## 自动转换
@@ -44,17 +108,51 @@
如果出于某些原因，你需要禁用下划线到连字符的自动转换，设置`Header`的参数 `convert_underscores` 为 `False`:
-```Python hl_lines="10"
-{!../../../docs_src/header_params/tutorial002.py!}
-```
+=== "Python 3.10+"
-!!! warning
- 在设置 `convert_underscores` 为 `False` 之前，请记住，一些HTTP代理和服务器不允许使用带有下划线的headers。
+ ```Python hl_lines="10"
+ {!> ../../../docs_src/header_params/tutorial002_an_py310.py!}
+ ```
+=== "Python 3.9+"
+
+ ```Python hl_lines="11"
+ !!! info
+ 为了声明headers， 你需要使用Header, 因为否则参数将被解释为查询参数。
+ ```
+, 因为否则参数将被解释为查询参数。
+
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="12"
+ {!> ../../../docs_src/header_params/tutorial002_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="8"
+ {!> ../../../docs_src/header_params/tutorial002_py310.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="10"
+ {!../../../docs_src/header_params/tutorial001.py!}
+ ```
+
+!!! warning
+ Before setting `convert_underscores` to `False`, bear in mind that some HTTP proxies and servers disallow the usage of headers with underscores.
## 重复的 headers
-有可能收到重复的headers。这意味着，相同的header具有多个值。
+有可能收到重复的headers。 这意味着，相同的header具有多个值。
您可以在类型声明中使用一个list来定义这些情况。
@@ -62,9 +160,53 @@
比如, 为了声明一个 `X-Token` header 可以出现多次，你可以这样写：
-```Python hl_lines="9"
-{!../../../docs_src/header_params/tutorial003.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="9"
+ {!> ../../../docs_src/header_params/tutorial003_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="9"
+ {!> ../../../docs_src/header_params/tutorial003_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="10"
+ {!> ../../../docs_src/header_params/tutorial003_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="7"
+ {!> ../../../docs_src/header_params/tutorial003_py310.py!}
+ ```
+
+=== "Python 3.9+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="9"
+ !!! warning
+ 在设置 convert_underscores 为 False 之前，请记住，一些HTTP代理和服务器不允许使用带有下划线的headers。
+ ```
+ 为 False 之前，请记住，一些HTTP代理和服务器不允许使用带有下划线的headers。
+
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="9"
+ {!../../../docs_src/header_params/tutorial003.py!}
+ ```
如果你与*路径操作*通信时发送两个HTTP headers，就像：
diff --git a/docs/zh/docs/tutorial/index.md b/docs/zh/docs/tutorial/index.md
index 6180d3de399ae..e9f55adc42962 100644
--- a/docs/zh/docs/tutorial/index.md
+++ b/docs/zh/docs/tutorial/index.md
@@ -25,10 +25,12 @@ $ uvicorn main:app --reload
INFO: Waiting for application startup.
INFO: Application startup complete.
```
+INFO: Application startup complete.
+```
-
-## 标签元数据
-
-你也可以使用参数 `openapi_tags`，为用于分组路径操作的不同标签添加额外的元数据。
-
-它接受一个列表，这个列表包含每个标签对应的一个字典。
-
-每个字典可以包含：
-
-* `name`（**必要**）：一个 `str`，它与*路径操作*和 `APIRouter` 中使用的 `tags` 参数有相同的标签名。
-* `description`：一个用于简短描述标签的 `str`。它支持 Markdown 并且会在文档用户界面中显示。
-* `externalDocs`：一个描述外部文档的 `dict`：
- * `description`：用于简短描述外部文档的 `str`。
- * `url`（**必要**）：外部文档的 URL `str`。
-
-### 创建标签元数据
-
-让我们在带有标签的示例中为 `users` 和 `items` 试一下。
-
-创建标签元数据并把它传递给 `openapi_tags` 参数：
-
-```Python hl_lines="3-16 18"
-{!../../../docs_src/metadata/tutorial004.py!}
-```
-
-注意你可以在描述内使用 Markdown，例如「login」会显示为粗体（**login**）以及「fancy」会显示为斜体（_fancy_）。
-
-!!! 提示
- 不必为你使用的所有标签都添加元数据。
-
-### 使用你的标签
-
-将 `tags` 参数和*路径操作*（以及 `APIRouter`）一起使用，将其分配给不同的标签：
-
-```Python hl_lines="21 26"
-{!../../../docs_src/metadata/tutorial004.py!}
-```
-
-!!! 信息
- 阅读更多关于标签的信息[路径操作配置](../path-operation-configuration/#tags){.internal-link target=_blank}。
-
-### 查看文档
-
-如果你现在查看文档，它们会显示所有附加的元数据：
-
-
-
-### 标签顺序
-
-每个标签元数据字典的顺序也定义了在文档用户界面显示的顺序。
-
-例如按照字母顺序，即使 `users` 排在 `items` 之后，它也会显示在前面，因为我们将它的元数据添加为列表内的第一个字典。
-
-## OpenAPI URL
-
-默认情况下，OpenAPI 模式服务于 `/openapi.json`。
-
-但是你可以通过参数 `openapi_url` 对其进行配置。
-
-例如，将其设置为服务于 `/api/v1/openapi.json`：
-
-```Python hl_lines="3"
-{!../../../docs_src/metadata/tutorial002.py!}
-```
-
-如果你想完全禁用 OpenAPI 模式，可以将其设置为 `openapi_url=None`，这样也会禁用使用它的文档用户界面。
-
-## 文档 URLs
-
-你可以配置两个文档用户界面，包括：
-
-* **Swagger UI**：服务于 `/docs`。
- * 可以使用参数 `docs_url` 设置它的 URL。
- * 可以通过设置 `docs_url=None` 禁用它。
-* ReDoc：服务于 `/redoc`。
- * 可以使用参数 `redoc_url` 设置它的 URL。
- * 可以通过设置 `redoc_url=None` 禁用它。
-
-例如，设置 Swagger UI 服务于 `/documentation` 并禁用 ReDoc：
-
-```Python hl_lines="3"
-{!../../../docs_src/metadata/tutorial003.py!}
-```
+# 元数据和文档 URL
+
+你可以在 **FastAPI** 应用中自定义几个元数据配置。
+
+## Metadata for API
+
+**Description**：在 OpenAPI 和自动 API 文档用户界面中用作 API 的描述。
+| The license information for the exposed API. It can contain several fields. 
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="19-27"
+ 下图为 Markdown 文本在 API 文档中的显示效果：
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="19-27"
+ 文档字符串（
+
+
+
+
-!!! check
+!!! !!! check
再一次，还是通过相同的 Python 类型声明，**FastAPI** 为你提供了自动生成的交互式文档（集成 Swagger UI）。
注意这里的路径参数被声明为一个整数。
@@ -87,19 +87,19 @@
正因如此，**FastAPI** 内置了一个可选的 API 文档（使用 Redoc）：
-
+
-同样的，还有很多其他兼容的工具，包括适用于多种语言的代码生成工具。
+The same way, there are many compatible tools. 同样的，还有很多其他兼容的工具，包括适用于多种语言的代码生成工具。
## Pydantic
-所有的数据校验都由 
+
### 使用 Python *枚举类型*
-*路径参数*的值将是一个*枚举成员*。
+因为已经指定了*路径参数*的可用值，所以交互式文档可以恰当地展示它们：
#### 比较*枚举成员*
@@ -166,11 +175,11 @@
你可以使用 `model_name.value` 或通常来说 `your_enum_member.value` 来获取实际的值（在这个例子中为 `str`）：
-```Python hl_lines="19"
+```Python hl_lines="20"
{!../../../docs_src/path_params/tutorial005.py!}
```
-!!! tip
+!!! !!! tip
你也可以通过 `ModelName.lenet.value` 来获取值 `"lenet"`。
#### 返回*枚举成员*
@@ -179,10 +188,19 @@
在返回给客户端之前，它们将被转换为对应的值：
-```Python hl_lines="18-21"
+```Python hl_lines="18 21 23"
{!../../../docs_src/path_params/tutorial005.py!}
```
+In your client you will get a JSON response like:
+
+```JSON
+{
+ "model_name": "alexnet",
+ "message": "Deep Learning FTW!"
+}
+```
+
## 包含路径的路径参数
假设你有一个*路径操作*，它的路径为 `/files/{file_path}`。
@@ -193,7 +211,7 @@
### OpenAPI 支持
-OpenAPI 不支持任何方式去声明*路径参数*以在其内部包含*路径*，因为这可能会导致难以测试和定义的情况出现。
+你可以使用直接来自 Starlette 的选项来声明一个包含*路径*的*路径参数*：
不过，你仍然可以通过 Starlette 的一个内部工具在 **FastAPI** 中实现它。
@@ -201,7 +219,7 @@ OpenAPI 不支持任何方式去声明*路径参数*以在其内部包含*路径
### 路径转换器
-你可以使用直接来自 Starlette 的选项来声明一个包含*路径*的*路径参数*：
+OpenAPI 不支持任何方式去声明*路径参数*以在其内部包含*路径*，因为这可能会导致难以测试和定义的情况出现。
```
/files/{file_path:path}
@@ -215,12 +233,12 @@ OpenAPI 不支持任何方式去声明*路径参数*以在其内部包含*路径
{!../../../docs_src/path_params/tutorial004.py!}
```
-!!! tip
+!!! !!! tip
你可能会需要参数包含 `/home/johndoe/myfile.txt`，以斜杠（`/`）开头。
在这种情况下，URL 将会是 `/files//home/johndoe/myfile.txt`，在`files` 和 `home` 之间有一个双斜杠（`//`）。
-## 总结
+## Recap
使用 **FastAPI**，通过简短、直观和标准的 Python 类型声明，你将获得：
diff --git a/docs/zh/docs/tutorial/query-params-str-validations.md b/docs/zh/docs/tutorial/query-params-str-validations.md
index 070074839f634..15ef418f38a1c 100644
--- a/docs/zh/docs/tutorial/query-params-str-validations.md
+++ b/docs/zh/docs/tutorial/query-params-str-validations.md
@@ -4,11 +4,25 @@
让我们以下面的应用程序为例：
-```Python hl_lines="7"
-{!../../../docs_src/query_params_str_validations/tutorial001.py!}
-```
+=== "Python 3.10+"
-查询参数 `q` 的类型为 `str`，默认值为 `None`，因此它是可选的。
+ ```Python hl_lines="7"
+ {!> ../../../docs_src/query_params_str_validations/tutorial001_py310.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="9"
+ {!> ../../../docs_src/query_params_str_validations/tutorial001.py!}
+ ```
+
+!!! note
+ 请记住，在这种情况下 FastAPI 将不会检查列表的内容。
+
+!!! note
+ FastAPI will know that the value of `q` is not required because of the default value `= None`.
+
+ The `Union` in `Union[str, None]` will allow your editor to give you better support and detect errors.
## 额外的校验
@@ -16,19 +30,122 @@
### 导入 `Query`
-为此，首先从 `fastapi` 导入 `Query`：
+To achieve that, first import:
-```Python hl_lines="1"
-{!../../../docs_src/query_params_str_validations/tutorial002.py!}
-```
+* 为此，首先从 `fastapi` 导入 `Query`：
+* `Annotated` from `typing` (or from `typing_extensions` in Python below 3.9)
+
+=== "Python 3.10+"
+
+ In Python 3.9 or above, `Annotated` is part of the standard library, so you can import it from `typing`.
+
+ ```Python hl_lines="1 3"
+ {!../../../docs_src/query_params_str_validations/tutorial002.py!}
+ ```
+
+=== "Python 3.6+"
+
+ In versions of Python below Python 3.9 you import `Annotated` from `typing_extensions`.
+
+ It will already be installed with FastAPI.
+
+ ```Python hl_lines="3-4"
+ {!> ../../../docs_src/query_params_str_validations/tutorial002_an.py!}
+ ```
+
+!!! info
+ FastAPI added support for `Annotated` (and started recommending it) in version 0.95.0.
+
+ If you have an older version, you would get errors when trying to use `Annotated`.
+
+ Make sure you [Upgrade the FastAPI version](../deployment/versions.md#upgrading-the-fastapi-versions){.internal-link target=_blank} to at least 0.95.1 before using `Annotated`.
+
+## !!! tip
+ 要声明类型为 `list` 的查询参数，如上例所示，你需要显式地使用 `Query`，否则该参数将被解释为请求体。
+
+Remember I told you before that `Annotated` can be used to add metadata to your parameters in the [Python Types Intro](../python-types.md#type-hints-with-metadata-annotations){.internal-link target=_blank}?
+
+Now it's the time to use it with FastAPI. 🚀
+
+We had this type annotation:
+
+=== "Python 3.10+"
+
+ ```Python
+ q: str | None = None
+ ```
+
+=== "Python 3.6+"
+
+ ```Python
+ q: Union[str, None] = None
+ ```
+
+What we will do is wrap that with `Annotated`, so it becomes:
+
+=== "Python 3.10+"
+
+ ```Python
+ 总结
+ ```
+
+=== "Python 3.6+"
+
+ ```Python
+ q: Annotated[Union[str, None]] = None
+ ```
+
+查询参数 `q` 的类型为 `str`，默认值为 `None`，因此它是可选的。
+
+Now let's jump to the fun stuff. 🎉
+
+## 但是 `Query` 显式地将其声明为查询参数。
+
+Now that we have this `Annotated` where we can put more metadata, add `Query` to it, and set the parameter `max_length` to 50:
+
+=== "Python 3.10+"
+
+ ```Python hl_lines="9"
+ {!> ../../../docs_src/query_params_str_validations/tutorial002_an_py310.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="10"
+ {!../../../docs_src/query_params_str_validations/tutorial006d.py!}
+ ```
+
+!!! note
+ 具有默认值还会使该参数成为可选参数。
+
+But now, having `Query(max_length=50)` inside of `Annotated`, we are telling FastAPI that we want it to extract this value from the query parameters (this would have been the default anyway 🤷) and that we want to have **additional validation** for this value (that's why we do this, to get the additional validation). 😎
+
+FastAPI will now:
+
+* **Validate** the data making sure that the max length is 50 characters
+* Show a **clear error** for the client when the data is not valid
+* **Document** the parameter in the OpenAPI schema *path operation* (so it will show up in the **automatic docs UI**)
-## 使用 `Query` 作为默认值
+## 你可以向 `Query` 的第一个参数传入 `None` 用作查询参数的默认值，以同样的方式你也可以传递其他默认值。
+
+Previous versions of FastAPI (before 0.95.0) required you to use `Query` as the default value of your parameter, instead of putting it in `Annotated`, there's a high chance that you will see code using it around, so I'll explain it to you.
+
+!!! tip
+ For new code and whenever possible, use `Annotated` as explained above. There are multiple advantages (explained below) and no disadvantages. 🍰
现在，将 `Query` 用作查询参数的默认值，并将它的 `max_length` 参数设置为 50：
-```Python hl_lines="9"
-{!../../../docs_src/query_params_str_validations/tutorial002.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="7"
+ {!> ../../../docs_src/query_params_str_validations/tutorial002_py310.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="9"
+ {!../../../docs_src/query_params_str_validations/tutorial002.py!}
+ ```
由于我们必须用 `Query(default=None)` 替换默认值 `None`，`Query` 的第一个参数同样也是用于定义默认值。
@@ -40,13 +157,44 @@ q: Union[str, None] = Query(default=None)
...使得参数可选，等同于：
+```Python
+q: Union[str, None] = None
+```
+
+And in Python 3.10 and above:
+
+```Python
+q: str | None = Query(default=None)
+```
+
+有另一种方法可以显式的声明一个值是必需的，即将默认参数的默认值设为 `...` ：
+
```Python
q: str = None
```
-但是 `Query` 显式地将其声明为查询参数。
+声明为必需参数
+
+!!! info
+ Have in mind that the most important part to make a parameter optional is the part:
+
+ ```Python
+ = None
+ ```
+
-然后，我们可以将更多的参数传递给 `Query`。在本例中，适用于字符串的 `max_length` 参数：
+ or the:
+
+ ```Python
+ = Query(default=None)
+ ```
+
+
+ as it will use that `None` as the default value, and that way make the parameter **not required**.
+
+ The `Union[str, None]` part allows your editor to provide better support, but it is not what tells FastAPI that this parameter is not required.
+
+然后，我们可以将更多的参数传递给 `Query`。 在本例中，适用于字符串的 `max_length` 参数：
```Python
q: Union[str, None] = Query(default=None, max_length=50)
@@ -54,21 +202,124 @@ q: Union[str, None] = Query(default=None, max_length=50)
将会校验数据，在数据无效时展示清晰的错误信息，并在 OpenAPI 模式的*路径操作*中记录该参数。
+### 使用 `Query` 作为默认值
+
+!!! tip
+ 请记住，在大多数情况下，当你需要某些东西时，可以简单地省略 `default` 参数，因此你通常不必使用 `...` 或 `Required`
+
+Instead use the actual default value of the function parameter. Otherwise, it would be inconsistent.
+
+For example, this is not allowed:
+
+```Python
+q: Annotated[str, Query(default="rick")] = "morty"
+```
+
+...because it's not clear if the default value should be `"rick"` or `"morty"`.
+
+So, you would use (preferably):
+
+```Python
+q: Annotated[str, Query()] = "rick"
+```
+
+...or in older code bases you will find:
+
+```Python
+q: str = Query(default="rick")
+```
+
+### Advantages of `Annotated`
+
+**Using `Annotated` is recommended** instead of the default value in function parameters, it is **better** for multiple reasons. 🤓
+
+The **default** value of the **function parameter** is the **actual default** value, that's more intuitive with Python in general. 😌
+
+You could **call** that same function in **other places** without FastAPI, and it would **work as expected**. If there's a **required** parameter (without a default value), your **editor** will let you know with an error, **Python** will also complain if you run it without passing the required parameter.
+
+When you don't use `Annotated` and instead use the **(old) default value style**, if you call that function without FastAPI in **other place**, you have to **remember** to pass the arguments to the function for it to work correctly, otherwise the values will be different from what you expect (e.g. `QueryInfo` or something similar instead of `str`). And your editor won't complain, and Python won't complain running that function, only when the operations inside error out.
+
+Because `Annotated` can have more than one metadata annotation, you could now even use the same function with other tools, like 
+
### 具有默认值的查询参数列表 / 多个值
你还可以定义在没有任何给定值时的默认 `list` 值：
-```Python hl_lines="9"
-{!../../../docs_src/query_params_str_validations/tutorial012.py!}
-```
+=== "Python 3.9+"
+
+ ```Python hl_lines="9"
+ {!> ../../../docs_src/query_params_str_validations/tutorial012_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="10"
+ {!> ../../../docs_src/query_params_str_validations/tutorial012_an.py!}
+ ```
+
+=== "Python 3.9+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="7"
+ {!> ../../../docs_src/query_params_str_validations/tutorial012_py39.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="9"
+ {!../../../docs_src/query_params_str_validations/tutorial012.py!}
+ ```
如果你访问：
@@ -223,14 +673,31 @@ http://localhost:8000/items/
你也可以直接使用 `list` 代替 `List [str]`：
-```Python hl_lines="7"
-{!../../../docs_src/query_params_str_validations/tutorial013.py!}
-```
+=== "Python 3.9+"
+
+ ```Python hl_lines="9"
+ {!> ../../../docs_src/query_params_str_validations/tutorial013_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="8"
+ {!> ../../../docs_src/query_params_str_validations/tutorial013_an.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="7"
+ {!> ../../../docs_src/query_params_str_validations/tutorial013.py!}
+ ```
!!! note
- 请记住，在这种情况下 FastAPI 将不会检查列表的内容。
+ Have in mind that in this case, FastAPI won't check the contents of the list.
- 例如，`List[int]` 将检查（并记录到文档）列表的内容必须是整数。但是单独的 `list` 不会。
+ 例如，`List[int]` 将检查（并记录到文档）列表的内容必须是整数。 但是单独的 `list` 不会。
## 声明更多元数据
@@ -239,21 +706,85 @@ http://localhost:8000/items/
这些信息将包含在生成的 OpenAPI 模式中，并由文档用户界面和外部工具所使用。
!!! note
- 请记住，不同的工具对 OpenAPI 的支持程度可能不同。
+ Have in mind that different tools might have different levels of OpenAPI support.
其中一些可能不会展示所有已声明的额外信息，尽管在大多数情况下，缺少的这部分功能已经计划进行开发。
你可以添加 `title`：
-```Python hl_lines="10"
-{!../../../docs_src/query_params_str_validations/tutorial007.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="10"
+ {!> ../../../docs_src/query_params_str_validations/tutorial007_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="10"
+ {!> ../../../docs_src/query_params_str_validations/tutorial007_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="11"
+ {!../../../docs_src/query_params_str_validations/tutorial007.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="8"
+ {!> ../../../docs_src/query_params_str_validations/tutorial007_py310.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="10"
+ {!> ../../../docs_src/query_params_str_validations/tutorial007.py!}
+ ```
以及 `description`：
-```Python hl_lines="13"
-{!../../../docs_src/query_params_str_validations/tutorial008.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="14"
+ {!> ../../../docs_src/query_params_str_validations/tutorial008_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="14"
+ {!> ../../../docs_src/query_params_str_validations/tutorial008_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="15"
+ {!> ../../../docs_src/query_params_str_validations/tutorial008_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="12"
+ {!> ../../../docs_src/query_params_str_validations/tutorial008_py310.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="13"
+ {!../../../docs_src/query_params_str_validations/tutorial001.py!}
+ ```
## 别名参数
@@ -273,9 +804,41 @@ http://127.0.0.1:8000/items/?item-query=foobaritems
这时你可以用 `alias` 参数声明一个别名，该别名将用于在 URL 中查找查询参数值：
-```Python hl_lines="9"
-{!../../../docs_src/query_params_str_validations/tutorial009.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="9"
+ {!> ../../../docs_src/query_params_str_validations/tutorial009_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="9"
+ {!> ../../../docs_src/query_params_str_validations/tutorial009_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="10"
+ {!> ../../../docs_src/query_params_str_validations/tutorial009_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="7"
+ {!> ../../../docs_src/query_params_str_validations/tutorial009_py310.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="9"
+ {!../../../docs_src/query_params_str_validations/tutorial009.py!}
+ ```
## 弃用参数
@@ -285,15 +848,87 @@ http://127.0.0.1:8000/items/?item-query=foobaritems
那么将参数 `deprecated=True` 传入 `Query`：
-```Python hl_lines="18"
-{!../../../docs_src/query_params_str_validations/tutorial010.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="19"
+ {!> ../../../docs_src/query_params_str_validations/tutorial010_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="19"
+ {!> ../../../docs_src/query_params_str_validations/tutorial010_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="20"
+ {!> ../../../docs_src/query_params_str_validations/tutorial010_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="17"
+ {!> ../../../docs_src/query_params_str_validations/tutorial010_py310.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="18"
+ {!../../../docs_src/query_params_str_validations/tutorial010.py!}
+ ```
文档将会像下面这样展示它：
-
+
+
+## Exclude from OpenAPI
+
+To exclude a query parameter from the generated OpenAPI schema (and thus, from the automatic documentation systems), set the parameter `include_in_schema` of `Query` to `False`:
+
+=== "Python 3.10+"
+
+ ```Python hl_lines="10"
+ {!> ../../../docs_src/query_params_str_validations/tutorial014_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="10"
+ {!> ../../../docs_src/query_params_str_validations/tutorial014_an_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="11"
+ {!> ../../../docs_src/query_params_str_validations/tutorial014_an.py!}
+ ```
+
+=== "Python 3.10+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="8"
+ {!> ../../../docs_src/query_params_str_validations/tutorial014_py310.py!}
+ ```
+
+=== "Python 3.6+ non-Annotated"
+
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
+
+ ```Python hl_lines="10"
+ {!> ../../../docs_src/query_params_str_validations/tutorial014.py!}
+ ```
-## 总结
+## Recap
你可以为查询参数声明额外的校验和元数据。
diff --git a/docs/zh/docs/tutorial/query-params.md b/docs/zh/docs/tutorial/query-params.md
index b1668a2d2523f..dead131d45f8e 100644
--- a/docs/zh/docs/tutorial/query-params.md
+++ b/docs/zh/docs/tutorial/query-params.md
@@ -6,7 +6,7 @@
{!../../../docs_src/query_params/tutorial001.py!}
```
-查询字符串是键值对的集合，这些键值对位于 URL 的 `？` 之后，并以 `&` 符号分隔。
+查询字符串是键值对的集合，这些键值对位于 URL 的 `？ ` 之后，并以 `&` 符号分隔。
例如，在以下 url 中：
@@ -42,7 +42,7 @@ http://127.0.0.1:8000/items/?skip=0&limit=10
http://127.0.0.1:8000/items/
```
-将与访问以下地址相同：
+would be the same as going to:
```
http://127.0.0.1:8000/items/?skip=0&limit=10
@@ -63,22 +63,41 @@ http://127.0.0.1:8000/items/?skip=20
通过同样的方式，你可以将它们的默认值设置为 `None` 来声明可选查询参数：
-```Python hl_lines="7"
-{!../../../docs_src/query_params/tutorial002.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="7"
+ 将与访问以下地址相同：
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="9"
+ {!../../../docs_src/query_params/tutorial002.py!}
+ ```
在这个例子中，函数参数 `q` 将是可选的，并且默认值为 `None`。
!!! check
- 还要注意的是，**FastAPI** 足够聪明，能够分辨出参数 `item_id` 是路径参数而 `q` 不是，因此 `q` 是一个查询参数。
+ Also notice that **FastAPI** is smart enough to notice that the path parameter `item_id` is a path parameter and `q` is not, so, it's a query parameter.
## 查询参数类型转换
你还可以声明 `bool` 类型，它们将被自动转换：
-```Python hl_lines="7"
-{!../../../docs_src/query_params/tutorial003.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="7"
+ {!../../../docs_src/query_params/tutorial003.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="9"
+ !!! check
+ 还要注意的是，FastAPI 足够聪明，能够分辨出参数 
+
并且两种模型都将在交互式 API 文档中使用：
-
+
+
+## Other Return Type Annotations
+
+There might be cases where you return something that is not a valid Pydantic field and you annotate it in the function, only to get the support provided by tooling (the editor, mypy, etc).
+
+### Return a Response Directly
+
+The most common case would be [returning a Response directly as explained later in the advanced docs](../advanced/response-directly.md){.internal-link target=_blank}.
+
+```Python hl_lines="8 10-11"
+{!../../../docs_src/response_model/tutorial002.py!}
+```
+
+This simple case is handled automatically by FastAPI because the return type annotation is the class (or a subclass) of `Response`.
+
+And tools will also be happy because both `RedirectResponse` and `JSONResponse` are subclasses of `Response`, so the type annotation is correct.
+
+### Annotate a Response Subclass
+
+You can also use a subclass of `Response` in the type annotation:
+
+```Python hl_lines="8-9"
+{!../../../docs_src/response_model/tutorial003.py!}
+```
+
+This will also work because `RedirectResponse` is a subclass of `Response`, and FastAPI will automatically handle this simple case.
+
+### Invalid Return Type Annotations
+
+But when you return some other arbitrary object that is not a valid Pydantic type (e.g. a database object) and you annotate it like that in the function, FastAPI will try to create a Pydantic response model from that type annotation, and will fail.
+
+The same would happen if you had something like a union between different types where one or more of them are not valid Pydantic types, for example this would fail 💥:
+
+=== "Python 3.10+"
+
+ ```Python hl_lines="8"
+ {!> ../../../docs_src/response_model/tutorial003_04_py310.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="10"
+ {!> ../../../docs_src/response_model/tutorial003_04.py!}
+ ```
+
+...this fails because the type annotation is not a Pydantic type and is not just a single `Response` class or subclass, it's a union (any of the two) between a `Response` and a `dict`.
+
+### Disable Response Model
+
+Continuing from the example above, you might not want to have the default data validation, documentation, filtering, etc. that is performed by FastAPI.
+
+But you might want to still keep the return type annotation in the function to get the support from tools like editors and type checkers (e.g. mypy).
+
+!!! tip
+ 请注意默认值可以是任何值，而不仅是`None`。
+
+=== "Python 3.10+"
+
+ ```Python hl_lines="7"
+ {!> ../../../docs_src/response_model/tutorial003_05_py310.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="9"
+ {!> ../../../docs_src/response_model/tutorial003_05.py!}
+ ```
+
+This will make FastAPI skip the response model generation and that way you can have any return type annotations you need without it affecting your FastAPI application. 🤓
## 响应模型编码参数
你的响应模型可以具有默认值，例如：
-```Python hl_lines="11 13-14"
-{!../../../docs_src/response_model/tutorial004.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="9 11-12"
+ {!> ../../../docs_src/response_model/tutorial004_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="11 13-14"
+ {!> ../../../docs_src/response_model/tutorial004_py39.py!}
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="11 13-14"
+ {!../../../docs_src/response_model/tutorial004.py!}
+ ```
* `description: Union[str, None] = None` 具有默认值 `None`。
* `tax: float = 10.5` 具有默认值 `10.5`.
@@ -102,13 +350,28 @@ FastAPI 将使用此 `response_model` 来：
举个例子，当你在 NoSQL 数据库中保存了具有许多可选属性的模型，但你又不想发送充满默认值的很长的 JSON 响应。
-### 使用 `response_model_exclude_unset` 参数
+### !!! info
+ FastAPI 通过 Pydantic 模型的 `.dict()` 配合 
+
-!!! note
+!!! !!! note
一些响应状态码（请参阅下一部分）表示响应没有响应体。
FastAPI 知道这一点，并将生成表明没有响应体的 OpenAPI 文档。
## 关于 HTTP 状态码
-!!! note
+!!! !!! note
如果你已经了解什么是 HTTP 状态码，请跳到下一部分。
在 HTTP 协议中，你将发送 3 位数的数字状态码作为响应的一部分。
@@ -43,18 +43,18 @@
简而言之：
-* `100` 及以上状态码用于「消息」响应。你很少直接使用它们。具有这些状态代码的响应不能带有响应体。
-* **`200`** 及以上状态码用于「成功」响应。这些是你最常使用的。
+* `100` 及以上状态码用于「消息」响应。 你很少直接使用它们。 具有这些状态代码的响应不能带有响应体。
+* **`200`** 及以上状态码用于「成功」响应。 这些是你最常使用的。
* `200` 是默认状态代码，它表示一切「正常」。
- * 另一个例子会是 `201`，「已创建」。它通常在数据库中创建了一条新记录后使用。
- * 一个特殊的例子是 `204`，「无内容」。此响应在没有内容返回给客户端时使用，因此该响应不能包含响应体。
-* **`300`** 及以上状态码用于「重定向」。具有这些状态码的响应可能有或者可能没有响应体，但 `304`「未修改」是个例外，该响应不得含有响应体。
-* **`400`** 及以上状态码用于「客户端错误」响应。这些可能是你第二常使用的类型。
+ * 另一个例子会是 `201`，「已创建」。 它通常在数据库中创建了一条新记录后使用。
+ * 一个特殊的例子是 `204`，「无内容」。 此响应在没有内容返回给客户端时使用，因此该响应不能包含响应体。
+* **`300`** 及以上状态码用于「重定向」。 具有这些状态码的响应可能有或者可能没有响应体，但 `304`「未修改」是个例外，该响应不得含有响应体。
+* **`400`** 及以上状态码用于「客户端错误」响应。 这些可能是你第二常使用的类型。
* 一个例子是 `404`，用于「未找到」响应。
* 对于来自客户端的一般错误，你可以只使用 `400`。
-* `500` 及以上状态码用于服务器端错误。你几乎永远不会直接使用它们。当你的应用程序代码或服务器中的某些部分出现问题时，它将自动返回这些状态代码之一。
+* `500` 及以上状态码用于服务器端错误。 你几乎永远不会直接使用它们。 当你的应用程序代码或服务器中的某些部分出现问题时，它将自动返回这些状态代码之一。
-!!! tip
+!!! !!! tip
要了解有关每个状态代码以及适用场景的更多信息，请查看 
+
-!!! note "技术细节"
+!!! !!! note "技术细节"
你也可以使用 `from starlette import status`。
- 为了给你（即开发者）提供方便，**FastAPI** 提供了与 `starlette.status` 完全相同的 `fastapi.status`。但它直接来自于 Starlette。
+ 为了给你（即开发者）提供方便，**FastAPI** 提供了与 `starlette.status` 完全相同的 `fastapi.status`。 但它直接来自于 Starlette。
## 更改默认状态码
diff --git a/docs/zh/docs/tutorial/schema-extra-example.md b/docs/zh/docs/tutorial/schema-extra-example.md
index 8f5fbfe70bbb5..14abdac8624b7 100644
--- a/docs/zh/docs/tutorial/schema-extra-example.md
+++ b/docs/zh/docs/tutorial/schema-extra-example.md
@@ -1,58 +1,262 @@
-# 模式的额外信息 - 例子
+# Declare Request Example Data
-您可以在JSON模式中定义额外的信息。
+You can declare examples of the data your app can receive.
-一个常见的用例是添加一个将在文档中显示的`example`。
+Here are several ways to do it.
-有几种方法可以声明额外的 JSON 模式信息。
+## Extra JSON Schema data in Pydantic models
-## Pydantic `schema_extra`
+You can declare `examples` for a Pydantic model that will be added to the generated JSON Schema.
-您可以使用 `Config` 和 `schema_extra` 为Pydantic模型声明一个示例，如
+
## 技术细节
-关于 `example` 和 `examples`...
+!!! tip
+ If you are already using **FastAPI** version **0.99.0 or above**, you can probably **skip** these details.
+
+ They are more relevant for older versions, before OpenAPI 3.1.0 was available.
+
+ You can consider this a brief OpenAPI and JSON Schema **history lesson**. 🤓
+
+!!! warning
+ These are very technical details about the standards **JSON Schema** and **OpenAPI**.
+
+ If the ideas above already work for you, that might be enough, and you probably don't need these details, feel free to skip them.
+
+Before OpenAPI 3.1.0, OpenAPI used an older and modified version of **JSON Schema**.
+
+在 `Field`, `Path`, `Query`, `Body` 和其他你之后将会看到的工厂函数，你可以为JSON 模式声明额外信息，你也可以通过给工厂函数传递其他的任意参数来给JSON 模式声明额外信息，比如增加 `example`:
+
+OpenAPI also added `example` and `examples` fields to other parts of the specification:
+
+* 所以 OpenAPI为了相似的目的定义了自己的 
-
-!!! check "Authorize 按钮！"
-
- 页面右上角出现了一个「**Authorize**」按钮。
-
- *路径操作*的右上角也出现了一个可以点击的小锁图标。
-
-点击 **Authorize** 按钮，弹出授权表单，输入 `username` 与 `password` 及其它可选字段：
-
-
-
-!!! note "笔记"
-
- 目前，在表单中输入内容不会有任何反应，后文会介绍相关内容。
-
-虽然此文档不是给前端最终用户使用的，但这个自动工具非常实用，可在文档中与所有 API 交互。
-
-前端团队（可能就是开发者本人）可以使用本工具。
+=== "Python 3.9+"
-第三方应用与系统也可以调用本工具。
+ ```Python
+ !!! tip "提示"
+ ```
-开发者也可以用它来调试、检查、测试应用。
+=== "Python 3.6+"
-## 密码流
+ ```Python
+ 令牌只是用于验证用户的字符串
+ ```
-现在，我们回过头来介绍这段代码的原理。
+=== "Python 3.6+ non-Annotated"
-`Password` **流**是 OAuth2 定义的，用于处理安全与身份验证的方式（**流**）。
+ !!! tip
+ Prefer to use the `Annotated` version if possible.
-OAuth2 的设计目标是为了让后端或 API 独立于服务器验证用户身份。
+ ```Python
+ {!../../../docs_src/security/tutorial001.py!}
+ ```
-但在本例中，**FastAPI** 应用会处理 API 与身份验证。
-下面，我们来看一下简化的运行流程：
-
-- 用户在前端输入 `username` 与`password`，并点击**回车**
-- （用户浏览器中运行的）前端把 `username` 与`password` 发送至 API 中指定的 URL（使用 `tokenUrl="token"` 声明）
-- API 检查 `username` 与`password`，并用令牌（`Token`） 响应（暂未实现此功能）：
- - 令牌只是用于验证用户的字符串
- - 一般来说，令牌会在一段时间后过期
- - 过时后，用户要再次登录
- - 这样一来，就算令牌被人窃取，风险也较低。因为它与永久密钥不同，**在绝大多数情况下**不会长期有效
-- 前端临时将令牌存储在某个位置
-- 用户点击前端，前往前端应用的其它部件
-- 前端需要从 API 中提取更多数据：
- - 为指定的端点（Endpoint）进行身份验证
- - 因此，用 API 验证身份时，要发送值为 `Bearer` + 令牌的请求头 `Authorization`
- - 假如令牌为 `foobar`，`Authorization` 请求头就是： `Bearer foobar`
-
-## **FastAPI** 的 `OAuth2PasswordBearer`
-
-**FastAPI** 提供了不同抽象级别的安全工具。
-
-本例使用 **OAuth2** 的 **Password** 流以及 **Bearer** 令牌（`Token`）。为此要使用 `OAuth2PasswordBearer` 类。
-
-!!! info "说明"
-
- `Bearer` 令牌不是唯一的选择。
-
- 但它是最适合这个用例的方案。
-
- 甚至可以说，它是适用于绝大多数用例的最佳方案，除非您是 OAuth2 的专家，知道为什么其它方案更合适。
-
- 本例中，**FastAPI** 还提供了构建工具。
-
-创建 `OAuth2PasswordBearer` 的类实例时，要传递 `tokenUrl` 参数。该参数包含客户端（用户浏览器中运行的前端） 的 URL，用于发送 `username` 与 `password`，并获取令牌。
-
-```Python hl_lines="6"
-{!../../../docs_src/security/tutorial001.py!}
-```
-
-!!! tip "提示"
-
- 在此，`tokenUrl="token"` 指向的是暂未创建的相对 URL `token`。这个相对 URL 相当于 `./token`。
-
- 因为使用的是相对 URL，如果 API 位于 `https://example.com/`，则指向 `https://example.com/token`。但如果 API 位于 `https://example.com/api/v1/`，它指向的就是`https://example.com/api/v1/token`。
-
- 使用相对 URL 非常重要，可以确保应用在遇到[使用代理](../../advanced/behind-a-proxy.md){.internal-link target=_blank}这样的高级用例时，也能正常运行。
-
-该参数不会创建端点或*路径操作*，但会声明客户端用来获取令牌的 URL `/token` 。此信息用于 OpenAPI 及 API 文档。
-
-接下来，学习如何创建实际的路径操作。
-
-!!! info "说明"
-
- 严苛的 **Pythonista** 可能不喜欢用 `tokenUrl` 这种命名风格代替 `token_url`。
-
- 这种命名方式是因为要使用与 OpenAPI 规范中相同的名字。以便在深入校验安全方案时，能通过复制粘贴查找更多相关信息。
+## 运行
-`oauth2_scheme` 变量是 `OAuth2PasswordBearer` 的实例，也是**可调用项**。
+!!! 打开 API 文档： 
+
+
用与上一章同样的方式实现应用授权。
@@ -210,11 +333,10 @@ JWT 规范还包括 `sub` 键，值是令牌的主题。
用户名: `johndoe` 密码: `secret`
-!!! check "检查"
+!!! check
+ Notice that nowhere in the code is the plaintext password "`secret`", we only have the hashed version.
- 注意，代码中没有明文密码**`secret`**，只保存了它的哈希值。
-
-
+
调用 `/users/me/` 端点，收到下面的响应：
@@ -227,44 +349,43 @@ JWT 规范还包括 `sub` 键，值是令牌的主题。
}
```
-
+
打开浏览器的开发者工具，查看数据是怎么发送的，而且数据里只包含了令牌，只有验证用户的第一个请求才发送密码，并获取访问令牌，但之后不会再发送密码：
-
-
-!!! note "笔记"
+
- 注意，请求中 `Authorization` 响应头的值以 `Bearer` 开头。
+!!! note
+ Notice the header `Authorization`, with a value that starts with `Bearer`.
## `scopes` 高级用法
-OAuth2 支持**`scopes`**（作用域）。
+OAuth2 has the notion of "scopes".
-**`scopes`**为 JWT 令牌添加指定权限。
+You can use them to add a specific set of permissions to a JWT token.
让持有令牌的用户或第三方在指定限制条件下与 API 交互。
**高级用户指南**中将介绍如何使用 `scopes`，及如何把 `scopes` 集成至 **FastAPI**。
-## 小结
+## Recap
至此，您可以使用 OAuth2 和 JWT 等标准配置安全的 **FastAPI** 应用。
几乎在所有框架中，处理安全问题很快都会变得非常复杂。
-有些包为了简化安全流，不得不在数据模型、数据库和功能上做出妥协。而有些过于简化的软件包其实存在了安全隐患。
+有些包为了简化安全流，不得不在数据模型、数据库和功能上做出妥协。 而有些过于简化的软件包其实存在了安全隐患。
---
**FastAPI** 不向任何数据库、数据模型或工具做妥协。
-开发者可以灵活选择最适合项目的安全机制。
+It gives you all the flexibility to choose the ones that fit your project the best.
还可以直接使用 `passlib` 和 `python-jose` 等维护良好、使用广泛的包，这是因为 **FastAPI** 不需要任何复杂机制，就能集成外部的包。
-而且，**FastAPI** 还提供了一些工具，在不影响灵活、稳定和安全的前提下，尽可能地简化安全机制。
+But it provides you the tools to simplify the process as much as possible without compromising flexibility, robustness, or security.
-**FastAPI** 还支持以相对简单的方式，使用 OAuth2 等安全、标准的协议。
+And you can use and implement secure, standard protocols, like OAuth2 in a relatively simple way.
-**高级用户指南**中详细介绍了 OAuth2**`scopes`**的内容，遵循同样的标准，实现更精密的权限系统。OAuth2 的作用域是脸书、谷歌、GitHub、微软、推特等第三方身份验证应用使用的机制，让用户授权第三方应用与 API 交互。
+**高级用户指南**中详细介绍了 OAuth2**`scopes`**的内容，遵循同样的标准，实现更精密的权限系统。 OAuth2 的作用域是脸书、谷歌、GitHub、微软、推特等第三方身份验证应用使用的机制，让用户授权第三方应用与 API 交互。
diff --git a/docs/zh/docs/tutorial/security/simple-oauth2.md b/docs/zh/docs/tutorial/security/simple-oauth2.md
index 276f3d63b69f9..7b782c9e1bd33 100644
--- a/docs/zh/docs/tutorial/security/simple-oauth2.md
+++ b/docs/zh/docs/tutorial/security/simple-oauth2.md
@@ -8,7 +8,7 @@
OAuth2 规定在使用（我们打算用的）「password 流程」时，客户端/用户必须将 `username` 和 `password` 字段作为表单数据发送。
-而且规范明确了字段必须这样命名。因此 `user-name` 或 `email` 是行不通的。
+而且规范明确了字段必须这样命名。 因此 `user-name` 或 `email` 是行不通的。
不过不用担心，你可以在前端按照你的想法将它展示给最终用户。
@@ -24,7 +24,7 @@ OAuth2 规定在使用（我们打算用的）「password 流程」时，客户
这个表单字段的名称为 `scope`（单数形式），但实际上它是一个由空格分隔的「作用域」组成的长字符串。
-每个「作用域」只是一个字符串（中间没有空格）。
+Each "scope" is just a string (without spaces).
它们通常用于声明特定的安全权限，例如：
@@ -33,12 +33,12 @@ OAuth2 规定在使用（我们打算用的）「password 流程」时，客户
* Google 使用了 `https://www.googleapis.com/auth/drive` 。
!!! info
- 在 OAuth2 中「作用域」只是一个声明所需特定权限的字符串。
+ In OAuth2 a "scope" is just a string that declares a specific permission required.
它有没有 `:` 这样的其他字符或者是不是 URL 都没有关系。
-
+
这些细节是具体的实现。
-
+
对 OAuth2 来说它们就只是字符串而已。
## 获取 `username` 和 `password` 的代码
@@ -49,9 +49,45 @@ OAuth2 规定在使用（我们打算用的）「password 流程」时，客户
首先，导入 `OAuth2PasswordRequestForm`，然后在 `token` 的*路径操作*中通过 `Depends` 将其作为依赖项使用。
-```Python hl_lines="4 76"
-{!../../../docs_src/security/tutorial003.py!}
-```
+=== "Python 3.10+"
+
+ ```Python hl_lines="4 78"
+ {!> ../../../docs_src/security/tutorial003_an_py310.py!}
+ ```
+
+=== "Python 3.9+"
+
+ ```Python hl_lines="4 78"
+ !!! tip
+ 在下一章中，你将看到一个真实的安全实现，使用了哈希密码和 JWT 令牌。
+ ```
+
+=== "Python 3.6+"
+
+ ```Python hl_lines="4 79"
+ !!! info
+ 
+
在系统中进行身份认证后，你将看到：
-
+
### 获取本人的用户数据
@@ -236,7 +416,7 @@ UserInDB(
}
```
-
+
如果你点击锁定图标并注销，然后再次尝试同一操作，则会得到 HTTP 401 错误：
@@ -264,7 +444,7 @@ UserInDB(
}
```
-## 总结
+## Recap
现在你掌握了为你的 API 实现一个基于 `username` 和 `password` 的完整安全系统的工具。
diff --git a/docs/zh/docs/tutorial/sql-databases.md b/docs/zh/docs/tutorial/sql-databases.md
index 482588f94d7ec..53de41a7bd3c2 100644
--- a/docs/zh/docs/tutorial/sql-databases.md
+++ b/docs/zh/docs/tutorial/sql-databases.md
@@ -1,5 +1,12 @@
# SQL (关系型) 数据库
+!!! info
+ These docs are about to be updated. 🎉
+
+ The current version assumes Pydantic v1, and SQLAlchemy versions less than 2.0.
+
+ The new docs will include Pydantic v2 and will use 
-
-## 直接与数据库交互
-
-如果您想独立于 FastAPI 直接浏览 SQLite 数据库（文件）以调试其内容、添加表、列、记录、修改数据等，您可以使用[SQLite 的 DB Browser](https://sqlitebrowser.org/)
-
-它看起来像这样：
-
-
-
-您还可以使用[SQLite Viewer](https://inloop.github.io/sqlite-viewer/)或[ExtendsClass](https://extendsclass.com/sqlite-browser.html)等在线 SQLite 浏览器。
-
-## 中间件替代数据库会话
-
-如果你不能使用依赖项`yield`——例如，如果你没有使用**Python 3.7**并且不能安装上面提到的**Python 3.6**的“backports” ——你可以在类似的“中间件”中设置会话方法。
-
-“中间件”基本功能是一个为每个请求执行的函数在请求之前进行执行相应的代码，以及在请求执行之后执行相应的代码。
-
-### 创建中间件
-
-我们将添加中间件（只是一个函数）将为每个请求创建一个新的 SQLAlchemy`SessionLocal`，将其添加到请求中，然后在请求完成后关闭它。
-
-=== "Python 3.9+"
-
- ```Python hl_lines="12-20"
- {!> ../../../docs_src/sql_databases/sql_app_py39/alt_main.py!}
- ```
-
-=== "Python 3.6+"
-
- ```Python hl_lines="14-22"
- {!> ../../../docs_src/sql_databases/sql_app/alt_main.py!}
- ```
-
-!!! info
- 我们将`SessionLocal()`请求的创建和处理放在一个`try`块中。
-
- 然后我们在finally块中关闭它。
-
- 通过这种方式，我们确保数据库会话在请求后始终关闭，即使在处理请求时出现异常也会关闭。
-
-### 关于`request.state`
-
-`request.state`是每个`Request`对象的属性。它用于存储附加到请求本身的任意对象，例如本例中的数据库会话。您可以在[Starlette 的关于`Request`state](https://www.starlette.io/requests/#other-state)的文档中了解更多信息。
-
-对于这种情况下，它帮助我们确保在所有请求中使用单个数据库会话，然后关闭（在中间件中）。
-
-### 使用`yield`依赖项与使用中间件的区别
-
-在此处添加**中间件**与`yield`的依赖项的作用效果类似，但也有一些区别：
-
-* 中间件需要更多的代码并且更复杂一些。
-* 中间件必须是一个`async`函数。
- * 如果其中有代码必须“等待”网络，它可能会在那里“阻止”您的应用程序并稍微降低性能。
- * 尽管这里的`SQLAlchemy`工作方式可能不是很成问题。
- * 但是，如果您向等待大量I/O的中间件添加更多代码，则可能会出现问题。
-* *每个*请求都会运行一个中间件。
- * 将为每个请求创建一个连接。
- * 即使处理该请求的*路径操作*不需要数据库。
-
-!!! tip
- `tyield`当依赖项 足以满足用例时，使用`tyield`依赖项方法会更好。
-
-!!! info
- `yield`的依赖项是最近刚加入**FastAPI**中的。
-
- 所以本教程的先前版本只有带有中间件的示例，并且可能有多个应用程序使用中间件进行数据库会话管理。
+打开浏览器进入