FastAPI教程

---

第一章 基础知识

        FastAPI框架不仅具有Flask或Django的Web核心功能，还兼具异步特性，可以同时兼容同步和异步这两种模式运行。换句话，用户可以使用同步编写API，也可以使用异步的方式编写API。FastAPI之所以被大众所认可，主要原因有两个：一是支持ASGI(Asynchronous Seriver Gateway Interface)协议的Web应用框架，即同时兼容ASGI和WSGI应用；二是支持异步协程处理，能快速处理更多的HTTP请求。
        ASGI是异步服务器网关接口，和WSGI一样，都是为Python语言定义的Web服务器和Web应用程序或框架之间的一种简单而通用的接口。但ASGI是WSGI的一种扩展，并且提供异步特性和WebSocket等支持。同时，ASGI兼容WSGI，所以ASGI在支持同步的同时，也支持异步，内部可以通过一个转换装饰器进行相互切换。
        并发通常是指在单核CPU下，同时运行多个应用程序。然而本质上，操作系统在处理任务时任一时刻点都只有一个程序在CPU中运行。我们之所以能看到多个应用程序同时执行，是因为操作系统给每个应用程序都分配了一定时间片，每个任务执行完分配的时间片后，操作系统通过调度切换到下一个任务执行，而这些时间片对于我们来讲短到无法感知。
        并行对于单核CPU不存在这样的说法，对于多核CPU，任务就可以分配到不同CPU执行，在这种情况下，在多个CPU上主席那个的任务就不会相互干扰，这才是真正的多任务同时进行。
        同步（Synchronous）是在强调多个任务在执行过程，其中的某个任务不允许被中断。多个任务执行是协调一致且有序的，若某个任务在执行过程中受阻，其他任务需要等待。
        异步（Asynchronous）是在强调多个任务可以分开执行，彼此之间相互不影响，若某个任务受阻，其他任务无需等待，但是任务执行的结果依然保持一致。如果某个任务被划分为多个任务单元，那么这些任务单元都是可以分开执行，多任务单元执行可以是无序的。
        注意：同步在调用IO操作时，必须等待IO操作完才能返回；异步在调用IO操作时，不必等待IO操作完成就可以返回。
        asyncio是Python官方提供的用于构建协程的并发应用库，是FastAPI实现异步特性的重要组成部分。基于asyncio，可以在单线程模式下，处理更多并发任务，它是异步IO框架，而异步IO是基于事件触发机制来实现异步回调。
        公网IP地址：互联网上的所有人都可以通过这个IP地址访问到服务。公网IP地址一般需要向服务提供商申请获得。
        内网IP地址：主要是指个人计算机内的局域网址。如果服务是通过内网IP开启，则只能使用本机或所属局域网内的其他内网IP地址访问，外部人员无法通过内网IP地址进行访问。

第二章 安装

第一步：安装FastAPI框架

pip install "fastapi[all]"
pip install "fastapi[standard]"

第二步：安装ASGI 服务器

pip install "uvicorn[standard]"

安装教程中的两个问题：

1. FastAPI 的主要功能是什么？
   FastAPI 是一个现代、高性能的Python Web框架，主要用于快速构建API（如RESTful API或WebSocker服务）。由于FastAPI早期版本没有提供基本的网关服务，所以需要借助外部的网关服务器来提供Web访问的基础架构。
2. Uvicorn ASGI 网关服务器的主要功能是什么？
   Uvicorn 是一个轻量级ASGI（异步服务器网关接口），专为运行FastAPI等异步框架设计。

第三章 实践与应用

3.1 简单案例

第一步：创建一个fast_service.py文件

"""
 @app.get()是pyhon里面的装饰器，用来创建一个API端点路由请求，该装饰器表示当前API只能使用GET请求方式进行请求处理。
 "/"表示请求访问URL径路地址；
 tags=["app实例对象注册接口示例"]表示这个API归属于'app实例对象注册接口示例'分组标签。
 注意：@app.get()装饰函数可以def定义的同步函数，也可以是async def定义的协程函数。同步函数会运行于外部线程池，
      协程函数会运行与异步事件循环中。
"""
from fastapi import FastAPI

