Uvicorn入门指南 – wiki大全

作者： /

Uvicorn 入门指南

在现代 Python Web 开发中，性能和异步处理能力变得越来越重要。Uvicorn 正是为此而生，它是一个高性能的 ASGI (Asynchronous Server Gateway Interface) 服务器，专为异步 Python Web 框架（如 FastAPI、Starlette 等）设计。本文将详细介绍 Uvicorn 的安装、基本使用以及一些高级配置，帮助您快速入门。

1. 引言

什么是 Uvicorn？

Uvicorn 是一个用 Python 编写的 ASGI 服务器实现。ASGI 是 Python 异步 Web 应用程序和服务器之间的一种标准接口，它扩展了传统的 WSGI 接口，以支持异步操作、WebSocket 和 HTTP/2 等现代 Web 特性。Uvicorn 利用 uvloop (一个快速的 asyncio 事件循环实现) 和 httptools (一个快速的 HTTP 解析器) 来提供卓越的性能，使其成为部署高性能异步 Python Web 应用的理想选择。

为什么选择 Uvicorn？

  • 高性能: 基于 uvloop 和 httptools，Uvicorn 能够高效地处理大量并发请求，响应速度极快。
  • ASGI 兼容: 完全遵循 ASGI 规范，这意味着它可以与任何基于 ASGI 的框架无缝协作，如 FastAPI、Starlette、Sanic 等。
  • 支持多种协议: 除了标准的 HTTP/1.1，Uvicorn 还原生支持 WebSocket，非常适合构建实时通信应用。
  • 易于使用: 无论是在开发环境还是生产环境，Uvicorn 都提供了简单直观的命令行接口和编程接口来启动和配置服务器。

2. 安装 Uvicorn

安装 Uvicorn 非常简单，推荐使用 pip 包管理器。为了获得最佳性能，建议安装包含 uvloop 和 httptools 的优化版本：

bash
pip install "uvicorn[standard]"

如果您只需要基本功能，也可以只安装核心版本：

bash
pip install uvicorn

3. 创建一个简单的 ASGI 应用

Uvicorn 需要一个 ASGI 应用才能运行。最常见的场景是与 FastAPI 这样的现代异步 Web 框架结合使用。这里我们以 FastAPI 为例，创建一个简单的 ASGI 应用。

首先，如果您尚未安装 FastAPI，请安装它：

bash
pip install fastapi

接下来，创建一个名为 main.py 的文件，并添加以下内容：

“`python

main.py

from fastapi import FastAPI

app = FastAPI()

@app.get(“/”)
async def read_root():
return {“message”: “Hello, Uvicorn!”}

@app.get(“/items/{item_id}”)
async def read_item(item_id: int, q: str = None):
return {“item_id”: item_id, “q”: q}
“`

这个 main.py 文件定义了一个 FastAPI 应用程序 app，包含了两个简单的路由：
* /: 访问时返回一个 JSON 消息 {"message": "Hello, Uvicorn!"}。
* /items/{item_id}: 接受一个路径参数 item_id 和一个可选的查询参数 q。

4. 运行 Uvicorn 服务器

有了 ASGI 应用后，您就可以使用 Uvicorn 来运行它了。

命令行方式运行

在 main.py 文件所在的目录中，打开终端并执行以下命令来启动 Uvicorn 服务器：

bash
uvicorn main:app --reload

这条命令的含义如下：
* uvicorn: 启动 Uvicorn 服务器的命令。
* main: 指代 main.py 这个 Python 模块文件（不带 .py 后缀）。
* app: 指代 main.py 文件中定义的 ASGI 应用程序实例（即 app = FastAPI() 中的 app 对象）。
* --reload: 这是一个非常有用的开发选项。当您修改 main.py 或其他相关代码文件并保存时，Uvicorn 会自动重启服务器，方便开发调试。

默认情况下，Uvicorn 会在 http://127.0.0.1:8000 上启动服务器。您可以在浏览器中访问 http://127.0.0.1:8000 来查看 “Hello, Uvicorn!” 的消息，或者访问 http://127.0.0.1:8000/docs 查看 FastAPI 自动生成的 API 文档。

常用命令行选项

Uvicorn 提供了丰富的命令行选项来配置服务器行为：

  • --host <IP地址>: 指定服务器监听的主机地址。例如，--host 0.0.0.0 会使服务器监听所有可用的网络接口，允许从任何 IP 地址访问。默认值为 127.0.0.1 (仅限本地访问)。
  • --port <端口号>: 指定服务器监听的端口号。例如，--port 8080 会在 8080 端口启动服务器。默认值为 8000。
  • --workers <数量>: 指定运行应用程序的工作进程数量。这在生产环境中很有用，可以利用多核 CPU 提高并发处理能力。例如，--workers 4。
  • --log-level <级别>: 设置日志的输出级别，可选值包括 debug, info, warning, error, critical。默认值为 info。
  • --app-dir <目录>: 指定应用程序文件所在的目录，如果您的 main.py 不在当前目录时非常有用。

例如，要在 9000 端口启动一个日志级别为 debug 的服务器，您可以使用：

bash
uvicorn main:app --port 9000 --log-level debug

5. 编程方式运行 Uvicorn

在某些生产部署场景或自动化脚本中，您可能希望通过 Python 代码来更精细地控制 Uvicorn 的启动和配置，而不是仅仅依赖命令行。Uvicorn 提供了 uvicorn.run() 函数来实现这一点。

您可以修改 main.py 文件，在底部添加以下代码块：

“`python

main.py (续)

import uvicorn

if name == “main“:
uvicorn.run(
“main:app”,
host=”0.0.0.0″,
port=8000,
log_level=”info”,
reload=True # 在开发环境可设置为 True
)
“`

现在，您可以像运行普通 Python 脚本一样执行 python main.py 来启动服务器。uvicorn.run() 函数接受与命令行选项相对应的参数，让您可以在代码中完全控制 Uvicorn 的启动配置。

6. 总结

Uvicorn 作为 ASGI 服务器的卓越实现，为异步 Python Web 应用程序提供了高性能的运行环境。无论是与 FastAPI、Starlette 还是其他 ASGI 框架配合，它都能提供快速、可靠的服务。通过本文的入门指南，您应该已经掌握了 Uvicorn 的基本概念、安装方法、如何运行一个简单的应用以及如何进行常见的配置。现在，您可以利用 Uvicorn 部署您的异步 Python Web 应用，享受它带来的高性能和开发便利。

滚动至顶部