呆鳥云：發(fā)布本系列旨在推廣 FastAPI 以及推進(jìn) FastAPI 中文官檔翻譯撑帖，目前，F(xiàn)astAPI 官檔已完成 98% 的中文翻譯弓叛，如果您對(duì) FastAPI 有興趣璃弄，可以為這個(gè)很贊的開源項(xiàng)目做些貢獻(xiàn)，比如校譯牧抽、翻譯嘉熊、審閱等。

開源項(xiàng)目的發(fā)展離不開大家的支持扬舒。當(dāng)然最簡(jiǎn)單的就是在 Github 上點(diǎn) Star 了阐肤。

如果覺得 FastAPI 不錯(cuò)，您也可以轉(zhuǎn)發(fā)讲坎、轉(zhuǎn)載本文孕惜，讓更多人知道 Python 還有這么簡(jiǎn)單、快速的后端支持庫(kù)晨炕。

FastAPI 官檔地址：https://fastapi.tiangolo.com/zh/

下面先列出幾個(gè)需要 Review 的 PR衫画，希望大家多多參與。

• https://github.com/tiangolo/fastapi/pull/3826
• https://github.com/tiangolo/fastapi/pull/3827
• https://github.com/tiangolo/fastapi/pull/3828
• https://github.com/tiangolo/fastapi/pull/3829
• https://github.com/tiangolo/fastapi/pull/3830
• https://github.com/tiangolo/fastapi/pull/3832
• https://github.com/tiangolo/fastapi/pull/3793
• https://github.com/tiangolo/fastapi/pull/3795
• https://github.com/tiangolo/fastapi/pull/3796

以下為正文瓮栗。

本指南將逐步介紹 FastAPI 的絕大部分功能碧磅。

本指南的每個(gè)章節(jié)循序漸進(jìn)碘箍，但又有各自的主題，您可以直接閱讀所需章節(jié)鲸郊，解決特定的 API 需求丰榴。

本指南還是參考手冊(cè)，供您隨時(shí)查閱秆撮。

運(yùn)行代碼

本指南中的所有代碼都能直接復(fù)制使用（實(shí)際上四濒，這些代碼都是經(jīng)過測(cè)試的 Python 文件）。

要運(yùn)行示例职辨，只需把代碼復(fù)制到 main.py盗蟆，用以下命令啟動(dòng) uvicorn：

$ uvicorn main:app --reload

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [28720]
INFO:     Started server process [28722]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

強(qiáng)烈建議您在本機(jī)編輯并運(yùn)行這些代碼。

只在有編輯器中輸入代碼時(shí)舒裤，您才能真正感受到 FastAPI 的優(yōu)勢(shì)喳资，體驗(yàn)到需要輸入的代碼到底有多少，還有類型檢查腾供、自動(dòng)補(bǔ)全等功能仆邓。

安裝 FastAPI

第一步是安裝 FastAPI。

學(xué)習(xí)本教程伴鳖，需要安裝所有可選依賴支持庫(kù)：

$ pip install fastapi[all]

......上述命令還安裝了運(yùn)行 FastAPI 應(yīng)用的服務(wù)器 - uvicorn节值。

!!! note "筆記"

您可以單獨(dú)安裝各個(gè)支持庫(kù)。

需要把應(yīng)用部署到生產(chǎn)環(huán)境時(shí)榜聂，首先要安裝 FastAPI：

```
pip install fastapi
```

然后搞疗，還要安裝服務(wù)器 `uvicorn`：

```
pip install uvicorn[standard]
```

按需單獨(dú)安裝其它可選依賴支持庫(kù)。

高級(jí)用戶指南

學(xué)完用戶指南后须肆，您還可以繼續(xù)學(xué)習(xí)高級(jí)用戶指南匿乃。

高級(jí)用戶指南基于本指南，核心概念都一樣豌汇，但介紹了更多功能扳埂。

建議您先閱讀用戶指南。

學(xué)完用戶指南就能開發(fā)完整的 FastAPI 應(yīng)用瘤礁。然后，再使用高級(jí)用戶指南中的功能擴(kuò)展應(yīng)用梅尤。

第一步

最簡(jiǎn)單的 FastAPI 文件所示如下：

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
async def root():
    return {"message": "Hello World"}

復(fù)制代碼到 main.py柜思。

