🚀 原文地址：https://fastapi.tiangolo.com/zh/tutorial/first-steps/

最简单的 FastAPI 文件可能像下面这样：

  1. from fastapi import FastAPI
  3. app = FastAPI()
  6. @app.get("/")
  7. async def root():
  8.     return {"message": "Hello World"}

运行实时服务器：

  1. $ uvicorn main:app --reload
  2. INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
  3. INFO:     Started reloader process [28720]
  4. INFO:     Started server process [28722]
  5. INFO:     Waiting for application startup.
  6. INFO:     Application startup complete.

对上述命令 uvicorn main:app --reload 简单介绍一下，并且终端中日志会输出本机所提供的 URL 访问地址：

  • main：对应 main.py 程序文件
  • app：在 main.py 文件中通过 app = FastAPI() 创建的对象

  • --reload：让服务器在更新代码后重新启动，仅在开发时使用该选项

    1. 查看

    打开浏览器访问 http://127.0.0.1:8000，我们将会看到如下 JSON 响应：

    1. {"message": "Hello World!"}

    2. 交互式 API 文档

    另外，我们还可以访问 http://127.0.0.1:8000/docs，将会看到自动生成的交互式 API 文档（由 Swagger UI 提供）：
    image.png

    3. 可选的 API 文档

    前往 http://127.0.0.1:8000/redoc，将会看到可选的自动生成文档 （由 ReDoc 提供)：
    image.png

    4. OpenAPI

    FastAPI 使用定义 API 的 OpenAPI 标准将你的所有 API 转换成「模式」。

  • 模式：模式是对事物的一种定义或描述，它并非具体的实现代码，而只是抽象的描述。

  • API 模式：在这种场景下，OpenAPI 是一种规定如何定义 API 模式的规范。定义的 OpenAPI 模式将包括你的 API 路径，以及它们可能使用的参数等等。
  • 数据模式：模式这个术语也可能指的是某些数据比如 JSON 的结构，在这种情况下，它可以表示 JSON 的属性及其具有的数据类型，等等。
  • OpenAPI 和 JSON Schema：OpenAPI 为你的 API 定义 API 模式，该模式中包含了你的 API 发送和接收的数据的定义（或称为模式），这些定义通过 JSON 数据模式标准 JSON Schema 所生成。

  • 查看 openapi.json：如果你对原始的 OpenAPI 模式长什么样子感到好奇，其实它只是一个自动生成的包含了所有 API 描述的 JSON。我们可以直接在：http://127.0.0.1:8000/openapi.json 看到它，将显示以如下内容开头的 JSON：

    1. {
    2.   "openapi": "3.0.2",
    3.   "info": {
    4.       "title": "FastAPI",
    5.       "version": "0.1.0"
    6.   },
    7.   "paths": {
    8.       "/items/": {
    9.           "get": {
    10.               "responses": {
    11.                   "200": {
    12.                       "description": "Successful Response",
    13.                       "content": {
    14.                           "application/json": {}
    15.                       }
    16.                   }
    17.               }
    18.           }
    19.       }
    20.   }
    21. }

  • OpenAPI 的用途：驱动 FastAPI 内置的 2 个交互式文档系统的正是 OpenAPI 模式，并且还有数十种替代方案，它们全部都基于 OpenAPI。我们可以轻松地将这些替代方案中的任何一种添加到使用 FastAPI 构建的应用程序中。我们还可以使用它自动生成与你的 API 进行通信的客户端代码。例如 web 前端，移动端或物联网嵌入程序。

    5. 分步概括

    5.1 导入 FastAPI

    ```python from fastapi import FastAPI

app = FastAPI()

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

  2. FastAPI 是一个为你的 API 提供了所有功能的 Python 类。
  4. :::info
  5. **💡 技术细节**<br />————————<br />FastAPI 是直接从 `Starlette` 继承的类，你可以通过 FastAPI 使用所有的 Starlette 的功能。
  6. :::
  7. <a name="zsdFN"></a>
  8. ## 5.2 创建一个 FastAPI 实例
  9. ```python
  10. from fastapi import FastAPI
  12. app = FastAPI()
  15. @app.get("/")
  16. async def root():
  17.     return {"message": "Hello World"}