# 创建app实例对象
app = FastAPI(
    title="ef算法",
    description="以下是ef文档介绍和描述",
    version="0.0.1",
)

# 使用app实例对象来装饰实现路由注册
@app.get("/", tags=["app实例对象注册接口示例"])
def read_root():
    return {"message": "Hello World"}

第二步：启动方式

1. 命令启动
   （1）开发模式启动

fastapi dev .\fast_service.py  # 开发模式

（2）生产模式启动

fastapi run .\fast_service.py  # 生产模式

结果：

(py310) PS E:\fault_diagnose\example\service> fastapi dev .\fast_api_service.py
   FastAPI   Starting development server 🚀
             Searching for package file structure from directories with __init__.py files
             Importing from E:\fault_diagnose\example\service
    module   🐍 fast_api_service.py
      code   Importing the FastAPI app object from the module with the following code:
             from fast_api_service import app
       app   Using import string: fast_api_service:app
    server   Server started at http://127.0.0.1:8000
    server   Documentation at http://127.0.0.1:8000/docs
       tip   Running in development mode, for production use: fastapi run

（3）Uvicorn启动

uvicorn fast_service:app --reload
<# 
	 用来启动fast_service中的app对象
	 --reload主要用于热启动，这个参数主要用于在编写代码阶段，若需要对当前代码进行改动，那么代码改完后
	 程序会自动重启服务的进行，使修改及时生效，正式部署到生产环境禁止使用该参数。
#>

uvicorn fast_service:app --reload --host 0.0.0.0 --port 8888

        如果希望对外允许访问服务，可以 – host 参数设置为0.0.0.0(表示本机上所有IP地址，也包括回环地址127.0.0.1。如果本机存在多网卡情况，则0.0.0.0是所有网卡IP的集合。如果使用host=0.0.0.0绑定IP地址，则表示服务进程会接受来自所有网卡的IP地址请求。此时，如果本机防火墙关闭或开启相关允许机制，则当前局域网内的其他人也可以通过访问本机IP地址的形式请求到接口服务)，如果希望自定义监听端口，可以添加 - -port 参数设置为16000。
        注意：127.0.0.1是一个回环地址，也可以认为127.0.0.1和localhost是等价的。其中localhost是一个域名，这个域名指向IP地址127.0.0.1。
结果：

(py310) PS E:\fault_diagnose\example\service> uvicorn fast_api_service:app --reload
INFO:     Will watch for changes in these directories: ['E:\\fault_diagnose\\example\\service']
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [24528] using WatchFiles
INFO:     Started server process [16544]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

1. 程序启动

import uvicorn

from typing import Union
from fastapi import FastAPI

app = FastAPI()

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

@app.get("/items/{item_id}")
def read_item(item_id: int, q: Union[int, str] = None):
    return {"item_id": item_id, "q": q}

if __name__ == "__main__":
    uvicorn.run("fast_api_service:app", host="0.0.0.0", port=8000, reload=True)

        uvicorn提供参数可通过官网进行学习：https://www.uvicorn.org/。
第三步： 访问

Swagger UI模式下，服务启动后，通过浏览器访问：http://127.0.0.1:8000/docs
PostAPI 访问：127.0.0.1:8000

3.2 URL配置多个http请求

        FastAPI提供了@app.api_route(）来支持配置路由函数使用不同http请求方法，示例代码如下：

import uvicorn
from fastapi import FastAPI

# 创建app实例对象
app = FastAPI(
    title="变电站主设备算法",
    description="以下是上海艾飞能源科技有限公司文档介绍和描述",
    version="0.0.1",
    debug=True,
    license_info={
        "name": "版权归上海艾飞能源科技有限公司所有 version 0.0.1",
        "url": "https://www.energyfuture.cn"
    },
    routes=None
)

# 使用app实例对象来装饰实现路由注册
@app.api_route(path="/fault_diagnose", methods=["POST", "GET"])
async def read_root():
    return {"message": "Hello World"}