運(yùn)行實(shí)時(shí)服務(wù)器：

$ uvicorn main:app --reload

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [28720]
INFO:     Started server process [28722]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

!!! note "筆記"

`uvicorn main:app` 命令說明如下：

* `main`：`main.py` 是 Python **模塊**；
* `app`：`main.py`  中 `app = FastAPI()` 創(chuàng)建的對(duì)象巷燥；
* `--reload`：代碼更新后赡盘，重啟服務(wù)器。僅在開發(fā)時(shí)使用缰揪。

輸出信息如下：

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

這是 FastAPI 應(yīng)用在本機(jī)提供服務(wù)的 URL陨享。

查看文檔

打開瀏覽器訪問 http://127.0.0.1:8000葱淳。

JSON 響應(yīng)如下：

{"message": "Hello World"}

API 文檔

跳轉(zhuǎn)到 http://127.0.0.1:8000/docs。

查看自動(dòng)生成的（Swagger UI）API 文檔：

Swagger UI

備選 API 文檔

跳轉(zhuǎn)到 http://127.0.0.1:8000/redoc抛姑。

查看自動(dòng)生成的（ReDoc）備選文檔 ：

ReDoc

OpenAPI

FastAPI 使用 OpenAPI （定義 API 的標(biāo)準(zhǔn) ）把所有 API 轉(zhuǎn)換成概圖赞厕。

概圖

概圖是對(duì)事物的定義與描述，不是實(shí)現(xiàn)功能的代碼定硝，只是抽象的描述皿桑。

API 概圖

本指南中，OpenAPI 是定義 API 概圖的規(guī)范蔬啡。

這里的概圖包括 API 路徑诲侮、路徑參數(shù)等。

數(shù)據(jù)概圖

概圖這一術(shù)語也指 JSON 等數(shù)據(jù)的結(jié)構(gòu)箱蟆。

本指南中沟绪，數(shù)據(jù)概圖是指 JSON 屬性、數(shù)據(jù)類型等空猜。

OpenAPI 和 JSON Schema

OpenAPI 用于定義 API 概圖绽慈。該概圖包含由 JSON Schema 為 API 發(fā)送與接收的數(shù)據(jù)所做的定義。JSON Schema 是 JSON 數(shù)據(jù)概圖標(biāo)準(zhǔn)抄肖。

查看 openapi.json

如果您對(duì) OpenAPI 原始概圖感興趣久信，F(xiàn)astAPI 自動(dòng)生成了描述所有 API 的 JSON （概圖）。

直接查看：http://127.0.0.1:8000/openapi.json漓摩。

JSON 文件的開頭如下：

