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.py 中app = 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).