uvicorn 极简教程：Python 的 ASGI Web 服务器

• main: 你的 Python 文件名（main.py）。
• app: 文件中实例化的对象名（比如 app = FastAPI()）。
• --reload: 开发模式神器。代码修改后自动重启服务器。

常用参数速查

4. 代码中启动 (脚本方式)

如果你想直接运行 Python 文件来启动服务器（方便调试）：

# main.py 文件底部
import uvicorn
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def root():
    return "OK"

if __name__ == "__main__":
    # 等同于命令行：uvicorn main:app --reload
    uvicorn.run("main:app", host="127.0.0.1", port=8000, reload=True)

运行方法：python main.py

5. 生产环境部署建议

在生产环境中（Linux），通常不直接裸跑 Uvicorn，而是使用 Gunicorn 作为进程管理器来管理 Uvicorn 的 Worker，以获得更好的稳定性和性能。

安装:

pip install gunicorn 

运行命令:

gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker 

• -w 4: 开启 4 个 Worker 进程。
• -k ...: 指定使用 Uvicorn 的 Worker 类。

uvloop 详解

这是一个关于 uvloop 的极简教程。uvloop 是 Python 标准库 asyncio 的高性能替代品。

1. 什么是 uvloop？

一句话介绍： 它是 Python 标准库 asyncio 的高性能替代品。

• 核心： 基于 libuv（Node.js 也在用这个库）构建。
• 效果： 让 Python 的异步代码运行速度提高 2-4 倍，性能直逼 Go 和 Node.js。
• 适用： Linux 和 macOS（不支持 Windows）。

2. 安装

pip install uvloop 

3. 如何使用

使用非常简单，只需要添加两行代码：引入库，然后调用 install()。

标准用法（推荐）

import asyncio
import uvloop

async def main():
    print("Hello, uvloop!")
    await asyncio.sleep(1)
    print("Done.")

if __name__ == "__main__":
    # 安装 uvloop 策略
    # 这行代码会将 asyncio 的默认事件循环替换为 uvloop
    uvloop.install()
    asyncio.run(main())

更推荐的'极简用法'：uvloop.run()

从 uvloop 0.18 开始，官方 README 推荐直接用 uvloop.run() 作为入口（它会把 asyncio.run() 配置成使用 uvloop）。

import asyncio
import uvloop

async def main():
    await asyncio.sleep(0.1)
    print("hello from uvloop")

uvloop.run(main())

4. 在 Web 框架中使用

如果你是做 Web 开发（FastAPI, Sanic, Django 等），通常不需要手动写代码。

• Sanic: Sanic 默认内置并使用 uvloop，无需额外操作。
• Gunicorn: 如果使用 Gunicorn 部署 Uvicorn worker，它也会自动继承 Uvicorn 的行为（自动使用 uvloop）。
• Uvicorn (FastAPI 的默认服务器): Uvicorn 默认就会检测并使用 uvloop。只要你安装了它，Uvicorn 就会自动启用。

# 只要安装了 uvloop，启动时不需要额外配置
pip install uvloop
uvicorn main:app 

如果想强制使用或禁用： uvicorn main:app --loop uvloop 或 --loop asyncio。

5. 注意事项

1. 操作系统限制： uvloop 不支持 Windows。如果在 Windows 上开发，请使用标准 asyncio，部署到 Linux 服务器时再安装 uvloop。
2. 兼容性： 虽然它力求与 asyncio 100% 兼容，但在极少数使用底层 API 的库中可能会有问题（非常罕见）。
3. 已有事件循环环境： Jupyter Notebook 或 IPython 中，因为环境已经在这个 Event Loop 中运行，直接 uvloop.install() 可能会报错或无效。

技巧： 可以用 try...except 兼容：

try:
    import uvloop
    uvloop.install()
except ImportError:
    pass # Windows 下没有 uvloop，回退到标准 asyncio

6. uvloop 原理深度解析

uvloop 之所以快，并不是因为它使用了什么魔法，而是因为它通过 Cython 将 Python 标准库 asyncio 的核心逻辑（事件循环）用 C 语言 重新写了一遍，底层则由高性能的 libuv 驱动。

可以将它的原理拆解为三个核心支柱：核心引擎 (libuv)、桥梁技术 (Cython) 和 极度优化的内存管理。

1. 核心引擎：libuv

uvloop 的名字就来源于 libuv。

• 什么是 libuv？ 它是 Node.js 的核心异步 I/O 库。它非常成熟、稳定且极快。
• 它做什么？ 它负责处理底层的操作系统通知。比如'网卡收到数据了'、'文件读取完毕了'。
• 为什么快？ 它在 Linux 上使用 epoll，在 macOS 上使用 kqueue，这些是操作系统能够提供的最高效的 I/O 通知机制。

2. 桥梁技术：Cython

这是 uvloop 最关键的实现细节。uvloop 不是简单地用 Python 调 C 库，而是用 Cython 编写的。

• 完全替换： uvloop 并不是'修补'了 asyncio，而是实现了 asyncio.AbstractEventLoop 接口的一个全新类。
• 绕过 Python 解释器：
  • 原生 asyncio： 事件循环的调度逻辑主要是 Python 代码。每次循环、每个回调，都要在 Python 解释器层面跑很多指令，产生大量 CPU 开销。
  • uvloop： 整个事件循环的'心跳'是在 C 语言层面（通过 Cython 编译）运行的。只有到了必须执行用户写的 Python 回调函数（比如你的 async def）时，它才会切换回 Python。

3. 性能优化的'黑魔法'

仅仅用 C 重写并不足以达到现在的速度，uvloop 的作者（MagicStack 团队）在实现细节上做了大量优化：

A. 零损耗的内存管理 (Memory Management)

在异步编程中，会频繁创建小的对象（比如 Future 对象、Task 对象、Handle 对象）。

• 原生 asyncio： 每次操作都可能分配新的 Python 对象，造成内存碎片和 GC（垃圾回收）压力。
• uvloop： 使用了 Free list（空闲链表） 技术。它会重用已经被废弃的 C 结构体内存，而不是反复向操作系统申请和释放内存。这极大地减少了内存分配的开销。

B. 函数调用开销最小化

Python 的函数调用是有开销的（参数解包、栈帧创建等）。

• uvloop 在内部处理 libuv 的回调时，尽可能保持在 C 层面流转，只有在最后一步才将数据转化为 Python 对象传给用户代码。

C. 高效的句柄 (Handle) 管理

uvloop 针对不同类型的 I/O（TCP, UDP, Pipe, Signal）进行了专门的优化路径，而不是使用通用的低效封装。

4. 架构对比图

为了直观理解，我们可以对比一下调用路径：

原生 asyncio 的路径：

Python 代码 -> asyncio (Python 循环) -> Select/Epoll (C 模块) -> 操作系统

uvloop 的路径：

Python 代码 -> uvloop (C/Cython 循环) -> libuv (C 库) -> 操作系统

5. 源码阅读路径

如果你准备进一步刨源码，按这个顺序最容易建立整体感：

1. loop.pyx：loop 的初始化、call_soon_threadsafe 唤醒、signals self-pipe、reader/writer 注册等。
2. handles/async_.pyx：uv_async_t 封装，理解'跨线程唤醒'的 C 层路径。
3. cbhandles.pyx：TimerHandle 如何用 UVTimer（libuv timer）实现。
4. dns.pyx：DNS request 如何对接 libuv。
5. poll/udp/tcp/stream 等：transport/protocol 如何把 socket I/O 对接到 libuv 的 handle。