FastAPI 库（Python 的 Web 框架）基本利用指南（一）

FastAPI 概述

参考文档：

• 中文文档
  
• 轻松上手Python的Web神器：FastAPI教程
  

介绍

FastAPI 是一个基于 Python 的当代 Web 框架，它具有快速构建高性能 API 的特点。
FastAPI 关键特性:

• 快速：可与 NodeJS 和 Go 并肩的极高性能（归功于 Starlette 和 Pydantic）。最快的 Python web 框架之一。
  
• 高效编码：进步功能开发速度约 200％ 至 300％。
  
• 更少 bug：镌汰约 40％ 的人为（开发者）导致错误。
  
• 智能：极佳的编辑器支持。到处皆可主动补全，镌汰调试时间。
  
• 简朴：设计的易于利用和学习，阅读文档的时间更短。
  
• 简短：使代码重复最小化。通过差别的参数声明实现丰富功能。bug 更少。
  
• 健壮：生产可用级别的代码。另有主动天生的交互式文档。
  
• 标准化：基于（并完全兼容）API 的相关开放标准：OpenAPI (以前被称为 Swagger) 和 JSON Schema。
  

常见 Python Web 框架的介绍与区别

性能：

• Django：是一个全功能的框架，它提供了很多内置的功能和扩展。固然它在性能方面相对较低，但它非常适合构建大型应用程序。
  
• Flask：是一个轻量级的框架，它更加注意简洁和机动性。相比于 Django，Flask 具有更好的性能表现，但它的功能相对较少。
  
• FastAPI：是一个高性能的框架，它基于异步哀求处置惩罚和类型注解。FastAPI 比 Django 和 Flask 在性能上更为精彩，而且它利用 Python 的 asyncio 库来实现高效的并发哀求处置惩罚。
  

开发难度：

• Django：是一个全功能的框架，它提供了很多现成的功能和组件，使得开发更加快速和简朴。但是，对于初学者来说，Django的学习曲线可能相对较陡。
  
• Flask：是一个简洁而机动的框架，它更多地侧重于自界说和设置。相对于 Django，Flask 的学习曲线较为平缓，适合小型和简朴的项目。
  
• FastAPI：利用了类型注解和主动天生文档的功能，使代码更易读和维护。它提供了基于标准的API模式和强盛的验证工具，镌汰了开发过程中的错误。
  

推广程度：

• Django：是最受接待和广泛利用的 Python Web 框架之一。它拥有巨大的社区支持和丰富的文档资源，可以轻松找到相关的教程、插件和办理方案。
  
• Flask：是一个比较受接待的框架，拥有巨大的社区和丰富的扩展库。固然它的用户群体相对较小，但在小型项目和快速原型开发中非常流行。
  
• FastAPI：是一个相对较新的框架，但它正在敏捷获得开发者的关注。它的高性能和当代特性吸引了很多开发者，而且社区正在渐渐扩大。
  FastAPI 是一个用于构建 API 的当代、快速（高性能）的 web 框架，利用 Python 3.6+ 并基于标准的 Python 类型提示。
  

入门示例

• 安装 FastAPI 和 uvicorn
  FastAPI 利用 uvicorn 作为默认的 Web 服务。因此，需要在安装 FastAPI 和 uvicorn
  uvicorn 是一个轻量级的 ASGI（异步服务器网关接口）服务器
  
  1. pip install fastapi
  2. pip install uvicorn

  复制代码
• 示例代码
  
  1. from fastapi import FastAPI
  2. import uvicorn
  4. # 创建一个FastAPI应用程序实例
  5. app = FastAPI()
  6. # 定义路由（使用装饰器将函数绑定到特定的路径和HTTP方法）
  7. @app.get("/")
  8. async def root():
  9.     return {"message": "Hello World"}
  11. @app.get("/items/{item_id}")
  12. def read_item(item_id: int, q: str = None):
  13.     return {"item_id": item_id, "q": q}
  15. # 启动程序时使用 uvicorn 允许 FastAPI 应用程序
  16. uvicorn.run(app)
  17. # 默认ip为127.0.0.1，默认端口为8000

  复制代码

启动 web 服务

• 方式1：uvicorn 内嵌式
  在代码中利用 uvicorn.run(app) 启用 uvicorn 服务器运行 python 服务，然后利用 python 启动 py 模块
  
  1. import uvicorn
  3. app = FastAPI()
  4. uvicorn.run(app)

  复制代码
