aiohttp：基于 asyncio 的 HTTP 客户端与服务端框架｜安装与使用指南

aiohttp 官方 Logo

仓库：https://github.com/aio-libs/aiohttp 官方文档：https://docs.aiohttp.org/ 许可证：Apache-2.0 定位：asyncio 原生的 HTTP 客户端与服务端框架

1. 项目简介与定位

aiohttp 是 aio-libs 团队维护的、基于 Python asyncio 的 HTTP 框架。官方 README 第一句话就是 "Async http client/server framework"：它既是异步 HTTP 客户端，也是异步 Web 服务端，并且两端都开箱支持 WebSocket。

它不是 requests 的异步替代品那么简单：客户端侧用 ClientSession 发请求，服务端侧用 web.Application 起一个带路由、中间件的 Web 服务器，二者共用同一套事件循环。

1.1 核心信息一览

项目	内容
仓库	aio-libs/aiohttp
定位	asyncio HTTP 客户端 + 服务端 + WebSocket
开源协议	Apache-2.0
安装方式	`pip install aiohttp`
运行时	Python 3 + asyncio
官方文档	https://docs.aiohttp.org/

1.2 适用场景

需要高并发异步抓取，用 ClientSession 配合 asyncio.gather 同时打大量请求；
想顺手用同一个事件循环起一个轻量异步 Web 服务；
需要原生 WebSocket 客户端或服务端；
已经在 FastAPI / Sanic 之外，想要一个更底层、更接近 stdlib 风格的异步 HTTP 框架。

2. 开源协议

3. 官方仓库链接

仓库主页：https://github.com/aio-libs/aiohttp
官方文档：https://docs.aiohttp.org/
Demos 集合：https://github.com/aio-libs/aiohttp-demos
第三方库列表：https://aiohttp.readthedocs.io/en/latest/third_party.html
Discussions：https://github.com/aio-libs/aiohttp/discussions
Matrix 社区：#aio-libs:matrix.org
Stack Overflow 标签：https://stackoverflow.com/questions/tagged/aiohttp

4. 前置要求

来自官方 README "Requirements" 章节：

Python 3（README 未在正文钉死最低版本，以 PyPI 页面 Requires-Python 为准；安装时 pip 会自动拒绝不兼容的 Python）；
必装依赖（pip 自动处理）：multidict、yarl、frozenlist；
可选但官方推荐：aiodns（提升 DNS 解析速度）；
操作系统：Linux / macOS / Windows 均可；
如用作服务端，需要一个可监听的 TCP 端口（README 示例 web.run_app(app) 默认起在 8080，可在调用时自行指定 host/port）。

5. 安装部署

通过 pip 安装（标准做法，官方 Demos 与文档均采用）：

$ pip install aiohttp

如要顺带装上推荐的异步 DNS 加速：

$ pip install aiohttp aiodns

依赖 multidict、yarl、frozenlist 会由 pip 自动拉取，无需手动安装。

6. 最小示例代码

6.1 客户端（官方 README 原文示例）

import aiohttp
import asyncio

async def main():

    async with aiohttp.ClientSession() as session:
        async with session.get('https://python.org') as response:

            print("Status:", response.status)
            print("Content-type:", response.headers['content-type'])

            html = await response.text()
            print("Body:", html[:15], "...")

asyncio.run(main())

官方给出的输出：

Status: 200
Content-type: text/html; charset=utf-8
Body: <!doctype html> ...

6.2 服务端（官方 README 原文示例）

# examples/server_simple.py
from aiohttp import web

async def handle(request):
    name = request.match_info.get('name', "Anonymous")
    text = "Hello, " + name
    return web.Response(text=text)

async def wshandle(request):
    ws = web.WebSocketResponse()
    await ws.prepare(request)

    async for msg in ws:
        if msg.type == web.WSMsgType.text:
            await ws.send_str("Hello, {}".format(msg.data))
        elif msg.type == web.WSMsgType.binary:
            await ws.send_bytes(msg.data)
        elif msg.type == web.WSMsgType.close:
            break

    return ws


app = web.Application()
app.add_routes([web.get('/', handle),
                web.get('/echo', wshandle),
                web.get('/{name}', handle)])

if __name__ == '__main__':
    web.run_app(app)

7. 配置项

aiohttp 没有独立配置文件，配置通过构造参数传入：

配置点	作用
`ClientSession(...)`	客户端会话：默认 headers、cookies、auth、超时、连接池大小
`session.get/post/...`	单次请求的 params、data、json、headers、timeout
`web.Application()`	服务端应用实例，注册路由与中间件
`web.run_app(app, host=..., port=...)`	启动服务时指定监听地址与端口
`WebSocketResponse`	WebSocket 会话，通过 `prepare(request)` 升级

官方在 README 末尾还专门写了一篇《why we need so many lines》解释为什么异步客户端不能像 `requests.get(...)` 那样一行完事——ClientSession 应当被复用而不是每次新建。

8. 常见问题

为什么不能直接 aiohttp.get(url)？ 官方建议复用 ClientSession，它内部维护连接池与 Cookie 持久化；每次新建 session 会丢失连接池复用。
和 requests 写法差这么多？ 官方专门写了一篇文章解释异步请求生命周期，从 requests 迁移过去建议先读那篇。
Windows 上 asyncio 报事件循环策略警告？ 新版 aiohttp 配合 Python 3.8+ 默认使用 Proactor 事件循环，遇到问题可参考官方文档 Windows 章节。
服务端默认端口是多少？ web.run_app(app) 不传参时由 aiohttp 自行选择并打印到控制台日志，不是固定端口；生产环境建议显式传 host 与 port。
怎么加速 DNS？ 装 aiodns，官方 README 在 Requirements 里强烈推荐。
想 benchmark 性能？ 官方 Wiki 维护了一份 asyncio 生态 benchmark 列表：https://github.com/python/asyncio/wiki/Benchmarks。

9. 与同类工具对比

vs requests：requests 是同步阻塞、API 极简；aiohttp 异步、并发高，但写法必须放进 async/await。
vs httpx：httpx 同时提供同步与异步 API，更贴近 requests 风格；aiohttp 是纯异步，且额外提供生产级 Web 服务端能力。
vs urllib3：urllib3 是底层连接池库；aiohttp 是完整的 asyncio HTTP 客户端/服务端框架。
vs FastAPI / Sanic：后两者是建在 ASGI 之上的 Web 框架，带依赖注入、自动文档；aiohttp 更底层，路由与中间件都要自己写，但也更轻量。

10. 许可

aiohttp 以 Apache License 2.0 发布：

允许个人与商业使用、修改、再分发；
包含明确的专利授权条款；
再分发时需保留 LICENSE 与版权声明；
修改过的文件建议标注变更。

具体条款以仓库 LICENSE.txt 原文为准。

11. 责任使用声明

使用 aiohttp 进行网页数据采集时，请遵守以下原则：

遵守目标网站的 robots.txt 与服务条款（ToS），不采集明确禁止抓取的路径；
控制并发数并在请求之间加入延时，避免高并发把目标服务器打挂；
不绕过登录态、付费墙或反爬机制，不伪造身份获取付费内容；
不批量抓取个人隐私数据，不收集、存储、传播可识别个人身份的信息；
仅将采集到的公开数据用于学习、研究与合规的业务用途；
尊重原作者版权，转载或二次发布数据时注明来源并遵守相应授权。