{
    "openapi": "3.0.2",
    "info": {
        "title": "FastAPI",
        "version": "0.1.0"
    },
    "paths": {
        "/items/": {
            "get": {
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
...

OpenAPI 是干什么用的

OpenAPI 概圖用于驅(qū)動(dòng) FastAPI 內(nèi)置的兩個(gè) API 文檔裙士。

基于 OpenAPI 的備選方案還有很多，為 FastAPI 應(yīng)用添加其它備選方案很容易管毙。

OpenAPI 還可以用于自動(dòng)生成和 API 通信的客戶端代碼腿椎。例如前端、移動(dòng)端夭咬、物聯(lián)網(wǎng)應(yīng)用等啃炸。

分步小結(jié)

第一步：導(dǎo)入 FastAPI

from fastapi import FastAPI

FastAPI 是為 API 提供所有功能的 Python 類。

!!! note "技術(shù)細(xì)節(jié)"

`FastAPI` 是直接繼承自 `Starlette` 的類卓舵。

`FastAPI` 可以調(diào)用 Starlette 的所有功能南用。

第二步：創(chuàng)建 FastAPI 實(shí)例

app = FastAPI()

變量 app 是 FastAPI 的類實(shí)例。

該實(shí)例是創(chuàng)建所有 API 的主要交互對(duì)象掏湾。

這個(gè) app 就是以下命令中由 uvicorn 引用的變量：

$ uvicorn main:app --reload

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

如果用下面的代碼創(chuàng)建應(yīng)用：

my_awesome_api = FastAPI()

把代碼存入 main.py裹虫，要以如下方式調(diào)用 uvicorn：

$ uvicorn main:my_awesome_api --reload

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

第三步：創(chuàng)建路徑操作

路徑

路徑是指 URL 的第一個(gè)反斜杠（/）及它之后的內(nèi)容。

下列 URL 中：

https://example.com/items/foo

……路徑是：

/items/foo

!!! info "說明"

**路徑**通常也叫作**端點(diǎn)**或**路由**融击。

開發(fā) API 時(shí)筑公，路徑是分離 concerns 和 resources 的主要方式。

操作

操作是指 HTTP 方法尊浪。

常用方法如下：

• POST
• GET
• PUT
• DELETE

罕見方法如下：

• OPTIONS
• HEAD
• PATCH
• TRACE

HTTP 協(xié)議支持使用上述任何一種（或多種）方法與路徑通信匣屡。

開發(fā) API 時(shí)封救，通常要使用特定 HTTP 方法執(zhí)行特定操作。

常用方法：

• POST：創(chuàng)建數(shù)據(jù)
• GET：讀取數(shù)據(jù)
• PUT：更新數(shù)據(jù)
• DELETE：刪除數(shù)據(jù)

OpenAPI 把 HTTP 方法稱為操作捣作。

我們也稱之為操作誉结。

定義路徑操作裝飾器

@app.get("/")

@app.get("/") 告訴 FastAPI 下方函數(shù)以如下方式處理訪問請(qǐng)求：

• 請(qǐng)求路徑為 /
• 使用 get 操作

!!! info "@decorator 說明"

`@something` 語法是 Python **裝飾器**。

就像一頂放在函數(shù)上面的裝飾帽（估計(jì)這個(gè)術(shù)語的命名就是這么來的）虾宇。

裝飾器接收下方函數(shù)搓彻，并用它執(zhí)行一些操作。

本例中嘱朽，這個(gè)裝飾器告訴 **FastAPI** 下方函數(shù)對(duì)應(yīng)的**路徑**是 `/` 及 `get` **操作**旭贬。

這就是***路徑操作裝飾器***。

其它常用操作如下：

• @app.post()
• @app.put()
• @app.delete()

及罕見的操作：

• @app.options()
• @app.head()
• @app.patch()
• @app.trace()

!!! tip "提示"

您可以隨意使用任何操作（HTTP方法）搪泳。

**FastAPI** 不向操作強(qiáng)制附加任何特定含義稀轨。

本章中的說明僅是指導(dǎo)，不是要求岸军。

例如奋刽，使用 GraphQL 時(shí)，通常所有操作都只使用 `post` 一種方法艰赞。

第四步：定義路徑操作函數(shù)

路徑操作函數(shù)由以下幾部分組成：

• 路徑： /
• 操作： get
• 函數(shù)：裝飾器下方的函數(shù)（位于 @app.get("/") 下方）

async def root():

路徑操作函數(shù)就是 Python 函數(shù)佣谐。

FastAPI 每次接收使用 GET 方法訪問 URL/的請(qǐng)求時(shí)都會(huì)調(diào)用這個(gè)函數(shù)。

本例中的路徑操作函數(shù)是異步函數(shù)（async）方妖。

也可以不使用 async def狭魂，把路徑操作函數(shù)定義為普通函數(shù)：

def root():

!!! note "筆記"

如果不清楚普通函數(shù)與異步函數(shù)的區(qū)別，請(qǐng)參閱異步：***等不及了党觅？***一節(jié)中的內(nèi)容雌澄。

第五步：返回內(nèi)容

return {"message": "Hello World"}

路徑操作函數(shù)可以返回字典、列表杯瞻，以及字符串镐牺、整數(shù)等單值。

還可以返回 Pydantic 模型（稍后介紹）魁莉。

還有很多能自動(dòng)轉(zhuǎn)換為 JSON 的對(duì)象與模型（比如 ORM 等）睬涧。您可以嘗試使用最喜歡的對(duì)象，F(xiàn)astAPI 很可能已經(jīng)為其提供支持了旗唁。

小結(jié)

• 導(dǎo)入 FastAPI
• 創(chuàng)建 app 實(shí)例
• 編寫路徑操作裝飾器（如 @app.get("/")）
• 編寫路徑操作函數(shù)（如 def root(): ...）
• 運(yùn)行開發(fā)服務(wù)器（如 uvicorn main:app --reload）