• 方式2：uvicorn 外启式
  在命令行输入命令：
  
  1. uvicorn main:app --host 0.0.0.0 --port 80 --reload

  复制代码
  
  
  • main：启动服务的py文件名
    
  • app：服务对象名
    
  • –-host：ip地点
    
  • –-port：端口
    
  • –-reload：代码修改后主动重启服务。仅在开发时利用，上线后不要带这个参数，会低沉性能
    
  
  

uvicorn.run 支持的参数

• app ：指定应用 app。‘脚本名:FastAPI 实例对象’ 或 FastAPI 实例对象
  
• host ：字符串，允许被访问的形式：locahost、127.0.0.1、当前 IP、0.0.0.0。默以为127.0.0.1
  
• port ：数字，应用的端口，默以为 8000
  
• uds ：字符串，socket 服务绑定到 UNIX 的域名
  
• fd ：数字，今后文件形貌符绑定到socket
  
• loop ：事件循环模式。选项列表为 [auto|asyncio|uvloop]，默以为 auto
  
• http ：HTTP协议实现。选项列表为 [auto|h11|httptools]，默以为auto
  
• ws ：WebSocket协议实现。选项列表为 [auto|none|websockets|wsproto]，默以为auto
  
• ws-max-size ：数字，WebSocket 最大消息大小（字节），默认值为 16777216
  
• lifespan ：生命周期实施。选项列表为 [auto|on|off]，默以为auto
  
• env-file ：PATH，环境设置文件
  
• log-config ：PATH，日志设置文件。支持的格式：.ini、.json、.yaml，默以为 fastapi 默认的 log 设置
  
• log-level ：日志级别。选项列表为 [critical|error|warning|info|debug|trace]，默认 info
  
• access-log ：boolean，access log 日志的开关，默以为 True
  
• use-colors ：boolean，彩色日志的开关（条件需指定log-config），默以为 None
  
• interface ：选择 ASGI3、ASGI2 或 WSGI 作为应用程序接口。选项列表为 [auto|asgi3|asgi2|wsgi]，默以为 auto
  
• debug ：是否利用 debug 模式，默认False,
  
• reload ：boolean，今世码发生更时，是否主动重启，默认 False,
  
• reload_dirs ：字符串，设置重新加载目次，当没有传这个参数的实时，将取当前工作目次
  
• reload-delay ：float，每隔多久检测代码是否有变动，默认 0.25 秒
  
• workers ：数字，工作进程数。默以为 WEB_CONCURRENCY 环境变量（如果可用） 或 1。对于 --reload 无效。
  
• proxy-headers ：boolean，启用/禁用 X-Forwarded-Proto、X-Forwarded-For、X-Forwarded-Port 以添补长途地点信息，默以为 True
  
• forwarded-allow-ips ：字符串，用逗号分隔的IP列表以信任署理标头。默以为 FORWARDED_ALLOW_IPS 环境变量（如果可用），或 None，为 None 时，代码里面则取 127.0.0.1
  
• root-path ：字符串，为安装在给定 URL 路径下的应用程序设置 ASGI “根路径”。
  
• limit-concurrency ：数字，在发出 HTTP503 响应之前，允许的最大并发连接数或任务数。默以为 None
  
• limit-max-requests ：数字，到达多少哀求数则终止进程，默以为 None
  
• backlog ：数字，等待处置惩罚的最大连接数，默以为 2048
  
• timeout-keep-alive ：数字，如果在此超时时间内未收到新数据，则关闭保持活动状态的连接，默以为 5
  
• ssl-keyfile ：字符串，SSL密钥文件，默以为 None
  
• ssl-certfile ：字符串，SSL证书文件，默以为 None
  
• ssl-keyfile-password ：字符串，SSL密钥文件暗码，默以为 None
  
• ssl-version ：数字，要利用的 SSL版本（详见 stdlib SS L模块），默以为 2
  
• ssl-cert-reqs ：数字，是否需要客户端证书（详见 stdlib SSL 模块），默以为 0
  
• ssl-ca-certs ：字符串，CA 证书文件
  
• ssl-ciphers ：字符串，要利用的 CA 证书文件暗码（详见 stdlib SSL 模块），默以为 TLSv1
  
• header ：字典，自界说响应头信息，键值对的形式，默以为 None
  

常用 API

app=FastAPI() ：创建 FastAPI 应用程序实例

