fastapi教程翻译(一):了解FastAPI结构

一、编写一个简单的FastAPI程序

最简单的FastAPI文件可能如下:

from fastapi import FastAPI

app = FastAPI()

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

将上面代码块复制到 main.py.

启动服务:

uvicorn main:app --reload

注意:

uvicorn main:app 命令指:

  • main: main.py 文件(也可理解为Python模块).
  • app: main.pyapp = FastAPI()语句创建的app对象.
  • --reload: 在代码改变后重启服务器,只能在开发的时候使用

你将会看到如下的输出:

INFO: Started reloader process [17961]
INFO: Started server process [17962]
INFO: Waiting for application startup.
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) </pre>

最后一句表明你的app服务在本地的URL地址。

二、检查

打开你的浏览器,输入 http://127.0.0.1:8000.

你将会看见JSON响应:

{"hello": "world"}

三、API交互文档

现在转到 http://127.0.0.1:8000/docs.

你将会看到自动生成的API交互文档(由 Swagger UI提供):

四、可选的API文档

现在,转到 http://127.0.0.1:8000/redoc.

你将会看到自动生成的可选的API文档(由(provided by ReDoc提供):

ReDoc

五、OpenAPI

FastAPI使用用于定义API的OpenAPI标准为您的所有API生成“模式”。

1. "模式"

模式”是事物的定义或描述。 不是实现它的代码,只是抽象描述。

2. API "模式"

在这种情况下,OpenAPI是规定如何定义API模式的规范。

此OpenAPI架构将包括您的API路径,以及路径中包含的可能参数等。

3. 数据 "模式"

术语“模式”也可能表示某些数据的形状,例如JSON内容。

在这种情况下,这将意味着JSON属性及其具有的数据类型,等等。

4. OpenAPI 和 JSON 模式

  • OpenAPI :为你的API定义API模式. 并且这个模式包含了API传输数据的定义和API接收数据的定义。
  • JSON 模式, the standard for JSON data schemas.

5. 检查

如果你对原生的OpenAPI是什么样子感兴趣,它只是一个自动生成的JSON,其中包含所有API的描述。

你可以直接转到: http://127.0.0.1:8000/openapi.json.

它将会展示可能是这样开头的JSON:

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

...

6. 做什么的?

此OpenAPI架构是为所包括的2个交互式文档系统提供支持的。

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

您还可以使用它为与您的API通信的客户端自动生成代码。 例如,前端,移动或物联网应用程序。

六、概括

Step 1: import FastAPI

from fastapi import FastAPI 
app = FastAPI()

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

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

技术细节

  • FastAPI是直接从Starlette继承的类。

您也可以将所有Starlette功能与FastAPI一起使用.

Step 2: 创建一个 FastAPI 实例

app = FastAPI() 

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

上面代码中app 变量就是FastAPI的一个实例.

这将是创建所有API的主要交互点。

该app与uvicorn在命令中引用的同一个app:

uvicorn main:app --reload

如果你创建的app像这样:

my_awesome_api = FastAPI() 

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

将上段代码保存到 main.py, 然后你可以这样启动 uvicorn :

uvicorn main:my_awesome_api --reload

Step 3: 创建一个path 操作

Path

这里的“路径”是指URL的最后一部分,从第一个/开始。

因此,在一个URL中:

https://example.com/items/foo

路径可能是:

/items/foo

“路径”通常也称为“端点”或“路由”。

构建API时,“路径”是分离“关注点”和“资源”的主要方法。

Operation

"Operation" 这里指 HTTP 方法:

比如:

  • POST
  • GET
  • PUT
  • DELETE

...还有更少见的一些方法:

  • OPTIONS
  • HEAD
  • PATCH
  • TRACE

在HTTP协议中,你可以使用任意方法访问一个路径


构建API时,通常使用这些特定的HTTP方法来执行特定的操作。

通常你会用到:

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

因此,在OpenAPI中,每个HTTP方法都称为方法

在以后的内容中,我们也把它称为方法。

定义URL路由

from fastapi import FastAPI

app = FastAPI()

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

@app.get("/")指明 FastAPI 下面的函数负责处理收到的请求:

  • 路径 /
  • 使用get 方法

Python中 @something 语法被称为装饰器.

将这个装饰器放在函数的上方,就像一个漂亮的装饰帽(我猜想这也是这个属于名称的来源).

一个"装饰器"使用下方的函数,并对其进行处理.

在我们的例子中,这个装饰器告诉FastAPI,下方视图函数将会响应路径/中的方法get.

这就是路由操作装饰器.

你也可以其他方法的装饰器:

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

还有一些比较少见的方法的装饰器:

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

建议

你可以使用任意的HTTP方法.

FastAPI不强制任何特定函数。

此处提供的信息,仅供参考,并非必需。

例如,当使用 GraphQL , 你通常会只执行post方法

Step 4: 定义路径操作函数

这是我们的 "路径操作函数":

  • 路径: /.
  • 操作: get.
  • 函数: @app.get("/")下方的函数.
from fastapi import FastAPI

app = FastAPI()

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

这是Python函数。

这个函数将会被 FastAPI 调用只要有 GET请求到URL "/".

在这个例子中,使用的是 async 函数。


你也可以定义普通的函数而不是async def:

from fastapi import FastAPI

app = FastAPI()

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

注释

如果你不了解其中的区别,可以查看"In a hurry?" 章节关于 async and await in the docs.

Step 5: 返回内容

from fastapi import FastAPI

app = FastAPI()

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

可返回的类型

你可以返回一个dict, list,单独的值,比如str, int

你也可以返回 Pydantic模型,在稍后的章节中会看到更多。

FastAPI中,许多其他的对象和模型都会被自动转换为JSON(包括ORM等)。

试着使用最适合您的方法,很有可能他们已经支持了。

七、总结

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

推荐阅读更多精彩内容