这里的变量 app 会是 FastAPI 类的一个实例，这个实例将是创建你所有 API 的主要交互对象，并且这个 app 同样在如下命令中被 uvicorn 所引用：

  1. $ uvicorn main:app --reload
  3. INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

如果你像下面这样创建应用：

  1. from fastapi import FastAPI
  3. my_awesome_api = FastAPI()
  6. @my_awesome_api.get("/")
  7. async def root():
  8.     return {"message": "Hello World"}

然后你可以像下面这样运行 uvicorn：

  1. $ uvicorn main:my_awesome_api --reload
  3. INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

5.3 创建一个路径操作

这里的路径指的是 URL 中从第一个 / 起的后半部分，所以，在一个 https://example.com/items/foo 这样的 URL 中：路径会是 /items/foo。

:::info 💡 笔记
————————————
路径也通常被称为端点(endpoint)或路由(route)。 :::

开发 API 时，路径是用来分离关注点和资源的主要手段。

1) 操作

这里的操作指的是一种 HTTP 方法，主要有以下这些，其中红色表示很少使用：

  • POST
  • GET
  • PUT
  • DELETE
  • OPTIONS
  • HEAD
  • PATCH
  • TRACE

在 HTTP 协议中，你可以使用以上的其中一种（或多种）方法与每个路径进行通信。在开发 API 时，你通常使用特定的 HTTP 方法去执行特定的行为，通常使用：

  • POST：创建数据
  • GET：读取数据
  • PUT：更新数据
  • DELETE：删除数据

因此，在 OpenAPI 中，每一个 HTTP 方法都被称为操作，我们也打算称呼它们为操作。

2) 定义一个路径操作装饰器

  1. from fastapi import FastAPI
  3. app = FastAPI()
  6. @app.get("/")
  7. async def root():
  8.     return {"message": "Hello World"}

@app.get("/") 告诉 FastAPI 在它下方的函数负责处理如下访问请求：

  • 请求路径为 /
  • 使用 get 操作

:::info 💡 装饰器
————————————
@something 语法在 Python 中被称为装饰器，像一顶漂亮的装饰帽一样，将它放在一个函数的上方（我猜测这个术语的命名就是这么来的）。

装饰器接收位于其下方的函数并且用它完成一些工作。在我们的例子中，这个装饰器告诉 FastAPI 位于其下方的函数对应着路径 / 加上 get 操作。它是一个路径操作装饰器。 :::

你也可以使用其他的操作，同样的红色表示比较少被使用：

  • @app.post()
  • @app.put()
  • @app.delete()
  • @app.options()
  • @app.head()
  • @app.patch()

  • @app.trace()

    5.4 定义路径操作函数

    这是我们的路径操作函数：

  • 路径：是 /

  • 操作：是 get
  • 函数：是位于装饰器下方的函数（位于 @app.get("/") 下方）
  1. from fastapi import FastAPI
  3. app = FastAPI()
  6. @app.get("/")
  7. async def root():
  8.     return {"message": "Hello World"}

这是一个 Python 函数，每当 FastAPI 接收一个使用 GET 方法访问 URL / 的请求时这个函数会被调用。在这个例子中，它是一个 async 函数。

你也可以将其定义为常规函数而不使用 async def：

  1. from fastapi import FastAPI
  3. app = FastAPI()
  6. @app.get("/")
  7. def root():
  8.     return {"message": "Hello World"}

:::info 💡 笔记
————————————
如果你不知道两者的区别，请查阅 Async:”In a hurry?”。 :::

5.5 返回内容

  1. from fastapi import FastAPI
  3. app = FastAPI()
  6. @app.get("/")
  7. async def root():
  8.     return {"message": "Hello World"}

你可以返回一个 dict、list，像 str、int 一样的单个值，等等。你还可以返回 Pydantic 模型（稍后你将了解更多）。还有许多其他将会自动转换为 JSON 的对象和模型（包括 ORM 对象等）。尝试下使用你最喜欢的一种，它很有可能已经被支持。

6. 总结

  • 导入 FastAPI
  • 创建一个 app 实例
  • 编写一个路径操作装饰器（如 @app.get("/")）
  • 编写一个路径操作函数（如上面的 def root(): ...）
  • 运行开发服务器（如 uvicorn main:app --reload）