• app = FastAPI() 是在 FastAPI 中创建应用程序实例的常见做法。这行代码创建了一个 FastAPI 应用程序对象，可以在这个对象上界说路由、中心件、异常处置惩罚等。
  
• 应用程序实例 app 具有很多属性和方法，用于设置和管理应用程序的各个方面，如路由、中心件、异常处置惩罚、依赖注入等。通过创建 app 实例，可以在其中界说和构造应用程序的逻辑。
  
• 代码示例
  
  1. from fastapi import FastAPI
  3. app = FastAPI()

  复制代码
• 支持参数（均为可选传）：
  
  
  
  • debug ：调试模式，True/False。此属性继承自 starlette，在 starlette 中利用的是 property 装饰器
    
  • routes ：路由列表，默认值为 None
    此属性继承自 starlette，类型为 startlette 的 BaseRoute 列表，BaseRoute 与 starlette 的底子类型 Scope 有关
    
  • title ：API文档的标题，默认值 FastAPI
    
  • description ：API文档的形貌，默以为空
    
  • version ：API 接口的版本号
    
  • openapi_url ：OpenAPI 文件路径，默以为 /opanapi.json
    
  • openapi_prefix ：OpenAPI 文件路径前缀，默以为空
    
  • default_response_class ：默认响应类型，默以为 JSONResponse
    此参数继承自 startlette 的 Response，有 HTMLResponse、PlainTextResponse、UJSONResponse、RedirectResponse、StreamingResponse、FileResponse 和 JSONResponse 七种，利用时需加载 starlette.responses 模块
    
  • docs_url ：交互式文档路径，默以为 /docs
    
  • redoc_url ：可选式文档路径，默以为 /redoc
    
  • swagger_ui_oauth2_redirect_url ：OAuth 重定向路径，默以为 /docs/oauth2-redirect
    
  • swagger_ui_init_oauth ：OAuth 重定向字典，默以为 None
    
  • middleware ：中心件，默以为空
    
  • exception_handlers ：异常处置惩罚方法，默以为 None
    
  • on_startup ：app 启动时调用的方法列表
    
  • on_shutdown ：app 关闭时调用的方法列表
    
  • extra : 额外可选参数
    
  
  

FastAPI() 实例常用 API

get()、post() 等：界说 HTTP 哀求的路由

在 FastAPI 中，app.get() 、app.post()等方法用于界说 HTTP 哀求的路由。这些方法接受多个参数，用于指定路由的路径、哀求处置惩罚函数、依赖项等。
以下是主要参数：

• path（必填）：用于指定路由的路径。这是一个字符串，表示 URL 路径，可以包含路径参数和查询参数。
  
• response_model：用于指定响应模子。响应模子是响应数据的数据结构，通常利用 Pydantic 模子来界说。
  
• summary：一个简短的字符串，用于形貌路由的目的或功能。
  
• description：用于提供更详细的路由阐明。
  
• tags：一个字符串列表，用于标记路由，以便在文档中分类和构造路由。
  
• dependencies：一个列表，指定在路由处置惩罚函数中需要注入的依赖项。
  
• response_description：用于指定响应的形貌信息。
  
• deprecated：一个布尔值，表示路由是否已被弃用。
  
• status_code：用于指定响应的 HTTP 状态码。
  
• response_model_include 和 response_model_exclude：用于指定在响应模子中包含或排除的字段。
  
• response_model_by_alias：一个布尔值，表示是否利用 Pydantic 模子中的别名来序列化响应。
  
• response_model_exclude_unset：一个布尔值，表示在响应中排除未设置的字段。
  
• response_model_exclude_defaults：一个布尔值，表示在响应中排除具有默认值的字段。
  
• response_model_exclude_none：一个布尔值，表示在响应中排除值为 None 的字段。
  
• operation_id：用于指定操纵的唯一标识符。
  
• deprecated：一个布尔值，表示路由是否已被弃用。
  
• callbacks：一个字典，用于指定回调函数。
  

这些参数可以根据需求来机动设置。一般来说，path 参数是必需的，而其他参数则根据需要来选择性地利用。

add_middleware()：添加中心件

• add_middleware() 函数：是 FastAPI 中用于添加中心件的方法。
  中心件是一种可以在哀求和响应处置惩罚过程中举行预处置惩罚和后处置惩罚的功能。可以利用中心件来实现各种需求，如添加全局头部、哀求日志记载、异常处置惩罚等。
  通过 app.add_middleware 方法将自界说中心件添加到应用程序。当哀求到达时，FastAPI 会依次实行添加的中心件，然后再调用路由处置惩罚函数。在响应返回时，会按照相反的顺序实行中心件的后处置惩罚逻辑。
  通过添加中心件，可以在哀求和响应处置惩罚过程中实现一些通用的功能，而不需要在每个路由中重复编写相同的代码。这有助于保持代码的整洁和可维护性。
  
