FastAPI | 教程 | 第一步

python , 评论

https://fastapi.tiangolo.com/zh/tutorial/first-steps/

第一步

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

1
2
3
4
5
6
7
8
from fastapi import FastAPI

app = FastAPI()


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

将其复制到 main.py 文件中。

运行实时服务器：

1
2
3
4
5
6
7
$ 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.

uvicorn main:app 命令含义如下:

  • main：main.py 文件（一个 Python「模块」）。
  • app：在 main.py 文件中通过 app = FastAPI() 创建的对象。
  • --reload：让服务器在更新代码后重新启动。仅在开发时使用该选项。

在输出中，会有一行信息像下面这样：

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

该行显示了你的应用在本机所提供服务的 URL 地址。

查看

打开浏览器访问 http://127.0.0.1:8000。

你将看到如下的 JSON 响应：

1
{"message": "Hello World"}

交互式 API 文档

跳转到 http://127.0.0.1:8000/docs。

你将会看到自动生成的交互式 API 文档（由 Swagger UI 提供）：

可选的 API 文档

前往 http://127.0.0.1:8000/redoc。

你将会看到可选的自动生成文档 （由 ReDoc 提供)：

OpenAPI

FastAPI 使用定义 API 的 OpenAPI 标准，将你的所有 API 转换成schema。

“Schema”

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

API “Schema”

在这种场景下，OpenAPI 是一种规定如何定义 API 模式的规范。

定义的 OpenAPI 模式将包括你的 API 路径，以及它们可能使用的参数等等。

Data “schema”

"Schema"这个术语也可能指的是某些数据比如 JSON 的结构。

在这种情况下，它可以表示 JSON 的属性及其具有的数据类型，等等。

OpenAPI and JSON Schema

OpenAPI 为你的 API 定义 API "Schema"。该模式中包含了你的 API 发送和接收的数据的定义（或称为"Schema"），这些定义通过 JSON 数据模式标准 JSON Schema 所生成。

查看 openapi.json

如果你对原始的 OpenAPI 模式长什么样子感到好奇，其实它只是一个自动生成的包含了所有 API 描述的 JSON。

你可以直接在：http://127.0.0.1:8000/openapi.json 看到它。

它将显示以如下内容开头的 JSON：

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



...

OpenAPI 的用途

驱动 FastAPI 内置的 2 个交互式文档系统的正是 OpenAPI 模式。

并且还有数十种替代方案，它们全部都基于 OpenAPI。你可以轻松地将这些替代方案中的任何一种添加到使用 FastAPI 构建的应用程序中。

你还可以使用它自动生成与你的 API 进行通信的客户端代码。例如 web 前端，移动端或物联网嵌入程序。

分步概括

步骤 1：导入 FastAPI

1
2
3
4
5
6
7
8
from fastapi import FastAPI ###############

app = FastAPI()


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

FastAPI 是一个为你的 API 提供了所有功能的 Python 类。

FastAPI 是直接从 Starlette 继承的类。

你可以通过 FastAPI 使用所有的 Starlette 的功能。

步骤 2：创建一个 FastAPI「实例」

1
2
3
4
5
6
7
8
from fastapi import FastAPI

app = FastAPI() #############


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

这里的变量 app 会是 FastAPI 类的一个「实例」。

这个实例将是创建你所有 API 的主要交互对象。

这个 app 同样在如下命令中被 uvicorn 所引用：

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

假如你的app是这么创建的：

1
2
3
4
5
6
7
8
from fastapi import FastAPI

my_awesome_api = FastAPI()


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

将代码放入 main.py 文件中，然后你可以像下面这样运行 uvicorn：

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

步骤 3：创建一个路径操作

路径(Path)

这里的"路径"(path)指的是 URL 中从第一个 / 起的后半部分。

所以，在一个这样的 URL 中：

1
https://example.com/items/foo

…路径会是：

1
/items/foo

A “path” is also commonly called an “endpoint” or a “route”.

「路径」也通常被称为「端点」或「路由」。

开发 API 时，「路径」是用来分离"关注点"(concerns)和"资源"(resources)的主要手段。

操作(Operation )

这里的 Operation 指的是一种 HTTP methods。

下列之一：

  • POST
  • GET
  • PUT
  • DELETE

…以及更少见的几种：

  • OPTIONS
  • HEAD
  • PATCH
  • TRACE

在 HTTP 协议中，你可以使用以上的其中一种（或多种）methods 与每个路径进行通信。

在开发 API 时，你通常使用特定的 HTTP 方法去执行特定的行为。

通常使用：

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

因此，在 OpenAPI 中，每一个 HTTP 方法都被称为Operation。

我们也打算称呼它们为Operation。

定义一个路径操作装饰器(path operation decorator)

1
2
3
4
5
6
7
8
from fastapi import FastAPI

app = FastAPI()


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

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

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

@something 语法在 Python 中被称为「装饰器」。
像一顶漂亮的装饰帽一样，将它放在一个函数的上方（我猜测这个术语的命名就是这么来的）。
装饰器接收位于其下方的函数并且用它完成一些工作。
在我们的例子中，这个装饰器告诉 FastAPI 位于其下方的函数对应着路径 / 加上 get 操作。
它是一个「路径操作装饰器」。

你也可以使用其他的操作：

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

以及更少见的：

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

您可以随意使用任何一个操作（HTTP方法）。

FastAPI 没有强制要求操作有任何特定的含义。

此处提供的信息仅作为指导，而不是要求。

比如，当使用 GraphQL 时通常你所有的动作都通过 post 一种方法执行。

步骤 4：定义路径操作函数

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

  • path：是 /。
  • operation：是 get。
  • function：是位于「装饰器」下方的函数（位于 @app.get("/") 下方）。
1
2
3
4
5
6
7
8
from fastapi import FastAPI

app = FastAPI()


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

这是一个 Python 函数。

每当 FastAPI 接收一个使用 GET 方法访问 URL"/"的请求时这个函数会被调用。

在这个例子中，它是一个 async 函数。

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

1
2
3
4
5
6
7
8
from fastapi import FastAPI

app = FastAPI()


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

如果你不知道两者的区别，请查阅 Async: “In a hurry?”。

步骤 5：返回内容

1
2
3
4
5
6
7
8
from fastapi import FastAPI

app = FastAPI()


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

你可以返回一个 dict、list，像 str、int 一样的单个值，等等。

你还可以返回 Pydantic 模型（稍后你将了解更多）。

还有许多其他将会自动转换为 JSON 的对象和模型（包括 ORM 对象等）。尝试下使用你最喜欢的一种，它很有可能已经被支持。

总结

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

XUQMAndroid开发

一个啥也不会的Android开发，励志转型ios开发，后来放弃了。还想搞后台，后台不让！python也不同意！！！