• 常用参数：
  
  
  
  • middleware_class（必需）：一个中心件类，希望添加到应用程序的中心件。
    中心件类应继承自 fastapi.middleware.base.BaseHTTPMiddleware 或类似的基类。
    
  • **options：这是中心件的设置选项，可以根据中心件的要求传递差别的参数。详细的选项取决于利用的中心件类。通常，可以传递任何与中心件相关的自界说参数，以便在中心件类中利用。
    
  
  

CORSMiddleware 中心件

• FastAPI 内置的中心件，用于处置惩罚跨源资源共享（CORS）问题。
  CORS 是一种浏览器安全机制，用于控制跨域哀求。在前端和后端分离的应用中，当前端代码（在浏览器中运行）从一个域向另一个域发出哀求时，浏览器会实行跨域检查，确保只有受信任的域可以访问资源。
  CORSMiddleware 可以帮助开发者设置 FastAPI 应用程序以精确处置惩罚跨域哀求。
  设置完中心件后，FastAPI 会主动处置惩罚跨域哀求，并在响应中添加适当的头部信息以满足 CORS 安全要求。
  请注意，CORS 设置涉及到应用程序的安全性。在生产环境中，应根据现实需求来设置 allow_origins 和其他参数。
  
• 常用参数（用于设置跨域计谋）：
  
  
  
  • allow_origins：允许访问资源的域名列表。
    可以利用 ["*"] 表示允许所有域名，但这通常不是推荐的做法。
    
  • allow_credentials：是否允许发送根据（如 cookie、HTTP 认证头部）的哀求。
    如果为 True，则需要确保在客户端和服务器端都举行相应的设置，且 allow_origins 必须为详细的源，不可以是 ["*"]
    
  • allow_methods：允许的 HTTP 方法列表如 ["GET", "OST"]。默认是 ["GET"]
    可以利用 ["*"] 表示允许所有方法
    
  • allow_headers：允许的 HTTP 头部列表，如 ["Content-Type", "Authorization"]。默认是 []
    可以利用 ["*"] 表示允许所有头部
    注：Accept、Accept-Language、Content-Language 以及 Content-Type 总是被允许的
    
  
  
• 代码示例：
  
  1. from fastapi import FastAPI
  2. from fastapi.middleware.cors import CORSMiddleware
  4. app = FastAPI()
  6. # 添加 CORS 中间件
  7. app.add_middleware(
  8.     CORSMiddleware,
  9.     allow_origins=["http://localhost", "https://example.com"],
  10.     allow_credentials=True,
  11.     allow_methods=["*"],
  12.     allow_headers=["*"],
  13. )

  复制代码

自界说中心件：

• 方式1：自界说中心件类，添加自界说中心件时通过 dispatch 参数传递自界说中心件类的对象
  
  1. from fastapi import FastAPI, Request
  2. from fastapi.middleware.cors import BaseHTTPMiddleware
  4. # 自定义中间件
  5. class MyMiddleware:
  6.     def __init__(self, some_attribute: str = None):
  7.         # some_attribute非必需，此处用于演示传参到自定义的中间件
  8.         self.some_attribute = some_attribute
  10.     async def __call__(self, request: Request, call_next):
  11.         # do something with the request object
  12.         # process the request and get the response   
  13.         response = await call_next(request)
  14.         # do something with the response object
  15.         return response
  17. app = FastAPI()
  18. # 添加自定义中间件
  19. app.add_middleware(BaseHTTPMiddleware, dispatch=MyMiddleware())

  复制代码
• 方式2：自界说中心件类继承 BaseHTTPMiddleware 类
  
  1. # 自定义中间件
  2. class MyMiddleware(BaseHTTPMiddleware):
  3.     def __init__(self, app, some_attribute: str):
  4.         super().__init__(app)
  5.         self.some_attribute = some_attribute
  7.     async def dispatch(self, request: Request, call_next):
  8.         # do something with the request object, for example
  9.         content_type = request.headers.get('Content-Type')
  10.         print(content_type)
  11.         
  12.         # process the request and get the response   
  13.         response = await call_next(request)
  14.         
  15.         return response
  17. app = FastAPI()
  18. # 添加自定义中间件
  19. app.add_middleware(MyMiddleware)

  复制代码
• 方式3：@app.middleware 装饰器
  在 FastAPI 中，可以利用 @app.middleware 装饰器来添加应用程序范围的中心件。
  即利用 @app.middleware 装饰器添加的中心件适用于整个 FastAPI 应用程序，通常用于实行全局操纵，例如身份验证、日志记载、异常处置惩罚等。这使得您可以在整个应用程序中共享相同的中心件逻辑，而不需要为每个路由重复添加相同的中心件。
  此装饰器可以接受以下两个参数：
  
  
  
  • middleware_type（必需）：字符串参数，用于指定中心件的类型。
    在 FastAPI 中，中心件可以分为以下两种类型：
    
    
    
    • “http”：HTTP 中心件
      这种中心件将在每个 HTTP 哀求处置惩罚期间实行，适用于处置惩罚 HTTP 哀求和响应的操纵。
      
    • “websocket”：WebSocket 中心件
      这种中心件将在 WebSocket 连接的处置惩罚期间实行，适用于处置惩罚 WebSocket 哀求和响应的操纵。
      
    
    
  • priority（可选）：整数参数，用于指定中心件的优先级。
    如果应用程序中有多个中心件，可以利用此参数来控制它们的实行顺序。
    较小的数字表示较高的优先级，中心件将按照优先级升序实行。
    如果不指定 priority 参数，中心件的默认优先级为 50。
    
  1. app = FastAPI()
  3. # 自定义中间件处理函数
  4. @app.middleware("http")
  5. async def log_requests(request: Request, call_next):
  6.     logger.info(f"Incoming request: {request.method} {request.url}")
  7.     response = await call_next(request)
  8.     logger.info(f"Outgoing response: {response.status_code}")
  9.     return response

  复制代码
  
  

websocket()：创建 WebSocket 路由

• websocket() 函数：创建 WebSocket 路由，从而实现与客户端之间的实时双向通信。
  WebSocket 是一种在单个长连接上举行全双工通信的协议，适用于需要实时更新数据的应用场景，例如聊天应用、实时数据展示等。
  在客户端，可以利用浏览器内置的 WebSocket API 或其他 WebSocket 客户端库来与 FastAPI WebSocket 路由举行通信。
  
• 代码示例：
  
  1. from fastapi import FastAPI, WebSocket
  3. app = FastAPI()
  5. # WebSocket 路由
  6. @app.websocket("/ws")
  7. async def websocket_endpoint(websocket: WebSocket):
  8.     await websocket.accept()
  9.     while True:
  10.         data = await websocket.receive_text()
  11.         await websocket.send_text(f"You said: {data}")

  复制代码
  
  
  • 利用 app.websocket() 方法创建了一个 /ws 的 WebSocket 路由。在 WebSocket 连接创建后，利用 await websocket.accept() 方法接受连接。
    
  • 然后，在一个无限循环中利用 await websocket.receive_text() 方法吸收客户端发送的文本消息，并利用 await websocket.send_text() 方法将消息返回给客户端。
    
  
  

mount()：安装子应用程序（静态文件）

• mount() 函数：用于将另一个 ASGI 应用程序安装为 FastAPI 应用程序的子应用程序。
  利用 mount 安装子应用程序可以方便的将多个应用程序组合在一起，实现更复杂的应用程序逻辑结构。例如，将多个 API 应用程序组装成一个网关应用程序，将多个应用程序组装成一个单页面应用程序等等。
  支持参数：
  
  
  
  • path ：类型为字符串，必传参数，指定 url 访问的路径
    
  • app ：类型为 ASGIApp，必传参数，挂载的是静态文件对象
    
    
    
    • directory ：指定挂载的是静态文件目次
      
    
    
  • name ：指定 fastapi 内部利用的名称。默以为 None
    
  
  
• 访问静态文件方式：直接在浏览器输入 ip:端口/路径/文件全名.后缀 即可
  
• 代码示例（设置静态文件路径）：
  
  1. import uvicorn
  2. from fastapi import FastAPI
  3. from fastapi.staticfiles import StaticFiles
  5. app = FastAPI()
  6. # 配置静态文件路径
  7. app.mount("/static", StaticFiles(directory="static"), name="static")
  8. uvicorn.run(app="main:app", host="0.0.0.0", port=8000, reload=True)

  复制代码

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。