xutopia77

从“知”到“行”：AI技能革命与传统行业的破局之路

Wed, 10 Jun 2026 00:00:00 GMT

# 从“知”到“行”：AI技能革命与传统行业的破局之路当我们谈论AI时，曾经的焦点总是停留在“它知道多少”——能否背完人类所有的书籍、能否回答任何常识问题、能否生成流畅的文本。但2025年的AI产业正在经历一场静水流深的范式转移：**AI的核心竞争力已从“知识储备量”转向“技能熟练度”**。它不再满足于做一个无所不知的“百科全书”，而是开始沉下心来，像一个学徒一样，钻研各行各业最核心、最隐秘的实操手艺。这场从“知”到“行”的跨越，不仅重新定义了AI的能力边界，更将彻底重塑传统行业的生存逻辑。

一、AI学习重心的根本性转向：从显性知识到隐性手艺#

人工智能的发展历程，本质上是一部不断拓展学习边界的历史。早期的大模型依托互联网上海量的文本数据，完成了对人类显性知识的全面吸收。它能精准复述理论定义、背诵历史事件、解释科学原理，甚至能写出逻辑严谨的论文。但这种“知道”始终停留在“是什么”和“为什么”的层面，一旦触及“怎么做”的实操环节，就常常显得力不从心。

而如今的智能体，正在攻克人类知识体系中最难以被编码的部分——隐性手艺。这是一种只可意会不可言传的经验，是行业专家经过成千上万次实践沉淀下来的直觉、技巧和流程。它不是写在教科书上的公式，而是建筑设计师调整外立面弧度时对光影的微妙把握；不是三维建模软件的操作手册，而是拓扑布线时为了后续渲染更流畅而做出的取舍；不是财务报表的模板，而是老会计在核对账目时一眼就能发现异常的敏锐。

今天的AI，正在系统性地学习这些“过程性知识”。在建筑设计领域，它不再只是生成一张好看的效果图，而是能完整走完从概念方案、平面布局、结构计算到施工图绘制的全流程，甚至能模拟不同施工方案的成本和工期；在视觉创作领域，它不再只是根据文字生成图片，而是能熟练操控Photoshop、Blender等专业软件，精准调整图层、参数、材质和光影，还原设计师反复修改的打磨过程；在财务办公领域，它能自动完成发票识别、凭证录入、对账结账到税务申报的完整闭环，还能根据历史数据预判财务风险。

这种学习重心的转变，标志着AI真正从“辅助工具”进化为“执行主体”。过去，AI只能帮人类“省脑子”；现在，它开始帮人类“省手脚”。它不再需要人类把每一个步骤拆解成指令，而是能自己理解任务目标，自主规划执行路径，甚至能在遇到问题时主动调整策略。

二、技术落地的铁证：当AI学会操控专业软件#

这场技能革命不是纸上谈兵，而是已经在多个行业落地生根，产生了实实在在的生产力提升。其中最具标志性的现象，就是AI对专业软件的原生操控能力。

过去，AI与专业软件的结合，大多停留在“插件式”的辅助层面——比如在设计软件里加一个AI生成素材的按钮，在办公软件里加一个AI写文案的功能。但现在的智能体，已经能像人类员工一样，直接打开软件、点击菜单、拖动滑块、输入参数，完成一整套复杂的操作。

在三维建模领域，新一代AI智能体可以仅凭一段文字描述，就在Blender中自动完成从基础建模、拓扑优化、UV展开、材质贴图到灯光渲染的全流程。它不仅能生成符合要求的模型，还能输出可编辑的工程文件，保留所有的图层和参数，方便人类设计师后续修改。在建筑行业，AI已经能根据地块条件和设计要求，自动生成多套符合国家规范的建筑方案，并且能直接导出CAD施工图和BIM模型，大大缩短了设计周期。在工业设计领域，AI能操控SolidWorks等软件完成产品的结构设计和力学仿真，甚至能根据生产工艺的要求自动优化设计方案。

这些案例有力地证明了：当AI掌握了行业的实操方法和专业技法后，其工作能力会呈现出指数级的提升。它不仅能完成人类能做的工作，还能以更快的速度、更低的成本、更稳定的质量完成重复性的劳动。这使得人类专家可以从繁琐的执行性工作中解放出来，专注于更具创造性和战略性的任务。

三、FDE：连接AI与传统行业的关键桥梁#

AI技能革命的背后，有一个容易被忽视但至关重要的角色——前线部署工程师（Frontline Deployment Engineer，FDE）。他们是连接通用大模型与垂直行业的桥梁，是AI学会隐性手艺的“师傅”。

FDE的工作本质，是把行业专家的大脑“数字化”。他们深入传统行业的一线，与最资深的专家并肩工作，观察他们的操作流程，拆解他们的决策逻辑，提炼他们的经验技巧。然后，他们把这些模糊的、碎片化的隐性知识，转化为标准化的、可复用的技能模块——包括详细的工作流、关键的参数阈值、常见的问题解决方案以及异常情况的处理机制。这些技能模块会被用来微调大模型，或者构建成专属的智能体，让AI能够快速掌握一个行业的核心能力。

与传统的数据标注员不同，FDE需要同时具备AI技术素养和行业认知能力。他们不仅要懂大模型的原理和prompt工程，还要懂建筑设计的规范、三维建模的技巧、财务核算的规则。他们不是简单地把专家的操作记录下来，而是要对这些操作进行抽象和提炼，找出其中的共性和规律，让AI能够举一反三。

更重要的是，FDE的工作是一个持续迭代的过程。他们会收集AI在实际工作中遇到的问题，反馈给行业专家，然后不断优化技能模块，让AI的能力越来越强。这种“专家经验-FDE转化-AI落地-反馈优化”的闭环，是AI吃透垂直领域的核心动力。可以说，未来哪个行业拥有更多优秀的FDE，哪个行业的AI落地速度就会更快，效果就会更好。

四、传统行业的破局之道：从固守壁垒到开放共生#

AI技能革命的到来，给传统行业带来了前所未有的挑战，也带来了千载难逢的机遇。很多传统企业的第一反应是筑起高墙，把自己的内部经验和流程封闭起来，试图以此阻挡AI的冲击。但这种做法无异于螳臂当车。

因为AI的发展速度远远超过了大多数人的想象。今天你引以为傲的核心经验，明天可能就会被AI学会并超越。固守数据壁垒，不仅无法阻挡AI的发展，反而会让自己与时代脱节。当你的竞争对手已经在用AI把效率提升几倍的时候，你还在用传统的方式慢慢打磨，最终只会被市场淘汰。

对于传统企业来说，更明智的做法是顺势而为，主动拥抱AI。你不必花费巨资去自研通用大模型——那是科技巨头的战场。你的核心竞争力，不在于拥有一个大模型，而在于拥有别人没有的行业经验和流程。你要做的，是把这些隐性的、分散在员工大脑里的经验，转化为可训练、可复用的过程资产。

具体来说，企业可以按照以下步骤进行转型：

梳理核心流程：对企业内部的所有业务流程进行全面梳理，找出哪些环节是重复性高、标准化程度高的，哪些环节是依赖专家经验的。
提炼隐性知识：组织资深专家和FDE一起，把核心环节的操作步骤、决策逻辑、经验技巧提炼出来，形成标准化的技能库。
对接AI能力：基于通用大模型，结合自己的技能库，打造专属的企业智能体，让AI成为每个员工的“数字助手”。
优化组织架构：调整企业的组织架构和工作模式，让人类员工和AI智能体能够高效协作。人类负责创意、决策和沟通，AI负责执行、计算和数据处理。

通过这种方式，企业不仅能大幅提升运营效率，降低成本，还能把自己的核心经验沉淀为企业的数字资产，实现可持续发展。

结语：技能时代，人与AI的共生未来#

从“知识型AI”到“技能型AI”，我们正在见证人工智能发展史上的一个重要里程碑。这场革命的最终目标，不是用AI取代人类，而是让AI成为人类能力的延伸。它将把人类从繁琐的体力劳动和重复性的脑力劳动中解放出来，让我们有更多的时间和精力去追求更有价值的事情——创造、探索、关爱。

对于传统行业来说，这是一个最好的时代，也是一个最坏的时代。那些能够主动拥抱变化，把自己的经验转化为AI能力的企业，将迎来指数级的增长；而那些固守陈规，拒绝改变的企业，终将被时代的浪潮所淹没。未来的竞争，不再是人与人之间的竞争，而是“人+AI”与“人+AI”之间的竞争。谁能更好地驾驭AI的技能，谁就能在未来的市场中占据先机。

AI新时代软件开发范式：从传统研发到LLM原生工程体系的革命性变革

Mon, 20 Apr 2026 00:00:00 GMT

🚀 AI新时代软件开发范式：从传统研发到LLM原生工程体系的革命性变革#

📖 引言：AI时代的软件开发革命#

随着大语言模型（LLM）技术的飞速发展，软件开发行业正经历着一场前所未有的范式革命。传统的软件开发模式——从需求分析、设计、编码、测试到部署——正在被以AI为核心生产力的新一代研发范式所重塑。这场变革不仅仅是工具的升级，更是整个软件工程体系的重构。

面向LLM原生软件工程体系，我们重构了传统瀑布式研发的核心链路，形成了以AI为核心生产力的新一代研发范式。这不仅仅是效率的提升，更是软件开发思维的根本性转变。

🎯 LLM原生软件工程体系的五大核心阶段#

1. 📋 需求锚定阶段：从模糊想法到精准定义#

⚠️ 传统模式痛点：需求文档往往模糊不清，开发过程中频繁变更，导致项目延期和质量问题。

✨ AI时代解决方案：

📄 产品端输出PRD（Product Requirements Document），完成业务价值与产品形态的顶层定义
🤖 AI辅助需求分析，通过自然语言处理技术识别需求中的模糊点和潜在冲突
📊 智能需求优先级排序，基于业务价值和实现难度自动推荐开发顺序
🔍 需求可行性预评估，AI快速判断技术实现难度和风险点

💡 核心价值：确保需求的清晰性、完整性和可实现性，为后续开发奠定坚实基础。

2. 🔧 规格拆解阶段：从业务需求到技术规格#

⚠️ 传统模式痛点：需求到设计的转化依赖个人经验，规格文档质量参差不齐，开发理解偏差大。

✨ AI时代解决方案：

📝 将非结构化业务需求转化为标准化FS（Functional Specification）功能规格文档
⚙️ 完成功能边界、输入输出、异常处理、验收标准的原子化定义
🎯 为LLM代码生成提供精准的Prompt工程底座
🏗️ AI自动生成接口定义、数据模型、业务流程图等技术规格
🚨 智能识别技术债务和潜在架构问题

💡 核心价值：建立标准化的技术规格体系，为AI代码生成提供高质量输入。

3. 💻 代码生成阶段：从手工编码到智能生成#

⚠️ 传统模式痛点：编码效率低，重复劳动多，代码质量依赖个人能力，开发周期长。

✨ AI时代解决方案：

🚀 基于功能规格说明书，通过代码大模型实现端到端的业务代码自动化生成
🧪 自动生成单元测试用例，提升测试覆盖率
🔧 AI辅助代码优化，自动重构低质量代码
⚡ 智能代码补全和生成，大幅提升编码效率
🌐 支持多种编程语言和框架的代码生成

💡 核心价值：完成研发环节的核心生产力替代，实现编码环节的自动化和智能化。

4. 🔍 智能评审阶段：从人工审查到AI增强#

⚠️ 传统模式痛点：代码评审依赖人工，效率低、覆盖不全，容易漏掉潜在问题。

✨ AI时代解决方案：

🤖 通过AI增强型代码评审体系，结合静态代码扫描、安全合规检测
✅ 逻辑一致性校验，确保代码实现与规格文档的一致性
🐛 自动识别代码异味、潜在bug、性能问题
💬 智能生成评审意见和改进建议
📋 完成全量代码的自动化复核，替代传统人工评审的核心流程

💡 核心价值：保障代码质量与可维护性，提升评审效率和覆盖度。

5. 🚀 集成交付阶段：从手动部署到自动化流水线#

⚠️ 传统模式痛点：部署过程复杂，容易出错，回滚困难，交付周期长。

✨ AI时代解决方案：

🔄 完成评审的代码通过标准化CI/CD流水线
📦 自动合入代码仓库主干分支，纳入版本迭代体系
🧪 AI辅助测试用例生成和执行
📊 智能监控和告警，自动识别生产环境问题
✅ 完成从需求到代码的全链路闭环

💡 核心价值：实现持续集成和持续交付，缩短交付周期，提升部署可靠性。

🌟 AI新时代开发范式的核心优势#

1. 📈 效率革命性提升#

开发效率提升3-5倍：AI代码生成大幅减少手工编码时间
需求到交付周期缩短60%以上：自动化流程减少等待和重复工作
代码质量显著提升：AI评审发现更多潜在问题

2. 🛡️ 质量保障全面强化#

测试覆盖率提升：自动生成测试用例，覆盖更多边界情况
代码一致性增强：标准化规格确保代码风格统一
安全性提升：AI安全扫描提前发现安全漏洞

3. 👥 团队协作优化升级#

沟通成本降低：标准化文档减少理解偏差
知识沉淀加速：AI辅助生成文档和注释
新人上手更快：标准化流程降低学习曲线

4. 💡 创新能力显著增强#

快速原型验证：AI快速生成原型代码，加速创新迭代
技术债务减少：AI自动识别和重构低质量代码
架构优化建议：AI分析代码库，提供架构改进建议

📊 实际应用案例#

案例1：🛒 电商平台后台管理系统重构#

传统模式：6个月开发周期，10人团队，多次延期

AI新模式：

📋 需求分析：AI辅助PRD生成，2天完成
🔧 规格拆解：自动生成FS文档，1周完成
💻 代码生成：AI生成80%核心代码，3周完成
🔍 智能评审：AI评审覆盖率100%，1周完成
🚀 集成交付：自动化CI/CD，持续交付

🎯 结果：2个月完成开发，团队规模缩减至4人，质量提升30%

案例2：💰 金融风控系统开发#

传统模式：复杂业务逻辑，开发难度大，测试周期长

AI新模式：

🧠 AI辅助复杂业务逻辑理解和规格定义
🛡️ 自动生成符合金融合规要求的代码
🔒 AI安全扫描确保代码安全性
🧪 自动生成测试用例，覆盖各种风控场景

🎯 结果：开发周期缩短50%，代码质量显著提升，合规性100%

⚠️ 面临的挑战与应对策略#

1. 🤔 AI生成代码的可信度问题#

挑战：AI可能生成有缺陷或不安全的代码

应对：

✅ 建立完善的AI代码评审体系
👤 人工关键环节把关
🔄 持续优化AI模型和Prompt工程

2. 🎓 团队技能转型压力#

挑战：传统开发者需要学习AI工具和新的工作方式

应对：

📚 系统化培训AI工具使用
📖 建立AI辅助开发的最佳实践
🚀 渐进式引入AI工具，降低转型阻力

3. 🔐 数据安全和隐私保护#

挑战：代码和数据可能涉及敏感信息

应对：

🏢 使用私有化部署的AI模型
🛡️ 建立数据脱敏和访问控制机制
⚖️ 符合相关法律法规要求

4. 🔄 AI模型的持续优化#

挑战：AI模型需要不断训练和优化以适应业务需求

应对：

📊 建立模型反馈和优化机制
🎯 收集和使用高质量训练数据
📈 定期评估和更新模型性能

🔮 未来展望#

1. 🌟 AI原生开发将成为主流#

未来3-5年，AI原生软件开发将成为行业标准，不采用AI的开发团队将失去竞争力。

2. 👨‍💻 开发者角色重新定义#

开发者将从”编码者”转变为”AI系统架构师”和”质量把关者”，更专注于业务逻辑和创新。

3. 🎓 软件工程教育体系重构#

传统的编程教育将转向AI辅助开发教育，培养学生的AI思维和系统设计能力。

4. 🛠️ 开发工具生态全面升级#

IDE、代码仓库、项目管理等工具将深度集成AI能力，形成完整的AI原生开发生态。

🎯 结语#

AI新时代的软件开发范式，不仅仅是技术的升级，更是思维方式的革命。从需求锚定到集成交付，AI正在重塑软件开发的每一个环节。拥抱这场变革，主动学习和实践AI原生开发模式，将成为每个软件开发者和团队的必然选择。

在这个AI驱动的时代，我们不仅要掌握工具的使用，更要理解背后的原理和思维模式。只有这样，才能真正发挥AI的潜力，创造出更优秀的软件产品，推动整个行业的进步。

AI新时代软件开发范式流程图

🧠第一性原理：从赚钱到系统复制的底层思维框架

Mon, 20 Apr 2026 00:00:00 GMT

第一性原理：从赚钱到系统复制的底层思维框架

第一性原理是一种思考方式，它要求我们回到事物的最基本事实，从最根本的真理出发，重新构建认知和解决方案。这种思维方式让我们跳出传统框架和经验主义的束缚，找到问题的本质。

赚钱的第一性原理，是创造价值，不是出卖时间。
创造价值的第一性原理，是解决问题，不是提供劳动。
解决问题的第一性原理，是识别真需求，不是自我感动。
识别真需求的第一性原理，是实践反馈，不是闭门造车。
实践反馈的第一性原理，是快速迭代，不是仔细打磨。
快速迭代的第一性原理，是验证模型，不是为了交付。
验证模型的第一性原理，是为了系统复制，而不是个人苦干。
系统复制的第一性原理，是杠杆思维，不是线性积累。

在不确定性中找到确定性，在复杂中找到简单，在变化中找到不变。

1776609030380

🟢 Node.js 完整笔记

Mon, 20 Apr 2026 00:00:00 GMT

Node.js 笔记#

Node.js 简介#

Node.js 是一个基于 Chrome V8 引擎的 JavaScript 运行时环境，允许在服务器端执行 JavaScript 代码。

特点：

事件驱动、非阻塞 I/O 模型
轻量高效，适合数据密集型实时应用
npm 是全球最大的开源库生态系统

版本说明：

LTS (Long Term Support)：长期稳定版，推荐生产环境使用
Current：最新特性版，包含最新功能但可能不稳定

安装 Node.js#

Windows 系统#

方式一：官网下载安装包

访问 Node.js 官网
下载 Windows Installer (.msi)
运行安装程序，一路 Next 即可

方式二：使用 Chocolatey

Terminal window

1
# 安装 Chocolatey (需管理员权限)
2
iwr https://chocolatey.org/install.ps1 -UseBasicParsing | iex
3

4
# 安装 Node.js
5
choco install nodejs

方式三：使用 Winget

Terminal window

1
winget install OpenJS.NodeJS
2
winget install OpenJS.NodeJS.LTS

macOS 系统#

方式一：官网下载安装包

访问 Node.js 官网
下载 macOS Installer (.pkg)
运行安装程序

方式二：使用 Homebrew

Terminal window

1
# 安装 Homebrew (若未安装)
2
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
3

4
# 安装 Node.js
5
brew install node
6

7
# 安装 LTS 版本
8
brew install node@lts

方式三：使用 nvm

Terminal window

1
# 安装 nvm (见下文 nvm 章节)

Linux 系统#

Ubuntu / Debian#

Terminal window展开收起

1
# 更新系统包
2
sudo apt update
3
sudo apt upgrade
4

5
# 移除旧版本(若有)
6
sudo apt remove nodejs npm
7

8
# 添加 NodeSource 仓库 (以 LTS 版本为例)
9
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
10

11
# 安装 Node.js
12
sudo apt-get install -y nodejs
13

14
# 验证安装
15
node -v
16
npm -v

展开收起

CentOS / RHEL / Fedora#

Terminal window

1
# 添加 NodeSource 仓库
2
curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
3

4
# 安装 Node.js
5
sudo yum install -y nodejs
6

7
# 或使用 dnf
8
sudo dnf install -y nodejs

Arch Linux#

Terminal window

1
sudo pacman -S nodejs npm

Alpine Linux#

Terminal window

1
apk add nodejs npm

Docker 环境中使用#

Terminal window

1
# 拉取官方镜像
2
docker pull node:latest
3
docker pull node:lts
4

5
# 运行交互式容器
6
docker run -it node:latest bash
7

8
# 运行特定版本
9
docker run -it node:18 bash

版本管理工具 nvm#

nvm (Node Version Manager) 允许在同一台机器上管理多个 Node.js 版本。

安装 nvm#

Linux / macOS

Terminal window

1
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

或使用 wget：

Terminal window

1
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

Windows Windows 系统使用 nvm-windows：

下载安装包：https://github.com/coreybutler/nvm-windows/releases
运行安装程序

nvm 常用命令#

Terminal window展开收起

1
# 安装 nvm-windows 后验证
2
nvm version
3

4
# 查看可用版本
5
nvm list available
6

7
# 安装最新稳定版
8
nvm install lts
9
nvm install --lts
10

11
# 安装最新版本
12
nvm install latest
13

14
# 安装指定版本
15
nvm install 18.17.0
16
nvm install 20
17

18
# 查看已安装版本
19
nvm list
20
nvm ls
21

22
# 切换使用某个版本
23
nvm use 18.17.0
24
nvm use lts
25

26
# 设置默认版本
27
nvm alias default 18.17.0
28

29
# 卸载指定版本
30
nvm uninstall 16.20.0
31

32
# 查看当前版本
33
nvm current
34

35
# 允许在特定版本上运行命令
36
nvm run 18.17.0 --version

展开收起

nvm 高级配置#

Terminal window

1
# 设置镜像 (解决国内下载慢的问题)
2
export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node
3

4
# 开启/关闭 node 版本自动切换
5
echo 'autoload -U add-zsh-hook' >> ~/.zshrc
6
load-nvmrc() { ... }  # 可配置自动读取 .nvmrc 文件

包管理器#

npm (Node Package Manager)#

npm 是 Node.js 默认的包管理器，集成在 Node.js 安装包中。

pnpm (Performant npm)#

pnpm 是一个快速、节省空间的包管理器，使用硬链接避免重复存储。

安装 pnpm

Terminal window

1
# 使用 npm 安装
2
npm install -g pnpm
3

4
# 使用 corepack 启用 (Node.js 16+)
5
corepack enable
6
corepack prepare pnpm@latest --activate
7

8
# 使用脚本安装
9
curl -fsSL https://get.pnpm.io/install.sh | sh -

pnpm 常用命令

Terminal window

1
pnpm install
2
pnpm add <package>
3
pnpm add <package> -D          # 开发依赖
4
pnpm add <package> -g           # 全局安装
5
pnpm remove <package>
6
pnpm update
7
pnpm outdated
8
pnpm list
9
pnpm list -g
10
pnpm run <script>
11
pnpm init

yarn#

安装 yarn

Terminal window

1
# 使用 npm 安装
2
npm install -g yarn
3

4
# 使用 corepack 启用
5
corepack enable
6
corepack prepare yarn@stable --activate

yarn 常用命令

Terminal window

1
yarn install
2
yarn add <package>
3
yarn add <package> --dev
4
yarn add <package> -g
5
yarn remove <package>
6
yarn upgrade
7
yarn upgrade-interactive
8
yarn list
9
yarn run <script>
10
yarn init
11
yarn info <package>

npm 常用命令#

基础命令#

Terminal window

1
# 查看 npm 版本
2
npm -v
3
npm --version
4

5
# 查看帮助
6
npm help
7
npm --help
8

9
# 查看命令列表
10
npm commands

package.json 相关#

Terminal window

1
# 初始化项目 (创建 package.json)
2
npm init
3
npm init -y                   # 跳过问答，全部默认
4
npm init --yes
5

6
# 设置初始值
7
npm init --scope=username     # 设置 scope 用户名
8
npm init --yes --scope=username --author-name="Your Name"

安装依赖#

Terminal window展开收起

1
# 安装项目所有依赖
2
npm install
3
npm install --legacy-peer-deps  # 忽略 peer dependencies 冲突
4

5
# 安装指定包
6
npm install <package>
7
npm install <package>@<version>    # 指定版本
8
npm install <package>@latest       # 最新版本
9
npm install <package>@">=1.0.0 <2.0.0"  # 版本范围
10

11
# 安装并保存到 dependencies (生产依赖)
12
npm install <package> --save
13
npm install <package> -S
14
npm install <package> --save-prod
15

16
# 安装并保存到 devDependencies (开发依赖)
17
npm install <package> --save-dev
18
npm install <package> -D
19

20
# 安装全局包
21
npm install <package> -g
22
npm install --global <package>
23

24
# 从本地安装
25
npm install ./path/to/package
26
npm install /path/to/package.tgz
27

28
# 安装 Git URL
29
npm install git://github.com/user/project.git
30
npm install git+ssh://git@github.com:user/project.git
31
npm install git+https://github.com/user/project.git
32

33
# 安装特定 tag
34
npm install <package>@beta
35
npm install <package>@rc

展开收起

更新依赖#

Terminal window

1
# 查看可更新的包
2
npm outdated
3

4
# 更新所有包
5
npm update
6

7
# 更新指定包
8
npm update <package>
9

10
# 检查包最新版本
11
npm outdated <package>

卸载依赖#

Terminal window

1
# 卸载指定包
2
npm uninstall <package>
3
npm remove <package>
4
npm rm <package>
5

6
# 卸载并从 package.json 移除
7
npm uninstall <package> --save
8
npm uninstall <package> -S
9
npm uninstall <package> --save-dev
10
npm uninstall <package> -D
11

12
# 卸载全局包
13
npm uninstall <package> -g

运行脚本#

Terminal window

1
# 运行 package.json 中定义的脚本
2
npm run <script>
3

4
# 常用预设脚本
5
npm run start          # 启动项目
6
npm run dev            # 开发模式
7
npm run build          # 构建项目
8
npm run test           # 运行测试
9
npm run lint           # 代码检查
10
npm run format        # 代码格式化
11

12
# 直接执行 bin 命令
13
npx <command>
14
npx create-react-app my-app

包搜索与管理#

Terminal window展开收起

1
# 在 npm 仓库搜索包
2
npm search <keyword>
3
npm s <keyword>
4

5
# 查看包信息
6
npm view <package>
7
npm v <package>
8

9
# 查看特定信息
10
npm view <package> version
11
npm view <package> versions
12
npm view <package> dependencies
13
npm view <package> repository.url
14
npm view <package>engines
15

16
# 查看包在仓库中的状态
17
npm pack <package>    # 下载包的 tarball

展开收起

查看已安装的包#

Terminal window

1
# 查看当前项目依赖树
2
npm list
3
npm ls
4

5
# 查看全局包
6
npm list -g
7
npm ls -g
8
npm list -g --depth=0
9

10
# 查看包的所有版本
11
npm view <package> versions --json

缓存管理#

Terminal window

1
# 查看缓存
2
npm cache ls
3
npm cache ls <package>
4

5
# 清理缓存
6
npm cache clean
7
npm cache clean --force
8

9
# 验证缓存
10
npm cache verify

npm 配置#

Terminal window展开收起

1
# 查看配置
2
npm config list
3
npm config list -l          # 查看所有配置
4
npm config get <key>
5
npm config list --json      # JSON 格式输出
6

7
# 设置配置
8
npm config set <key> <value>
9
npm config set registry https://registry.npmjs.org
10
npm config set <key> <value> --location=user     # 用户配置
11
npm config set <key> <value> --location=project   # 项目配置
12

13
# 删除配置
14
npm config delete <key>
15

16
# 编辑配置文件
17
npm config edit

展开收起

package.json 详解#

package.json 是 Node.js 项目的核心配置文件。

基本结构#

1
{
2
  "name": "my-project",
3
  "version": "1.0.0",
4
  "description": "项目描述",
5
  "main": "index.js",
6
  "scripts": {
7
    "start": "node index.js",
8
    "dev": "nodemon index.js",
9
    "build": "webpack --mode production",
10
    "test": "jest",
11
    "lint": "eslint ."
12
  },
13
  "keywords": ["nodejs", "javascript"],
14
  "author": "Your Name <email@example.com>",
15
  "license": "MIT",
16
  "repository": {
17
    "type": "git",
18
    "url": "https://github.com/username/project.git"
19
  },
20
  "bugs": {
21
    "url": "https://github.com/username/project/issues"
22
  },
23
  "homepage": "https://github.com/username/project#readme",
24
  "dependencies": {},
25
  "devDependencies": {}
26
}

展开收起

字段说明#

字段	说明	示例
`name`	项目名称	`"my-project"`
`version`	版本号	`"1.0.0"`
`description`	项目描述	`"A cool project"`
`main`	入口文件	`"src/index.js"`
`type`	模块类型	`"module"` 或 `"commonjs"`
`scripts`	命令别名	`{"start": "node index.js"}`
`keywords`	关键字	`["web", "nodejs"]`
`author`	作者	`"Name <email>"`
`license`	许可证	`"MIT"`
`repository`	仓库地址	`{type: "git", url: "..."}`
`engines`	Node 版本要求	`{"node": ">=16"}`
`os`	支持的操作系统	`["darwin", "linux"]`
`cpu`	支持的 CPU 架构	`["x64", "arm64"]`

dependencies vs devDependencies#

dependencies - 生产环境依赖

1
"dependencies": {
2
  "express": "^4.18.2",
3
  "axios": "^1.6.0",
4
  "dotenv": "^16.3.1"
5
}

devDependencies - 开发环境依赖

1
"devDependencies": {
2
  "webpack": "^5.88.0",
3
  "jest": "^29.6.0",
4
  "eslint": "^8.45.0"
5
}

版本号语义化 (SemVer)#

1
major.minor.patch
2
  ^     ^    ^
3
  |     |    +-- patch: 修复 bug，完全向下兼容
4
  |     +------- minor: 新功能，向后兼容
5
  +------------- major: 破坏性更新，不向下兼容

符号	含义	示例
`^`	允许 minor 和 patch 更新	`^1.2.3` → `1.x.x`
`~`	允许 patch 更新	`~1.2.3` → `1.2.x`
`*`	最新版本	`*`
`>=`	大于等于	`>=1.0.0`
`1.0.0 - 2.0.0`	版本范围	`1.0.0 - 2.0.0`
`latest`	最新标签版本	`latest`

scripts 变量#

1
{
2
  "scripts": {
3
    "build": "webpack --progress --config webpack.config.js",
4
    "postinstall": "if [ -f ./scripts/postinstall.js ]; then node ./scripts/postinstall.js; fi",
5
    "prebuild": "rimraf dist"
6
  }
7
}

常用生命周期钩子：

preinstall - 安装前
postinstall - 安装后
preuninstall - 卸载前
postuninstall - 卸载后
prepublish - 发布前
preversion - 版本更新前
postversion - 版本更新后
pretest / posttest - 测试前后
prestop / poststop - 停止前后
prestart / poststart - 启动前后

模块系统#

CommonJS (CJS)#

Node.js 默认的模块系统，使用 require() 导入和 module.exports 导出。

module.exports展开收起

1
const add = (a, b) => a + b;
2
module.exports = add;
3

4
// 导出方式 2: module.exports = {}
5
module.exports = {
6
  add,
7
  subtract: (a, b) => a - b
8
};
9

10
// 导出方式 3: exports.alias
11
exports.add = add;
12
exports.subtract = (a, b) => a - b;
13

14
// 导入
15
const add = require('./math');
16
const { add, subtract } = require('./math');

展开收起

ES Modules (ESM)#

ES6 引入的模块系统，使用 import 导入和 export 导出。

注意： 需要在 package.json 中设置 "type": "module"，或使用 .mjs 扩展名。

1
// 导出方式 1: export
2
export const add = (a, b) => a + b;
3
export const subtract = (a, b) => a - b;
4

5
// 导出方式 2: export default
6
const add = (a, b) => a + b;
7
export default add;
8

9
// 导出方式 3: export { }
10
const add = (a, b) => a + b;
11
export { add };
12

13
// 导入
14
import add from './math.js';
15
import { add, subtract } from './math.js';
16
import * as math from './math.js';

展开收起

模块解析#

1
// 相对路径
2
require('./utils');           // ./utils.js
3
require('./utils.js');       // 明确扩展名
4
require('./');                // 查找 ./index.js
5

6
// 绝对路径
7
require('/usr/local/utils');  // 绝对路径
8

9
// 模块路径 (node_modules)
10
require('express');           // 查找 node_modules/express
11
require('@babel/core');       // 查找 node_modules/@babel/core
12

13
// 目录作为模块
14
require('./dir');             // 查找 ./dir/index.js 或 ./dir/package.json 的 main 字段

require() 缓存机制#

1
// 模块只会被加载一次，之后从缓存返回
2
console.log(require.cache);
3

4
// 清除特定模块缓存
5
delete require.cache[require.resolve('./module')];

核心模块#

Node.js 内置的核心模块，无需额外安装即可使用。

path - 路径操作#

1
const path = require('path');
2

3
// 路径拼接
4
path.join('/foo', 'bar', 'baz/asdf');
5
// → '/foo/bar/baz/asdf'
6

7
// 解析为绝对路径
8
path.resolve('index.js');
9
// → '/Users/me/project/index.js'
10

11
path.resolve('/foo', './bar');
12
// → '/foo/bar'
13

14
// 获取路径信息
15
path.basename('/foo/bar/index.js');  // → 'index.js'
16
path.dirname('/foo/bar/index.js');   // → '/foo/bar'
17
path.extname('/foo/bar/index.js');   // → '.js'
18

19
// 判断路径类型
20
path.isAbsolute('/foo/bar');   // → true
21
path.isAbsolute('./foo/bar');  // → false
22

23
// 解析路径
24
path.parse('/foo/bar/index.js');
25
// → { root: '/', dir: '/foo/bar', base: 'index.js', ext: '.js', name: 'index' }
26

27
// 路径格式化
28
path.format({
29
  dir: '/foo/bar',
30
  name: 'index',
31
  ext: '.js'
32
});
33
// → '/foo/bar/index.js'
34

35
// 跨平台路径分隔符
36
path.sep;           // Linux/macOS: '/', Windows: '\\'
37
path.delimiter;     // Linux/macOS: ':', Windows: ';'

展开收起

fs - 文件系统#

1
const fs = require('fs');
2
const fsPromises = require('fs').promises;  // Promise 风格
3

4
// 同步读取
5
const content = fs.readFileSync('./file.txt', 'utf8');
6

7
// 异步回调风格
8
fs.readFile('./file.txt', 'utf8', (err, data) => {
9
  if (err) throw err;
10
  console.log(data);
11
});
12

13
// Promise 风格 (Node.js 10+)
14
(async () => {
15
  const data = await fsPromises.readFile('./file.txt', 'utf8');
16
  console.log(data);
17
})();
18

19
// 同步方法列表
20
fs.readFileSync()
21
fs.writeFileSync()
22
fs.appendFileSync()
23
fs.mkdirSync()
24
fs.rmdirSync()
25
fs.readdirSync()
26
fs.statSync()
27
fs.existsSync()
28
fs.copyFileSync()
29
fs.unlinkSync()
30
fs.renameSync()
31

32
// 异步方法列表
33
fs.readFile()
34
fs.writeFile()
35
fs.appendFile()
36
fs.mkdir()
37
fs.rmdir()
38
fs.readdir()
39
fs.stat()
40
fs.access()
41
fs.copyFile()
42
fs.unlink()
43
fs.rename()
44

45
// Promise 方法 (fs.promises)
46
fsPromises.readFile()
47
fsPromises.writeFile()
48
fsPromises.mkdir()
49
fsPromises.readdir()
50
fsPromises.stat()
51
fsPromises.access()

展开收起

os - 操作系统信息#

1
const os = require('os');
2

3
os.platform();      // 'linux', 'darwin', 'win32'
4
os.arch();           // 'x64', 'arm64'
5
os.release();        // 操作系统版本
6
os.type();           // 'Linux', 'Darwin', 'Windows_NT'
7
os.homedir();        // 用户主目录
8
os.tmpdir();         // 临时文件目录
9
os.hostname();       // 主机名
10
os.EOL;              // 换行符 '\n' (Linux/macOS) 或 '\r\n' (Windows)
11
os.cpus();           // CPU 信息
12
os.totalmem();       // 总内存 (bytes)
13
os.freemem();        // 空闲内存 (bytes)
14
os.networkInterfaces();  // 网络接口
15
os.uptime();         // 系统运行时间 (秒)
16
os.loadavg();        // 平均负载 (Linux/macOS)

展开收起

util - 工具函数#

1
const util = require('util');
2
const { promisify } = util;
3
const { callbackify } = util;
4

5
// 将回调函数转为 Promise
6
const fsReadFile = promisify(fs.readFile);
7
const data = await fsReadFile('./file.txt', 'utf8');
8

9
// 将 async 函数转为回调风格
10
const asyncFn = async () => {};
11
const callbackFn = callbackify(asyncFn);
12

13
// 格式化字符串
14
util.format('%s:%d', 'hello', 123);  // 'hello:123'
15
util.format('%s:%s', 'hello');       // 'hello:%s'
16

17
// inspect 对象查看
18
util.inspect({ a: 1, b: { c: 2 } });
19
// → "{ a: 1, b: { c: 2 } }"
20

21
// 类型检查
22
util.types.isPromise(p);           // 是否为 Promise
23
util.types.isArray(arr);           // 是否为数组
24
util.types.isDate(date);           // 是否为日期
25
util.types.isRegExp(regex);        // 是否为正则
26
util.types.isMap(map);             // 是否为 Map
27
util.types.isSet(set);             // 是否为 Set
28
util.types.isAsyncFunction(fn);    // 是否为 async 函数
29
util.types.isGeneratorFunction(fn);// 是否为生成器函数

展开收起

events - 事件触发器#

1
const EventEmitter = require('events');
2

3
class MyEmitter extends EventEmitter {}
4

5
const emitter = new MyEmitter();
6

7
// 监听事件
8
emitter.on('event', (arg1, arg2) => {
9
  console.log('事件触发', arg1, arg2);
10
});
11

12
// 只触发一次的监听器
13
emitter.once('event', () => {
14
  console.log('只触发一次');
15
});
16

17
// 发送事件
18
emitter.emit('event', '参数1', '参数2');
19

20
// 移除监听器
21
emitter.off('event', listenerFn);
22
emitter.removeListener('event', listenerFn);
23

24
// 移除所有监听器
25
emitter.removeAllListeners();
26
emitter.removeAllListeners('event');
27

28
// 查看监听器数量
29
emitter.listenerCount('event');
30

31
// 查看所有监听器
32
emitter.listeners('event');
33

34
// 错误事件
35
emitter.on('error', (err) => {
36
  console.error('错误:', err);
37
});

展开收起

crypto - 加密模块#

1
const crypto = require('crypto');
2

3
// 创建哈希
4
const hash = crypto.createHash('sha256');
5
hash.update('hello');
6
console.log(hash.digest('hex'));
7

8
// 创建 HMAC
9
const hmac = crypto.createHmac('sha256', 'secret-key');
10
hmac.update('hello');
11
console.log(hmac.digest('hex'));
12

13
// 加密
14
const cipher = crypto.createCipher('aes192', 'password');
15
let encrypted = cipher.update('hello', 'utf8', 'hex');
16
encrypted += cipher.final('hex');
17

18
// 解密
19
const decipher = crypto.createDecipher('aes192', 'password');
20
let decrypted = decipher.update(encrypted, 'hex', 'utf8');
21
decrypted += decipher.final('utf8');
22

23
// 随机数据
24
crypto.randomBytes(16);            // 16 字节随机数据
25
crypto.randomUUID();               // UUID v4
26

27
// 生成密钥
28
crypto.generateKey('aes', { length: 256 });
29

30
// diffie-hellman 密钥交换
31
const dh = crypto.createDiffieHellman(2048);

展开收起

buffer - 二进制数据#

1
const buffer = Buffer.alloc(10);       // 创建 10 字节缓冲区
2
const buffer = Buffer.from('hello');   // 从字符串创建
3
const buffer = Buffer.from([1, 2, 3]);  // 从数组创建
4

5
// 编码转换
6
buffer.toString('utf8');
7
buffer.toString('hex');
8
buffer.toString('base64');
9

10
// 写入
11
buffer.write('hello', 0, 5, 'utf8');
12

13
// 拼接
14
Buffer.concat([buf1, buf2, buf3]);
15

16
// 复制
17
buf.copy(targetBuf, targetStart, sourceStart, sourceEnd);
18

19
// 比较
20
buffer.compare(otherBuffer);
21

22
// 切片
23
buffer.slice(0, 5);
24

25
// 长度
26
buffer.length;

展开收起

stream - 流#

1
const { Readable, Writable, Transform, Duplex, pipeline } = require('stream');
2
const fs = require('fs');
3

4
// 读取流
5
const readStream = fs.createReadStream('./file.txt');
6
readStream.on('data', chunk => { /* 处理数据块 */ });
7
readStream.on('end', () => { /* 读取完成 */ });
8
readStream.on('error', err => { /* 错误处理 */ });
9

10
// 写入流
11
const writeStream = fs.createWriteStream('./output.txt');
12
writeStream.write('hello');
13
writeStream.end();
14
writeStream.on('finish', () => { /* 写入完成 */ });
15

16
// 管道 (pipe)
17
readStream.pipe(writeStream);
18

19
// pipeline (更好的错误处理)
20
pipeline(
21
  fs.createReadStream('./file.txt'),
22
  gzip(),
23
  fs.createWriteStream('./file.txt.gz'),
24
  (err) => { if (err) console.error('失败:', err); }
25
);
26

27
// Transform 流
28
const upperCase = new Transform({
29
  transform(chunk, encoding, callback) {
30
    this.push(chunk.toString().toUpperCase());
31
    callback();
32
  }
33
});

展开收起

http / https - HTTP 服务器#

1
const http = require('http');
2
const https = require('https');
3
const fs = require('fs');
4

5
// 创建 HTTP 服务器
6
const server = http.createServer((req, res) => {
7
  res.statusCode = 200;
8
  res.setHeader('Content-Type', 'text/plain');
9
  res.end('Hello World');
10
});
11

12
server.listen(3000, '127.0.0.1', () => {
13
  console.log('服务器运行在 http://127.0.0.1:3000');
14
});
15

16
// HTTP 请求
17
http.get('http://api.example.com/data', (res) => {
18
  let data = '';
19
  res.on('data', chunk => { data += chunk; });
20
  res.on('end', () => { console.log(data); });
21
});
22

23
// HTTPS 请求
24
const options = {
25
  hostname: 'api.example.com',
26
  port: 443,
27
  path: '/data',
28
  method: 'GET'
29
};
30
https.request(options, (res) => {
31
  // 处理响应
32
});

展开收起

url - URL 解析#

1
const url = require('url');
2

3
// 解析 URL
4
const myURL = new URL('https://user:pass@host.com:8080/path?query=value#hash');
5

6
console.log(myURL.href);          // 完整 URL
7
console.log(myURL.protocol);      // 'https:'
8
console.log(myURL.host);           // 'host.com:8080'
9
console.log(myURL.hostname);       // 'host.com'
10
console.log(myURL.port);          // '8080'
11
console.log(myURL.pathname);       // '/path'
12
console.log(myURL.search);         // '?query=value'
13
console.log(myURL.searchParams);  // URLSearchParams
14
console.log(myURL.hash);          // '#hash'
15
console.log(myURL.username);      // 'user'
16
console.log(myURL.password);      // 'pass'
17

18
// URLSearchParams
19
const params = new URLSearchParams(myURL.search);
20
params.get('query');              // 'value'
21
params.set('query', 'newvalue');
22
params.append('page', '1');
23
params.has('query');              // true
24
params.delete('query');
25

26
// 旧式 url.parse (已废弃)
27
url.parse('https://example.com/path?query=value', true);

展开收起

querystring - 查询字符串#

1
const querystring = require('querystring');
2

3
// 解析查询字符串
4
querystring.parse('name=test&age=18');
5
// → { name: 'test', age: '18' }
6

7
// 构建查询字符串
8
querystring.stringify({ name: 'test', age: 18 });
9
// → 'name=test&age=18'
10

11
// 编码
12
querystring.escape('name=test&age=18');
13
// → 'name%3Dtest%26age%3D18'
14

15
// 解码
16
querystring.unescape('name%3Dtest');
17
// → 'name=test'

展开收起

zlib - 压缩#

1
const zlib = require('zlib');
2

3
// gzip 压缩
4
const gzip = zlib.createGzip();
5
const inp = fs.createReadStream('./file.txt');
6
const out = fs.createWriteStream('./file.txt.gz');
7
inp.pipe(gzip).pipe(out);
8

9
// 压缩数据
10
zlib.gzipSync(Buffer.from('hello'));
11

12
// 解压数据
13
zlib.unzipSync(Buffer.from(gzipData));
14

15
// 其他压缩格式
16
zlib.deflateSync();   // deflate
17
zlib.deflateRawSync(); // raw deflate
18
zlib.brotli*();       // brotli 压缩

展开收起

net - TCP 服务器#

1
const net = require('net');
2

3
// 创建 TCP 服务器
4
const server = net.createServer((socket) => {
5
  console.log('客户端连接:', socket.remoteAddress);
6

7
  socket.on('data', (data) => {
8
    console.log('收到数据:', data.toString());
9
    socket.write('服务器收到');
10
  });
11

12
  socket.on('end', () => {
13
    console.log('客户端断开');
14
  });
15

16
  socket.write('欢迎连接');
17
});
18

19
server.listen(8080, () => {
20
  console.log('TCP 服务器监听 8080 端口');
21
});
22

23
// 创建 TCP 客户端
24
const client = net.createConnection(8080, '127.0.0.1', () => {
25
  console.log('已连接到服务器');
26
  client.write('Hello Server');
27
});

展开收起

dns - 域名解析#

1
const dns = require('dns');
2
const dnsPromises = require('dns').promises;
3

4
// 解析域名
5
dns.resolve4('example.com', (err, addresses) => {
6
  if (err) throw err;
7
  console.log('IPv4 地址:', addresses);
8
});
9

10
dns.resolve6('example.com');
11
dns.resolveMx('example.com');
12
dns.resolveTxt('example.com');
13
dns.resolveNs('example.com');
14
dns.resolveCname('example.com');
15
dns.resolveSoa('example.com');
16
dns.resolveSrv('example.com');
17
dns.reverse('93.184.216.34');
18

19
// Promise 风格
20
(async () => {
21
  const addresses = await dnsPromises.resolve4('example.com');
22
  console.log(addresses);
23
})();
24

25
// 反向解析
26
dns.reverse('93.184.216.34');
27

28
// 查找
29
dns.lookup('example.com', (err, address, family) => {
30
  console.log('地址:', address, '类型:', family); // family: 4 或 6
31
});

展开收起

process - 进程信息#

1
// 进程信息
2
process.version;           // Node.js 版本
3
process.versions;          // 依赖库版本
4
process.platform;          // 平台 'linux', 'darwin', 'win32'
5
process.arch;              // 架构 'x64', 'arm64'
6
process.title;             // 进程标题
7
process.pid;               // 进程 ID
8
process.ppid;              // 父进程 ID
9

10
// 内存使用
11
process.memoryUsage();
12
// { rss: 23MB, heapTotal: 10MB, heapUsed: 7MB, external: 1MB }
13

14
process.memoryUsage().heapUsed;  // 堆内存使用量
15

16
// CPU 使用
17
process.cpuUsage();
18
// { user: 10000, system: 5000 }
19

20
// 运行时间
21
process.uptime();          // 进程运行秒数
22
process.hrtime.bigint();   // 高精度时间 (纳秒)
23

24
// 环境变量
25
process.env;               // 环境变量对象
26
process.env.NODE_ENV;     // 'development', 'production'
27
process.env.PATH;
28
process.env.HOME;
29

30
// 命令行参数
31
process.argv;             // ['node', 'script.js', 'arg1', 'arg2']
32
process.execArgv;         // Node 特殊参数
33

34
// 工作目录
35
process.cwd();             // 当前工作目录
36

37
// 用户信息
38
process.getuid();          // 用户 ID
39
process.getgid();          // 组 ID
40
process.groups;            // 附加组 ID
41

42
// 信号
43
process.on('SIGINT', () => { /* 处理 Ctrl+C */ });
44
process.on('SIGTERM', () => { /* 处理终止信号 */ });
45

46
// 退出
47
process.exit(0);           // 正常退出
48
process.exit(1);           // 异常退出
49
process.kill(pid, 'SIGTERM');
50

51
// 下一轮事件循环
52
process.nextTick(() => { /* 异步执行 */ });
53
process.setImmediate(() => { /* 立即执行 */ });
54

55
// 错误传播
56
process.on('uncaughtException', (err) => {
57
  console.error('未捕获异常:', err);
58
});
59

60
process.on('unhandledRejection', (reason, promise) => {
61
  console.error('未处理的 Promise 拒绝:', reason);
62
});

展开收起

环境配置#

npm 镜像源配置#

Terminal window

1
# 查看当前镜像
2
npm config get registry
3

4
# 设置淘宝镜像
5
npm config set registry https://registry.npmmirror.com
6

7
# 设置官方镜像
8
npm config set registry https://registry.npmjs.org
9

10
# 还原默认镜像
11
npm config set registry https://registry.npmjs.org

nrm - 镜像源管理器#

Terminal window展开收起

1
# 安装 nrm
2
npm install -g nrm
3

4
# 查看可用镜像
5
nrm ls
6

7
# 切换镜像
8
nrm use taobao
9
nrm use npm
10

11
# 添加镜像
12
nrm add <name> <url>
13

14
# 删除镜像
15
nrm del <name>
16

17
# 测试镜像速度
18
nrm test
19
nrm test taobao
20

21
# 查看当前使用的镜像
22
nrm current

展开收起

cnpm - 淘宝镜像客户端#

Terminal window

1
# 安装 cnpm
2
npm install -g cnpm --registry=https://registry.npmmirror.com
3

4
# 使用 cnpm 代替 npm
5
cnpm install <package>
6
cnpm install
7

8
# 或使用 npx 直接运行 cnpm
9
npx cnpm install <package>

.npmrc 配置文件#

在用户主目录或项目根目录创建 .npmrc 文件：

1
# 项目级 .npmrc
2
registry=https://registry.npmmirror.com
3
prefix=C:\Users\username\.npm-global
4
cache=C:\Users\username\.npm-cache
5
tmp=C:\Users\username\.npm-tmp

1
# 用户级 .npmrc (~/.npmrc)
2
registry=https://registry.npmmirror.com

n 环境管理 (Node 版本切换)#

Terminal window展开收起

1
# 全局安装 n
2
npm install -g n
3

4
# 安装稳定版
5
n stable
6

7
# 安装最新版
8
n latest
9

10
# 安装 LTS 版
11
n lts
12

13
# 安装指定版本
14
n 18.17.0
15

16
# 切换版本
17
n 16.20.0
18

19
# 列出已安装版本
20
n list
21

22
# 显示可安装版本
23
n list --all
24

25
# 移除版本
26
n rm 14.20.0
27

28
# 查看当前版本
29
n
30

31
# 使用指定版本执行脚本
32
n use 18.17.0 node script.js

展开收起

常见问题#

安装失败#

问题：npm 安装报错 EACCES (权限拒绝)

Terminal window

1
# 解决方案：修改 npm 全局目录权限
2
mkdir ~/.npm-global
3
npm config set prefix '~/.npm-global'
4
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
5
source ~/.bashrc

问题：安装卡住不动

Terminal window

1
# 清理缓存后重试
2
npm cache clean --force
3
npm install
4

5
# 或使用淘宝镜像
6
npm install --registry=https://registry.npmmirror.com

版本问题#

Node.js 和 npm 版本不匹配

Terminal window

1
# 查看版本对应关系
2
# https://nodejs.org/zh-cn/download/releases/
3
# https://nodejs.org/en/download/releases/
4

5
# 升级 npm
6
npm install -g npm
7

8
# 升级 Node.js (使用 nvm)
9
nvm install lts
10
nvm use lts

权限问题#

问题：全局安装报 EACCES

Terminal window

1
# 方法 1：使用 nvm 管理 Node
2
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
3
nvm install --lts
4
nvm use --lts
5

6
# 方法 2：修复 npm 目录权限
7
sudo chown -R $(whoami) ~/.npm
8
sudo chown -R $(whoami) /usr/local/lib/node_modules

网络问题#

问题：下载慢或超时

Terminal window

1
# 设置国内镜像
2
npm config set registry https://registry.npmmirror.com
3

4
# 或使用代理
5
npm config set proxy http://proxy.company.com:8080
6
npm config set https-proxy http://proxy.company.com:8080
7

8
# 取消代理
9
npm config delete proxy
10
npm config delete https-proxy

其他问题#

Windows 下找不到 node_modules/.bin

Terminal window

1
# 确保在项目根目录执行
2
cd project-dir
3
npm install
4

5
# Windows 下可能需要使用 Git Bash 或 WSL

删除 node_modules

Terminal window

1
# 使用 rimraf (推荐)
2
npm install -g rimraf
3
rimraf node_modules
4

5
# 或手动删除
6
rm -rf node_modules      # Linux/macOS
7
rd /s /q node_modules     # Windows CMD

npm link 使用

Terminal window

1
# 在开发包目录创建链接
2
cd package-dir
3
npm link
4

5
# 在项目中使用链接
6
cd project-dir
7
npm link package-name
8

9
# 取消链接
10
npm unlink package-name
11
npm unlink -g package-name

🔄 Server-Sent Events (SSE) 技术详解

Mon, 20 Apr 2026 00:00:00 GMT

Server-Sent Events (SSE) 技术详解#

目录#

SSE 简介
SSE vs WebSocket vs Long Polling
SSE 协议格式
EventSource API
服务端实现
浏览器兼容性
重连机制
字段说明
安全考虑
实际应用场景
性能优化
完整示例
调试工具
常见问题

SSE 简介#

Server-Sent Events (SSE) 是一种基于 HTTP 的单向通信技术，允许服务器主动向浏览器推送数据。SSE 是 HTML5 规范的一部分，提供了一种简单的方式来获取服务器的实时更新。

核心特点#

单向通信: 服务器 → 客户端，客户端不能向服务器发送数据
基于 HTTP/1.1: 使用 HTTP 协议，兼容现有网络架构
自动重连: 浏览器自动维护连接并在断线时重连
文本协议: 数据格式简单，是 UTF-8 编码的文本
轻量级: 相比 WebSocket 协议更简单，开销更小

工作原理#

1
┌─────────┐                    ┌─────────┐                    ┌─────────┐
2
│ Browser │ ── HTTP Request ──▶│ Server  │                    │         │
3
│         │◀─ Keep-Alive ──────│         │◀── Data Stream ────┤  Data   │
4
│         │◀─ text/event-stream│         │                    │  Source │
5
│         │                    │         │                    │         │
6
│         │    (持久连接)        │         │                    │         │
7
└─────────┘                    └─────────┘                    └─────────┘

客户端通过 EventSource API 发起 HTTP 请求到服务器
服务器保持连接打开，不断发送事件
客户端接收事件并触发相应的 JavaScript 回调
连接断开时，浏览器自动尝试重连

SSE vs WebSocket vs Long Polling#

对比表#

特性	SSE	WebSocket	Long Polling
通信方向	单向 (服务器→客户端)	全双工 (双向)	半双工 (伪双向)
协议	HTTP/1.1	WebSocket (ws/wss)	HTTP
连接数限制	受浏览器同源连接限制	相同	每次轮询都是新连接
数据格式	UTF-8 文本	二进制/文本	任意
自动重连	内置支持	需要手动实现	无 (轮询间隔)
CORS	需要服务器配置	需要 WebSocket 服务器	需要服务器配置
防火墙/代理	友好	可能被阻止	友好
复杂度	低	中	低
服务器资源	较低 (持久连接)	较高 (全双工)	较高 (频繁建连)
适合场景	实时通知、推送更新	实时游戏、聊天	简单轮询需求

如何选择#

1
选择 SSE 的场景:
2
├── 只需要服务器向客户端推送数据
3
├── 需要通过 HTTP/HTTPS 传输
4
├── 需要自动重连功能
5
└── 需要兼容不支持 WebSocket 的环境
6

7
选择 WebSocket 的场景:
8
├── 需要双向通信
9
├── 传输延迟要求极低
10
├── 需要传输二进制数据
11
├── 高频数据交换
12
└── 实时游戏、在线协作、交易系统
13

14
选择 Long Polling 的场景:
15
├── 现有系统改造困难
16
├── 服务器不支持长连接
17
└── 数据更新频率很低

展开收起

SSE 协议格式#

基本格式#

SSE 数据以 field: value 的形式传输，以两个换行符 \n\n 结束一个事件。

1
field: value\n\n

字段说明#

字段名	说明
`event`	事件类型，客户端可据此区分不同事件
`data`	事件数据，可以有多行
`id`	事件 ID，客户端发送 `Last-Event-ID` 用于断线重连
`retry`	重连时间（毫秒），覆盖默认重连时间
`:`	注释，以冒号开头，用于心跳或传输注释

单行事件示例#

1
data: {"message": "Hello World"}\n\n

多行数据#

1
data: {"status": "ok",
2
data: "message": "Processing complete"
3
data: }\n\n

带事件类型#

1
event: user-join\n
2
data: {"username": "Alice"}\n\n

带事件 ID (用于重连)#

1
id: 123\n
2
data: {"message": "First event"}\n\n
3

4
id: 124\n
5
data: {"message": "Second event"}\n\n

指定重连时间#

1
retry: 10000\n
2
data: {"message": "Set retry to 10 seconds"}\n\n

注释行 (心跳)#

1
: This is a comment\n
2
data: ping\n\n

完整事件示例#

1
event: notification\n
2
id: evt-001\n
3
retry: 5000\n
4
data: {"title": "New Message", "body": "You have a new notification", "timestamp": 1699000000}\n\n

EventSource API#

基本用法#

1
// 创建 EventSource 连接
2
const eventSource = new EventSource('/api/events');
3

4
// 监听默认事件 (message)
5
eventSource.onmessage = function(event) {
6
  console.log('Received:', event.data);
7
};
8

9
// 监听自定义事件
10
eventSource.addEventListener('notification', function(event) {
11
  const data = JSON.parse(event.data);
12
  console.log('Notification:', data);
13
});
14

15
// 监听连接打开
16
eventSource.onopen = function(event) {
17
  console.log('Connection opened');
18
};
19

20
// 监听错误
21
eventSource.onerror = function(event) {
22
  if (event.readyState === EventSource.CONNECTING) {
23
    console.log('Reconnecting...');
24
  } else if (event.readyState === EventSource.CLOSED) {
25
    console.log('Connection closed');
26
  } else {
27
    console.error('Error:', event);
28
  }
29
};

展开收起

EventSource 属性#

1
const eventSource = new EventSource('/api/events');
2

3
console.log(eventSource.url);          // 连接 URL
4
console.log(eventSource.readyState);  // 连接状态
5
console.log(eventSource.withCredentials); // 是否携带凭证

readyState 状态#

常量	值	说明
`EventSource.CONNECTING`	0	连接中或重连中
`EventSource.OPEN`	1	连接已打开
`EventSource.CLOSED`	2	连接已关闭

1
switch (eventSource.readyState) {
2
  case EventSource.CONNECTING:
3
    console.log('Connecting...');
4
    break;
5
  case EventSource.OPEN:
6
    console.log('Connected');
7
    break;
8
  case EventSource.CLOSED:
9
    console.log('Disconnected');
10
    break;
11
}

关闭连接#

1
// 手动关闭连接
2
eventSource.close();
3

4
console.log(eventSource.readyState); // EventSource.CLOSED

携带凭证 (CORS)#

1
// withCredentials 设置为 true 时，会携带 cookie、Authorization header 等
2
const eventSource = new EventSource('/api/events', {
3
  withCredentials: true
4
});

断线重连与 Last-Event-ID#

服务器可发送 id 字段标记事件 ID。当连接断开重连时，浏览器会自动在请求头中携带 Last-Event-ID，服务器据此可以继续推送未发送的事件。

1
// 服务器端发送带 ID 的事件
2
// id: 123\n
3
// data: {"message": "Event 123"}\n\n
4

5
// 客户端断开后重连时，HTTP 请求头会包含:
6
// Last-Event-ID: 123
7

8
// 服务器收到后可以发送 124 开始的后续事件

服务端实现#

Node.js + Express#

server-express.js展开收起

1
const express = require('express');
2
const app = express();
3

4
// SSE 路由
5
app.get('/api/sse', (req, res) => {
6
  // 设置 SSE 相关 headers
7
  res.setHeader('Content-Type', 'text/event-stream');
8
  res.setHeader('Cache-Control', 'no-cache');
9
  res.setHeader('Connection', 'keep-alive');
10
  res.setHeader('Access-Control-Allow-Origin', '*');
11

12
  // 发送初始连接消息
13
  res.write('event: connected\n');
14
  res.write('data: {"status": "connected"}\n\n');
15

16
  // 定时发送数据
17
  const intervalId = setInterval(() => {
18
    const data = {
19
      timestamp: Date.now(),
20
      random: Math.random().toFixed(4)
21
    };
22

23
    res.write(`event: heartbeat\n`);
24
    res.write(`data: ${JSON.stringify(data)}\n\n`);
25
  }, 5000);
26

27
  // 模拟事件推送
28
  const eventId = setInterval(() => {
29
    const messages = ['Hello!', 'New notification', 'System update'];
30
    const message = messages[Math.floor(Math.random() * messages.length)];
31

32
    res.write(`event: notification\n`);
33
    res.write(`id: ${Date.now()}\n`);
34
    res.write(`data: {"message": "${message}"}\n\n`);
35
  }, 15000);
36

37
  // 客户端断开连接时清理
38
  req.on('close', () => {
39
    clearInterval(intervalId);
40
    clearInterval(eventId);
41
    console.log('Client disconnected');
42
  });
43
});
44

45
app.listen(3000, () => {
46
  console.log('Server running on http://localhost:3000');
47
});

展开收起

Node.js + 原生 HTTP#

server-http.js展开收起

1
const http = require('http');
2

3
const server = http.createServer((req, res) => {
4
  if (req.url === '/api/events') {
5
    res.writeHead(200, {
6
      'Content-Type': 'text/event-stream',
7
      'Cache-Control': 'no-cache',
8
      'Connection': 'keep-alive',
9
      'Access-Control-Allow-Origin': '*',
10
      'X-Accel-Buffering': 'no' // 禁用 Nginx 缓冲
11
    });
12

13
    const sendEvent = (eventName, data) => {
14
      res.write(`event: ${eventName}\n`);
15
      res.write(`data: ${JSON.stringify(data)}\n\n`);
16
    };
17

18
    const heartbeat = setInterval(() => {
19
      res.write(`: heartbeat\n\n`);
20
    }, 30000);
21

22
    const pushData = setInterval(() => {
23
      sendEvent('update', {
24
        time: new Date().toISOString(),
25
        value: Math.random()
26
      });
27
    }, 2000);
28

29
    req.on('close', () => {
30
      clearInterval(heartbeat);
31
      clearInterval(pushData);
32
      console.log('Connection closed');
33
    });
34
  } else {
35
    res.writeHead(404);
36
    res.end('Not Found');
37
  }
38
});
39

40
server.listen(8080, () => {
41
  console.log('SSE Server running on http://localhost:8080');
42
});

展开收起

Node.js + Koa#

server-koa.js展开收起

1
const Koa = require('koa');
2
const Router = require('@koa/router');
3

4
const app = new Koa();
5
const router = new Router();
6

7
router.get('/api/sse', async (ctx) => {
8
  ctx.set('Content-Type', 'text/event-stream');
9
  ctx.set('Cache-Control', 'no-cache');
10
  ctx.set('Connection', 'keep-alive');
11
  ctx.set('Access-Control-Allow-Origin', '*');
12
  ctx.set('X-Accel-Buffering', 'no');
13

14
  const encoder = new TextEncoder();
15

16
  const send = (eventName, data, eventId = null) => {
17
    let message = '';
18
    if (eventId) message += `id: ${eventId}\n`;
19
    message += `event: ${eventName}\n`;
20
    message += `data: ${JSON.stringify(data)}\n\n`;
21
    ctx.res.write(message);
22
  };
23

24
  send('connected', { status: 'connected' });
25

26
  const interval = setInterval(() => {
27
    send('heartbeat', { timestamp: Date.now() });
28
  }, 5000);
29

30
  ctx.req.on('close', () => {
31
    clearInterval(interval);
32
  });
33
});
34

35
app.use(router.routes());
36
app.listen(3000);

展开收起

Python + Flask#

server-flask.py展开收起

1
from flask import Flask, Response, request
2
import json
3
import time
4
import random
5
from datetime import datetime
6

7
app = Flask(__name__)
8

9
def generate_events():
10
    """生成 SSE 事件流"""
11
    event_id = 0
12

13
    while True:
14
        event_id += 1
15
        data = {
16
            'id': event_id,
17
            'timestamp': datetime.now().isoformat(),
18
            'value': round(random.random() * 100, 2)
19
        }
20

21
        yield f"event: update\n"
22
        yield f"id: {event_id}\n"
23
        yield f"data: {json.dumps(data)}\n\n"
24

25
        time.sleep(2)
26

27
@app.route('/api/events')
28
def events():
29
    """SSE 端点"""
30
    last_event_id = request.headers.get('Last-Event-ID')
31

32
    if last_event_id:
33
        print(f"Reconnecting from event ID: {last_event_id}")
34

35
    return Response(
36
        generate_events(),
37
        mimetype='text/event-stream',
38
        headers={
39
            'Cache-Control': 'no-cache',
40
            'Connection': 'keep-alive',
41
            'Access-Control-Allow-Origin': '*',
42
            'X-Accel-Buffering': 'no'
43
        }
44
    )
45

46
if __name__ == '__main__':
47
    app.run(host='0.0.0.0', port=5000, threaded=True)

展开收起

Python + FastAPI#

server-fastapi.py展开收起

1
from fastapi import FastAPI, Request
2
from fastapi.responses import StreamingResponse
3
import asyncio
4
import json
5
import random
6
from datetime import datetime
7
from typing import AsyncGenerator
8

9
app = FastAPI()
10

11
@app.get("/api/events")
12
async def sse_endpoint(request: Request):
13
    """SSE 端点"""
14
    last_event_id = request.headers.get("last-event-id")
15

16
    async def event_generator() -> AsyncGenerator[str, None]:
17
        event_id = int(last_event_id) if last_event_id else 0
18

19
        while True:
20
            event_id += 1
21
            data = {
22
                "id": event_id,
23
                "timestamp": datetime.now().isoformat(),
24
                "value": round(random.random() * 100, 2)
25
            }
26

27
            yield f"event: update\n"
28
            yield f"id: {event_id}\n"
29
            yield f"data: {json.dumps(data)}\n\n"
30

31
            await asyncio.sleep(2)
32

33
    return StreamingResponse(
34
        event_generator(),
35
        media_type="text/event-stream",
36
        headers={
37
            "Cache-Control": "no-cache",
38
            "Connection": "keep-alive",
39
            "Access-Control-Allow-Origin": "*",
40
            "X-Accel-Buffering": "no"
41
        }
42
    )

展开收起

Go#

server-go/main.go展开收起

1
package main
2

3
import (
4
  "fmt"
5
  "log"
6
  "net/http"
7
  "time"
8
)
9

10
func sseHandler(w http.ResponseWriter, r *http.Request) {
11
  w.Header().Set("Content-Type", "text/event-stream")
12
  w.Header().Set("Cache-Control", "no-cache")
13
  w.Header().Set("Connection", "keep-alive")
14
  w.Header().Set("Access-Control-Allow-Origin", "*")
15

16
  flusher, ok := w.(http.Flusher)
17
  if !ok {
18
    http.Error(w, "SSE not supported", http.StatusInternalServerError)
19
    return
20
  }
21

22
  eventID := 0
23
  ticker := time.NewTicker(2 * time.Second)
24
  defer ticker.Stop()
25

26
  for {
27
    select {
28
    case <-r.Context().Done():
29
      log.Println("Client disconnected")
30
      return
31
    case <-ticker.C:
32
      eventID++
33
      data := map[string]interface{}{
34
        "id":        eventID,
35
        "timestamp": time.Now().Format(time.RFC3339),
36
        "value":     float64(eventID) * 1.5,
37
      }
38

39
      fmt.Fprintf(w, "id: %d\n", eventID)
40
      fmt.Fprintf(w, "event: update\n")
41
      fmt.Fprintf(w, "data: %s\n\n", toJSON(data))
42
      flusher.Flush()
43
    }
44
  }
45
}
46

47
func toJSON(data map[string]interface{}) string {
48
  return fmt.Sprintf(`{"id":%d,"timestamp":"%s","value":%.2f}`,
49
    data["id"], data["timestamp"], data["value"])
50
}
51

52
func main() {
53
  http.HandleFunc("/api/events", sseHandler)
54
  log.Println("Server running on http://localhost:8080")
55
  log.Fatal(http.ListenAndServe(":8080", nil))
56
}

展开收起

Java + Spring Boot#

SseController.java展开收起

1
@RestController
2
@RequestMapping("/api")
3
public class SseController {
4

5
    @GetMapping("/events")
6
    public SseEmitter streamEvents() {
7
        SseEmitter emitter = new SseEmitter(0L);
8

9
        ExecutorService executor = Executors.newCachedThreadPool();
10

11
        executor.execute(() -> {
12
            try {
13
                int[] eventId = {0};
14

15
                while (true) {
16
                    eventId[0]++;
17
                    Map<String, Object> data = new HashMap<>();
18
                    data.put("id", eventId[0]);
19
                    data.put("timestamp", Instant.now().toString());
20
                    data.put("value", Math.random() * 100);
21

22
                    emitter.send(SseEmitter.event()
23
                        .name("update")
24
                        .id(String.valueOf(eventId[0]))
25
                        .data(data));
26

27
                    Thread.sleep(2000);
28
                }
29
            } catch (Exception e) {
30
                emitter.completeWithError(e);
31
            }
32
        });
33

34
        emitter.onCompletion(() -> log.info("SSE stream completed"));
35
        emitter.onError(e -> log.error("SSE error", e));
36
        emitter.onTimeout(() -> log.warning("SSE timeout"));
37

38
        return emitter;
39
    }
40
}

展开收起

Nginx 配置#

nginx.conf展开收起

1
server {
2
    location /api/sse {
3
        # 禁用缓冲
4
        proxy_buffering off;
5
        proxy_cache off;
6

7
        # 禁用 gzip (SSE 需要原始流)
8
        gzip off;
9

10
        proxy_pass http://backend;
11
        proxy_http_version 1.1;
12
        proxy_set_header Connection '';
13
        proxy_read_timeout 86400;
14
        proxy_send_timeout 86400;
15
    }
16
}

展开收起

浏览器兼容性#

支持情况#

浏览器	支持版本	备注
Chrome	6+	完整支持
Firefox	6+	完整支持
Safari	5+	完整支持
Edge	79+	完整支持 (Chromium)
IE	不支持	需要 polyfill
Opera	11+	完整支持
iOS Safari	4+	完整支持
Android Browser	4.4+	完整支持

Polyfill (兼容 IE)#

1
<!-- 使用 polyfill -->
2
<script src="https://cdn.jsdelivr.net/npm/event-source-polyfill@1.0.31/src/event_source_polyfill.js"></script>
3

4
<script>
5
  // 自动使用 polyfill (如果原生不支持)
6
  if (typeof EventSource === 'undefined') {
7
    EventSource = EventSourcePolyfill;
8
  }
9
</script>

检测支持#

1
if (typeof EventSource !== 'undefined') {
2
  // 支持 SSE
3
  const eventSource = new EventSource('/api/events');
4
} else {
5
  // 不支持，使用 Fallback
6
  console.warn('SSE not supported');
7
}

重连机制#

自动重连#

浏览器内置自动重连机制。连接断开后，浏览器会自动等待一段时间后重连，默认重连时间约 3 秒。

自定义重连时间#

1
// 服务器端设置重连时间 (毫秒)
2
retry: 10000\n
3
data: {"message": "Retry in 10 seconds"}\n\n

手动重连控制#

1
class SSEClient {
2
  constructor(url, options = {}) {
3
    this.url = url;
4
    this.options = options;
5
    this.eventSource = null;
6
    this.reconnectAttempts = 0;
7
    this.maxReconnectAttempts = options.maxReconnectAttempts || 10;
8
    this.reconnectDelay = options.reconnectDelay || 3000;
9
  }
10

11
  connect() {
12
    this.eventSource = new EventSource(this.url);
13

14
    this.eventSource.onopen = () => {
15
      console.log('Connected');
16
      this.reconnectAttempts = 0;
17
    };
18

19
    this.eventSource.onmessage = (event) => {
20
      console.log('Message:', event.data);
21
    };
22

23
    this.eventSource.onerror = (event) => {
24
      if (this.reconnectAttempts < this.maxReconnectAttempts) {
25
        this.reconnectAttempts++;
26
        console.log(`Reconnecting... (${this.reconnectAttempts}/${this.maxReconnectAttempts})`);
27
        setTimeout(() => this.connect(), this.reconnectDelay);
28
      } else {
29
        console.error('Max reconnect attempts reached');
30
        this.close();
31
      }
32
    };
33
  }
34

35
  close() {
36
    if (this.eventSource) {
37
      this.eventSource.close();
38
      this.eventSource = null;
39
    }
40
  }
41
}

展开收起

重连与事件顺序#

服务器需要确保事件的顺序和连续性：

1
class EventPublisher {
2
  constructor() {
3
    this.events = [];
4
    this.maxStoredEvents = 100;
5
    this.lastEventId = 0;
6
  }
7

8
  publish(eventType, data) {
9
    const event = {
10
      id: ++this.lastEventId,
11
      type: eventType,
12
      data: data,
13
      timestamp: Date.now()
14
    };
15

16
    this.events.push(event);
17

18
    if (this.events.length > this.maxStoredEvents) {
19
      this.events.shift();
20
    }
21

22
    this.broadcast(event);
23
  }
24

25
  getEventsSince(lastEventId) {
26
    return this.events.filter(e => e.id > lastEventId);
27
  }
28

29
  broadcast(event) {
30
    this.clients.forEach(client => {
31
      client.send(event);
32
    });
33
  }
34
}

展开收起

字段说明#

data 字段#

数据内容，可以是多行。多行数据会自动用换行符连接。

1
data: First line\n
2
data: Second line\n
3
data: Third line\n\n
4

5
// 解析为:
6
// "First line\nSecond line\nThird line"

event 字段#

事件类型，客户端通过 addEventListener 监听。

1
event: custom-event\n
2
data: {"message": "Hello"}\n\n

id 字段#

事件唯一标识，用于断线重连时恢复。

1
id: 123\n
2
event: update\n
3
data: {"value": 100}\n\n

retry 字段#

指定重连时间（毫秒）。

1
retry: 5000\n
2
data: {"message": "Set 5s retry"}\n\n

冒号开头的注释#

1
: This is a comment\n
2
data: ping\n\n

安全考虑#

CORS 配置#

1
app.get('/api/sse', (req, res) => {
2
  res.setHeader('Access-Control-Allow-Origin', 'https://yourdomain.com');
3
  res.setHeader('Content-Type', 'text/event-stream');
4
  res.setHeader('Cache-Control', 'no-cache');
5
  res.setHeader('Connection', 'keep-alive');
6
});

认证与授权#

1
// 方式 1: Cookie (withCredentials)
2
const eventSource = new EventSource('/api/sse', {
3
  withCredentials: true
4
});
5

6
// 方式 2: 初始连接后验证
7
app.get('/api/sse', (req, res) => {
8
  const sessionId = req.cookies.sessionId;
9

10
  if (!validateSession(sessionId)) {
11
    res.writeHead(401);
12
    res.end('Unauthorized');
13
    return;
14
  }
15

16
  // ... 建立 SSE 连接
17
});

展开收起

连接数限制#

1
const connections = new Map();
2
const MAX_CONNECTIONS_PER_IP = 5;
3

4
app.get('/api/sse', (req, res) => {
5
  const ip = req.ip;
6

7
  if (connections.get(ip) >= MAX_CONNECTIONS_PER_IP) {
8
    res.writeHead(429);
9
    res.end('Connection limit exceeded');
10
    return;
11
  }
12

13
  connections.set(ip, connections.get(ip) + 1);
14

15
  req.on('close', () => {
16
    connections.set(ip, connections.get(ip) - 1);
17
  });
18
});

展开收起

速率限制#

1
const rateLimiter = {
2
  windowMs: 1000,
3
  maxEvents: 10,
4
  counts: {},
5

6
  check(clientId) {
7
    const now = Date.now();
8
    const key = `${clientId}:${Math.floor(now / this.windowMs)}`;
9
    this.counts[key] = (this.counts[key] || 0) + 1;
10
    return this.counts[key] <= this.maxEvents;
11
  }
12
};

实际应用场景#

1. 实时通知系统#

1
// 服务器: 通知推送服务
2
class NotificationService {
3
  constructor() {
4
    this.subscribers = new Map();
5
  }
6

7
  subscribe(userId, client) {
8
    if (!this.subscribers.has(userId)) {
9
      this.subscribers.set(userId, []);
10
    }
11
    this.subscribers.get(userId).push(client);
12
  }
13

14
  notify(userId, notification) {
15
    const clients = this.subscribers.get(userId);
16
    if (clients) {
17
      clients.forEach(client => {
18
        client.send({
19
          event: 'notification',
20
          data: notification
21
        });
22
      });
23
    }
24
  }
25
}
26

27
// 客户端
28
const eventSource = new EventSource(`/api/notifications/${userId}`);
29

30
eventSource.addEventListener('notification', (event) => {
31
  const notification = JSON.parse(event.data);
32
  showToast(notification.title, notification.body);
33
});

展开收起

2. 实时数据仪表盘#

1
// 服务器: 系统监控
2
app.get('/api/metrics', (req, res) => {
3
  res.setHeader('Content-Type', 'text/event-stream');
4

5
  const sendMetric = () => {
6
    const metrics = {
7
      cpu: os.loadavg()[0],
8
      memory: (1 - os.freemem() / os.totalmem()) * 100,
9
      connections: activeConnections.size()
10
    };
11
    res.write(`data: ${JSON.stringify(metrics)}\n\n`);
12
  };
13

14
  const interval = setInterval(sendMetric, 1000);
15

16
  req.on('close', () => {
17
    clearInterval(interval);
18
  });
19
});

展开收起

3. 聊天消息推送#

1
// 服务器: 消息推送
2
function handleChatSSE(req, res, userId) {
3
  res.setHeader('Content-Type', 'text/event-stream');
4

5
  const sendMessage = (message) => {
6
    res.write(`event: message\n`);
7
    res.write(`data: ${JSON.stringify(message)}\n\n`);
8
  };
9

10
  subscribe(userId, sendMessage);
11

12
  req.on('close', () => {
13
    unsubscribe(userId, sendMessage);
14
  });
15
}

展开收起

4. AI 流式响应#

1
// 服务器: AI 流式生成
2
app.post('/api/ai/chat', async (req, res) => {
3
  const { prompt } = req.body;
4
  res.setHeader('Content-Type', 'text/event-stream');
5

6
  try {
7
    const stream = await ai.generateStream(prompt);
8

9
    for await (const chunk of stream) {
10
      res.write(`data: ${JSON.stringify({ token: chunk })}\n\n`);
11
    }
12

13
    res.write(`event: done\n`);
14
    res.write(`data: ${JSON.stringify({ completed: true })}\n\n`);
15
  } catch (error) {
16
    res.write(`event: error\n`);
17
    res.write(`data: ${JSON.stringify({ message: error.message })}\n\n`);
18
  }
19

20
  res.end();
21
});

展开收起

性能优化#

1. 连接池管理#

1
class SSEConnectionPool {
2
  constructor(maxConnections = 100) {
3
    this.pool = new Map();
4
    this.maxConnections = maxConnections;
5
  }
6

7
  get(key) {
8
    if (this.pool.size >= this.maxConnections) {
9
      const oldest = this.findOldest();
10
      if (oldest) {
11
        oldest.close();
12
        this.pool.delete(oldest.key);
13
      }
14
    }
15

16
    const connection = new SSEConnection(key);
17
    this.pool.set(key, connection);
18
    return connection;
19
  }
20

21
  remove(key) {
22
    const connection = this.pool.get(key);
23
    if (connection) {
24
      connection.close();
25
      this.pool.delete(key);
26
    }
27
  }
28
}

展开收起

2. 心跳优化#

1
const HEARTBEAT_INTERVAL = 30000; // 30 秒
2
let lastActivity = Date.now();
3

4
const heartbeat = setInterval(() => {
5
  if (Date.now() - lastActivity >= HEARTBEAT_INTERVAL) {
6
    res.write(`: heartbeat\n\n`);
7
    lastActivity = Date.now();
8
  }
9
}, HEARTBEAT_INTERVAL);
10

11
function onActivity() {
12
  lastActivity = Date.now();
13
}

3. 消息批量处理#

1
class MessageBuffer {
2
  constructor(callback, batchSize = 10, flushInterval = 100) {
3
    this.callback = callback;
4
    this.batchSize = batchSize;
5
    this.buffer = [];
6
    this.timer = null;
7
  }
8

9
  push(message) {
10
    this.buffer.push(message);
11

12
    if (this.buffer.length >= this.batchSize) {
13
      this.flush();
14
    } else if (!this.timer) {
15
      this.timer = setTimeout(() => this.flush(), this.flushInterval);
16
    }
17
  }
18

19
  flush() {
20
    if (this.buffer.length > 0) {
21
      this.callback([...this.buffer]);
22
      this.buffer = [];
23
    }
24
    if (this.timer) {
25
      clearTimeout(this.timer);
26
      this.timer = null;
27
    }
28
  }
29
}

展开收起

完整示例#

实时股票行情系统#

前端页面

1
<!DOCTYPE html>
2
<html lang="zh-CN">
3
<head>
4
  <meta charset="UTF-8">
5
  <title>Real-time Stock Quotes</title>
6
  <style>
7
    body { font-family: Arial, sans-serif; margin: 20px; }
8
    .stock-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(200px, 1fr)); gap: 16px; }
9
    .stock-card {
10
      border: 1px solid #ddd;
11
      border-radius: 8px;
12
      padding: 16px;
13
      transition: box-shadow 0.3s;
14
    }
15
    .stock-card:hover { box-shadow: 0 4px 12px rgba(0,0,0,0.1); }
16
    .stock-symbol { font-weight: bold; font-size: 18px; }
17
    .stock-price { font-size: 24px; color: #333; margin: 8px 0; }
18
    .stock-change { font-size: 14px; }
19
    .up { color: #4caf50; }
20
    .down { color: #f44336; }
21
  </style>
22
</head>
23
<body>
24
  <h1>Real-time Stock Quotes</h1>
25
  <div id="stockGrid" class="stock-grid"></div>
26

27
  <script>
28
    const stocks = new Map();
29

30
    const eventSource = new EventSource('/api/stocks/stream');
31

32
    eventSource.addEventListener('initial-data', (event) => {
33
      const data = JSON.parse(event.data);
34
      data.forEach(stock => {
35
        stocks.set(stock.symbol, stock);
36
        createStockCard(stock);
37
      });
38
    });
39

40
    eventSource.addEventListener('stock-update', (event) => {
41
      const data = JSON.parse(event.data);
42
      updateStockCard(data);
43
    });
44

45
    function updateStockCard(stock) {
46
      const existing = stocks.get(stock.symbol);
47
      if (existing) {
48
        existing.price = stock.price;
49
        existing.change = stock.change;
50
        existing.changePercent = stock.changePercent;
51

52
        const card = document.querySelector(`[data-symbol="${stock.symbol}"]`);
53
        if (card) {
54
          const priceEl = card.querySelector('.stock-price');
55
          const changeEl = card.querySelector('.stock-change');
56

57
          priceEl.textContent = `$${stock.price.toFixed(2)}`;
58
          const isUp = stock.change >= 0;
59
          changeEl.textContent = `${isUp ? '+' : ''}${stock.change.toFixed(2)} (${isUp ? '+' : ''}${stock.changePercent.toFixed(2)}%)`;
60
          changeEl.className = `stock-change ${isUp ? 'up' : 'down'}`;
61
        }
62
      } else {
63
        stocks.set(stock.symbol, stock);
64
        createStockCard(stock);
65
      }
66
    }
67

68
    function createStockCard(stock) {
69
      const grid = document.getElementById('stockGrid');
70
      const isUp = stock.change >= 0;
71

72
      const card = document.createElement('div');
73
      card.className = 'stock-card';
74
      card.dataset.symbol = stock.symbol;
75
      card.innerHTML = `
76
        <div class="stock-symbol">${stock.symbol}</div>
77
        <div class="stock-price">$${stock.price.toFixed(2)}</div>
78
        <div class="stock-change ${isUp ? 'up' : 'down'}">
79
          ${isUp ? '+' : ''}${stock.change.toFixed(2)} (${isUp ? '+' : ''}${stock.changePercent.toFixed(2)}%)
80
        </div>
81
      `;
82

83
      grid.appendChild(card);
84
    }
85

86
    window.addEventListener('beforeunload', () => {
87
      eventSource.close();
88
    });
89
  </script>
90
</body>
91
</html>

展开收起

Node.js 服务器

server-stock.js展开收起

1
const express = require('express');
2
const app = express();
3

4
const stocks = [
5
  { symbol: 'AAPL', basePrice: 175.50 },
6
  { symbol: 'GOOGL', basePrice: 140.25 },
7
  { symbol: 'MSFT', basePrice: 378.90 },
8
  { symbol: 'AMZN', basePrice: 178.50 },
9
  { symbol: 'TSLA', basePrice: 242.80 },
10
];
11

12
const stockPrices = new Map();
13
stocks.forEach(s => {
14
  stockPrices.set(s.symbol, {
15
    symbol: s.symbol,
16
    price: s.basePrice,
17
    change: 0,
18
    changePercent: 0
19
  });
20
});
21

22
const clients = new Set();
23

24
app.get('/api/stocks/stream', (req, res) => {
25
  res.setHeader('Content-Type', 'text/event-stream');
26
  res.setHeader('Cache-Control', 'no-cache');
27
  res.setHeader('Connection', 'keep-alive');
28
  res.setHeader('Access-Control-Allow-Origin', '*');
29

30
  const initialData = Array.from(stockPrices.values());
31
  res.write(`event: initial-data\n`);
32
  res.write(`data: ${JSON.stringify(initialData)}\n\n`);
33

34
  clients.add(res);
35
  console.log(`Client connected. Total: ${clients.size}`);
36

37
  const heartbeat = setInterval(() => {
38
    res.write(`: heartbeat\n\n`);
39
  }, 30000);
40

41
  req.on('close', () => {
42
    clearInterval(heartbeat);
43
    clients.delete(res);
44
    console.log(`Client disconnected. Total: ${clients.size}`);
45
  });
46
});
47

48
function broadcastUpdate() {
49
  const symbols = Array.from(stockPrices.keys());
50
  const symbol = symbols[Math.floor(Math.random() * symbols.length)];
51

52
  const stock = stockPrices.get(symbol);
53
  const change = (Math.random() - 0.5) * 2;
54
  const newPrice = Math.max(1, stock.price + change);
55
  const totalChange = newPrice - stock.basePrice;
56
  const changePercent = (totalChange / stock.basePrice) * 100;
57

58
  stock.price = parseFloat(newPrice.toFixed(2));
59
  stock.change = parseFloat(totalChange.toFixed(2));
60
  stock.changePercent = parseFloat(changePercent.toFixed(2));
61

62
  const message = `event: stock-update\ndata: ${JSON.stringify(stock)}\n\n`;
63

64
  clients.forEach(client => {
65
    client.write(message);
66
  });
67
}
68

69
setInterval(broadcastUpdate, 1000);
70

71
app.listen(3000, () => {
72
  console.log('Stock SSE server running on http://localhost:3000');
73
});

展开收起

调试工具#

curl 测试#

Terminal window

1
# 测试 SSE 端点
2
curl -N -H "Accept: text/event-stream" http://localhost:3000/api/events
3

4
# 测试带 Last-Event-ID 的重连
5
curl -N -H "Accept: text/event-stream" -H "Last-Event-ID: 5" http://localhost:3000/api/events

浏览器开发者工具#

Network 面板: 查看 SSE 连接，类型为 EventSource
Response 面板: 实时查看接收到的数据

JavaScript 调试技巧#

1
class DebugEventSource {
2
  constructor(url, options = {}) {
3
    this.original = new EventSource(url, options);
4
    this.debug = options.debug || false;
5

6
    this.original.onopen = (e) => this.log('OPEN', e);
7
    this.original.onmessage = (e) => this.log('MESSAGE', e.data);
8
    this.original.onerror = (e) => this.log('ERROR', e);
9

10
    return this.original;
11
  }
12

13
  log(type, data) {
14
    if (this.debug) {
15
      console.log(`[SSE ${type}]`, data);
16
    }
17
  }
18

19
  addEventListener(type, listener) {
20
    this.original.addEventListener(type, (e) => {
21
      if (this.debug) {
22
        console.log(`[SSE EVENT: ${type}]`, e.data);
23
      }
24
      listener(e);
25
    });
26
  }
27
}
28

29
const eventSource = new DebugEventSource('/api/events', { debug: true });

展开收起

常见问题#

Q: 为什么收到两条相同的消息？#

可能是重连导致的。检查 Last-Event-ID 是否正确传递，服务器需要实现去重逻辑。

1
const processedEvents = new Set();
2

3
function sendEvent(res, eventId, data) {
4
  if (processedEvents.has(eventId)) {
5
    return;
6
  }
7
  processedEvents.add(eventId);
8
  res.write(`id: ${eventId}\n`);
9
  res.write(`data: ${JSON.stringify(data)}\n\n`);
10
}

Q: 连接经常断开？#

检查网络和代理配置：

Nginx 代理: 确保 proxy_buffering off;
Cloudflare: SSE 可能被识别为爬虫
AWS ALB: 默认 60 秒超时，需要配置更长超时

Q: 如何在 Vue/React 中使用？#

Vue 3 Composition API

1
import { ref, onMounted, onUnmounted } from 'vue';
2

3
export function useSSE(url) {
4
  const data = ref(null);
5
  const error = ref(null);
6
  const connected = ref(false);
7
  let eventSource = null;
8

9
  onMounted(() => {
10
    eventSource = new EventSource(url);
11

12
    eventSource.onopen = () => { connected.value = true; };
13
    eventSource.onmessage = (event) => { data.value = JSON.parse(event.data); };
14
    eventSource.onerror = (err) => { error.value = err; connected.value = false; };
15
  });
16

17
  onUnmounted(() => {
18
    if (eventSource) {
19
      eventSource.close();
20
    }
21
  });
22

23
  return { data, error, connected };
24
}

展开收起

React Hook

1
import { useState, useEffect, useRef } from 'react';
2

3
function useSSE(url) {
4
  const [data, setData] = useState(null);
5
  const [connected, setConnected] = useState(false);
6
  const eventSourceRef = useRef(null);
7

8
  useEffect(() => {
9
    const eventSource = new EventSource(url);
10
    eventSourceRef.current = eventSource;
11

12
    eventSource.onopen = () => setConnected(true);
13
    eventSource.onmessage = (event) => setData(JSON.parse(event.data));
14
    eventSource.onerror = () => setConnected(false);
15

16
    return () => {
17
      eventSource.close();
18
    };
19
  }, [url]);
20

21
  return { data, connected };
22
}

展开收起

Q: SSE 与 WebSocket 同时使用？#

可以共存，根据场景选择：

1
// 简单推送场景用 SSE
2
const eventSource = new EventSource('/api/notifications');
3

4
// 实时交互场景用 WebSocket
5
const ws = new WebSocket('wss://api/ws');

Q: 如何限制最大连接数？#

1
const MAX_CONNECTIONS = 1000;
2
const activeConnections = new Set();
3

4
app.get('/api/sse', (req, res) => {
5
  if (activeConnections.size >= MAX_CONNECTIONS) {
6
    res.writeHead(503, { 'Retry-After': 30 });
7
    res.end('Server busy');
8
    return;
9
  }
10

11
  activeConnections.add(res);
12

13
  res.on('close', () => {
14
    activeConnections.delete(res);
15
  });
16
});

展开收起

Q: 支持二进制数据？#

SSE 本身是文本协议。传输二进制需要 Base64 编码：

1
// Base64 编码
2
const binaryData = new Uint8Array([0x00, 0xFF, 0x42]);
3
const base64 = btoa(String.fromCharCode(...binaryData));
4

5
res.write(`data: ${base64}\n\n`);

参考资源#

今日头条创作

Sun, 19 Apr 2026 00:00:00 GMT

今日头条程序员/科技博主创作全攻略（2026最新）#

作为软件程序员与科技人文爱好者，在今日头条创作的核心是合规+原创+垂直，守住这三点，配合平台规则与流量扶持，就能快速成长为优质创作者。以下是为你量身定制的详细指南，覆盖规则红线、新手入门与账号进阶全流程。

一、核心创作规则（程序员/科技领域重点）#

1. 账号基础规则（必知）#

实名认证：必须完成，否则无法开通创作收益与原创标签
信用分机制（满分100）：
- 违规扣分，低于60分核心权益冻结，连续10天无违规自动恢复10分
- 程序员常见风险点：AI代码未标注（扣20分）、技术观点错误（扣10分）、无资质谈安全/金融技术（扣20分）
垂直领域：选择1-2个专注方向（如C++开发、AI应用、嵌入式系统），避免跨领域发布

2. 内容红线清单（程序员需特别注意）#

违规类型	处罚力度	典型案例（程序员常踩）
AI内容未标注	限流+扣20分	整篇AI生成技术文章未勾选”引用AI”选项；AI生成代码未说明
无资质专业内容	限流+扣分	无网络安全资质谈渗透测试；无金融资质分析区块链投资
代码版权问题	取消原创+扣分	未经授权复制开源代码；未注明出处引用他人技术方案
技术误导	扣10-20分	发布错误技术教程；夸大AI编程能力；编造技术数据
标题党/夸大宣传	扣10分	“零基础7天精通C++”、“AI编程让程序员失业”等夸大标题
违规导流	限流+扣分	文章中引导至未认证个人博客；无广告标识推广技术课程

3. 原创与AI使用规范（程序员创作关键）#

原创判定标准：技术文章需包含独特见解、实际代码示例、个人经验总结，引用资料必须注明来源
AI内容标注规则：
- 整篇AI生成内容必须在发布页勾选”引用AI/AI生成内容”
- 视频在前5秒添加”AI辅助创作”文字标注，图文在标题下方标注
- 仅用AI辅助代码生成/资料整理无需标注，避免误标影响流量
代码发布规范：
- 开源代码需提供GitHub链接并遵守开源协议
- 商业代码仅展示关键片段，避免泄露核心逻辑
- AI生成代码需添加注释说明生成工具与人工修改部分

4. 专业领域资质要求（程序员常见领域）#

领域	所需资质	平台认证方式
网络安全	CISP/CISAW等认证	创作中心→资质认证→上传证书
金融科技	金融从业资格证	创作中心→资质认证→上传证书
医疗IT	医疗相关资质	创作中心→资质认证→上传证书
教育技术	教师资格证	创作中心→资质认证→上传证书
技术培训	企业/机构认证	完成企业认证后发布培训内容

二、新手创作引导（程序员专属入门路径）#

1. 账号开通五步走（快速启动）#

下载注册：安装官方今日头条APP，用手机号注册，完善头像（技术相关）、昵称（含领域标识，如”码农阿泽”）、简介（突出技术专长）
实名认证：我的→设置→账号与安全→实名认证（准备身份证）
开通创作权益：我的→创作中心→创作权益，开启文章创作收益、头条首发、微头条创作收益（0粉丝即可开通）
兴趣认证：选择”程序员/技术专家”领域，发布4条优质技术内容通过认证，增强账号垂直度
设备准备：电脑端使用头条号后台（mp.toutiao.com）撰写技术文章，支持代码高亮与格式编辑

2. 7天起号计划（程序员专属，平台考核期关键）#

天数	任务清单	技术创作重点	目标
Day1	1条300字微头条（技术热点+个人见解）	如”AI编程工具对比：Copilot vs CodeLlama”	告诉系统账号定位为技术领域
Day2-3	每天1条微头条+2条高质量评论	评论同领域爆款文章，提供技术补充	提升账号活跃度，建立专业形象
Day4	1篇800字技术文章（含代码示例）	如”C++智能指针使用误区与解决方案”	展示技术实力，申请原创标签铺垫
Day5	1条技术短视频（5分钟内）	演示”如何用CMake构建C++项目”	测试视频内容流量表现
Day6-7	每天1篇技术文章+1条微头条	技术文章深入讲解，微头条分享技术感悟	完成平台考核，提升账号权重

3. 内容创作技巧（程序员快速出爆款）#

选题方向（高流量技术领域）：
1. 技术实战：如”嵌入式Linux驱动开发步骤”、“WebRTC音视频通话实现”（结合代码示例）
2. AI应用：如”用Ollama部署本地大模型”、“AI Agent在软件工程中的应用”（结合实际案例）
3. 技术对比：如”C++ vs Rust性能对比”、“libuv vs Boost.Asio异步IO库分析”（数据支撑）
4. 踩坑经验：如”排查C++内存泄漏的5种方法”、“Docker部署C++项目常见问题”（实用价值高）
5. 技术人文：如”程序员职业发展路径”、“开源社区文化分析”（吸引非技术读者）
标题撰写公式：
- 问题+解决方案：“如何解决C++多线程死锁问题？3种实用方案”
- 经验+数据：“我用libuv开发网络库的3年经验，性能提升40%”
- 趋势+见解：“2026年嵌入式AI发展趋势，程序员该如何转型？”

内容结构（技术文章标准）：

1
标题（25字内）→ 引言（问题背景）→ 核心技术原理 → 代码实现（带注释）→ 实战演示 → 问题排查 → 总结与展望

代码展示规范：
- 使用代码块，添加语法高亮（头条号后台支持）
- 关键代码添加详细注释，解释设计思路
- 提供完整代码GitHub链接，方便读者下载测试

三、账号进阶指南（从技术博主到专业创作者）#

1. 原创标签申请（程序员必备权益）#

申请条件：
1. 账号注册满30天，近30天发布≥3篇原创技术文章，原创比例超70%
2. 账号状态正常，信用分100分，无违规记录
3. 技术文章包含独特见解、实际代码、个人经验，非纯理论复述
申请流程：创作中心→创作权益→原创标签→提交申请（24小时内审核）
权益提升：原创文章收益提升3-5倍，获得平台优先推荐

2. 变现路径（程序员技术变现全攻略）#

变现方式	开通条件	技术创作应用	收益预估
基础创作收益	实名认证+0粉丝	技术文章、微头条、视频	千次阅读1-5元，爆款单篇可达千元
原创补贴	原创标签	深度技术文章、系列教程	单篇补贴50-200元，优质内容最高5倍奖励
头条首发	开通首发权益	技术文章优先在头条发布	额外10-30%收益加成
商品卡	粉丝≥1000	推荐技术书籍、开发板、工具软件	佣金率10-30%，月入可达数千元
专栏订阅	优质创作者认证	系列技术课程（如”C++并发编程实战”）	定价9.9-99元，订阅量决定收益
直播带货	粉丝≥10000	技术直播+开发工具/课程推广	单次直播收益可达万元
技术咨询	优质创作者认证	提供技术问题解答、项目指导	按次收费，单次100-500元

3. 账号进阶三步法（从新手到专家）#

深耕垂直领域：
- 选择1个核心技术方向（如嵌入式AI、视频流媒体），成为该领域权威
- 建立系列内容（如”C++性能优化系列”、“嵌入式Linux开发系列”），增强用户粘性
- 定期发布深度内容（10分钟+视频、2000字+长文），获取平台深度内容补贴
数据驱动优化：
- 创作中心数据分析：重点关注阅读完成率（技术文章需>60%）、收藏/转发比（>0.5%为优质）、粉丝增长
- 发布时间优化：程序员读者活跃时段为21:00-23<00>（下班后）、12:00-13<00>（午休）
- 内容形式调整：技术复杂内容用视频+图文组合；入门内容用微头条+短视频快速传播
建立个人品牌：
- 统一账号名称、头像、简介，强化技术形象
- 与同领域创作者互动，参与技术话题讨论，扩大影响力
- 开通知乎、GitHub等平台账号，多平台联动引流
- 定期举办技术直播，解答读者问题，增强粉丝粘性

四、避坑指南（程序员常见错误）#

忽视信用分：信用分是创作”生命线”，扣分后立即整改，连续10天无违规恢复
跨领域乱发：今天发C++，明天发Python，后天发AI，导致账号定位模糊，流量分散
技术内容太晦涩：用太多专业术语，缺乏通俗解释，导致阅读完成率低，推荐量受限
不标注AI内容：用AI生成技术文章未标注，被系统判定为低质内容，影响账号权重
忽视版权问题：复制他人代码或技术文章未注明出处，被投诉侵权，取消原创标签
不看平台规则：未关注”头条号”官方账号，错过技术领域规则更新，导致违规

五、官方支持与申诉渠道#

创作中心：提供新手引导、权益说明、数据分析等一站式服务
规则查询：在创作中心查看《今日头条社区规范》《内容审核标准》
申诉流程：系统通知→处罚详情→提交申诉，附上代码原创证明/授权文件/AI使用说明，24小时内回复
技术创作者交流群：关注头条号官方账号，获取加入方式，与其他技术博主交流经验

六、程序员创作黄金建议#

技术+人文结合：在技术内容中融入个人经验、行业洞察，让文章既有深度又有温度，吸引更多读者
实战为王：技术文章必须包含可运行代码、实际案例、踩坑经验，这是区别于AI生成内容的关键
持续输出：新号前7天保持日更，建立系统对账号的信任度，之后保持每周3-5篇稳定更新
对标学习：关注10个同领域爆款技术账号（如”Linux内核之旅”、“AI编程实验室”），分析其选题、标题、结构特点
数据驱动：定期查看创作中心数据分析，优化内容方向和发布时间，提升推荐量和收益

记住：今日头条对技术内容（特别是AI、嵌入式、流媒体等前沿领域）有流量扶持，作为软件程序员，你拥有天然的内容优势。只要遵守规则、坚持原创、深耕垂直领域，就能在平台快速成长，实现技术变现与个人品牌建设的双赢！

要不要我给你整理一份可直接套用的技术文章发布模板（含标题公式、内容结构、代码展示规范和AI标注说明），你照着填就能快速发布？

引流#

可以给个人博客引流，但必须严格遵守今日头条导流规范，违规会被限流、扣分（信用分），严重时影响账号权益，具体要求如下：

合规引流边界：仅可在账号简介中合理标注个人博客信息（需清晰、无诱导性），且博客需为正规备案、非违规平台，不可出现“点击跳转”“去我博客看完整内容”等诱导性表述；
绝对禁止行为：正文（文章、微头条、视频）、评论区、私信中，禁止放置博客链接、引导跳转至博客（如“完整代码在我博客”），禁止用谐音、隐晦表述引导（参考superscript:1superscript<3>），否则判定为违规导流，触发限流+扣分；
补充说明：即使是技术类个人博客，未按规范引流也会违规（对应canvas中“违规导流”红线），平台严打私自向外导流行为，所有推广类引导需符合《今日头条内容电商创作管理规范》（参考superscript<1>）。

核心原则：不影响头条内容本身的完整性，不诱导用户脱离平台，仅在简介中被动展示博客信息，不主动引导跳转。

需要我帮你检查一下你准备的简介博客标注文案，判断是否符合平台合规要求吗？

结合你的博客情况（阿里云域名+GitHub Pages搭建），可以合规引流，但需严格遵守今日头条规则，违规会直接影响账号权益，具体说明如下：

一、能否引流（核心判断）#

可以引流，但仅限定「合规场景」，你的博客本身符合平台要求（GitHub Pages允许个人非商业使用，阿里云域名完成实名认证后可正常展示），但需满足2个核心前提：

阿里云域名需合规：若为国内后缀（如.cn），必须完成ICP备案（备案流程参考）；若为国际后缀（如.com），需完成域名实名认证，无违规内容（如低俗、违法信息）；
引流方式仅可「被动展示」：仅能在账号简介中标注博客域名（无诱导性表述），不可在正文、评论区、私信中引导跳转。

二、引流的影响（分合规/违规两种情况）#

1. 合规引流（无负面影响，可实现被动引流）#

无处罚：严格按规则在简介标注（如“个人技术博客：xxx.xxx（阿里云域名），分享编程干货”），不主动引导，不会触发限流、扣分；
正向作用：吸引对技术内容感兴趣的粉丝，主动访问你的博客，实现头条账号与个人博客的联动，助力个人品牌建设（契合canvas中“品牌建设”进阶要求）。

2. 违规引流（直接影响账号权益，重点规避）#

处罚类型：对应canvas中“违规导流”红线，触发限流（内容推荐量骤降）、信用分扣分（10-20分），严重时冻结创作收益、原创标签；
常见违规场景（针对你的博客）：
1. 正文/评论区引导：如“完整代码在我的博客（xxx.xxx）”“去我博客看详细教程”，或用谐音、隐晦表述引导；
2. 域名不合规：阿里云国内后缀域名未完成ICP备案，标注后被判定为“违规平台导流”；
3. 诱导性表述：简介中出现“点击”“跳转”“关注博客”等诱导性文字（参考头条严打诱导导流要求）。

三、补充注意事项#

GitHub Pages本身合规（个人非商业使用不受限），但不可在头条内容中放置GitHub Pages的原生链接（仅可标注绑定的阿里云域名）；
博客内容需与头条账号垂直领域一致（均为程序员/科技类），避免博客含违规内容（如无资质专业内容、低俗信息），否则会连带影响头条账号；
若违规被处罚，可按canvas中“申诉流程”，提交域名备案证明、博客合规说明，24小时内平台会回复。

☁️ 云计算服务模型全解析：从 IaaS 到 CaaS，一文读懂所有「aaS」

Sat, 11 Apr 2026 00:00:00 GMT

云计算服务模型全解析：从 IaaS 到 CaaS，一文读懂所有「aaS」#

给程序员的云计算模型指南，建议收藏

目录#

概述：什么是 XaaS
IaaS - 基础设施即服务
PaaS - 平台即服务
SaaS - 软件即服务
DaaS - 数据即服务
BaaS - 后端即服务
CaaS - 容器即服务
对比总结
如何选择

概述：什么是 XaaS#

XaaS (Everything as a Service) 指的是”一切皆服务”，是云计算的核心商业模式。本质上是将 IT 资源、能力以服务的形式通过互联网提供给用户，按需使用，按量付费。

核心特征#

按需自助服务：用户可自行获取资源，无需人工干预
广泛的网络访问：通过网络随时随地访问
资源池化：多租户共享资源池
快速弹性：资源可快速扩展或收缩
可计量服务：使用情况可监控、控制和报告

传统模型 vs 云服务模型#

1
传统自建模式：
2
┌─────────────────────────────────────┐
3
│  应用  │  数据  │  运行时  │  中间件  │
4
├─────────────────────────────────────┤
5
│        操作系统      │   虚拟化     │
6
├─────────────────────────────────────┤
7
│           服务器         │   存储     │
8
├─────────────────────────────────────┤
9
│              网络设备                │
10
└─────────────────────────────────────┘
11
     ↑ 全部自己管理和维护
12

13
云服务模式：
14
┌─────────────────────────────────────┐
15
│  应用  │  数据  │  运行时  │  中间件  │  ← SaaS
16
├─────────────────────────────────────┤
17
│        操作系统      │   虚拟化     │  ← PaaS
18
├─────────────────────────────────────┤
19
│           服务器         │   存储     │  ← IaaS
20
└─────────────────────────────────────┘
21
     ↑ 云服务商管理底层，你专注上层

展开收起

IaaS - 基础设施即服务#

定义#

Infrastructure as a Service 提供虚拟化的计算资源（虚拟机、存储、网络等），是最底层的云服务模型。

你管理什么 vs 云厂商管理什么#

1
你管理：    应用 + 数据 + 运行时 + 中间件 + 操作系统
2
云厂商管理：虚拟化 + 服务器 + 存储 + 网络

核心服务#

计算资源：虚拟机实例（EC2、ECS）
存储服务：块存储、对象存储（S3、OSS）
网络资源：VPC、负载均衡、CDN
安全组：防火墙规则

典型场景#

需要完全控制操作系统和运行环境
迁移现有应用到云端（Lift & Shift）
开发和测试环境
高性能计算（HPC）
大数据处理

主流产品#

厂商	产品
AWS	EC2, S3, VPC
阿里云	ECS, OSS, VPC
腾讯云	CVM, COS, VPC
Azure	Virtual Machines, Blob Storage

代码示例：启动一台 EC2 实例#

1
import boto3
2

3
ec2 = boto3.resource('ec2')
4

5
instance = ec2.create_instances(
6
    ImageId='ami-0c55b159cbfafe1f0',
7
    InstanceType='t2.micro',
8
    MinCount=1,
9
    MaxCount=1,
10
    KeyName='my-key-pair'
11
)
12

13
print(f"Instance ID: {instance[0].id}")

优缺点#

✅ 优点：

最高灵活性和控制权
无需投资硬件
按需付费，成本可控

❌ 缺点：

需要自己管理操作系统和安全补丁
运维复杂度较高
需要专业的系统管理员

PaaS - 平台即服务#

定义#

Platform as a Service 提供应用程序开发和部署所需的完整平台环境，开发者只需关注代码。

你管理什么 vs 云厂商管理什么#

1
你管理：    应用 + 数据
2
云厂商管理：运行时 + 中间件 + 操作系统 + 虚拟化 + 服务器 + 存储 + 网络

核心服务#

应用托管：自动部署和扩展
数据库服务：托管数据库（RDS、Cloud SQL）
中间件：消息队列、缓存
开发工具：CI/CD、监控

典型场景#

Web 应用快速开发和部署
微服务架构
API 服务
移动应用后端
需要自动扩缩容的场景

主流产品#

厂商	产品
Heroku	Heroku Platform
Google	App Engine, Cloud Run
AWS	Elastic Beanstalk, Lambda
阿里云	函数计算，Web+

代码示例：部署到 Heroku#

Terminal window

1
# 初始化 Git 仓库
2
git init
3
git add .
4
git commit -m "Initial commit"
5

6
# 添加 Heroku remote
7
heroku git:remote -a my-app
8

9
# 部署
10
git push heroku main
11

12
# 查看日志
13
heroku logs --tail

优缺点#

✅ 优点：

专注业务逻辑，无需关心基础设施
快速开发和部署
自动扩缩容
内置高可用和备份

❌ 缺点：

平台锁定风险
自定义能力受限
成本可能高于 IaaS（大规模时）

SaaS - 软件即服务#

定义#

Software as a Service 提供完整的软件应用，用户通过浏览器或客户端直接使用，无需安装和维护。

你管理什么 vs 云厂商管理什么#

1
你管理：    （几乎不管理，只配置和使用）
2
云厂商管理：应用 + 数据 + 运行时 + 中间件 + 操作系统 + 所有底层

核心特征#

通过浏览器访问
订阅制付费
自动更新
多租户架构

典型场景#

办公协作（Office 365、Google Workspace）
CRM（Salesforce）
项目管理（Jira、Trello）
邮件服务（Gmail）
在线会议（Zoom、飞书）

主流产品#

类别	产品
办公套件	Office 365, Google Workspace, 飞书
CRM	Salesforce, HubSpot
项目管理	Jira, Asana, Trello
设计	Figma, Canva
客服	Zendesk, Intercom

优缺点#

✅ 优点：

开箱即用，零运维
跨设备访问
自动更新和安全补丁
低成本启动

❌ 缺点：

数据存储在第三方
定制化能力有限
依赖网络连接
长期成本可能较高

DaaS - 数据即服务#

定义#

Data as a Service 提供数据访问、管理和分析服务，用户按需获取数据，无需关心数据存储和处理细节。

核心服务#

数据存储：托管数据库、数据仓库
数据处理：ETL、数据清洗
数据分析：BI 工具、报表
数据 API：通过 API 访问数据

典型场景#

大数据分析
商业智能（BI）
数据湖/数据仓库
实时数据流处理
机器学习数据管道

主流产品#

厂商	产品
Snowflake	Data Cloud
AWS	Redshift, Athena
Google	BigQuery
阿里云	MaxCompute, DataWorks

代码示例：查询 BigQuery#

1
from google.cloud import bigquery
2

3
client = bigquery.Client()
4

5
query = """
6
    SELECT
7
        user_id,
8
        COUNT(*) as order_count,
9
        SUM(amount) as total_amount
10
    FROM `project.dataset.orders`
11
    WHERE created_at >= '2024-01-01'
12
    GROUP BY user_id
13
    ORDER BY total_amount DESC
14
    LIMIT 100
15
"""
16

17
query_job = client.query(query)
18
results = query_job.result()
19

20
for row in results:
21
    print(f"{row.user_id}: {row.order_count} orders, ${row.total_amount}")

展开收起

优缺点#

✅ 优点：

无需管理数据基础设施
弹性扩展
内置分析和可视化工具
支持多种数据源

❌ 缺点：

数据迁移成本高
查询成本可能不可控
数据安全和合规要求

BaaS - 后端即服务#

定义#

Backend as a Service 提供现成的后端功能（数据库、认证、存储等），让开发者专注于前端开发。

核心服务#

数据库：实时数据库、NoSQL
用户认证：登录、注册、权限
文件存储：图片、视频上传
推送通知：消息推送
云函数：无服务器计算

典型场景#

移动应用快速开发
小程序后端
原型验证（MVP）
物联网应用
实时协作应用

主流产品#

厂商	产品
Firebase	Firebase Platform
Supabase	Supabase
AWS	Amplify
LeanCloud	LeanCloud

代码示例：使用 Firebase#

1
// 初始化 Firebase
2
import { initializeApp } from 'firebase/app';
3
import { getFirestore, collection, addDoc } from 'firebase/firestore';
4

5
const firebaseConfig = {
6
  apiKey: "your-api-key",
7
  authDomain: "your-app.firebaseapp.com",
8
  projectId: "your-project-id"
9
};
10

11
const app = initializeApp(firebaseConfig);
12
const db = getFirestore(app);
13

14
// 添加数据
15
async function addUser(name, email) {
16
  const docRef = await addDoc(collection(db, "users"), {
17
    name: name,
18
    email: email,
19
    createdAt: new Date()
20
  });
21
  console.log("Document written with ID: ", docRef.id);
22
}

展开收起

优缺点#

✅ 优点：

极速开发
无需后端开发经验
内置实时同步
免费额度友好

❌ 缺点：

平台锁定严重
复杂业务逻辑受限
大规模时成本高
数据导出困难

CaaS - 容器即服务#

定义#

Container as a Service 提供容器化应用的部署、管理和编排服务，基于 Kubernetes 等容器编排技术。

你管理什么 vs 云厂商管理什么#

1
你管理：    应用 + 数据 + 容器镜像
2
云厂商管理：Kubernetes + 操作系统 + 虚拟化 + 服务器 + 存储 + 网络

核心服务#

容器编排：Kubernetes 集群
容器 registry：镜像仓库
服务网格：Istio、Linkerd
监控日志：Prometheus、ELK

典型场景#

微服务架构
持续集成/持续部署（CI/CD）
混合云部署
需要环境一致性的场景
大规模分布式系统

主流产品#

厂商	产品
AWS	EKS, ECS
Google	GKE
Azure	AKS
阿里云	ACK

代码示例：Kubernetes 部署 YAML#

1
apiVersion: apps/v1
2
kind: Deployment
3
metadata:
4
  name: my-app
5
spec:
6
  replicas: 3
7
  selector:
8
    matchLabels:
9
      app: my-app
10
  template:
11
    metadata:
12
      labels:
13
        app: my-app
14
    spec:
15
      containers:
16
      - name: my-app
17
        image: myregistry/my-app:v1.0
18
        ports:
19
        - containerPort: 8080
20
        resources:
21
          requests:
22
            memory: "256Mi"
23
            cpu: "250m"
24
          limits:
25
            memory: "512Mi"
26
            cpu: "500m"
27
---
28
apiVersion: v1
29
kind: Service
30
metadata:
31
  name: my-app-service
32
spec:
33
  selector:
34
    app: my-app
35
  ports:
36
  - port: 80
37
    targetPort: 8080
38
  type: LoadBalancer

展开收起

优缺点#

✅ 优点：

环境一致性
快速部署和回滚
资源利用率高
强大的编排能力

❌ 缺点：

学习曲线陡峭
Kubernetes 复杂度高
运维成本不低
需要容器化改造

对比总结#

管理层级对比#

1
控制程度：IaaS > PaaS > CaaS > BaaS > DaaS > SaaS
2
抽象程度：SaaS > DaaS > BaaS > CaaS > PaaS > IaaS
3
灵活性：  IaaS > PaaS > CaaS > BaaS > DaaS > SaaS
4
开发速度：SaaS > BaaS > PaaS > CaaS > DaaS > IaaS

详细对比表#

模型	管理内容	适用场景	技术门槛	成本特点
IaaS	应用+OS+中间件	迁移上云、完全控制	高	按资源计费
PaaS	应用 + 数据	Web 应用、快速开发	中	按使用量计费
SaaS	仅配置	办公软件、CRM	低	订阅制
DaaS	数据应用	大数据分析、BI	中高	按查询量计费
BaaS	前端应用	移动应用、MVP	低中	按请求计费
CaaS	容器化应用	微服务、DevOps	高	按节点计费

可视化对比图#

1
┌──────────────────────────────────────────────────────────┐
2
│                        你管理的部分                        │
3
├──────────────────────────────────────────────────────────┤
4
│  SaaS  │                    ●                           │
5
│  DaaS  │                 ●  ●                           │
6
│  BaaS  │              ●  ●  ●                           │
7
│  CaaS  │           ●  ●  ●  ●                           │
8
│  PaaS  │        ●  ●  ●  ●  ●                           │
9
│  IaaS  │     ●  ●  ●  ●  ●  ●  ●                        │
10
├────────┼────────────────────────────────────────────────┤
11
│        │ 应 数 运 中 操 虚 服 存 网                      │
12
│        │ 用 据 行 间 作 拟 务 储 络                      │
13
└────────┴────────────────────────────────────────────────┘

如何选择#

决策树#

1
开始
2
 │
3
 ├─ 只需要使用软件？ ──────────────→ SaaS
4
 │
5
 ├─ 需要快速开发移动应用？ ────────→ BaaS
6
 │
7
 ├─ 主要做大数据分析？ ────────────→ DaaS
8
 │
9
 ├─ 已经容器化了？ ────────────────→ CaaS
10
 │
11
 ├─ 想专注业务逻辑，不想管运维？ ──→ PaaS
12
 │
13
 └─ 需要完全控制，或有特殊需求？ ──→ IaaS

选择建议#

选择 IaaS 如果：#

需要完全控制操作系统
有特殊的性能或安全要求
正在迁移现有应用到云端
团队有系统管理经验

选择 PaaS 如果：#

快速开发和部署是首要目标
团队规模小，想减少运维负担
应用是标准的 Web 架构
需要自动扩缩容

选择 SaaS 如果：#

需求是通用的（办公、CRM、协作）
不想投入任何运维资源
需要快速上线
预算有限，按订阅付费

选择 CaaS 如果：#

采用微服务架构
需要混合云或多云部署
已有容器化经验
追求 DevOps 最佳实践

混合使用策略#

实际项目中，经常混合使用多种模型：

1
示例：现代电商架构
2

3
SaaS: 飞书（办公协作）、Salesforce（CRM）
4
      ↓
5
PaaS: Heroku（营销页面）、Vercel（前端托管）
6
      ↓
7
CaaS: EKS（核心交易系统 - 微服务）
8
      ↓
9
DaaS: Snowflake（数据分析）、Redis Cloud（缓存）
10
      ↓
11
IaaS: EC2（遗留系统、特殊性能需求）

总结#

关键点	说明
本质	都是将 IT 能力以服务形式提供，按需使用
趋势	从底层基础设施向高层应用抽象演进
选择	根据团队能力、业务需求、成本综合考量
现实	混合使用多种模型是常态

学习路线建议#

入门：先从 SaaS 和 PaaS 理解云服务的基本理念
进阶：学习 IaaS，理解云计算的底层原理
深入：掌握 CaaS，跟上容器化和云原生趋势
专精：根据职业方向选择 DaaS（数据工程师）或 BaaS（全栈开发）

参考资源#

AWS Well-Architected Framework
CNCF Cloud Native Landscape
Gartner Magic Quadrant for Cloud Infrastructure
《云原生模式》- Leonard Richardson 等著
《凤凰架构》- 周志明著

本文最后更新于 2026-03-31 *作者：xutopia *

📤 bufferevent详解 - libevent源码深度解析系列（七）

Sat, 11 Apr 2026 00:00:00 GMT

📊 bufferevent详解#

一、概述#

在libevent中，bufferevent是一个高级抽象，它封装了底层的I/O事件和缓冲区管理，使得开发者可以更方便地处理网络I/O操作。bufferevent提供了一种机制，允许应用程序在数据可读或可写时得到通知，而不需要手动处理底层的I/O事件。

bufferevent内部有两个缓冲区：一个用于读取数据，一个用于写入数据。当底层socket有数据可读时，bufferevent会自动将数据读入读缓冲区，并触发读回调；当写缓冲区有数据时，bufferevent会自动将数据写入底层socket，并触发写回调。

二、bufferevent工作流程#

2.1 bufferevent架构#

1
┌─────────────────────────────────────────────────────────┐
2
│                    bufferevent                       │
3
├─────────────────────────────────────────────────────────┤
4
│  ┌────────────┐  ┌────────────┐  ┌────────────┐      │
5
│  │  输入缓冲区  │  │  输出缓冲区  │  │  事件回调  │      │
6
│  └─────┬──────┘  └─────┬──────┘  └─────┬──────┘      │
7
│        │               │               │              │
8
├────────┼───────────────┼───────────────┼──────────────┤
9
│        │               │               │              │
10
├────────▼───────────────▼───────────────▼──────────────┤
11
│                 底层event机制                         │
12
└─────────────────────────────────────────────────────────┘

2.2 bufferevent数据流程#

1
┌─────────────────────────────────────────────────────────┐
2
│                bufferevent数据流程                   │
3
├─────────────────────────────────────────────────────────┤
4
│ 1. 网络数据到达                                       │
5
│ 2. 底层event触发读事件                                 │
6
│ 3. bufferevent自动读取数据到输入缓冲区                    │
7
│ 4. 当数据达到读水位时，触发用户读回调                      │
8
│ 5. 用户通过bufferevent_read读取数据                    │
9
│ 6. 用户通过bufferevent_write写入数据                   │
10
│ 7. 数据被写入输出缓冲区                                  │
11
│ 8. 当输出缓冲区有数据且可写时，自动写入网络                  │
12
│ 9. 当输出缓冲区数据低于写水位时，触发用户写回调                │
13
└─────────────────────────────────────────────────────────┘

三、bufferevent结构体#

1
struct bufferevent {
2
    struct event_base *be_base;
3
    const struct bufferevent_ops *be_ops;
4
    struct event ev_read;       // 读事件
5
    struct event ev_write;      // 写事件
6
    struct evbuffer *input;     // 读缓冲区
7
    struct evbuffer *output;    // 写缓冲区
8

9
    bufferevent_data_cb readcb;   // 读回调
10
    bufferevent_data_cb writecb;  // 写回调
11
    bufferevent_event_cb errorcb; // 错误回调
12
    void *cbarg;
13

14
    struct timeval timeout_read;  // 读超时
15
    struct timeval timeout_write; // 写超时
16

17
    short enabled;
18
    short options;
19
};

展开收起

四、bufferevent类型#

类型	说明
`bufferevent_socket`	基于socket的bufferevent
`bufferevent_async`	Windows IOCP
`bufferevent_pair`	用于线程间通信
`bufferevent_filter`	数据过滤
`bufferevent_openssl`	SSL/TLS加密

四、创建与销毁#

4.1 创建bufferevent#

1
/* 创建基于socket的bufferevent
2
 * @param base   event_base
3
 * @param fd     文件描述符，如果为-1，后续需要调用bufferevent_socket_connect
4
 * @param options 选项标志
5
 */
6
struct bufferevent *bufferevent_socket_new(struct event_base *base,
7
    evutil_socket_t fd, int options);
8

9
/* 释放bufferevent */
10
void bufferevent_free(struct bufferevent *bev);

4.2 选项标志#

1
#define BEV_OPT_CLOSE_ON_FREE    0x01  // 释放时关闭底层文件描述符
2
#define BEV_OPT_THREADSAFE       0x02  // 使bufferevent线程安全
3
#define BEV_OPT_DEFER_CALLBACKS  0x04  // 延迟回调执行
4
#define BEV_OPT_UNLOCK_CALLBACKS 0x08  // 回调时不持有锁

五、回调函数#

5.1 回调函数类型#

1
/* 读/写回调函数类型
2
 * @param bev   bufferevent指针
3
 * @param ctx   用户提供的参数
4
 */
5
typedef void (*bufferevent_data_cb)(struct bufferevent *bev, void *ctx);
6

7
/* 事件回调函数类型
8
 * @param bev   bufferevent指针
9
 * @param what  事件标志
10
 * @param ctx   用户提供的参数
11
 */
12
typedef void (*bufferevent_event_cb)(struct bufferevent *bev, short what, void *ctx);

5.2 事件标志#

1
#define BEV_EVENT_READING    0x01  // 读操作时发生
2
#define BEV_EVENT_WRITING    0x02  // 写操作时发生
3
#define BEV_EVENT_EOF        0x10  // 遇到文件结束符
4
#define BEV_EVENT_ERROR      0x20  // 发生错误
5
#define BEV_EVENT_TIMEOUT    0x40  // 超时
6
#define BEV_EVENT_CONNECTED  0x80  // 连接成功

5.3 设置回调#

1
/* 设置回调函数
2
 * @param readcb  读回调，当读缓冲区有数据时触发，NULL表示禁用
3
 * @param writecb 写回调，当写缓冲区数据发送完毕时触发，NULL表示禁用
4
 * @param eventcb 事件回调，连接、错误等事件
5
 * @param cbarg   回调函数的参数
6
 */
7
void bufferevent_setcb(struct bufferevent *bufev,
8
    bufferevent_data_cb readcb, bufferevent_data_cb writecb,
9
    bufferevent_event_cb eventcb, void *cbarg);

六、启用和禁用事件#

1
/* 启用事件
2
 * @param event EV_READ, EV_WRITE, 或两者的组合
3
 */
4
int bufferevent_enable(struct bufferevent *bufev, short event);
5

6
/* 禁用事件 */
7
int bufferevent_disable(struct bufferevent *bufev, short event);
8

9
/* 获取当前启用的事件 */
10
short bufferevent_get_enabled(struct bufferevent *bufev);

七、缓冲区操作#

7.1 获取缓冲区#

1
/* 获取输入缓冲区（读缓冲区） */
2
struct evbuffer *bufferevent_get_input(struct bufferevent *bufev);
3

4
/* 获取输出缓冲区（写缓冲区） */
5
struct evbuffer *bufferevent_get_output(struct bufferevent *bufev);

7.2 读写数据#

1
/* 向输出缓冲区写入数据 */
2
int bufferevent_write(struct bufferevent *bufev, const void *data, size_t size);
3

4
/* 向输出缓冲区写入格式化数据 */
5
int bufferevent_write_buffer(struct bufferevent *bufev, struct evbuffer *buf);
6

7
/* 从输入缓冲区读取数据 */
8
size_t bufferevent_read(struct bufferevent *bufev, void *data, size_t size);
9

10
/* 从输入缓冲区读取数据到evbuffer */
11
int bufferevent_read_buffer(struct bufferevent *bufev, struct evbuffer *buf);

八、水位控制#

水位（Watermarks）用于控制缓冲区的大小，当缓冲区中的数据量达到水位时，会触发相应的行为。

8.1 读水位#

水位类型	说明
低水位	读缓冲区数据量达到此值时，才会触发读回调。默认为0，表示有数据就触发
高水位	读缓冲区数据量达到此值时，停止读取数据，直到缓冲区数据量降低

8.2 写水位#

水位类型	说明
低水位	写缓冲区数据量低于此值时，才会触发写回调。默认为0

8.3 设置水位#

1
/* 设置水位
2
 * @param events    EV_READ 或 EV_WRITE
3
 * @param lowmark   低水位
4
 * @param highmark  高水位，0表示无限制
5
 */
6
void bufferevent_setwatermark(struct bufferevent *bufev, short events,
7
    size_t lowmark, size_t highmark);

8.4 水位示例#

1
// 设置读高水位为1MB，防止内存耗尽
2
bufferevent_setwatermark(bev, EV_READ, 0, 1024*1024);
3

4
// 设置读低水位为100字节，只有数据量>=100时才触发读回调
5
bufferevent_setwatermark(bev, EV_READ, 100, 0);

九、超时设置#

1
/* 设置超时
2
 * @param timeout_read  读超时，NULL表示禁用
3
 * @param timeout_write 写超时，NULL表示禁用
4
 */
5
int bufferevent_set_timeouts(struct bufferevent *bufev,
6
    const struct timeval *timeout_read, const struct timeval *timeout_write);

十、连接操作#

10.1 服务端连接#

1
/* 获取底层socket */
2
evutil_socket_t bufferevent_getfd(struct bufferevent *bufev);
3

4
/* 获取所属的event_base */
5
struct event_base *bufferevent_get_base(struct bufferevent *bufev);

10.2 客户端连接#

1
/* 连接服务器
2
 * @param addr 服务器地址
3
 * @param socklen 地址长度
4
 */
5
int bufferevent_socket_connect(struct bufferevent *bev,
6
    const struct sockaddr *addr, int socklen);
7

8
/* 通过主机名连接 */
9
int bufferevent_socket_connect_hostname(struct bufferevent *bev,
10
    struct evdns_base *dns_base, int family, const char *hostname, int port);
11

12
/* 获取连接错误码 */
13
int bufferevent_socket_get_dns_error(struct bufferevent *bev);

十一、使用示例#

11.1 TCP服务端#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <event2/buffer.h>
5
#include <event2/bufferevent.h>
6
#include <event2/listener.h>
7
#include <event2/event.h>
8

9
static void read_cb(struct bufferevent *bev, void *ctx) {
10
    struct evbuffer *input = bufferevent_get_input(bev);
11
    struct evbuffer *output = bufferevent_get_output(bev);
12

13
    // 回显数据
14
    evbuffer_add_buffer(output, input);
15
}
16

17
static void event_cb(struct bufferevent *bev, short events, void *ctx) {
18
    if (events & BEV_EVENT_ERROR) {
19
        perror("Error from bufferevent");
20
    }
21
    if (events & (BEV_EVENT_EOF | BEV_EVENT_ERROR)) {
22
        bufferevent_free(bev);
23
    }
24
}
25

26
static void accept_conn_cb(struct evconnlistener *listener,
27
    evutil_socket_t fd, struct sockaddr *address, int socklen, void *ctx) {
28

29
    struct event_base *base = evconnlistener_get_base(listener);
30
    struct bufferevent *bev = bufferevent_socket_new(base, fd, BEV_OPT_CLOSE_ON_FREE);
31

32
    bufferevent_setcb(bev, read_cb, NULL, event_cb, NULL);
33
    bufferevent_enable(bev, EV_READ | EV_WRITE);
34
}
35

36
int main() {
37
    struct event_base *base = event_base_new();
38

39
    struct sockaddr_in sin;
40
    memset(&sin, 0, sizeof(sin));
41
    sin.sin_family = AF_INET;
42
    sin.sin_port = htons(8080);
43
    sin.sin_addr.s_addr = htonl(INADDR_ANY);
44

45
    struct evconnlistener *listener = evconnlistener_new_bind(base,
46
        accept_conn_cb, NULL, LEV_OPT_CLOSE_ON_FREE | LEV_OPT_REUSEABLE,
47
        -1, (struct sockaddr*)&sin, sizeof(sin));
48

49
    event_base_dispatch(base);
50

51
    evconnlistener_free(listener);
52
    event_base_free(base);
53
    return 0;
54
}

展开收起

11.2 TCP客户端#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <event2/buffer.h>
5
#include <event2/bufferevent.h>
6
#include <event2/event.h>
7

8
static void read_cb(struct bufferevent *bev, void *ctx) {
9
    char buf[1024];
10
    size_t n;
11
    while ((n = bufferevent_read(bev, buf, sizeof(buf))) > 0) {
12
        fwrite(buf, 1, n, stdout);
13
    }
14
}
15

16
static void event_cb(struct bufferevent *bev, short events, void *ctx) {
17
    if (events & BEV_EVENT_CONNECTED) {
18
        printf("Connected!\n");
19
        // 发送数据
20
        bufferevent_write(bev, "Hello, Server!\n", 15);
21
    } else if (events & BEV_EVENT_ERROR) {
22
        printf("Error: %s\n", strerror(errno));
23
    }
24
    if (events & (BEV_EVENT_EOF | BEV_EVENT_ERROR)) {
25
        bufferevent_free(bev);
26
    }
27
}
28

29
int main() {
30
    struct event_base *base = event_base_new();
31
    struct bufferevent *bev = bufferevent_socket_new(base, -1, BEV_OPT_CLOSE_ON_FREE);
32

33
    bufferevent_setcb(bev, read_cb, NULL, event_cb, NULL);
34
    bufferevent_enable(bev, EV_READ | EV_WRITE);
35

36
    struct sockaddr_in sin;
37
    memset(&sin, 0, sizeof(sin));
38
    sin.sin_family = AF_INET;
39
    sin.sin_port = htons(8080);
40
    inet_pton(AF_INET, "127.0.0.1", &sin.sin_addr);
41

42
    bufferevent_socket_connect(bev, (struct sockaddr*)&sin, sizeof(sin));
43

44
    event_base_dispatch(base);
45
    event_base_free(base);
46
    return 0;
47
}

展开收起

其他相关资料请移步到个人主页

🔗 bufferevent高级特性 - libevent源码深度解析系列（二十四）

Sat, 11 Apr 2026 00:00:00 GMT

🔗 bufferevent高级特性#

一、概述#

除了基本的socket bufferevent，libevent还提供了多种高级bufferevent类型，包括pair（成对连接）、filter（过滤器）等。这些特性使得bufferevent可以用于更复杂的场景。

二、bufferevent_pair#

2.1 概述#

bufferevent_pair 创建两个相互连接的bufferevent，写入其中一个的数据可以从另一个读取。这非常适合进程内通信、测试、以及构建复杂的数据流管道。

2.2 创建API#

1
#include <event2/bufferevent.h>
2

3
/* 创建一对相互连接的bufferevent
4
 * @param base     event_base
5
 * @param options  选项标志
6
 * @param pair     输出数组，存储两个bufferevent
7
 * @return         0成功，-1失败
8
 */
9
int bufferevent_pair_new(struct event_base *base, int options,
10
                         struct bufferevent *pair[2]);
11

12
/* 获取pair的另一个端点 */
13
struct bufferevent *bufferevent_pair_get_partner(struct bufferevent *bev);

2.3 基本示例#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <event2/event.h>
5
#include <event2/bufferevent.h>
6

7
static void read_cb(struct bufferevent *bev, void *arg) {
8
    char buf[1024];
9
    size_t n;
10

11
    while ((n = bufferevent_read(bev, buf, sizeof(buf) - 1)) > 0) {
12
        buf[n] = '\0';
13
        printf("Received: %s", buf);
14
    }
15
}
16

17
int main() {
18
    struct event_base *base = event_base_new();
19
    struct bufferevent *pair[2];
20

21
    // 创建一对bufferevent
22
    if (bufferevent_pair_new(base, BEV_OPT_CLOSE_ON_FREE, pair) < 0) {
23
        fprintf(stderr, "Failed to create pair\n");
24
        return 1;
25
    }
26

27
    // 设置回调
28
    bufferevent_setcb(pair[1], read_cb, NULL, NULL, NULL);
29
    bufferevent_enable(pair[1], EV_READ);
30

31
    // 从pair[0]写入，pair[1]读取
32
    const char *msg = "Hello from pair[0]!\n";
33
    bufferevent_write(pair[0], msg, strlen(msg));
34

35
    // 处理事件
36
    event_base_loop(base, EVLOOP_ONCE);
37

38
    // 获取伙伴
39
    struct bufferevent *partner = bufferevent_pair_get_partner(pair[0]);
40
    printf("Partner of pair[0] is pair[1]: %s\n",
41
           partner == pair[1] ? "yes" : "no");
42

43
    // 释放（只需释放一个，另一个会自动关闭）
44
    bufferevent_free(pair[0]);
45
    bufferevent_free(pair[1]);
46

47
    event_base_free(base);
48
    return 0;
49
}

展开收起

2.4 进程间通信示例#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <unistd.h>
5
#include <sys/socket.h>
6
#include <event2/event.h>
7
#include <event2/bufferevent.h>
8

9
static void on_read_from_stdin(struct bufferevent *bev, void *arg) {
10
    struct bufferevent *partner = arg;
11
    char buf[1024];
12
    size_t n;
13

14
    while ((n = bufferevent_read(bev, buf, sizeof(buf))) > 0) {
15
        // 转发到伙伴
16
        bufferevent_write(partner, buf, n);
17
    }
18
}
19

20
static void on_read_from_partner(struct bufferevent *bev, void *arg) {
21
    char buf[1024];
22
    size_t n;
23

24
    while ((n = bufferevent_read(bev, buf, sizeof(buf))) > 0) {
25
        // 输出到stdout
26
        write(STDOUT_FILENO, "Echo: ", 6);
27
        write(STDOUT_FILENO, buf, n);
28
    }
29
}
30

31
int main() {
32
    struct event_base *base = event_base_new();
33
    struct bufferevent *pair[2];
34

35
    bufferevent_pair_new(base, BEV_OPT_CLOSE_ON_FREE, pair);
36

37
    // 创建stdin的bufferevent
38
    struct bufferevent *stdin_bev = bufferevent_socket_new(
39
        base, STDIN_FILENO, 0);
40

41
    // stdin -> pair[0]
42
    bufferevent_setcb(stdin_bev, on_read_from_stdin, NULL, NULL, pair[0]);
43
    bufferevent_enable(stdin_bev, EV_READ);
44

45
    // pair[1] -> stdout
46
    bufferevent_setcb(pair[1], on_read_from_partner, NULL, NULL, NULL);
47
    bufferevent_enable(pair[1], EV_READ);
48

49
    printf("Type something and press Enter (Ctrl+D to exit):\n");
50

51
    event_base_dispatch(base);
52

53
    bufferevent_free(stdin_bev);
54
    bufferevent_free(pair[0]);
55
    bufferevent_free(pair[1]);
56
    event_base_free(base);
57

58
    return 0;
59
}

展开收起

三、bufferevent_filter#

3.1 概述#

bufferevent_filter 是一种包装器，可以在底层bufferevent之上添加数据转换层。它允许在读写数据时进行自定义处理，如压缩、加密、编码转换等。

3.2 创建API#

1
#include <event2/bufferevent.h>
2

3
/* 过滤器回调函数类型 */
4
typedef enum bufferevent_filter_result (*bufferevent_filter_cb)(
5
    struct evbuffer *src, struct evbuffer *dst,
6
    ev_ssize_t dst_limit, enum bufferevent_flush_mode mode, void *ctx);
7

8
/* 创建过滤bufferevent
9
 * @param base          event_base
10
 * @param underlying    底层bufferevent
11
 * @param input_filter  输入过滤器（读取时调用）
12
 * @param output_filter 输出过滤器（写入时调用）
13
 * @param options       选项标志
14
 * @param free_ctx      释放上下文的函数
15
 * @param ctx           过滤器上下文
16
 */
17
struct bufferevent *bufferevent_filter_new(
18
    struct event_base *base,
19
    struct bufferevent *underlying,
20
    bufferevent_filter_cb input_filter,
21
    bufferevent_filter_cb output_filter,
22
    int options,
23
    void (*free_ctx)(void *), void *ctx);
24

25
/* 过滤器返回值 */
26
enum bufferevent_filter_result {
27
    BEV_OK = 0,      // 成功
28
    BEV_NEED_MORE,   // 需要更多数据
29
    BEV_ERROR        // 错误
30
};
31

32
/* 刷新模式 */
33
enum bufferevent_flush_mode {
34
    BEV_NORMAL = 0,  // 正常
35
    BEV_FLUSH,       // 刷新
36
    BEV_FINISHED     // 完成
37
};

展开收起

3.3 大写转换过滤器示例#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <ctype.h>
5
#include <event2/event.h>
6
#include <event2/bufferevent.h>
7
#include <event2/buffer.h>
8

9
static enum bufferevent_filter_result uppercase_filter(
10
    struct evbuffer *src, struct evbuffer *dst,
11
    ev_ssize_t dst_limit, enum bufferevent_flush_mode mode, void *ctx) {
12

13
    char buf[1024];
14
    size_t n;
15

16
    while ((n = evbuffer_remove(src, buf, sizeof(buf))) > 0) {
17
        // 转换为大写
18
        for (size_t i = 0; i < n; i++) {
19
            buf[i] = toupper((unsigned char)buf[i]);
20
        }
21
        evbuffer_add(dst, buf, n);
22
    }
23

24
    return BEV_OK;
25
}
26

27
static void read_cb(struct bufferevent *bev, void *arg) {
28
    char buf[1024];
29
    size_t n;
30

31
    while ((n = bufferevent_read(bev, buf, sizeof(buf) - 1)) > 0) {
32
        buf[n] = '\0';
33
        printf("Received (filtered): %s", buf);
34
    }
35
}
36

37
int main() {
38
    struct event_base *base = event_base_new();
39
    struct bufferevent *pair[2];
40

41
    bufferevent_pair_new(base, BEV_OPT_CLOSE_ON_FREE, pair);
42

43
    // 在pair[1]上添加过滤器
44
    struct bufferevent *filtered = bufferevent_filter_new(
45
        base, pair[1],
46
        uppercase_filter,  // 输入过滤器
47
        NULL,              // 无输出过滤器
48
        BEV_OPT_CLOSE_ON_FREE,
49
        NULL, NULL);
50

51
    bufferevent_setcb(filtered, read_cb, NULL, NULL, NULL);
52
    bufferevent_enable(filtered, EV_READ);
53

54
    // 写入小写数据
55
    const char *msg = "hello, world!\n";
56
    printf("Sending: %s", msg);
57
    bufferevent_write(pair[0], msg, strlen(msg));
58

59
    event_base_loop(base, EVLOOP_ONCE);
60

61
    bufferevent_free(pair[0]);
62
    bufferevent_free(filtered);
63
    event_base_free(base);
64

65
    return 0;
66
}

展开收起

3.4 Base64编码过滤器#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <event2/event.h>
5
#include <event2/bufferevent.h>
6
#include <event2/buffer.h>
7

8
static const char base64_table[] =
9
    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
10

11
static enum bufferevent_filter_result base64_encode_filter(
12
    struct evbuffer *src, struct evbuffer *dst,
13
    ev_ssize_t dst_limit, enum bufferevent_flush_mode mode, void *ctx) {
14

15
    unsigned char in[3];
16
    char out[4];
17
    size_t n;
18

19
    while ((n = evbuffer_remove(src, in, 3)) > 0) {
20
        // 编码
21
        out[0] = base64_table[in[0] >> 2];
22
        out[1] = base64_table[((in[0] & 0x03) << 4) | (in[1] >> 4)];
23

24
        if (n > 1) {
25
            out[2] = base64_table[((in[1] & 0x0f) << 2) | (in[2] >> 6)];
26
            out[3] = (n > 2) ? base64_table[in[2] & 0x3f] : '=';
27
        } else {
28
            out[2] = '=';
29
            out[3] = '=';
30
        }
31

32
        evbuffer_add(dst, out, 4);
33
    }
34

35
    if (mode == BEV_FLUSH || mode == BEV_FINISHED) {
36
        evbuffer_add(dst, "\n", 1);
37
    }
38

39
    return BEV_OK;
40
}
41

42
static void read_cb(struct bufferevent *bev, void *arg) {
43
    char buf[1024];
44
    size_t n;
45

46
    while ((n = bufferevent_read(bev, buf, sizeof(buf) - 1)) > 0) {
47
        buf[n] = '\0';
48
        printf("%s", buf);
49
    }
50
}
51

52
int main() {
53
    struct event_base *base = event_base_new();
54
    struct bufferevent *pair[2];
55

56
    bufferevent_pair_new(base, BEV_OPT_CLOSE_ON_FREE, pair);
57

58
    struct bufferevent *filtered = bufferevent_filter_new(
59
        base, pair[1],
60
        base64_encode_filter,
61
        NULL,
62
        BEV_OPT_CLOSE_ON_FREE,
63
        NULL, NULL);
64

65
    bufferevent_setcb(filtered, read_cb, NULL, NULL, NULL);
66
    bufferevent_enable(filtered, EV_READ);
67

68
    const char *msg = "Hello, World!";
69
    printf("Original: %s\n", msg);
70
    printf("Base64: ");
71
    bufferevent_write(pair[0], msg, strlen(msg));
72

73
    event_base_loop(base, EVLOOP_ONCE);
74

75
    bufferevent_free(pair[0]);
76
    bufferevent_free(filtered);
77
    event_base_free(base);
78

79
    return 0;
80
}

展开收起

3.5 行缓冲过滤器#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <event2/event.h>
5
#include <event2/bufferevent.h>
6
#include <event2/buffer.h>
7

8
typedef struct {
9
    char *partial_line;
10
    size_t partial_len;
11
    size_t partial_cap;
12
} line_buffer_ctx_t;
13

14
static enum bufferevent_filter_result line_buffer_filter(
15
    struct evbuffer *src, struct evbuffer *dst,
16
    ev_ssize_t dst_limit, enum bufferevent_flush_mode mode, void *ctx) {
17

18
    line_buffer_ctx_t *lb = ctx;
19
    char buf[1024];
20
    size_t n;
21

22
    while ((n = evbuffer_remove(src, buf, sizeof(buf))) > 0) {
23
        for (size_t i = 0; i < n; i++) {
24
            if (buf[i] == '\n') {
25
                // 找到换行符，输出完整行
26
                if (lb->partial_len > 0) {
27
                    evbuffer_add(dst, lb->partial_line, lb->partial_len);
28
                    lb->partial_len = 0;
29
                }
30
                evbuffer_add(dst, "\n", 1);
31
            } else {
32
                // 累积字符
33
                if (lb->partial_len >= lb->partial_cap) {
34
                    lb->partial_cap = lb->partial_cap ? lb->partial_cap * 2 : 256;
35
                    lb->partial_line = realloc(lb->partial_line, lb->partial_cap);
36
                }
37
                lb->partial_line[lb->partial_len++] = buf[i];
38
            }
39
        }
40
    }
41

42
    // 刷新时输出剩余数据
43
    if (mode == BEV_FLUSH && lb->partial_len > 0) {
44
        evbuffer_add(dst, lb->partial_line, lb->partial_len);
45
        lb->partial_len = 0;
46
    }
47

48
    return BEV_OK;
49
}
50

51
static void free_line_buffer_ctx(void *ctx) {
52
    line_buffer_ctx_t *lb = ctx;
53
    free(lb->partial_line);
54
    free(lb);
55
}

展开收起

四、链式过滤器#

4.1 多层过滤#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <ctype.h>
5
#include <event2/event.h>
6
#include <event2/bufferevent.h>
7

8
static enum bufferevent_filter_result trim_filter(
9
    struct evbuffer *src, struct evbuffer *dst,
10
    ev_ssize_t dst_limit, enum bufferevent_flush_mode mode, void *ctx) {
11

12
    char buf[1024];
13
    size_t n;
14

15
    while ((n = evbuffer_remove(src, buf, sizeof(buf))) > 0) {
16
        size_t start = 0, end = n;
17

18
        // 去除前导空白
19
        while (start < n && isspace((unsigned char)buf[start])) start++;
20

21
        // 去除尾部空白
22
        while (end > start && isspace((unsigned char)buf[end - 1])) end--;
23

24
        if (start < end) {
25
            evbuffer_add(dst, buf + start, end - start);
26
        }
27
    }
28

29
    return BEV_OK;
30
}
31

32
static enum bufferevent_filter_result uppercase_filter(
33
    struct evbuffer *src, struct evbuffer *dst,
34
    ev_ssize_t dst_limit, enum bufferevent_flush_mode mode, void *ctx) {
35

36
    char buf[1024];
37
    size_t n;
38

39
    while ((n = evbuffer_remove(src, buf, sizeof(buf))) > 0) {
40
        for (size_t i = 0; i < n; i++) {
41
            buf[i] = toupper((unsigned char)buf[i]);
42
        }
43
        evbuffer_add(dst, buf, n);
44
    }
45

46
    return BEV_OK;
47
}
48

49
int main() {
50
    struct event_base *base = event_base_new();
51
    struct bufferevent *pair[2];
52

53
    bufferevent_pair_new(base, BEV_OPT_CLOSE_ON_FREE, pair);
54

55
    // 第一层：去除空白
56
    struct bufferevent *filter1 = bufferevent_filter_new(
57
        base, pair[1],
58
        trim_filter,
59
        NULL,
60
        BEV_OPT_CLOSE_ON_FREE,
61
        NULL, NULL);
62

63
    // 第二层：转大写
64
    struct bufferevent *filter2 = bufferevent_filter_new(
65
        base, filter1,
66
        uppercase_filter,
67
        NULL,
68
        BEV_OPT_CLOSE_ON_FREE,
69
        NULL, NULL);
70

71
    char buf[1024];
72
    bufferevent_setcb(filter2,
73
        [](struct bufferevent *bev, void *arg) {
74
            char b[1024];
75
            size_t n;
76
            while ((n = bufferevent_read(bev, b, sizeof(b) - 1)) > 0) {
77
                b[n] = '\0';
78
                printf("Result: '%s'\n", b);
79
            }
80
        }, NULL, NULL, NULL);
81
    bufferevent_enable(filter2, EV_READ);
82

83
    const char *msg = "  hello world  \n";
84
    printf("Original: '%s'\n", msg);
85
    bufferevent_write(pair[0], msg, strlen(msg));
86

87
    event_base_loop(base, EVLOOP_ONCE);
88

89
    bufferevent_free(pair[0]);
90
    bufferevent_free(filter2);
91
    event_base_free(base);
92

93
    return 0;
94
}

展开收起

五、SSL过滤器#

5.1 SSL作为过滤器#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <event2/event.h>
5
#include <event2/bufferevent.h>
6
#include <event2/bufferevent_ssl.h>
7
#include <openssl/ssl.h>
8

9
int main() {
10
    SSL_library_init();
11
    SSL_load_error_strings();
12

13
    struct event_base *base = event_base_new();
14

15
    // 创建SSL上下文
16
    SSL_CTX *ssl_ctx = SSL_CTX_new(TLS_method());
17

18
    // 加载证书和私钥（服务器端）
19
    SSL_CTX_use_certificate_file(ssl_ctx, "server.crt", SSL_FILETYPE_PEM);
20
    SSL_CTX_use_PrivateKey_file(ssl_ctx, "server.key", SSL_FILETYPE_PEM);
21

22
    // 创建底层连接
23
    struct bufferevent *pair[2];
24
    bufferevent_pair_new(base, BEV_OPT_CLOSE_ON_FREE, pair);
25

26
    // 在pair[0]上创建SSL客户端
27
    SSL *ssl_client = SSL_new(ssl_ctx);
28
    SSL_set_connect_state(ssl_client);
29
    struct bufferevent *ssl_bev_client = bufferevent_openssl_filter_new(
30
        base, pair[0], ssl_client, BUFFEREVENT_SSL_CONNECTING,
31
        BEV_OPT_CLOSE_ON_FREE);
32

33
    // 在pair[1]上创建SSL服务器
34
    SSL *ssl_server = SSL_new(ssl_ctx);
35
    SSL_set_accept_state(ssl_server);
36
    struct bufferevent *ssl_bev_server = bufferevent_openssl_filter_new(
37
        base, pair[1], ssl_server, BUFFEREVENT_SSL_ACCEPTING,
38
        BEV_OPT_CLOSE_ON_FREE);
39

40
    // 设置回调
41
    bufferevent_setcb(ssl_bev_server,
42
        [](struct bufferevent *bev, void *arg) {
43
            char buf[1024];
44
            size_t n;
45
            while ((n = bufferevent_read(bev, buf, sizeof(buf) - 1)) > 0) {
46
                buf[n] = '\0';
47
                printf("Server received: %s\n", buf);
48
                bufferevent_write(bev, buf, n);  // 回显
49
            }
50
        }, NULL, NULL, NULL);
51
    bufferevent_enable(ssl_bev_server, EV_READ | EV_WRITE);
52

53
    // 客户端发送数据
54
    const char *msg = "Hello, SSL!";
55
    bufferevent_write(ssl_bev_client, msg, strlen(msg));
56

57
    event_base_loop(base, EVLOOP_NONBLOCK);
58

59
    bufferevent_free(ssl_bev_client);
60
    bufferevent_free(ssl_bev_server);
61
    SSL_CTX_free(ssl_ctx);
62
    event_base_free(base);
63

64
    return 0;
65
}

展开收起

六、完整示例：代理服务器#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <signal.h>
5
#include <event2/event.h>
6
#include <event2/listener.h>
7
#include <event2/bufferevent.h>
8

9
static struct event_base *g_base = NULL;
10

11
typedef struct {
12
    struct bufferevent *client_bev;
13
    struct bufferevent *server_bev;
14
} proxy_conn_t;
15

16
static void client_read_cb(struct bufferevent *bev, void *arg);
17
static void server_read_cb(struct bufferevent *bev, void *arg);
18
static void event_cb(struct bufferevent *bev, short events, void *arg);
19

20
static void client_read_cb(struct bufferevent *bev, void *arg) {
21
    proxy_conn_t *conn = arg;
22
    char buf[4096];
23
    size_t n;
24

25
    while ((n = bufferevent_read(bev, buf, sizeof(buf))) > 0) {
26
        printf("Client -> Server: %zu bytes\n", n);
27
        bufferevent_write(conn->server_bev, buf, n);
28
    }
29
}
30

31
static void server_read_cb(struct bufferevent *bev, void *arg) {
32
    proxy_conn_t *conn = arg;
33
    char buf[4096];
34
    size_t n;
35

36
    while ((n = bufferevent_read(bev, buf, sizeof(buf))) > 0) {
37
        printf("Server -> Client: %zu bytes\n", n);
38
        bufferevent_write(conn->client_bev, buf, n);
39
    }
40
}
41

42
static void event_cb(struct bufferevent *bev, short events, void *arg) {
43
    proxy_conn_t *conn = arg;
44

45
    if (events & (BEV_EVENT_EOF | BEV_EVENT_ERROR)) {
46
        printf("Connection closed\n");
47

48
        if (conn->client_bev) {
49
            bufferevent_free(conn->client_bev);
50
        }
51
        if (conn->server_bev) {
52
            bufferevent_free(conn->server_bev);
53
        }
54
        free(conn);
55
    } else if (events & BEV_EVENT_CONNECTED) {
56
        printf("Connected to upstream server\n");
57
    }
58
}
59

60
static void accept_cb(struct evconnlistener *listener, evutil_socket_t fd,
61
                      struct sockaddr *addr, int len, void *arg) {
62
    printf("New client connection\n");
63

64
    proxy_conn_t *conn = calloc(1, sizeof(proxy_conn_t));
65

66
    // 客户端连接
67
    conn->client_bev = bufferevent_socket_new(g_base, fd, BEV_OPT_CLOSE_ON_FREE);
68
    bufferevent_setcb(conn->client_bev, client_read_cb, NULL, event_cb, conn);
69
    bufferevent_enable(conn->client_bev, EV_READ | EV_WRITE);
70

71
    // 连接上游服务器
72
    conn->server_bev = bufferevent_socket_new(g_base, -1, BEV_OPT_CLOSE_ON_FREE);
73
    bufferevent_setcb(conn->server_bev, server_read_cb, NULL, event_cb, conn);
74
    bufferevent_enable(conn->server_bev, EV_READ | EV_WRITE);
75

76
    struct sockaddr_in server_addr;
77
    memset(&server_addr, 0, sizeof(server_addr));
78
    server_addr.sin_family = AF_INET;
79
    server_addr.sin_port = htons(80);  // 代理到HTTP服务器
80
    inet_pton(AF_INET, "127.0.0.1", &server_addr.sin_addr);
81

82
    bufferevent_socket_connect(conn->server_bev,
83
                               (struct sockaddr *)&server_addr,
84
                               sizeof(server_addr));
85
}
86

87
static void signal_cb(evutil_socket_t fd, short events, void *arg) {
88
    printf("\nShutting down...\n");
89
    event_base_loopbreak(g_base);
90
}
91

92
int main() {
93
    g_base = event_base_new();
94

95
    struct event *sigint = evsignal_new(g_base, SIGINT, signal_cb, NULL);
96
    event_add(sigint, NULL);
97

98
    struct sockaddr_in listen_addr;
99
    memset(&listen_addr, 0, sizeof(listen_addr));
100
    listen_addr.sin_family = AF_INET;
101
    listen_addr.sin_port = htons(8080);
102
    listen_addr.sin_addr.s_addr = INADDR_ANY;
103

104
    struct evconnlistener *listener = evconnlistener_new_bind(
105
        g_base, accept_cb, NULL,
106
        LEV_OPT_CLOSE_ON_FREE | LEV_OPT_REUSEABLE,
107
        -1, (struct sockaddr *)&listen_addr, sizeof(listen_addr));
108

109
    printf("Proxy server listening on port 8080\n");
110
    printf("Forwarding to 127.0.0.1:80\n");
111

112
    event_base_dispatch(g_base);
113

114
    evconnlistener_free(listener);
115
    event_free(sigint);
116
    event_base_free(g_base);
117

118
    return 0;
119
}

展开收起

七、最佳实践#

特性	用途	建议
pair	进程内通信、测试	适合单元测试和管道构建
filter	数据转换	保持过滤器简单高效
链式过滤	多层处理	注意性能开销
SSL过滤	安全通信	使用filter模式更灵活
代理	数据转发	合理管理连接生命周期

其他相关资料请移步到个人主页

🔑 核心概念与API - libevent源码深度解析系列（四）

Sat, 11 Apr 2026 00:00:00 GMT

🧠 核心概念与API#

一、事件编程模型#

在事件驱动编程模型中，主要有三个核心组件：

🔷 事件源（Event Source）：产生事件的对象，如网络连接、文件描述符等。
🔷 事件处理器（Event Handler）：负责处理事件的回调函数。
🔷 事件循环（Event Loop）：负责调度事件处理器的中心组件。

1.1 事件驱动模型流程图#

1
┌─────────────────────────────────────────────────────────┐
2
│                   事件循环 (event_base)              │
3
├─────────────────────────────────────────────────────────┤
4
│ 1. 初始化事件基                                     │
5
│ 2. 注册事件 (event_new + event_add)                 │
6
│ 3. 进入事件循环 (event_base_dispatch)               │
7
│    ├─ 等待事件触发                                   │
8
│    ├─ 分发事件到对应的处理器                           │
9
│    ├─ 执行事件回调                                   │
10
│    └─ 重复上述步骤                                   │
11
│ 4. 退出事件循环                                     │
12
└─────────────────────────────────────────────────────────┘

1.2 事件处理流程#

1
┌─────────────────────────────────────────────────────────┐
2
│                 事件处理流程                         │
3
├─────────────────────────────────────────────────────────┤
4
│ 1. 事件源产生事件 (如网络数据到达)                    │
5
│ 2. I/O多路复用机制检测到事件                          │
6
│ 3. event_base获取就绪事件                            │
7
│ 4. 查找对应的event结构体                             │
8
│ 5. 将event添加到活跃事件队列                          │
9
│ 6. 按优先级处理活跃事件                              │
10
│ 7. 调用事件的回调函数                                │
11
│ 8. 如果是持久事件(EV_PERSIST)，重新添加到事件队列        │
12
└─────────────────────────────────────────────────────────┘

二、事件基（Event Base）#

在 libevent 中，事件基（Event Base）是一个核心概念，它是事件驱动编程模型中的事件循环的实现。事件基负责管理所有注册的事件，并在事件发生时调度相应的事件处理器。

2.1 主要功能#

🔶 事件注册：将事件注册到事件基
🔶 事件调度：在事件发生时调度相应的事件处理器
🔶 事件循环：通过 event_base_dispatch() 启动事件循环，处理事件

2.2 event_base_new API 详解#

1
struct event_base *event_base_new(void);

返回值#

成功：返回事件基结构体指针
失败：返回 NULL

2.3 event_base_new_with_config API 详解#

1
struct event_base *event_base_new_with_config(const struct event_config *cfg);

参数说明#

参数	类型	说明
cfg	const struct event_config*	事件基配置结构体

返回值#

成功：返回事件基结构体指针
失败：返回 NULL

2.4 event_base_dispatch API 详解#

1
int event_base_dispatch(struct event_base *base);

参数说明#

参数	类型	说明
base	struct event_base*	要启动的事件基

返回值#

成功：返回 0
失败：返回 -1

2.5 event_base_loop API 详解#

1
int event_base_loop(struct event_base *base, int flags);

参数说明#

参数	类型	说明
base	struct event_base*	要启动的事件基
flags	int	循环标志，如 EVLOOP_ONCE、EVLOOP_NONBLOCK 等

返回值#

成功：返回 0
失败：返回 -1

2.6 event_base_loopexit API 详解#

1
int event_base_loopexit(struct event_base *base, const struct timeval *tv);

参数说明#

参数	类型	说明
base	struct event_base*	要退出的事件基
tv	const struct timeval*	退出延迟时间，NULL表示立即退出

返回值#

成功：返回 0
失败：返回 -1

2.7 event_base_loopbreak API 详解#

1
int event_base_loopbreak(struct event_base *base);

参数说明#

参数	类型	说明
base	struct event_base*	要中断的事件基

返回值#

成功：返回 0
失败：返回 -1

2.8 event_base_free API 详解#

1
void event_base_free(struct event_base *base);

参数说明#

参数	类型	说明
base	struct event_base*	要释放的事件基

2.9 基本操作示例#

1
// 创建事件基
2
struct event_base *base = event_base_new();
3
if (!base) {
4
    fprintf(stderr, "Failed to create event base\n");
5
    return 1;
6
}
7

8
// 带配置创建事件基
9
struct event_config *cfg = event_config_new();
10
event_config_require_features(cfg, EV_FEATURE_ET);
11
struct event_base *base_with_config = event_base_new_with_config(cfg);
12
event_config_free(cfg);
13

14
// 启动事件循环（阻塞模式）
15
event_base_dispatch(base);
16

17
// 启动事件循环（非阻塞模式）
18
event_base_loop(base, EVLOOP_NONBLOCK);
19

20
// 延迟退出事件循环
21
struct timeval tv = {5, 0}; // 5秒后退出
22
event_base_loopexit(base, &tv);
23

24
// 立即中断事件循环
25
event_base_loopbreak(base);
26

27
// 释放事件基
28
event_base_free(base);
29
event_base_free(base_with_config);

展开收起

三、事件（Event）#

在 libevent 中，事件（Event）代表了一个具体的事件源及其相关的事件处理器。事件可以绑定到不同的事件源上，如文件描述符、网络套接字等。

3.1 event_new API 详解#

1
struct event *event_new(struct event_base *base, evutil_socket_t fd, short flags,
2
                        event_callback_fn callback, void *arg);

参数说明#

参数	类型	说明
base	struct event_base*	事件所属的事件基
fd	evutil_socket_t	事件绑定的文件描述符，对于定时器事件设为-1
flags	short	事件标志，如 EV_READ、EV_WRITE、EV_PERSIST 等
callback	event_callback_fn	事件触发时的回调函数
arg	void*	传递给回调函数的参数

返回值#

成功：返回事件结构体指针
失败：返回 NULL

回调函数签名#

1
typedef void (*event_callback_fn)(evutil_socket_t fd, short events, void *arg);

参数	类型	说明
fd	evutil_socket_t	事件绑定的文件描述符
events	short	触发的事件类型，如 EV_READ、EV_WRITE 等
arg	void*	传递给回调函数的参数

3.2 event_add API 详解#

1
int event_add(struct event *ev, const struct timeval *timeout);

参数说明#

参数	类型	说明
ev	struct event*	要添加的事件
timeout	const struct timeval*	超时时间，NULL表示无超时

返回值#

成功：返回 0
失败：返回 -1

3.3 event_del API 详解#

1
int event_del(struct event *ev);

参数说明#

参数	类型	说明
ev	struct event*	要删除的事件

返回值#

成功：返回 0
失败：返回 -1

3.4 event_free API 详解#

1
void event_free(struct event *ev);

参数说明#

参数	类型	说明
ev	struct event*	要释放的事件

3.5 事件的主要属性#

属性	说明
描述符（Descriptor）	事件绑定的文件描述符或套接字
标志（Flags）	表示事件类型和行为的标志位，如 `EV_READ`、`EV_WRITE`、`EV_PERSIST` 等
回调函数（Callback）	事件发生时调用的函数
回调参数（Argument）	传递给回调函数的参数

3.6 事件操作示例#

1
// 创建事件
2
struct event *ev = event_new(base, fd, EV_READ | EV_PERSIST, read_callback, arg);
3
if (!ev) {
4
    fprintf(stderr, "Failed to create event\n");
5
    return -1;
6
}
7

8
// 添加事件（无超时）
9
if (event_add(ev, NULL) < 0) {
10
    fprintf(stderr, "Failed to add event\n");
11
    event_free(ev);
12
    return -1;
13
}
14

15
// 添加事件（带超时）
16
struct timeval tv = {5, 0}; // 5秒超时
17
if (event_add(ev, &tv) < 0) {
18
    fprintf(stderr, "Failed to add event with timeout\n");
19
    event_free(ev);
20
    return -1;
21
}
22

23
// 删除事件
24
if (event_del(ev) < 0) {
25
    fprintf(stderr, "Failed to delete event\n");
26
}
27

28
// 释放事件
29
event_free(ev);

展开收起

四、事件处理（Event Handling）#

事件处理是 libevent 的核心功能之一。当事件发生时，事件基会调度相应的事件处理器。

1
void event_callback(evutil_socket_t fd, short event, void *arg) {
2
    // 处理事件
3
}
4

5
struct event *event = event_new(base, fd, EV_READ | EV_PERSIST, event_callback, arg);
6
event_add(event, NULL);  // 添加事件

五、事件标志#

事件标志用于指定事件的类型和行为：

标志	值	说明
`EV_TIMEOUT`	0x01	定时事件
`EV_READ`	0x02	读事件，表示当文件描述符可读时触发事件
`EV_WRITE`	0x04	写事件，表示当文件描述符可写时触发事件
`EV_SIGNAL`	0x08	信号事件
`EV_PERSIST`	0x10	持久事件，表示事件在触发后不会自动删除，而是继续保留在事件基中
`EV_ET`	0x20	边缘触发模式，仅在数据可用时触发

六、定时器（Timer）#

libevent 支持定时器功能，允许开发者在特定的时间间隔内执行任务。

1
void timer_callback(evutil_socket_t fd, short event, void *arg) {
2
    printf("Timer fired!\n");
3
}
4

5
// -1 表示定时器不绑定到任何文件描述符
6
struct event *timer = event_new(base, -1, EV_PERSIST, timer_callback, NULL);
7
struct timeval delay = {5, 0};  // 设置定时器时间为 5 秒
8
event_add(timer, &delay);

七、信号处理#

libevent 支持信号处理，允许开发者在接收到特定信号时执行相应的动作。

1
void signal_handler(evutil_socket_t fd, short event, void *arg) {
2
    printf("Signal received!\n");
3
    event_base_loopexit(base, NULL);
4
}
5

6
struct event *signal_event = evsignal_new(base, SIGINT, signal_handler, base);
7
event_add(signal_event, NULL);

八、多线程支持#

libevent 支持多线程环境，允许开发者在多线程程序中安全地使用事件基。

1
event_base_mutex_lock(base);
2
event_base_mutex_unlock(base);

九、事件基的生命周期#

事件基的生命周期包括创建、启动和销毁三个阶段：

创建：使用 event_base_new() 创建事件基
启动：使用 event_base_dispatch() 启动事件循环
销毁：使用 event_base_free() 销毁事件基

十、示例代码#

下面是一个完整的示例代码，展示了如何使用 libevent 创建一个简单的定时器：

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <unistd.h>
4
#include <event2/event.h>
5

6
static void timer_callback(evutil_socket_t fd, short event, void *arg) {
7
    printf("Timer fired!\n");
8

9
    // 重新调度定时器
10
    struct event *timer = (struct event *)arg;
11
    struct timeval delay = {5, 0};
12
    event_add(timer, &delay);
13
}
14

15
int main() {
16
    struct event_base *base;
17
    struct event *timer;
18

19
    base = event_base_new();
20
    if (!base) {
21
        fprintf(stderr, "Failed to create event base\n");
22
        return 1;
23
    }
24

25
    timer = event_new(base, -1, EV_PERSIST, timer_callback, timer);
26
    if (!timer) {
27
        fprintf(stderr, "Failed to create timer event\n");
28
        event_base_free(base);
29
        return 1;
30
    }
31

32
    struct timeval delay = {5, 0};
33
    event_add(timer, &delay);
34

35
    event_base_dispatch(base);
36

37
    event_free(timer);
38
    event_base_free(base);
39

40
    return 0;
41
}

展开收起

十一、使用注意事项#

11.1 事件基的管理和使用#

单线程原则：事件基（event_base）的设计是单线程的，即一个事件基只能在一个线程中使用。如果在多线程环境下使用 libevent，每个线程应有自己的事件基实例。

1
struct event_base *base1 = event_base_new();  // 第一个线程的事件基
2
struct event_base *base2 = event_base_new();  // 第二个线程的事件基

线程安全：虽然 libevent 提供了一些线程安全的功能，但在多线程环境中，对事件基的操作（如添加、删除事件）必须确保线程安全。

11.2 回调函数的设计#

非阻塞性：事件处理函数（回调函数）不应执行长时间的阻塞操作，否则会影响事件循环的效率。
资源管理：在事件处理函数中，应妥善管理资源，确保资源的正确释放。

11.3 定时器的使用#

精确度：定时器的精度取决于底层操作系统提供的定时器机制。在某些情况下，定时器的触发时间可能会有所偏差。
循环定时器：使用 EV_PERSIST 标志创建的定时器会在每次触发后自动重新调度。

其他相关资料请移步到个人主页

📦 evbuffer详解 - libevent源码深度解析系列（十八）

Sat, 11 Apr 2026 00:00:00 GMT

📦 evbuffer详解#

一、概述#

evbuffer 是libevent提供的动态缓冲区实现，用于高效地管理二进制数据。它是bufferevent的底层缓冲区实现，也可以独立使用。evbuffer提供了丰富的数据操作接口，支持数据的添加、删除、搜索、移动等操作，并且支持零拷贝优化。

二、evbuffer结构体#

1
struct evbuffer {
2
    struct evbuffer_chain *first;   // 第一个数据块
3
    struct evbuffer_chain *last;    // 最后一个数据块
4
    struct evbuffer_chain **last_with_datap;  // 最后一个包含数据的块
5

6
    size_t total_len;               // 总数据长度
7
    size_t n_add_for_cb;            // 自上次回调以来添加的字节数
8
    size_t n_del_for_cb;            // 自上次回调以来删除的字节数
9

10
    int freeze_start;               // 冻结前端标志
11
    int freeze_end;                 // 冻结后端标志
12

13
    TAILQ_HEAD(evbuffer_cb_queue, evbuffer_cb_entry) callbacks;  // 回调队列
14

15
    struct event_base *ev_base;     // 关联的event_base
16
};

展开收起

2.1 evbuffer_chain结构体#

1
struct evbuffer_chain {
2
    struct evbuffer_chain *next;    // 下一个链
3
    size_t buffer_len;              // 缓冲区总长度
4
    size_t misalign;                // 未对齐的字节数（已读但未释放）
5
    size_t off;                     // 有效数据长度
6

7
    unsigned char *buffer;          // 数据缓冲区
8
};

三、创建与销毁#

3.1 创建evbuffer#

1
/* 创建新的evbuffer */
2
struct evbuffer *evbuffer_new(void);
3

4
/* 释放evbuffer */
5
void evbuffer_free(struct evbuffer *buf);
6

7
/* 启用线程安全 */
8
int evbuffer_enable_locking(struct evbuffer *buf, void *lock);
9

10
/* 获取锁 */
11
void evbuffer_lock(struct evbuffer *buf);
12
void evbuffer_unlock(struct evbuffer *buf);

3.2 基本示例#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <event2/buffer.h>
4

5
int main() {
6
    struct evbuffer *buf = evbuffer_new();
7
    if (!buf) {
8
        fprintf(stderr, "Failed to create evbuffer\n");
9
        return 1;
10
    }
11

12
    printf("Created evbuffer, length: %zu\n", evbuffer_get_length(buf));
13

14
    evbuffer_free(buf);
15
    return 0;
16
}

展开收起

四、数据添加操作#

4.1 基本添加#

1
/* 添加数据到缓冲区末尾 */
2
int evbuffer_add(struct evbuffer *buf, const void *data, size_t datlen);
3

4
/* 添加格式化字符串 */
5
int evbuffer_add_printf(struct evbuffer *buf, const char *fmt, ...);
6
int evbuffer_add_vprintf(struct evbuffer *buf, const char *fmt, va_list ap);
7

8
/* 添加另一个evbuffer的所有数据（并清空源缓冲区） */
9
int evbuffer_add_buffer(struct evbuffer *dst, struct evbuffer *src);
10

11
/* 添加另一个evbuffer的数据（不清空源缓冲区） */
12
int evbuffer_prepend_buffer(struct evbuffer *dst, struct evbuffer *src);
13

14
/* 在缓冲区开头添加数据 */
15
int evbuffer_prepend(struct evbuffer *buf, const void *data, size_t size);

展开收起

4.2 添加示例#

1
#include <stdio.h>
2
#include <event2/buffer.h>
3

4
int main() {
5
    struct evbuffer *buf = evbuffer_new();
6

7
    // 添加字符串
8
    evbuffer_add(buf, "Hello, ", 7);
9
    evbuffer_add(buf, "World!", 6);
10

11
    // 添加格式化字符串
12
    evbuffer_add_printf(buf, " Number: %d", 42);
13

14
    printf("Length: %zu\n", evbuffer_get_length(buf));
15
    // 输出: Length: 21
16

17
    evbuffer_free(buf);
18
    return 0;
19
}

展开收起

4.3 添加文件（零拷贝）#

1
/* 添加文件内容（零拷贝）
2
 * @param fd        文件描述符
3
 * @param offset    起始偏移
4
 * @param length    长度，-1表示到文件末尾
5
 */
6
int evbuffer_add_file(struct evbuffer *buf, int fd, ev_off_t offset, ev_off_t length);
7

8
/* 添加文件引用（不复制数据） */
9
int evbuffer_add_file_segment(struct evbuffer *buf,
10
    struct evbuffer_file_segment *seg, ev_off_t offset, ev_off_t length);
11

12
/* 创建文件段 */
13
struct evbuffer_file_segment *evbuffer_file_segment_new(
14
    int fd, ev_off_t offset, ev_off_t length, unsigned flags);
15

16
/* 释放文件段 */
17
void evbuffer_file_segment_free(struct evbuffer_file_segment *seg);

展开收起

五、数据读取操作#

5.1 基本读取#

1
/* 从缓冲区读取数据（并移除）
2
 * @return 实际读取的字节数
3
 */
4
size_t evbuffer_remove(struct evbuffer *buf, void *data, size_t datlen);
5

6
/* 从缓冲区读取数据到另一个evbuffer */
7
int evbuffer_remove_buffer(struct evbuffer *src, struct evbuffer *dst,
8
    size_t datlen);
9

10
/* 拷贝数据（不移除） */
11
ev_ssize_t evbuffer_copyout(struct evbuffer *buf, void *data, size_t datlen);
12

13
/* 拷贝数据到另一个evbuffer（不移除） */
14
int evbuffer_copyout_to(struct evbuffer *src, struct evbuffer *dst,
15
    size_t datlen);
16

17
/* 丢弃数据 */
18
int evbuffer_drain(struct evbuffer *buf, size_t len);

展开收起

5.2 读取示例#

1
#include <stdio.h>
2
#include <string.h>
3
#include <event2/buffer.h>
4

5
int main() {
6
    struct evbuffer *buf = evbuffer_new();
7

8
    // 添加数据
9
    evbuffer_add(buf, "Hello, World!", 13);
10

11
    // 读取数据
12
    char data[20];
13
    size_t n = evbuffer_remove(buf, data, sizeof(data) - 1);
14
    data[n] = '\0';
15
    printf("Read: %s (%zu bytes)\n", data, n);
16

17
    // 再次添加
18
    evbuffer_add(buf, "Test Data", 9);
19

20
    // 拷贝不移除
21
    char copy[10];
22
    evbuffer_copyout(buf, copy, 4);
23
    copy[4] = '\0';
24
    printf("Copy: %s, remaining: %zu\n", copy, evbuffer_get_length(buf));
25

26
    evbuffer_free(buf);
27
    return 0;
28
}

展开收起

六、行读取操作#

6.1 按行读取#

1
/* 读取一行并移除
2
 * @param n_eol_style 行结束符类型
3
 * @return 读取的行（需要调用者free），NULL表示没有完整行
4
 */
5
char *evbuffer_readln(struct evbuffer *buffer, size_t *n_read_out,
6
    enum evbuffer_eol_style n_eol_style);
7

8
/* 行结束符类型 */
9
enum evbuffer_eol_style {
10
    EVBUFFER_EOL_ANY,       // 任意换行符
11
    EVBUFFER_EOL_CRLF,      // \r\n
12
    EVBUFFER_EOL_CRLF_STRICT, // 严格的\r\n
13
    EVBUFFER_EOL_LF,        // \n
14
    EVBUFFER_EOL_NUL        // \0
15
};

展开收起

6.2 行读取示例#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <event2/buffer.h>
4

5
int main() {
6
    struct evbuffer *buf = evbuffer_new();
7

8
    // 添加多行数据
9
    evbuffer_add(buf, "Line 1\nLine 2\r\nLine 3\n", 21);
10

11
    // 逐行读取
12
    char *line;
13
    size_t len;
14

15
    while ((line = evbuffer_readln(buf, &len, EVBUFFER_EOL_ANY)) != NULL) {
16
        printf("Line: %s (len=%zu)\n", line, len);
17
        free(line);
18
    }
19

20
    evbuffer_free(buf);
21
    return 0;
22
}

展开收起

七、搜索操作#

7.1 搜索API#

1
/* evbuffer指针结构体 */
2
struct evbuffer_ptr {
3
    ev_ssize_t pos;         // 位置，-1表示无效
4

5
    struct {
6
        void *chain;
7
        size_t pos_in_chain;
8
    } internal_;
9
};
10

11
/* 搜索字符串 */
12
struct evbuffer_ptr evbuffer_search(struct evbuffer *buffer,
13
    const char *what, size_t len, const struct evbuffer_ptr *start);
14

15
/* 搜索字符范围 */
16
struct evbuffer_ptr evbuffer_search_range(struct evbuffer *buffer,
17
    const char *what, size_t len, const struct evbuffer_ptr *start,
18
    const struct evbuffer_ptr *end);
19

20
/* 搜索行结束符 */
21
enum evbuffer_eol_style;
22
struct evbuffer_ptr evbuffer_search_eol(struct evbuffer *buffer,
23
    struct evbuffer_ptr *start, size_t *eol_len_out,
24
    enum evbuffer_eol_style eol_style);
25

26
/* 移动指针 */
27
int evbuffer_ptr_set(struct evbuffer *buf, struct evbuffer_ptr *pos,
28
    size_t position, enum evbuffer_ptr_how how);
29

30
enum evbuffer_ptr_how {
31
    EVBUFFER_PTR_SET,   // 设置绝对位置
32
    EVBUFFER_PTR_ADD    // 相对当前位置移动
33
};

展开收起

7.2 搜索示例#

1
#include <stdio.h>
2
#include <event2/buffer.h>
3

4
int main() {
5
    struct evbuffer *buf = evbuffer_new();
6

7
    evbuffer_add(buf, "Hello, World! Hello, libevent!", 30);
8

9
    // 搜索"Hello"
10
    struct evbuffer_ptr ptr = evbuffer_search(buf, "Hello", 5, NULL);
11
    if (ptr.pos != -1) {
12
        printf("Found 'Hello' at position %zd\n", ptr.pos);
13
    }
14

15
    // 从上次位置之后继续搜索
16
    evbuffer_ptr_set(buf, &ptr, 5, EVBUFFER_PTR_ADD);
17
    ptr = evbuffer_search(buf, "Hello", 5, &ptr);
18
    if (ptr.pos != -1) {
19
        printf("Found second 'Hello' at position %zd\n", ptr.pos);
20
    }
21

22
    evbuffer_free(buf);
23
    return 0;
24
}

展开收起

八、迭代器操作#

8.1 迭代器API#

1
/* 创建迭代器 */
2
struct evbuffer_iovec {
3
    void *iov_base;    // 数据指针
4
    size_t iov_len;    // 数据长度
5
};
6

7
/* 预留空间（用于直接写入） */
8
int evbuffer_reserve_space(struct evbuffer *buf, ev_ssize_t size,
9
    struct evbuffer_iovec *vec, int n_vecs);
10

11
/* 提交预留空间 */
12
int evbuffer_commit_space(struct evbuffer *buf,
13
    struct evbuffer_iovec *vec, int n_vecs);
14

15
/* 获取数据指针（用于直接读取） */
16
int evbuffer_peek(struct evbuffer *buf, ev_ssize_t len,
17
    struct evbuffer_ptr *start_at, struct evbuffer_iovec *vec, int n_vecs);

展开收起

8.2 直接写入示例#

1
#include <stdio.h>
2
#include <string.h>
3
#include <event2/buffer.h>
4

5
int main() {
6
    struct evbuffer *buf = evbuffer_new();
7

8
    // 预留空间
9
    struct evbuffer_iovec vec[2];
10
    int n = evbuffer_reserve_space(buf, 1024, vec, 2);
11

12
    // 直接写入数据
13
    for (int i = 0; i < n; i++) {
14
        const char *msg = "Direct write data";
15
        size_t len = strlen(msg);
16
        if (len > vec[i].iov_len) len = vec[i].iov_len;
17
        memcpy(vec[i].iov_base, msg, len);
18
        vec[i].iov_len = len;
19
    }
20

21
    // 提交数据
22
    evbuffer_commit_space(buf, vec, n);
23

24
    printf("Buffer length: %zu\n", evbuffer_get_length(buf));
25

26
    evbuffer_free(buf);
27
    return 0;
28
}

展开收起

九、文件描述符I/O#

9.1 直接读写文件描述符#

1
/* 从文件描述符读取数据到缓冲区 */
2
int evbuffer_read(struct evbuffer *buffer, evutil_socket_t fd, int howmuch);
3

4
/* 将缓冲区数据写入文件描述符 */
5
int evbuffer_write(struct evbuffer *buffer, evutil_socket_t fd);
6
int evbuffer_write_atmost(struct evbuffer *buffer, evutil_socket_t fd, ev_ssize_t howmuch);

9.2 文件I/O示例#

1
#include <stdio.h>
2
#include <unistd.h>
3
#include <event2/buffer.h>
4

5
int main() {
6
    struct evbuffer *buf = evbuffer_new();
7

8
    // 从标准输入读取
9
    printf("Enter some text (Ctrl+D to end):\n");
10
    int n = evbuffer_read(buf, STDIN_FILENO, -1);
11

12
    if (n > 0) {
13
        printf("Read %d bytes\n", n);
14

15
        // 写入标准输出
16
        evbuffer_write(buf, STDOUT_FILENO);
17
    }
18

19
    evbuffer_free(buf);
20
    return 0;
21
}

展开收起

十、回调函数#

10.1 回调API#

1
/* 回调函数类型 */
2
typedef void (*evbuffer_cb_func)(struct evbuffer *buffer,
3
    size_t old_len, size_t new_len, void *arg);
4

5
/* 添加回调 */
6
struct evbuffer_cb_entry *evbuffer_add_cb(struct evbuffer *buffer,
7
    evbuffer_cb_func cb, void *cbarg);
8

9
/* 移除回调 */
10
int evbuffer_remove_cb_entry(struct evbuffer *buffer,
11
    struct evbuffer_cb_entry *ent);
12
int evbuffer_remove_cb(struct evbuffer *buffer, evbuffer_cb_func cb, void *cbarg);
13

14
/* 设置回调标志 */
15
#define EVBUFFER_CB_ENABLED 1
16
int evbuffer_cb_set_flags(struct evbuffer *buffer,
17
    struct evbuffer_cb_entry *cb, ev_uint32_t flags);
18
int evbuffer_cb_clear_flags(struct evbuffer *buffer,
19
    struct evbuffer_cb_entry *cb, ev_uint32_t flags);

展开收起

10.2 回调示例#

1
#include <stdio.h>
2
#include <event2/buffer.h>
3

4
static void buffer_cb(struct evbuffer *buffer, size_t old_len,
5
                      size_t new_len, void *arg) {
6
    const char *name = (const char *)arg;
7

8
    if (new_len > old_len) {
9
        printf("[%s] Added %zu bytes (total: %zu)\n",
10
               name, new_len - old_len, new_len);
11
    } else if (new_len < old_len) {
12
        printf("[%s] Removed %zu bytes (total: %zu)\n",
13
               name, old_len - new_len, new_len);
14
    }
15
}
16

17
int main() {
18
    struct evbuffer *buf = evbuffer_new();
19

20
    // 添加回调
21
    evbuffer_add_cb(buf, buffer_cb, "MyBuffer");
22

23
    // 操作缓冲区
24
    evbuffer_add(buf, "Hello", 5);
25
    evbuffer_add(buf, " World", 6);
26

27
    char tmp[10];
28
    evbuffer_remove(buf, tmp, 5);
29

30
    evbuffer_free(buf);
31
    return 0;
32
}

展开收起

十一、冻结操作#

11.1 冻结API#

1
/* 冻结缓冲区前端（禁止从头部读取/删除） */
2
int evbuffer_freeze(struct evbuffer *buf, int start);
3

4
/* 冻结缓冲区后端（禁止向尾部添加） */
5
int evbuffer_unfreeze(struct evbuffer *buf, int start);

11.2 冻结示例#

1
#include <stdio.h>
2
#include <event2/buffer.h>
3

4
int main() {
5
    struct evbuffer *buf = evbuffer_new();
6

7
    evbuffer_add(buf, "Header", 6);
8
    evbuffer_add(buf, "Body", 4);
9

10
    // 冻结前端，保护头部数据
11
    evbuffer_freeze(buf, 1);
12

13
    // 尝试从前端读取会失败
14
    char tmp[10];
15
    size_t n = evbuffer_remove(buf, tmp, 6);
16
    printf("Remove from front: %zu (should be 0)\n", n);
17

18
    // 解冻
19
    evbuffer_unfreeze(buf, 1);
20

21
    // 现在可以读取
22
    n = evbuffer_remove(buf, tmp, 6);
23
    printf("Remove after unfreeze: %zu\n", n);
24

25
    evbuffer_free(buf);
26
    return 0;
27
}

展开收起

十二、其他实用函数#

12.1 信息获取#

1
/* 获取缓冲区总长度 */
2
size_t evbuffer_get_length(const struct evbuffer *buf);
3

4
/* 获取连续内存块数量 */
5
int evbuffer_get_contiguous_space(const struct evbuffer *buf);
6

7
/* 拉取数据到连续内存（不复制，仅重组） */
8
int evbuffer_pullup(struct evbuffer *buf, ev_ssize_t size);

12.2 扩展操作#

1
/* 添加引用（不复制数据）
2
 * @param data      数据指针
3
 * @param datlen    数据长度
4
 * @param cleanupfn 清理函数
5
 * @param cleanupfn_arg 清理函数参数
6
 */
7
int evbuffer_add_reference(struct evbuffer *buf,
8
    const void *data, size_t datlen,
9
    void (*cleanupfn)(void *extra), void *cleanupfn_arg);
10

11
/* 添加引用示例 */
12
static void my_cleanup(void *arg) {
13
    char *data = (char *)arg;
14
    printf("Cleaning up: %s\n", data);
15
    free(data);
16
}
17

18
void add_ref_example() {
19
    struct evbuffer *buf = evbuffer_new();
20

21
    char *external_data = strdup("External data");
22
    evbuffer_add_reference(buf, external_data, strlen(external_data),
23
                          my_cleanup, external_data);
24

25
    // 当数据从缓冲区移除时，会调用my_cleanup
26
    evbuffer_drain(buf, evbuffer_get_length(buf));
27

28
    evbuffer_free(buf);
29
}

展开收起

十三、完整示例：HTTP请求解析#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <event2/buffer.h>
5

6
typedef struct {
7
    char method[16];
8
    char path[256];
9
    char version[16];
10
    char headers[1024];
11
    char body[4096];
12
} http_request_t;
13

14
int parse_http_request(struct evbuffer *buf, http_request_t *req) {
15
    char *line;
16
    size_t len;
17

18
    // 读取请求行
19
    line = evbuffer_readln(buf, &len, EVBUFFER_EOL_CRLF);
20
    if (!line) return -1;
21

22
    sscanf(line, "%15s %255s %15s", req->method, req->path, req->version);
23
    free(line);
24

25
    // 读取头部
26
    while ((line = evbuffer_readln(buf, &len, EVBUFFER_EOL_CRLF)) != NULL) {
27
        if (len == 0) {
28
            free(line);
29
            break;  // 空行表示头部结束
30
        }
31
        strncat(req->headers, line, sizeof(req->headers) - strlen(req->headers) - 1);
32
        strncat(req->headers, "\n", sizeof(req->headers) - strlen(req->headers) - 1);
33
        free(line);
34
    }
35

36
    // 读取body（如果有）
37
    size_t body_len = evbuffer_get_length(buf);
38
    if (body_len > 0) {
39
        size_t n = evbuffer_remove(buf, req->body,
40
                                   body_len < sizeof(req->body) - 1 ? body_len : sizeof(req->body) - 1);
41
        req->body[n] = '\0';
42
    }
43

44
    return 0;
45
}
46

47
int main() {
48
    struct evbuffer *buf = evbuffer_new();
49
    http_request_t req = {0};
50

51
    // 模拟HTTP请求
52
    const char *request =
53
        "GET /index.html HTTP/1.1\r\n"
54
        "Host: example.com\r\n"
55
        "User-Agent: TestClient\r\n"
56
        "\r\n";
57

58
    evbuffer_add(buf, request, strlen(request));
59

60
    if (parse_http_request(buf, &req) == 0) {
61
        printf("Method: %s\n", req.method);
62
        printf("Path: %s\n", req.path);
63
        printf("Version: %s\n", req.version);
64
        printf("Headers:\n%s\n", req.headers);
65
    }
66

67
    evbuffer_free(buf);
68
    return 0;
69
}

展开收起

十四、最佳实践#

场景	建议
大数据传输	使用evbuffer_add_file实现零拷贝
行协议解析	使用evbuffer_readln逐行处理
高性能写入	使用evbuffer_reserve_space直接写入
内存敏感	及时evbuffer_drain释放已处理数据
线程安全	使用evbuffer_enable_locking
数据保护	使用evbuffer_freeze保护关键数据

其他相关资料请移步到个人主页

🌐 evdns异步DNS - libevent源码深度解析系列（十九）

Sat, 11 Apr 2026 00:00:00 GMT

🌐 evdns异步DNS#

一、概述#

evdns 是libevent提供的异步DNS解析库，它允许应用程序在不阻塞的情况下进行DNS查询。evdns支持正向解析（域名到IP）、反向解析（IP到域名）、以及运行DNS服务器。

二、evdns_base结构体#

1
struct evdns_base {
2
    struct event_base *event_base;
3

4
    struct evdns_server_port **server_ports;
5
    int n_server_ports;
6

7
    struct evdns_request **reqs;
8
    int n_reqs;
9

10
    struct nameserver **servers;
11
    int n_servers;
12

13
    struct timeval global_nameserver_probe_initial_timeout;
14
    struct timeval global_nameserver_probe_period;
15
    // ...
16
};

展开收起

三、创建与销毁#

3.1 创建evdns_base#

1
/* 创建evdns_base
2
 * @param base            event_base
3
 * @param init_nameservers 是否初始化系统DNS服务器
4
 *                         1: 从/etc/resolv.conf读取
5
 *                         0: 不初始化，需要手动添加
6
 */
7
struct evdns_base *evdns_base_new(struct event_base *base, int init_nameservers);
8

9
/* 释放evdns_base
10
 * @param fail_requests  是否让pending的请求失败
11
 *                       1: 请求回调会被调用并返回错误
12
 *                       0: 请求回调不会被调用
13
 */
14
void evdns_base_free(struct evdns_base *base, int fail_requests);

3.2 基本示例#

1
#include <stdio.h>
2
#include <event2/event.h>
3
#include <event2/dns.h>
4

5
int main() {
6
    struct event_base *base = event_base_new();
7
    struct evdns_base *dns_base = evdns_base_new(base, 1);
8

9
    if (!dns_base) {
10
        fprintf(stderr, "Failed to create dns base\n");
11
        return 1;
12
    }
13

14
    printf("evdns_base created successfully\n");
15

16
    evdns_base_free(dns_base, 0);
17
    event_base_free(base);
18
    return 0;
19
}

展开收起

四、DNS服务器配置#

4.1 添加DNS服务器#

1
/* 添加DNS服务器（IPv4地址） */
2
int evdns_base_nameserver_add(struct evdns_base *base, unsigned long address);
3

4
/* 添加DNS服务器（支持IPv6） */
5
int evdns_base_nameserver_ip_add(struct evdns_base *base, const char *ip_as_string);
6

7
/* 添加Unix域套接字DNS服务器 */
8
int evdns_base_nameserver_sockaddr_add(struct evdns_base *base,
9
    const struct sockaddr *sa, ev_socklen_t len, unsigned flags);
10

11
/* 清除所有DNS服务器 */
12
void evdns_base_clear_nameservers_and_suspend(struct evdns_base *base);
13

14
/* 恢复DNS解析 */
15
int evdns_base_resume(struct evdns_base *base);
16

17
/* 设置DNS服务器探测超时 */
18
void evdns_base_set_nameserver_probe_timeout(struct evdns_base *base,
19
    const struct timeval *timeout);

展开收起

4.2 配置示例#

1
#include <stdio.h>
2
#include <arpa/inet.h>
3
#include <event2/event.h>
4
#include <event2/dns.h>
5

6
int main() {
7
    struct event_base *base = event_base_new();
8

9
    // 不自动初始化，手动添加DNS服务器
10
    struct evdns_base *dns_base = evdns_base_new(base, 0);
11

12
    // 添加Google DNS (8.8.8.8)
13
    evdns_base_nameserver_add(dns_base, inet_addr("8.8.8.8"));
14

15
    // 添加Cloudflare DNS (1.1.1.1)
16
    evdns_base_nameserver_ip_add(dns_base, "1.1.1.1");
17

18
    // 添加IPv6 DNS服务器
19
    evdns_base_nameserver_ip_add(dns_base, "[2001:4860:4860::8888]:53");
20

21
    printf("DNS servers configured\n");
22

23
    evdns_base_free(dns_base, 0);
24
    event_base_free(base);
25
    return 0;
26
}

展开收起

五、正向DNS解析#

5.1 解析API#

1
/* DNS回调函数类型
2
 * @param result   DNS结果码
3
 * @param type     记录类型 (DNS_IPv4_A, DNS_IPv6_AAAA等)
4
 * @param count    返回的地址数量
5
 * @param ttl      生存时间
6
 * @param addresses 地址数组
7
 * @param arg      用户参数
8
 */
9
typedef void (*evdns_callback_type)(int result, char type, int count,
10
                                     int ttl, void *addresses, void *arg);
11

12
/* 异步解析IPv4地址
13
 * @param name      域名
14
 * @param flags     解析标志
15
 * @param callback  回调函数
16
 * @param arg       用户参数
17
 * @return          evdns_request指针，可用于取消请求
18
 */
19
struct evdns_request *evdns_base_resolve_ipv4(
20
    struct evdns_base *base, const char *name, int flags,
21
    evdns_callback_type callback, void *arg);
22

23
/* 异步解析IPv6地址 */
24
struct evdns_request *evdns_base_resolve_ipv6(
25
    struct evdns_base *base, const char *name, int flags,
26
    evdns_callback_type callback, void *arg);
27

28
/* 解析任意记录类型 */
29
struct evdns_request *evdns_base_resolve(
30
    struct evdns_base *base, const char *name, int type, int flags,
31
    evdns_callback_type callback, void *arg);

展开收起

5.2 解析标志#

1
#define DNS_QUERY_NO_SEARCH   0x01  // 不使用搜索列表
2
#define DNS_IPv4_A            1     // A记录
3
#define DNS_IPv6_AAAA         28    // AAAA记录
4
#define DNS_PTR               12    // PTR记录
5
#define DNS_CNAME             5     // CNAME记录
6
#define DNS_MX                15    // MX记录
7
#define DNS_TXT               16    // TXT记录

5.3 DNS结果码#

1
#define DNS_ERR_NONE          0   // 成功
2
#define DNS_ERR_FORMAT        1   // 查询格式错误
3
#define DNS_ERR_SERVERFAILED  2   // 服务器错误
4
#define DNS_ERR_NOTEXIST      3   // 域名不存在
5
#define DNS_ERR_NOTIMPL       4   // 未实现
6
#define DNS_ERR_REFUSED       5   // 拒绝
7
#define DNS_ERR_TRUNCATED     6   // 响应被截断
8
#define DNS_ERR_UNKNOWN       7   // 未知错误
9
#define DNS_ERR_TIMEOUT       8   // 超时
10
#define DNS_ERR_SHUTDOWN      9   // DNS服务关闭
11
#define DNS_ERR_CANCEL        10  // 请求被取消
12
#define DNS_ERR_NODATA        11  // 无数据

5.4 正向解析示例#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <arpa/inet.h>
4
#include <event2/event.h>
5
#include <event2/dns.h>
6

7
static void dns_callback(int result, char type, int count, int ttl,
8
                         void *addresses, void *arg) {
9
    const char *hostname = (const char *)arg;
10

11
    if (result == DNS_ERR_NONE) {
12
        printf("Resolved %s:\n", hostname);
13

14
        if (type == DNS_IPv4_A) {
15
            struct in_addr *addrs = (struct in_addr *)addresses;
16
            for (int i = 0; i < count; i++) {
17
                printf("  IPv4: %s (TTL: %d)\n",
18
                       inet_ntoa(addrs[i]), ttl);
19
            }
20
        } else if (type == DNS_IPv6_AAAA) {
21
            char addr_str[INET6_ADDRSTRLEN];
22
            struct in6_addr *addrs = (struct in6_addr *)addresses;
23
            for (int i = 0; i < count; i++) {
24
                inet_ntop(AF_INET6, &addrs[i], addr_str, sizeof(addr_str));
25
                printf("  IPv6: %s (TTL: %d)\n", addr_str, ttl);
26
            }
27
        }
28
    } else {
29
        printf("DNS lookup failed for %s: %s\n",
30
               hostname, evdns_err_to_string(result));
31
    }
32

33
    // 退出事件循环
34
    event_base_loopbreak((struct event_base *)arg);
35
}
36

37
int main(int argc, char *argv[]) {
38
    const char *hostname = argc > 1 ? argv[1] : "www.google.com";
39

40
    struct event_base *base = event_base_new();
41
    struct evdns_base *dns_base = evdns_base_new(base, 1);
42

43
    printf("Resolving %s...\n", hostname);
44

45
    // 解析IPv4
46
    evdns_base_resolve_ipv4(dns_base, hostname, 0, dns_callback, (void *)hostname);
47

48
    event_base_dispatch(base);
49

50
    evdns_base_free(dns_base, 0);
51
    event_base_free(base);
52

53
    return 0;
54
}

展开收起

六、反向DNS解析#

6.1 反向解析API#

1
/* 反向解析IPv4地址 */
2
struct evdns_request *evdns_base_resolve_reverse(
3
    struct evdns_base *base, const struct in_addr *in, int flags,
4
    evdns_callback_type callback, void *arg);
5

6
/* 反向解析IPv6地址 */
7
struct evdns_request *evdns_base_resolve_reverse_ipv6(
8
    struct evdns_base *base, const struct in6_addr *in, int flags,
9
    evdns_callback_type callback, void *arg);

6.2 反向解析示例#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <arpa/inet.h>
5
#include <event2/event.h>
6
#include <event2/dns.h>
7

8
static void reverse_callback(int result, char type, int count, int ttl,
9
                             void *addresses, void *arg) {
10
    if (result == DNS_ERR_NONE) {
11
        printf("PTR records:\n");
12
        char **names = (char **)addresses;
13
        for (int i = 0; i < count; i++) {
14
            printf("  %s (TTL: %d)\n", names[i], ttl);
15
        }
16
    } else {
17
        printf("Reverse lookup failed: %s\n", evdns_err_to_string(result));
18
    }
19

20
    event_base_loopbreak((struct event_base *)arg);
21
}
22

23
int main(int argc, char *argv[]) {
24
    const char *ip_str = argc > 1 ? argv[1] : "8.8.8.8";
25

26
    struct event_base *base = event_base_new();
27
    struct evdns_base *dns_base = evdns_base_new(base, 1);
28

29
    struct in_addr addr;
30
    inet_pton(AF_INET, ip_str, &addr);
31

32
    printf("Reverse lookup for %s...\n", ip_str);
33
    evdns_base_resolve_reverse(dns_base, &addr, 0, reverse_callback, base);
34

35
    event_base_dispatch(base);
36

37
    evdns_base_free(dns_base, 0);
38
    event_base_free(base);
39

40
    return 0;
41
}

展开收起

七、取消DNS请求#

1
/* 取消DNS请求 */
2
int evdns_cancel_request(struct evdns_base *base, struct evdns_request *req);

取消示例#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <event2/event.h>
4
#include <event2/dns.h>
5

6
static struct evdns_request *pending_req = NULL;
7

8
static void dns_callback(int result, char type, int count, int ttl,
9
                         void *addresses, void *arg) {
10
    if (result == DNS_ERR_CANCEL) {
11
        printf("Request was cancelled\n");
12
    } else if (result == DNS_ERR_NONE) {
13
        printf("DNS resolved successfully\n");
14
    } else {
15
        printf("DNS error: %s\n", evdns_err_to_string(result));
16
    }
17

18
    event_base_loopbreak((struct event_base *)arg);
19
}
20

21
static void timer_callback(evutil_socket_t fd, short events, void *arg) {
22
    struct event_base *base = arg;
23
    printf("Timeout, cancelling DNS request...\n");
24

25
    if (pending_req) {
26
        evdns_cancel_request(NULL, pending_req);
27
        pending_req = NULL;
28
    }
29
}
30

31
int main() {
32
    struct event_base *base = event_base_new();
33
    struct evdns_base *dns_base = evdns_base_new(base, 1);
34

35
    // 发起DNS请求
36
    pending_req = evdns_base_resolve_ipv4(dns_base, "www.example.com",
37
                                          0, dns_callback, base);
38

39
    // 设置1秒超时
40
    struct event *timer = event_new(base, -1, 0, timer_callback, base);
41
    struct timeval tv = {1, 0};
42
    event_add(timer, &tv);
43

44
    event_base_dispatch(base);
45

46
    event_free(timer);
47
    evdns_base_free(dns_base, 0);
48
    event_base_free(base);
49

50
    return 0;
51
}

展开收起

八、DNS服务器#

8.1 创建DNS服务器#

1
/* DNS请求回调函数类型 */
2
typedef void (*evdns_request_callback_fn_type)(struct evdns_server_request *, void *);
3

4
/* 创建DNS服务器端口 */
5
struct evdns_server_port *evdns_add_server_port(
6
    struct event_base *base, evutil_socket_t socket, int flags,
7
    evdns_request_callback_fn_type cb, void *arg);
8

9
/* 创建DNS服务器端口（带地址） */
10
struct evdns_server_port *evdns_add_server_port_with_listener(
11
    struct event_base *base, struct evconnlistener *listener, int flags,
12
    evdns_request_callback_fn_type cb, void *arg);
13

14
/* 释放DNS服务器端口 */
15
void evdns_close_server_port(struct evdns_server_port *port);

展开收起

8.2 DNS服务器请求处理#

1
/* 获取请求中的问题数量 */
2
int evdns_server_request_get_requesting_addr(
3
    struct evdns_server_request *req, struct sockaddr *sa, socklen_t *len);
4

5
/* 获取问题 */
6
int evdns_server_request_get_requesting_nameserver_addr(
7
    struct evdns_server_request *req, struct sockaddr *sa, socklen_t *len);
8

9
/* 回复A记录 */
10
int evdns_server_request_add_a_reply(struct evdns_server_request *req,
11
    const char *name, int n, const void *addrs, int ttl);
12

13
/* 回复AAAA记录 */
14
int evdns_server_request_add_aaaa_reply(struct evdns_server_request *req,
15
    const char *name, int n, const void *addrs, int ttl);
16

17
/* 回复PTR记录 */
18
int evdns_server_request_add_ptr_reply(struct evdns_server_request *req,
19
    struct in_addr *in, const char *name, int ttl);
20

21
/* 回复CNAME记录 */
22
int evdns_server_request_add_cname_reply(struct evdns_server_request *req,
23
    const char *name, const char *cname, int ttl);
24

25
/* 发送回复 */
26
int evdns_server_request_respond(struct evdns_server_request *req, int err);
27

28
/* 丢弃请求 */
29
int evdns_server_request_drop(struct evdns_server_request *req);

展开收起

8.3 DNS服务器示例#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <arpa/inet.h>
5
#include <event2/event.h>
6
#include <event2/dns.h>
7
#include <event2/dns_struct.h>
8

9
static void dns_server_callback(struct evdns_server_request *request, void *arg) {
10
    printf("DNS request received\n");
11

12
    // 获取问题
13
    int n_questions = request->n_questions;
14

15
    for (int i = 0; i < n_questions; i++) {
16
        struct evdns_server_question *q = request->questions[i];
17
        printf("Question %d: name=%s, type=%d, class=%d\n",
18
               i, q->name, q->type, q->dns_question_class);
19

20
        // 简单处理：对于特定域名返回固定IP
21
        if (q->type == EVDNS_TYPE_A && strcmp(q->name, "test.local.") == 0) {
22
            struct in_addr addr;
23
            inet_pton(AF_INET, "192.168.1.100", &addr);
24
            evdns_server_request_add_a_reply(request, q->name, 1, &addr, 60);
25
        } else if (q->type == EVDNS_TYPE_AAAA && strcmp(q->name, "test.local.") == 0) {
26
            struct in6_addr addr;
27
            inet_pton(AF_INET6, "::1", &addr);
28
            evdns_server_request_add_aaaa_reply(request, q->name, 1, &addr, 60);
29
        } else {
30
            // 其他请求返回NXDOMAIN
31
            evdns_server_request_respond(request, DNS_ERR_NOTEXIST);
32
            return;
33
        }
34
    }
35

36
    evdns_server_request_respond(request, DNS_ERR_NONE);
37
}
38

39
int main() {
40
    struct event_base *base = event_base_new();
41

42
    // 创建UDP socket
43
    int fd = socket(AF_INET, SOCK_DGRAM, 0);
44
    evutil_make_socket_nonblocking(fd);
45

46
    int reuse = 1;
47
    setsockopt(fd, SOL_SOCKET, SO_REUSEADDR, &reuse, sizeof(reuse));
48

49
    struct sockaddr_in sin;
50
    memset(&sin, 0, sizeof(sin));
51
    sin.sin_family = AF_INET;
52
    sin.sin_port = htons(5353);  // 使用5353端口
53
    sin.sin_addr.s_addr = INADDR_ANY;
54

55
    bind(fd, (struct sockaddr *)&sin, sizeof(sin));
56

57
    // 创建DNS服务器
58
    struct evdns_server_port *dns_port = evdns_add_server_port(
59
        base, fd, 0, dns_server_callback, NULL);
60

61
    printf("DNS server listening on port 5353\n");
62
    printf("Try: nslookup -port=5353 test.local 127.0.0.1\n");
63

64
    event_base_dispatch(base);
65

66
    evdns_close_server_port(dns_port);
67
    evutil_closesocket(fd);
68
    event_base_free(base);
69

70
    return 0;
71
}

展开收起

九、DNS配置选项#

9.1 配置API#

1
/* 设置搜索域名 */
2
int evdns_base_search_add(struct evdns_base *base, const char *domain);
3

4
/* 清除搜索域名 */
5
void evdns_base_search_clear(struct evdns_base *base);
6

7
/* 设置搜索域名数量限制 */
8
void evdns_base_search_ndots_set(struct evdns_base *base, int ndots);
9

10
/* 设置是否使用TCP */
11
int evdns_base_set_option(struct evdns_base *base, const char *option,
12
                          const char *val);
13

14
/* 常用选项 */
15
// "timeout"        - 超时时间（秒）
16
// "max-timeouts"   - 最大超时次数
17
// "attempts"       - 重试次数
18
// "randomize-case" - 随机化大小写（DNS安全）
19
// "use-vc"         - 使用TCP
20
// "ndots"          - 点的数量阈值

展开收起

9.2 配置示例#

1
#include <stdio.h>
2
#include <event2/event.h>
3
#include <event2/dns.h>
4

5
int main() {
6
    struct event_base *base = event_base_new();
7
    struct evdns_base *dns_base = evdns_base_new(base, 0);
8

9
    // 添加DNS服务器
10
    evdns_base_nameserver_add(dns_base, inet_addr("8.8.8.8"));
11

12
    // 设置选项
13
    evdns_base_set_option(dns_base, "timeout", "5");      // 5秒超时
14
    evdns_base_set_option(dns_base, "attempts", "3");     // 重试3次
15
    evdns_base_set_option(dns_base, "use-vc", NULL);      // 使用TCP
16
    evdns_base_set_option(dns_base, "randomize-case", "1"); // 启用DNS安全
17

18
    // 添加搜索域名
19
    evdns_base_search_add(dns_base, "example.com");
20
    evdns_base_search_add(dns_base, "local");
21

22
    // 设置ndots
23
    evdns_base_search_ndots_set(dns_base, 2);
24

25
    printf("DNS configuration complete\n");
26

27
    evdns_base_free(dns_base, 0);
28
    event_base_free(base);
29
    return 0;
30
}

展开收起

十、错误处理#

10.1 错误字符串#

1
/* 将DNS错误码转换为字符串 */
2
const char *evdns_err_to_string(int err);

10.2 错误处理示例#

1
#include <stdio.h>
2
#include <event2/dns.h>
3

4
void print_dns_error(int err) {
5
    switch (err) {
6
        case DNS_ERR_NONE:
7
            printf("Success\n");
8
            break;
9
        case DNS_ERR_FORMAT:
10
            printf("Query format error\n");
11
            break;
12
        case DNS_ERR_SERVERFAILED:
13
            printf("Server failed\n");
14
            break;
15
        case DNS_ERR_NOTEXIST:
16
            printf("Domain name does not exist\n");
17
            break;
18
        case DNS_ERR_TIMEOUT:
19
            printf("Query timeout\n");
20
            break;
21
        case DNS_ERR_CANCEL:
22
            printf("Request cancelled\n");
23
            break;
24
        default:
25
            printf("Unknown error: %s\n", evdns_err_to_string(err));
26
    }
27
}

展开收起

十一、完整示例：异步HTTP客户端DNS解析#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <arpa/inet.h>
5
#include <event2/event.h>
6
#include <event2/dns.h>
7
#include <event2/bufferevent.h>
8

9
typedef struct {
10
    struct event_base *base;
11
    struct evdns_base *dns_base;
12
    const char *hostname;
13
    int port;
14
} http_context_t;
15

16
static void http_event_cb(struct bufferevent *bev, short events, void *arg) {
17
    http_context_t *ctx = arg;
18

19
    if (events & BEV_EVENT_CONNECTED) {
20
        printf("Connected to %s:%d\n", ctx->hostname, ctx->port);
21

22
        // 发送HTTP请求
23
        char request[256];
24
        snprintf(request, sizeof(request),
25
                 "GET / HTTP/1.1\r\n"
26
                 "Host: %s\r\n"
27
                 "Connection: close\r\n"
28
                 "\r\n", ctx->hostname);
29

30
        bufferevent_write(bev, request, strlen(request));
31
    } else if (events & (BEV_EVENT_EOF | BEV_EVENT_ERROR)) {
32
        if (events & BEV_EVENT_ERROR) {
33
            printf("Connection error\n");
34
        }
35
        bufferevent_free(bev);
36
        event_base_loopexit(ctx->base, NULL);
37
    }
38
}
39

40
static void http_read_cb(struct bufferevent *bev, void *arg) {
41
    char buf[4096];
42
    size_t n;
43

44
    while ((n = bufferevent_read(bev, buf, sizeof(buf) - 1)) > 0) {
45
        buf[n] = '\0';
46
        printf("%s", buf);
47
    }
48
}
49

50
static void dns_callback(int result, char type, int count, int ttl,
51
                         void *addresses, void *arg) {
52
    http_context_t *ctx = arg;
53

54
    if (result != DNS_ERR_NONE || count == 0) {
55
        printf("DNS lookup failed for %s: %s\n",
56
               ctx->hostname, evdns_err_to_string(result));
57
        event_base_loopexit(ctx->base, NULL);
58
        return;
59
    }
60

61
    struct in_addr *addrs = (struct in_addr *)addresses;
62
    printf("Resolved %s to %s\n", ctx->hostname, inet_ntoa(addrs[0]));
63

64
    // 创建连接
65
    struct bufferevent *bev = bufferevent_socket_new(ctx->base, -1,
66
                                                      BEV_OPT_CLOSE_ON_FREE);
67
    bufferevent_setcb(bev, http_read_cb, NULL, http_event_cb, ctx);
68
    bufferevent_enable(bev, EV_READ | EV_WRITE);
69

70
    struct sockaddr_in sin;
71
    memset(&sin, 0, sizeof(sin));
72
    sin.sin_family = AF_INET;
73
    sin.sin_port = htons(ctx->port);
74
    sin.sin_addr = addrs[0];
75

76
    bufferevent_socket_connect(bev, (struct sockaddr *)&sin, sizeof(sin));
77
}
78

79
int main(int argc, char *argv[]) {
80
    const char *hostname = argc > 1 ? argv[1] : "www.example.com";
81
    int port = argc > 2 ? atoi(argv[2]) : 80;
82

83
    struct event_base *base = event_base_new();
84
    struct evdns_base *dns_base = evdns_base_new(base, 1);
85

86
    http_context_t ctx = {
87
        .base = base,
88
        .dns_base = dns_base,
89
        .hostname = hostname,
90
        .port = port
91
    };
92

93
    printf("Resolving %s...\n", hostname);
94
    evdns_base_resolve_ipv4(dns_base, hostname, 0, dns_callback, &ctx);
95

96
    event_base_dispatch(base);
97

98
    evdns_base_free(dns_base, 0);
99
    event_base_free(base);
100

101
    return 0;
102
}

展开收起

十二、最佳实践#

场景	建议
生产环境	配置多个DNS服务器，提高可用性
超时设置	根据网络环境调整超时时间
错误处理	实现重试机制和降级策略
DNS缓存	应用层实现缓存，减少DNS查询
IPv6支持	同时解析IPv4和IPv6地址
DNS安全	启用randomize-case防止DNS欺骗

其他相关资料请移步到个人主页

🎭 event详解 - libevent源码深度解析系列（六）

Sat, 11 Apr 2026 00:00:00 GMT

📦 event详解#

一、概述#

event是libevent的基本单元。事件添加到event_base中之后，如果触发条件发生（例如，文件描述符的状态发生改变、时间超时等），则事件就会被激活，然后事件中的回调函数就会被执行。如果事件被配置为了持久形的（EV_PERSIST），那么事件仍然在event_base中，继续等待下一次的条件被触发，否则事件就会从event_base中删除。

二、event结构体#

1
struct event {
2
    // 外部操作ev_evcallback时，是基于宏定义操作的
3
    #define ev_pri ev_evcallback.evcb_pri
4
    #define ev_flags ev_evcallback.evcb_flags
5
    #define ev_closure ev_evcallback.evcb_closure
6
    #define ev_callback ev_evcallback.evcb_cb_union.evcb_callback
7
    #define ev_arg ev_evcallback.evcb_arg
8
    struct event_callback ev_evcallback;
9

10
    /* for managing timeouts */
11
    union {
12
        TAILQ_ENTRY(event) ev_next_with_common_timeout;
13
        int min_heap_idx;
14
    } ev_timeout_pos;
15

16
    evutil_socket_t ev_fd;      // 文件句柄
17
    struct event_base *ev_base;
18

19
    union {
20
        /* used for io events */
21
        struct {
22
            LIST_ENTRY (event) ev_io_next;
23
            struct timeval ev_timeout;
24
        } ev_io;
25

26
        /* used by signal events */
27
        struct {
28
            LIST_ENTRY (event) ev_signal_next;
29
            short ev_ncalls;
30
            short *ev_pncalls;
31
        } ev_signal;
32
    } ev_;
33

34
    short ev_events;            // 事件集合
35
    struct timeval ev_timeout;
36
};

展开收起

三、事件的创建#

3.1 回调函数类型#

1
/**
2
 * @param fd    An fd or signal
3
 * @param events One or more EV_* flags
4
 * @param arg   A user-supplied argument
5
 */
6
typedef void (*event_callback_fn)(evutil_socket_t, short, void *);

3.2 创建函数#

1
/* 创建通用事件处理器
2
 * @param base     指定新创建的事件处理器从属的Reactor
3
 * @param fd       指定与事件处理器关联的句柄。创建I/O事件处理器时，传递文件描述符；
4
 *                 创建信号事件处理器时，传递信号值；创建定时事件处理器时传递-1
5
 * @param events   指定事件类型，详细见EV_XXX
6
 * @param cb       指定目标事件对应的回调函数
7
 * @param arg      Reactor传递给回调函数的参数
8
 */
9
struct event *event_new(struct event_base *, evutil_socket_t, short,
10
                        event_callback_fn, void *);
11

12
/* 设置event参数，函数内部同时会设置事件的base */
13
void event_set(struct event *, evutil_socket_t, short,
14
               void (*)(evutil_socket_t, short, void *), void *);
15

16
/* 同时设置事件的event_base
17
 * 不要对已经在event_base中的事件调用event_assign()，这可能会导致错误
18
 * 如果已经添加进来了，需要调用event_assign()之前先调用event_del()
19
 */
20
int event_assign(struct event* event, struct event_base * base,
21
                 evutil_socket_t fd, short what,
22
                 void (*callback)(evutil_socket_t, short, void*), void * arg);
23

24
/* 释放事件资源 */
25
void event_free(struct event *);
26

27
/* 返回sizeof(struct event) */
28
size_t event_get_struct_event_size(void);

展开收起

3.3 添加和删除事件#

1
/* 如果 tv 为 NULL，添加的事件不会超时。否则，tv以秒和微秒指定超时值 */
2
int event_add(struct event* ev, const struct timeval * tv);
3
int event_del(struct event* ev);
4
int event_remove_timer(struct event* ev);

四、事件的信息获取#

1
// 获取信号事件的信号值
2
#define event_get_signal(ev) ((int)event_get_fd(ev))
3

4
// 获取信号事件的信号值，或者IO事件的描述符
5
evutil_socket_t event_get_fd(const struct event *ev);
6

7
// 获取事件所属的event_base
8
struct event_base *event_get_base(const struct event *ev);
9

10
// 获取事件类型（EV_READ, EV_WRITE等）
11
short event_get_events(const struct event *ev);
12

13
// 获取回调函数
14
event_callback_fn event_get_callback(const struct event *ev);
15

16
// 获取回调参数
17
void *event_get_callback_arg(const struct event *ev);
18

19
// 获取libevent版本
20
const char *event_get_version(void);
21
ev_uint32_t event_get_version_number(void);
22

23
// 检测事件是否被初始化
24
int event_initialized(const struct event *ev);
25

26
/* 检测事件是否处于pending状态
27
 * @param ev      事件
28
 * @param events  请求的事件类型：EV_TIMEOUT|EV_READ|EV_WRITE|EV_SIGNAL
29
 * @param tv      如果不为NULL，且事件有超时，设置超时时间
30
 * @return        如果事件pending返回true，否则返回0
31
 */
32
int event_pending(const struct event *ev, short events, struct timeval *tv);
33

34
/* 提取一个给定事件的所有参数 */
35
void event_get_assignment(const struct event *event,
36
    struct event_base **base_out, evutil_socket_t *fd_out, short *events_out,
37
    event_callback_fn *callback_out, void **arg_out);
38

39
/* 获取当前正在运行的事件，线程不安全 */
40
struct event* event_base_get_running_event(struct event_base * base);

展开收起

五、手动激活事件#

1
/* EV_READ、EV_WRITE、EV_TIMEOUT的组合 */
2
void event_active(struct event* ev, int what, short ncalls);

注意：尽量不要在事件回调本身里激活自身，否则会一直循环激活。

六、定时器事件#

1
/**
2
 * @name evtimer_* macros
3
 * Aliases for working with one-shot timer events
4
 * If you need EV_PERSIST timer use event_*() functions.
5
 */
6
#define evtimer_assign(ev, b, cb, arg) \
7
    event_assign((ev), (b), -1, 0, (cb), (arg))
8
#define evtimer_new(b, cb, arg)        event_new((b), -1, 0, (cb), (arg))
9
#define evtimer_add(ev, tv)            event_add((ev), (tv))
10
#define evtimer_del(ev)                event_del(ev)
11
#define evtimer_pending(ev, tv)        event_pending((ev), EV_TIMEOUT, (tv))
12
#define evtimer_initialized(ev)        event_initialized(ev)

七、信号事件#

1
/**
2
 * @name evsignal_* macros
3
 * Aliases for working with signal events
4
 */
5
#define evsignal_add(ev, tv)           event_add((ev), (tv))
6
#define evsignal_assign(ev, b, x, cb, arg) \
7
    event_assign((ev), (b), (x), EV_SIGNAL|EV_PERSIST, cb, (arg))
8
#define evsignal_new(b, x, cb, arg) \
9
    event_new((b), (x), EV_SIGNAL|EV_PERSIST, (cb), (arg))
10
#define evsignal_del(ev)               event_del(ev)
11
#define evsignal_pending(ev, tv)       event_pending((ev), EV_SIGNAL, (tv))
12
#define evsignal_initialized(ev)       event_initialized(ev)

使用信号时的注意事项#

当前版本的信号大多数运行在后台，每个进程只能有一个event_base可以同时监控信号，如果同时添加两个event到event_base，即使信号是不同的，也只会有一个event_base会接收到信号。

八、事件优先级#

当多个event同时触发，libevent并没有定义回调函数执行要遵循的任何顺序。可以用优先级来决定当多个事件同时发生时的回调函数执行顺序。

默认情况下，Libevent为所有事件分配中间优先级，除非它们的优先级被明确设置。

1
int event_priority_set(struct event* event, int priority);
2
int event_get_priority(const struct event *ev);
3

4
/** Largest number of priorities that Libevent can support. */
5
#define EVENT_MAX_PRIORITIES 256
6

7
/* 设置优先级的最大数量 */
8
int event_base_priority_init(struct event_base *, int);
9

10
/* 获取优先级的最大数量 */
11
int event_base_get_npriorities(struct event_base *eb);

九、事件的生命周期#

事件的生命周期包括创建、添加、触发、移除和销毁等阶段：

创建：通过 event_new 或 event_assign 创建事件
添加：通过 event_add 将事件添加到事件基中
触发：事件条件满足时，libevent 自动调用回调函数，也可以通过 event_active 手动触发
移除：通过 event_del 将事件从事件基中移除
销毁：通过 event_free 销毁事件

十、使用示例#

10.1 基本事件使用#

1
#include <stdio.h>
2
#include <event.h>
3

4
void callback(evutil_socket_t fd, short events, void *arg) {
5
    printf("Event triggered, events=%d\n", events);
6
}
7

8
int main() {
9
    struct event_base *base = event_base_new();
10

11
    // 创建事件
12
    struct event *ev = event_new(base, -1, EV_TIMEOUT, callback, NULL);
13

14
    // 添加事件，1秒后触发
15
    struct timeval tv = {1, 0};
16
    event_add(ev, &tv);
17

18
    // 开始事件循环
19
    event_base_dispatch(base);
20

21
    // 清理
22
    event_free(ev);
23
    event_base_free(base);
24
    return 0;
25
}

展开收起

10.2 持久事件#

1
#include <stdio.h>
2
#include <event.h>
3

4
void callback(evutil_socket_t fd, short events, void *arg) {
5
    printf("Persistent event triggered\n");
6
}
7

8
int main() {
9
    struct event_base *base = event_base_new();
10

11
    // 创建持久事件
12
    struct event *ev = event_new(base, -1, EV_TIMEOUT | EV_PERSIST, callback, NULL);
13

14
    struct timeval tv = {1, 0};  // 每1秒触发一次
15
    event_add(ev, &tv);
16

17
    event_base_dispatch(base);
18

19
    event_free(ev);
20
    event_base_free(base);
21
    return 0;
22
}

展开收起

其他相关资料请移步到个人主页

🎯 event_base详解 - libevent源码深度解析系列（五）

Sat, 11 Apr 2026 00:00:00 GMT

🏗️ event_base详解#

一、概述#

最重要的 event_base，就是一个 Reactor框架，我们都是需要先申请 event_base 结构体。对于一个 event_base 结构来说，它会保存一系列的 event 事件并且以轮训的方式去关注每一个事件，去查看哪一个事件是就绪的，事件就绪之后，就会调用事件回调。

我们可以取消(disable)指定的method通过环境变量，比如设置 EVENT_NOQUEUE 环境变量。也可以通过调用 event_config_avoid_method 函数来关闭相应的method。

二、事件类型定义#

1
#define EV_TIMEOUT  0x01    // 定时事件
2
#define EV_READ     0x02    // 可读事件
3
#define EV_WRITE    0x04    // 可写事件
4
#define EV_SIGNAL   0x08    // 信号事件
5
#define EV_PERSIST  0x10    // 永久事件，EV_PERSIST的作用是：事件被触发后，自动重新对这个event调用event_add函数
6
#define EV_ET       0x20    // 边缘触发事件，需要I/O复用系统调用支持，比如epoll

三、event_base结构体#

1
struct event_base {
2
    /* eventop 实际上就是对系统提供的I/O复用接口进行封装（select、poll、epoll、kqueue...）
3
       这个赋值是在创建event_base的时候 event_base_new -> event_base_new_with_config，
4
       在这个函数中从 eventops 结构体数组中选出合适的I/O复用机制 */
5
    const struct eventop *evsel;
6

7
    /* 上面选出合适的I/O复用机制之后，通过base->evsel->init生成 evbase
8
       所以可以说evsel 和 evbase 的关系就是c++中类和类的实例的关系 */
9
    void *evbase;
10

11
    /* 使用changelist后，对事件的修改不会立即作用到epoll上，而是把这些修改保存到一个list上，
12
       在作用到epoll之前，这些修改可以抵消，合并 */
13
    struct event_changelist changelist;
14

15
    const struct eventop *evsigsel;
16
    struct evsig_info sig;
17

18
    int virtual_event_count;
19
    int virtual_event_count_max;
20
    int event_count;              // 事件总数
21
    int event_count_max;
22
    int event_count_active;       // 活跃事件数
23
    int event_count_active_max;
24

25
    int event_gotterm;            // 设置在处理完事件后是否应该终止循环
26
    int event_break;              // 设置是否应该立即终止循环
27
    int event_continue;           // 设置是否应该立即启动一个新的循环实例
28

29
    int event_running_priority;
30
    int running_loop;
31

32
    /* 触发的事件列表，后面会遍历这个列表，执行其中的回调 */
33
    struct evcallback_list *activequeues;
34
    int nactivequeues;
35
    struct evcallback_list active_later_queue;
36

37
    struct common_timeout_list **common_timeout_queues;
38
    int n_common_timeouts;
39
    int n_common_timeouts_allocated;
40

41
    struct event_io_map io;       // Mapping from file descriptors to events
42
    struct event_signal_map sigmap; // Mapping from signal numbers to events
43
    struct min_heap timeheap;     // Priority queue of events with timeouts
44

45
    struct timeval tv_cache;
46
    struct evutil_monotonic_timer monotonic_timer;
47

48
#ifndef EVENT__DISABLE_THREAD_SUPPORT
49
    unsigned long th_owner_id;
50
    void *th_base_lock;
51
    void *current_event_cond;
52
    int current_event_waiters;
53
#endif
54

55
    struct event_callback *current_event;
56
    enum event_base_config_flag flags;
57
    // ... 其他字段
58
};

展开收起

四、eventop结构体#

1
struct eventop {
2
    const char *name;            // 后端名称
3
    /* 创建一个新结构，包含运行后端所需的任何信息 */
4
    void *(*init)(struct event_base *);
5
    /* 在给定的 fd 或信号上启用读/写 */
6
    int (*add)(struct event_base *, evutil_socket_t fd, short old, short events, void *fdinfo);
7
    /* 禁用事件 */
8
    int (*del)(struct event_base *, evutil_socket_t fd, short old, short events, void *fdinfo);
9
    /* 事件派遣分发 */
10
    int (*dispatch)(struct event_base *, struct timeval *);
11
    /* 释放资源 */
12
    void (*dealloc)(struct event_base *);
13
    int need_reinit;             // 是否需要重新初始化
14
    enum event_method_feature features;  // 支持的特性
15
    size_t fdinfo_len;
16
};

展开收起

4.1 epoll后端示例#

1
const struct eventop epollops = {
2
    "epoll",
3
    epoll_init,
4
    epoll_nochangelist_add,
5
    epoll_nochangelist_del,
6
    epoll_dispatch,
7
    epoll_dealloc,
8
    1, /* need reinit */
9
    EV_FEATURE_ET|EV_FEATURE_O1|EV_FEATURE_EARLY_CLOSE,
10
    0
11
};

五、event_base API#

5.1 创建event_base#

1
// 简单创建
2
struct event_base *event_base_new(void);
3

4
// 带配置创建
5
struct event_base *event_base_new_with_config(const struct event_config *cfg);
6

7
// 旧版本兼容
8
struct event_base *event_init(void);
9

10
// 释放
11
void event_base_free(struct event_base *base);

5.1.1 event_base_new 源码解析#

event_base_new 函数的核心实现流程：

1
struct event_base *event_base_new(void) {
2
    struct event_config *cfg = event_config_new();
3
    struct event_base *base = event_base_new_with_config(cfg);
4
    event_config_free(cfg);
5
    return base;
6
}
7

8
struct event_base *event_base_new_with_config(const struct event_config *cfg) {
9
    struct event_base *base;
10

11
    // 1. 分配event_base结构
12
    base = calloc(1, sizeof(struct event_base));
13
    if (!base) return NULL;
14

15
    // 2. 初始化基本字段
16
    base->evsel = NULL;
17
    base->evbase = NULL;
18

19
    // 3. 选择合适的I/O多路复用后端
20
    if (!event_base_choose_method(base, cfg)) {
21
        event_base_free(base);
22
        return NULL;
23
    }
24

25
    // 4. 初始化其他组件
26
    if (event_base_init_common_timeout_lists(base)) {
27
        event_base_free(base);
28
        return NULL;
29
    }
30

31
    // 5. 初始化信号处理
32
    if (evsig_init(base)) {
33
        event_base_free(base);
34
        return NULL;
35
    }
36

37
    return base;
38
}

展开收起

5.1.2 后端选择机制#

event_base_choose_method 函数会从 eventops 数组中选择最合适的后端：

1
static int event_base_choose_method(struct event_base *base, const struct event_config *cfg) {
2
    const struct eventop *best_method = NULL;
3
    int best_priority = 0;
4

5
    // 遍历所有可用的后端
6
    for (const struct eventop **method = eventops; *method; method++) {
7
        // 检查是否满足配置要求
8
        if (!event_config_is_method_disabled(cfg, (*method)->name)) {
9
            // 选择优先级最高的方法
10
            if (!best_method || (*method)->features > best_priority) {
11
                best_method = *method;
12
                best_priority = (*method)->features;
13
            }
14
        }
15
    }
16

17
    if (!best_method) return 0;
18

19
    // 初始化选中的后端
20
    base->evsel = best_method;
21
    base->evbase = base->evsel->init(base);
22

23
    return 1;
24
}

展开收起

5.1.3 后端优先级#

后端	优先级	特性
epoll	最高	EV_FEATURE_ETEV_FEATURE_O1EV_FEATURE_EARLY_CLOSE
kqueue	高	EV_FEATURE_ETEV_FEATURE_O1EV_FEATURE_EARLY_CLOSE
poll	中	基本功能
select	低	基本功能

5.1.4 创建流程图示#

1
┌─────────────────────────────────────────────────────┐
2
│                event_base_new()                   │
3
├─────────────────────────────────────────────────────┤
4
│ 1. 创建event_config                               │
5
│ 2. 调用event_base_new_with_config()               │
6
│    ├─ 分配event_base结构                          │
7
│    ├─ 选择I/O多路复用后端                         │
8
│    │  ├─ 遍历eventops数组                        │
9
│    │  ├─ 检查配置要求                            │
10
│    │  └─ 选择优先级最高的方法                      │
11
│    ├─ 初始化后端                                  │
12
│    ├─ 初始化通用超时列表                          │
13
│    └─ 初始化信号处理                              │
14
│ 3. 释放event_config                              │
15
│ 4. 返回event_base指针                             │
16
└─────────────────────────────────────────────────────┘

展开收起

event_base_new 从全局变量 eventops 中选出操作系统支持的最快方法：

1
static const struct eventop *eventops[] = {
2
#ifdef EVENT__HAVE_EVENT_PORTS
3
    &evportops,
4
#endif
5
#ifdef EVENT__HAVE_WORKING_KQUEUE
6
    &kqops,
7
#endif
8
#ifdef EVENT__HAVE_EPOLL
9
    &epollops,
10
#endif
11
#ifdef EVENT__HAVE_DEVPOLL
12
    &devpollops,
13
#endif
14
#ifdef EVENT__HAVE_POLL
15
    &pollops,
16
#endif
17
#ifdef EVENT__HAVE_SELECT
18
    &selectops,
19
#endif
20
#ifdef _WIN32
21
    &win32ops,
22
#endif
23
    NULL
24
};

展开收起

5.2 运行事件循环#

1
/* 阻塞等待事件的到来，如果列表中没有事件，或者事件中调用
2
   event_base_loopbreak() 或者 event_base_loopexit()，此函数将会退出阻塞 */
3
int event_base_dispatch(struct event_base *base);
4

5
/* 更细粒度控制的事件循环 */
6
int event_base_loop(struct event_base *base, int flags);

5.2.1 event_base_loop 源码解析#

event_base_loop 函数是事件循环的核心实现：

1
int event_base_loop(struct event_base *base, int flags) {
2
    int res, done;
3
    struct timeval tv;
4
    struct timeval *tv_p;
5

6
    // 检查是否已经在运行
7
    if (base->running_loop) {
8
        return -1;
9
    }
10

11
    base->running_loop = 1;
12
    done = 0;
13

14
    while (!done) {
15
        // 1. 计算超时时间
16
        tv_p = &tv;
17
        if (!N_ACTIVE_CALLBACKS(base) && !(flags & EVLOOP_NONBLOCK)) {
18
            timeout = event_base_get_next_timeout(base, &tv);
19
        } else {
20
            // 如果有活跃回调或非阻塞模式，不等待
21
            evutil_timerclear(&tv);
22
        }
23

24
        // 2. 处理待处理的事件变更
25
        if (base->changelist) {
26
            event_process_changelist(base);
27
        }
28

29
        // 3. 调用后端的dispatch方法
30
        res = base->evsel->dispatch(base, tv_p);
31

32
        // 4. 处理定时器事件
33
        event_process_active(base);
34

35
        // 5. 检查是否需要退出
36
        if (base->event_gotterm) {
37
            done = 1;
38
        } else if (base->event_break) {
39
            done = 1;
40
        } else if ((flags & EVLOOP_ONCE) && !N_ACTIVE_CALLBACKS(base)) {
41
            done = 1;
42
        } else if ((flags & EVLOOP_NONBLOCK) && !N_ACTIVE_CALLBACKS(base)) {
43
            done = 1;
44
        }
45
    }
46

47
    base->running_loop = 0;
48
    return 0;
49
}

展开收起

5.2.2 事件循环流程#

计算超时时间：根据定时器事件计算下次超时时间
处理事件变更：应用之前积累的事件添加/删除操作
等待事件：调用后端的dispatch方法等待事件触发
处理活跃事件：执行触发的事件回调
检查退出条件：根据标志和状态决定是否退出循环

5.2.3 事件循环图示#

1
┌─────────────────────────────────────────────────────┐
2
│             event_base_loop()                     │
3
├─────────────────────────────────────────────────────┤
4
│ 1. 检查是否已在运行                               │
5
│ 2. 进入主循环                                     │
6
│    ├─ 计算下次超时时间                             │
7
│    ├─ 处理待处理的事件变更                          │
8
│    ├─ 调用后端dispatch等待事件                      │
9
│    ├─ 处理定时器事件                                │
10
│    ├─ 处理活跃事件                                  │
11
│    └─ 检查退出条件                                  │
12
│ 3. 退出循环                                        │
13
└─────────────────────────────────────────────────────┘

循环标志#

1
#define EVLOOP_ONCE            0x01  // 触发一次后退出
2
#define EVLOOP_NONBLOCK        0x02  // 非阻塞模式
3
#define EVLOOP_NO_EXIT_ON_EMPTY 0x04 // 无事件时不退出

5.3 停止事件循环#

1
/* 让 event_base 在给定时间之后停止循环
2
   如果tv参数NULL，event_base会立即停止循环 */
3
int event_base_loopexit(struct event_base *base, const struct timeval *tv);
4

5
/* event_base 立即退出循环，不会等待正在执行的事件完成 */
6
int event_base_loopbreak(struct event_base *base);
7

8
/* 检查退出原因 */
9
int event_base_got_exit(struct event_base *base);  // 因为loopexit退出
10
int event_base_got_break(struct event_base *base); // 因为loopbreak退出
11

12
/* 如果事件处理完后loop会退出，在回调中执行此函数则loop不会退出 */
13
int event_base_loopcontinue(struct event_base *base);

5.4 获取event_base信息#

1
/* 获取Libevent使用的内核I/O复用机制 */
2
const char *event_base_get_method(const struct event_base *base);
3

4
/* 获取支持的方法列表 */
5
const char **event_get_supported_methods(void);
6

7
/* 获取事件数量 */
8
int event_base_get_num_events(struct event_base *base, unsigned int type);
9
// type: EVENT_BASE_COUNT_ACTIVE, EVENT_BASE_COUNT_VIRTUAL, EVENT_BASE_COUNT_ADDED
10

11
/* 获取最大事件数量 */
12
int event_base_get_max_events(struct event_base *base, unsigned int type, int clear);

六、event_config配置#

1
struct event_config *event_config_new(void);
2
void event_config_free(struct event_config *cfg);
3

4
/* 设置不使用指定的I/O复用机制 */
5
int event_config_avoid_method(struct event_config *cfg, const char *method);

6.1 特性设置#

1
enum event_method_feature {
2
    EV_FEATURE_ET = 0x01,          // 要求支持边沿触发
3
    EV_FEATURE_O1 = 0x02,          // 要求O(1)复杂度
4
    EV_FEATURE_FDS = 0x04,         // 要求支持任意文件描述符
5
    EV_FEATURE_EARLY_CLOSE = 0x08  // 要求支持EV_CLOSED
6
};
7

8
int event_config_require_features(struct event_config *cfg, int feature);
9
int event_base_get_features(const struct event_base *base);

6.2 标志设置#

1
enum event_base_config_flag {
2
    EVENT_BASE_FLAG_NOLOCK = 0x01,              // 不分配锁
3
    EVENT_BASE_FLAG_IGNORE_ENV = 0x02,          // 忽略环境变量
4
    EVENT_BASE_FLAG_STARTUP_IOCP = 0x04,        // Windows IOCP
5
    EVENT_BASE_FLAG_NO_CACHE_TIME = 0x08,       // 不缓存时间
6
    EVENT_BASE_FLAG_EPOLL_USE_CHANGELIST = 0x10,// 使用epoll changelist
7
    EVENT_BASE_FLAG_PRECISE_TIMER = 0x20        // 精确计时器
8
};
9

10
int event_config_set_flag(struct event_config *cfg, int flag);

七、使用示例#

1
#include <stdio.h>
2
#include <event2/event.h>
3

4
int main() {
5
    // 简单创建
6
    struct event_base *base = event_base_new();
7

8
    // 带配置创建
9
    struct event_config *cfg = event_config_new();
10
    event_config_require_features(cfg, EV_FEATURE_ET | EV_FEATURE_O1);
11
    event_config_avoid_method(cfg, "select");
12
    struct event_base *base2 = event_base_new_with_config(cfg);
13
    event_config_free(cfg);
14

15
    printf("Using method: %s\n", event_base_get_method(base));
16

17
    event_base_free(base);
18
    event_base_free(base2);
19
    return 0;
20
}

展开收起

其他相关资料请移步到个人主页

📊 事件数量分析 - libevent源码深度解析系列（十七）

Sat, 11 Apr 2026 00:00:00 GMT

📊 事件数量分析#

一、概述#

libevent内部维护了事件数量的统计信息，这对于监控和调试非常有用。本文分析事件数量的含义和使用方法。

二、事件数量类型#

1
/* 事件数量类型 */
2
#define EVENT_BASE_COUNT_ACTIVE   0x01  // 活跃事件数量
3
#define EVENT_BASE_COUNT_VIRTUAL  0x02  // 虚拟事件数量
4
#define EVENT_BASE_COUNT_ADDED    0x04  // 已添加事件数量

2.1 各类型说明#

类型	说明
ACTIVE	当前处于活跃状态的事件数量，即已触发但尚未处理的事件
VIRTUAL	虚拟事件数量，用于内部机制（如定时器、信号等）
ADDED	已添加到event_base的事件总数

三、API#

3.1 获取事件数量#

1
/**
2
 * 获取事件数量
3
 * @param base  event_base
4
 * @param type  事件类型（EVENT_BASE_COUNT_*的组合）
5
 * @return 事件数量
6
 */
7
int event_base_get_num_events(struct event_base *base, unsigned int type);
8

9
/**
10
 * 获取最大事件数量
11
 * @param base  event_base
12
 * @param type  事件类型
13
 * @param clear 是否清除最大值
14
 * @return 最大事件数量
15
 */
16
int event_base_get_max_events(struct event_base *base, unsigned int type, int clear);

展开收起

四、event_base结构体中的计数器#

1
struct event_base {
2
    // ...
3
    int virtual_event_count;        // 虚拟事件计数
4
    int virtual_event_count_max;    // 虚拟事件最大计数
5

6
    int event_count;                // 事件总数
7
    int event_count_max;            // 事件最大总数
8

9
    int event_count_active;         // 活跃事件数
10
    int event_count_active_max;     // 活跃事件最大数
11
    // ...
12
};

五、事件计数更新时机#

5.1 事件添加时#

1
int event_add_nolock_(struct event *ev, const struct timeval *tv, int tv_is_absolute) {
2
    struct event_base *base = ev->ev_base;
3

4
    // 增加事件计数
5
    base->event_count++;
6
    if (base->event_count > base->event_count_max)
7
        base->event_count_max = base->event_count;
8

9
    // 如果是定时器，增加虚拟事件计数
10
    if (tv != NULL) {
11
        base->virtual_event_count++;
12
        if (base->virtual_event_count > base->virtual_event_count_max)
13
            base->virtual_event_count_max = base->virtual_event_count;
14
    }
15

16
    // ...
17
}

展开收起

5.2 事件删除时#

1
int event_del_nolock_(struct event *ev, int blocking) {
2
    struct event_base *base = ev->ev_base;
3

4
    // 减少事件计数
5
    base->event_count--;
6

7
    // 如果是定时器，减少虚拟事件计数
8
    if (ev->ev_flags & EVLIST_TIMEOUT) {
9
        base->virtual_event_count--;
10
    }
11

12
    // 如果在活跃队列中，减少活跃事件计数
13
    if (ev->ev_flags & EVLIST_ACTIVE) {
14
        base->event_count_active--;
15
    }
16

17
    // ...
18
}

展开收起

5.3 事件激活时#

1
void event_active_nolock_(struct event *ev, int res, short ncalls) {
2
    struct event_base *base = ev->ev_base;
3

4
    // 增加活跃事件计数
5
    base->event_count_active++;
6
    if (base->event_count_active > base->event_count_active_max)
7
        base->event_count_active_max = base->event_count_active;
8

9
    // ...
10
}

六、使用示例#

6.1 监控事件数量#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <unistd.h>
4
#include <event2/event.h>
5

6
static void print_event_stats(struct event_base *base) {
7
    int active = event_base_get_num_events(base, EVENT_BASE_COUNT_ACTIVE);
8
    int virtual = event_base_get_num_events(base, EVENT_BASE_COUNT_VIRTUAL);
9
    int added = event_base_get_num_events(base, EVENT_BASE_COUNT_ADDED);
10

11
    printf("Event Statistics:\n");
12
    printf("  Active events: %d\n", active);
13
    printf("  Virtual events: %d\n", virtual);
14
    printf("  Total added events: %d\n", added);
15
}
16

17
static void timer_cb(evutil_socket_t fd, short events, void *arg) {
18
    struct event_base *base = arg;
19
    static int count = 0;
20

21
    count++;
22
    printf("Timer %d fired\n", count);
23
    print_event_stats(base);
24

25
    if (count >= 5) {
26
        event_base_loopexit(base, NULL);
27
    }
28
}
29

30
int main() {
31
    struct event_base *base = event_base_new();
32

33
    printf("Initial state:\n");
34
    print_event_stats(base);
35

36
    // 创建多个定时器
37
    struct event *timers[3];
38
    for (int i = 0; i < 3; i++) {
39
        timers[i] = event_new(base, -1, EV_PERSIST, timer_cb, base);
40
        struct timeval tv = {i + 1, 0};
41
        event_add(timers[i], &tv);
42
    }
43

44
    printf("\nAfter adding timers:\n");
45
    print_event_stats(base);
46

47
    event_base_dispatch(base);
48

49
    printf("\nFinal state:\n");
50
    print_event_stats(base);
51

52
    for (int i = 0; i < 3; i++) {
53
        event_free(timers[i]);
54
    }
55
    event_base_free(base);
56

57
    return 0;
58
}

展开收起

6.2 性能监控#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <unistd.h>
4
#include <event2/event.h>
5

6
struct monitor_data {
7
    struct event_base *base;
8
    int check_interval;
9
};
10

11
static void monitor_cb(evutil_socket_t fd, short events, void *arg) {
12
    struct monitor_data *data = arg;
13

14
    int active = event_base_get_num_events(data->base, EVENT_BASE_COUNT_ACTIVE);
15
    int added = event_base_get_num_events(data->base, EVENT_BASE_COUNT_ADDED);
16
    int max_active = event_base_get_max_events(data->base, EVENT_BASE_COUNT_ACTIVE, 0);
17

18
    printf("[Monitor] Active: %d, Added: %d, Max Active: %d\n",
19
           active, added, max_active);
20
}
21

22
int main() {
23
    struct event_base *base = event_base_new();
24

25
    // 创建监控定时器
26
    struct monitor_data data = {base, 1};
27
    struct event *monitor = event_new(base, -1, EV_PERSIST, monitor_cb, &data);
28
    struct timeval tv = {1, 0};
29
    event_add(monitor, &tv);
30

31
    // 创建一些工作定时器
32
    for (int i = 0; i < 5; i++) {
33
        struct event *ev = event_new(base, -1, EV_PERSIST,
34
            [](evutil_socket_t fd, short events, void *arg) {}, NULL);
35
        struct timeval t = {0, (i + 1) * 200000};
36
        event_add(ev, &t);
37
    }
38

39
    // 运行10秒
40
    struct timeval exit_tv = {10, 0};
41
    event_base_loopexit(base, &exit_tv);
42

43
    event_base_dispatch(base);
44

45
    event_free(monitor);
46
    event_base_free(base);
47

48
    return 0;
49
}

展开收起

七、虚拟事件详解#

虚拟事件是libevent内部使用的事件，主要用于：

类型	说明
定时器	每个定时器都是一个虚拟事件
信号	信号处理使用虚拟事件
内部通知	线程间通信等内部机制

7.1 虚拟事件计数#

1
// 定时器添加时
2
event_count_added = 1
3
virtual_event_count = 1
4

5
// 定时器触发时
6
event_count_active = 1
7

8
// 定时器回调执行后（非EV_PERSIST）
9
event_count_added = 0
10
virtual_event_count = 0
11
event_count_active = 0

八、最佳实践#

建议	说明
定期监控	在生产环境中定期检查事件数量
设置阈值	设置合理的最大事件数阈值
资源预警	事件数量异常时发出警告
调试辅助	使用事件数量帮助调试内存泄漏

其他相关资料请移步到个人主页

🔄 事件触发流程 - libevent源码深度解析系列（十五）

Sat, 11 Apr 2026 00:00:00 GMT

🔄 事件触发流程#

一、概述#

本文详细分析libevent事件触发的内部流程，从事件添加到回调执行的完整链路。

二、事件触发流程图#

1
┌─────────────────────────────────────────────────────────────────────┐
2
│                        事件触发流程                                   │
3
├─────────────────────────────────────────────────────────────────────┤
4
│                                                                     │
5
│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐     │
6
│  │event_add │───>│epoll_ctl │───>│epoll_wait│───>│回调执行   │     │
7
│  └──────────┘    └──────────┘    └──────────┘    └──────────┘     │
8
│       │              │               │                │            │
9
│       ▼              ▼               ▼                ▼            │
10
│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐     │
11
│  │加入事件   │    │注册到内核 │    │等待事件   │    │处理事件   │     │
12
│  │队列       │    │           │    │就绪       │    │           │     │
13
│  └──────────┘    └──────────┘    └──────────┘    └──────────┘     │
14
│                                                                     │
15
└─────────────────────────────────────────────────────────────────────┘

展开收起

三、核心数据结构#

3.1 event_base结构体关键字段#

1
struct event_base {
2
    const struct eventop *evsel;    // I/O复用机制（epoll/select等）
3
    void *evbase;                   // I/O复用机制的数据
4

5
    struct event_io_map io;         // fd到event的映射
6
    struct event_signal_map sigmap; // 信号到event的映射
7

8
    struct min_heap timeheap;       // 定时器小根堆
9

10
    struct evcallback_list *activequeues;  // 活跃事件队列
11
    int nactivequeues;              // 活跃队列数量
12

13
    int event_count;                // 事件总数
14
    int event_count_active;         // 活跃事件数
15
    // ...
16
};

展开收起

3.2 eventop结构体#

1
struct eventop {
2
    const char *name;
3
    void *(*init)(struct event_base *);
4
    int (*add)(struct event_base *, evutil_socket_t fd, short old, short events, void *);
5
    int (*del)(struct event_base *, evutil_socket_t fd, short old, short events, void *);
6
    int (*dispatch)(struct event_base *, struct timeval *);
7
    void (*dealloc)(struct event_base *);
8
    int need_reinit;
9
    enum event_method_feature features;
10
    size_t fdinfo_len;
11
};

四、事件添加流程#

4.1 event_add函数#

1
int event_add(struct event *ev, const struct timeval *tv) {
2
    struct event_base *base = ev->ev_base;
3

4
    // 1. 如果有超时，添加到定时器堆
5
    if (tv != NULL && !(ev->ev_flags & EVLIST_TIMEOUT)) {
6
        if (min_heap_reserve(&base->timeheap, 1) == -1)
7
            return -1;
8
        min_heap_push(&base->timeheap, ev);
9
    }
10

11
    // 2. 如果是I/O事件，添加到I/O映射
12
    if ((ev->ev_events & (EV_READ | EV_WRITE)) &&
13
        !(ev->ev_flags & (EVLIST_INSERTED | EVLIST_ACTIVE))) {
14

15
        // 调用底层I/O复用机制的add函数
16
        if (base->evsel->add(base, ev->ev_fd,
17
            old, ev->ev_events, ev->ev_.ev_io.ev_timeout) == -1)
18
            return -1;
19

20
        ev->ev_flags |= EVLIST_INSERTED;
21
    }
22

23
    return 0;
24
}

展开收起

4.2 epoll_add函数#

1
static int epoll_add(struct event_base *base, int fd,
2
                     short old, short events, void *p) {
3
    struct epoll *epollop = base->evbase;
4
    struct epoll_event epev;
5

6
    memset(&epev, 0, sizeof(epev));
7
    epev.data.fd = fd;
8

9
    if (events & EV_READ)
10
        epev.events |= EPOLLIN;
11
    if (events & EV_WRITE)
12
        epev.events |= EPOLLOUT;
13

14
    int op = old ? EPOLL_CTL_MOD : EPOLL_CTL_ADD;
15

16
    if (epoll_ctl(epollop->epfd, op, fd, &epev) == -1) {
17
        return -1;
18
    }
19

20
    return 0;
21
}

展开收起

五、事件循环流程#

5.1 event_base_dispatch函数#

1
int event_base_dispatch(struct event_base *base) {
2
    return event_base_loop(base, 0);
3
}

5.2 event_base_loop函数#

1
int event_base_loop(struct event_base *base, int flags) {
2
    while (!done) {
3
        // 1. 计算超时时间
4
        timeout = get_timeout(base);
5

6
        // 2. 调用I/O复用机制等待事件
7
        res = base->evsel->dispatch(base, timeout);
8

9
        // 3. 处理定时器事件
10
        process_timers(base);
11

12
        // 4. 处理活跃事件
13
        process_active_events(base);
14

15
        if (flags & EVLOOP_ONCE)
16
            break;
17
    }
18

19
    return 0;
20
}

展开收起

5.3 epoll_dispatch函数#

1
static int epoll_dispatch(struct event_base *base, struct timeval *tv) {
2
    struct epoll *epollop = base->evbase;
3
    struct epoll_event events[32];
4
    int timeout = -1;
5

6
    // 计算超时时间（毫秒）
7
    if (tv != NULL) {
8
        timeout = tv->tv_sec * 1000 + tv->tv_usec / 1000;
9
    }
10

11
    // 调用epoll_wait
12
    int n = epoll_wait(epollop->epfd, events, 32, timeout);
13

14
    if (n > 0) {
15
        for (int i = 0; i < n; i++) {
16
            int fd = events[i].data.fd;
17
            short what = 0;
18

19
            if (events[i].events & EPOLLIN)
20
                what |= EV_READ;
21
            if (events[i].events & EPOLLOUT)
22
                what |= EV_WRITE;
23
            if (events[i].events & EPOLLERR)
24
                what |= EV_READ | EV_WRITE;
25

26
            // 将事件加入活跃队列
27
            event_active(evmap_io_get_event(base, fd), what, 1);
28
        }
29
    }
30

31
    return 0;
32
}

展开收起

六、事件激活流程#

6.1 event_active函数#

1
void event_active(struct event *ev, int what, short ncalls) {
2
    struct event_base *base = ev->ev_base;
3

4
    // 如果已经在活跃队列中，不重复添加
5
    if (ev->ev_flags & EVLIST_ACTIVE)
6
        return;
7

8
    // 设置活跃事件类型
9
    ev->ev_.ev_io.ev_res = what;
10

11
    // 加入活跃队列
12
    ev->ev_flags |= EVLIST_ACTIVE;
13
    TAILQ_INSERT_TAIL(&base->activequeues[ev->ev_pri],
14
                      ev->ev_.ev_io.ev_active_next);
15
}

展开收起

6.2 process_active_events函数#

1
static void process_active_events(struct event_base *base) {
2
    struct event *ev;
3

4
    // 按优先级处理活跃事件
5
    for (int i = 0; i < base->nactivequeues; i++) {
6
        while ((ev = TAILQ_FIRST(&base->activequeues[i])) != NULL) {
7
            // 从活跃队列移除
8
            TAILQ_REMOVE(&base->activequeues[i], ev, ev_.ev_io.ev_active_next);
9
            ev->ev_flags &= ~EVLIST_ACTIVE;
10

11
            // 执行回调
12
            if (ev->ev_events & EV_SIGNAL) {
13
                ev->ev_.ev_signal.ev_ncalls = ev->ev_.ev_signal.ev_pncalls;
14
                while (ev->ev_.ev_signal.ev_ncalls--) {
15
                    ev->ev_callback(ev->ev_fd, ev->ev_.ev_signal.ev_res, ev->ev_arg);
16
                }
17
            } else {
18
                ev->ev_callback(ev->ev_fd, ev->ev_.ev_io.ev_res, ev->ev_arg);
19
            }
20

21
            // 如果是持久事件，重新添加
22
            if (ev->ev_flags & EVLIST_INSERTED) {
23
                // 事件仍在插入状态，如果是EV_PERSIST，保持
24
            }
25
        }
26
    }
27
}

展开收起

七、完整流程图#

1
┌──────────────────────────────────────────────────────────────────────┐
2
│                          完整事件流程                                  │
3
├──────────────────────────────────────────────────────────────────────┤
4
│                                                                      │
5
│  1. 初始化阶段                                                        │
6
│     event_base_new()                                                 │
7
│         │                                                            │
8
│         ├── 选择I/O复用机制（epoll/select/poll等）                     │
9
│         └── 初始化数据结构                                            │
10
│                                                                      │
11
│  2. 事件注册阶段                                                      │
12
│     event_new() → event_add()                                        │
13
│         │                                                            │
14
│         ├── I/O事件 → evmap_io_add → epoll_ctl(EPOLL_CTL_ADD)        │
15
│         ├── 定时器 → min_heap_push                                   │
16
│         └── 信号 → evmap_signal_add                                  │
17
│                                                                      │
18
│  3. 事件循环阶段                                                      │
19
│     event_base_dispatch()                                            │
20
│         │                                                            │
21
│         ┌─────────────────────────────────────────┐                  │
22
│         │  while (!done) {                         │                  │
23
│         │      1. 计算超时时间                      │                  │
24
│         │      2. epoll_wait() 等待事件            │                  │
25
│         │      3. 处理定时器超时                   │                  │
26
│         │      4. 处理活跃事件                     │                  │
27
│         │  }                                      │                  │
28
│         └─────────────────────────────────────────┘                  │
29
│                                                                      │
30
│  4. 事件处理阶段                                                      │
31
│     process_active_events()                                          │
32
│         │                                                            │
33
│         ├── 按优先级遍历活跃队列                                       │
34
│         ├── 取出事件                                                  │
35
│         └── 执行回调函数                                              │
36
│                                                                      │
37
│  5. 清理阶段                                                          │
38
│     event_free() → event_base_free()                                 │
39
│                                                                      │
40
└──────────────────────────────────────────────────────────────────────┘

展开收起

八、性能优化点#

优化点	说明
epoll ET模式	使用边缘触发减少系统调用次数
changelist	批量处理事件修改，减少epoll_ctl调用
优先级队列	高优先级事件优先处理
时间缓存	避免频繁调用gettimeofday
最小堆	高效管理定时器

其他相关资料请移步到个人主页

🛠️ evutil工具函数 - libevent源码深度解析系列（二十）

Sat, 11 Apr 2026 00:00:00 GMT

🔧 evutil工具函数#

一、概述#

evutil 是libevent提供的跨平台工具函数库，封装了各种操作系统差异，提供统一的API。这些函数包括socket操作、地址处理、字符串处理、时间操作、随机数生成等。

二、Socket操作#

2.1 Socket创建与配置#

1
/* 创建socket */
2
evutil_socket_t evutil_socket_(int domain, int type, int protocol);
3

4
/* 创建socket pair */
5
int evutil_socketpair(int domain, int type, int protocol,
6
                      evutil_socket_t pair[2]);
7

8
/* 设置非阻塞 */
9
int evutil_make_socket_nonblocking(evutil_socket_t sock);
10

11
/* 设置关闭时执行 */
12
int evutil_make_socket_closeonexec(evutil_socket_t sock);
13

14
/* 关闭socket（跨平台） */
15
int evutil_closesocket(evutil_socket_t sock);
16

17
/* 获取socket错误码 */
18
int evutil_socket_geterror(evutil_socket_t sock);
19

20
/* 设置socket重用地址 */
21
int evutil_socket_connect_(evutil_socket_t *fd_ptr,
22
    const struct sockaddr *sa, int socklen);

展开收起

2.2 Socket操作示例#

1
#include <stdio.h>
2
#include <event2/util.h>
3

4
int main() {
5
    // 创建socket
6
    evutil_socket_t fd = evutil_socket_(AF_INET, SOCK_STREAM, 0);
7
    if (fd < 0) {
8
        perror("socket");
9
        return 1;
10
    }
11

12
    // 设置非阻塞
13
    if (evutil_make_socket_nonblocking(fd) < 0) {
14
        perror("nonblocking");
15
        evutil_closesocket(fd);
16
        return 1;
17
    }
18

19
    // 设置close-on-exec
20
    evutil_make_socket_closeonexec(fd);
21

22
    printf("Socket created and configured\n");
23

24
    evutil_closesocket(fd);
25
    return 0;
26
}

展开收起

2.3 Socket Pair示例#

1
#include <stdio.h>
2
#include <string.h>
3
#include <unistd.h>
4
#include <event2/util.h>
5

6
int main() {
7
    evutil_socket_t pair[2];
8

9
    // 创建socket pair
10
    if (evutil_socketpair(AF_UNIX, SOCK_STREAM, 0, pair) < 0) {
11
        perror("socketpair");
12
        return 1;
13
    }
14

15
    // 设置非阻塞
16
    evutil_make_socket_nonblocking(pair[0]);
17
    evutil_make_socket_nonblocking(pair[1]);
18

19
    // 写入数据
20
    const char *msg = "Hello from pair[0]";
21
    write(pair[0], msg, strlen(msg));
22

23
    // 读取数据
24
    char buf[64];
25
    ssize_t n = read(pair[1], buf, sizeof(buf) - 1);
26
    if (n > 0) {
27
        buf[n] = '\0';
28
        printf("Received: %s\n", buf);
29
    }
30

31
    evutil_closesocket(pair[0]);
32
    evutil_closesocket(pair[1]);
33

34
    return 0;
35
}

展开收起

三、地址操作#

3.1 地址解析#

1
/* 解析地址字符串
2
 * @param str      地址字符串，如 "192.168.1.1:8080" 或 "[::1]:8080"
3
 * @param out      输出sockaddr结构
4
 * @param outlen   输出长度
5
 * @return         0成功，-1失败
6
 */
7
int evutil_parse_sockaddr_port(const char *str, struct sockaddr *out,
8
                                int *outlen);
9

10
/* 比较两个地址 */
11
int evutil_sockaddr_cmp(const struct sockaddr *sa1, const struct sockaddr *sa2,
12
                        int include_port);
13

14
/* 获取地址字符串 */
15
const char *evutil_inet_ntop(int af, const void *src, char *dst, size_t size);
16

17
/* 解析地址字符串 */
18
int evutil_inet_pton(int af, const char *src, void *dst);

展开收起

3.2 地址操作示例#

1
#include <stdio.h>
2
#include <string.h>
3
#include <arpa/inet.h>
4
#include <event2/util.h>
5

6
int main() {
7
    struct sockaddr_in sin;
8
    int len = sizeof(sin);
9

10
    // 解析地址字符串
11
    if (evutil_parse_sockaddr_port("192.168.1.1:8080",
12
                                    (struct sockaddr *)&sin, &len) == 0) {
13
        char ip[INET_ADDRSTRLEN];
14
        evutil_inet_ntop(AF_INET, &sin.sin_addr, ip, sizeof(ip));
15
        printf("Parsed: %s:%d\n", ip, ntohs(sin.sin_port));
16
    }
17

18
    // 解析IPv6地址
19
    struct sockaddr_in6 sin6;
20
    len = sizeof(sin6);
21
    if (evutil_parse_sockaddr_port("[::1]:8080",
22
                                    (struct sockaddr *)&sin6, &len) == 0) {
23
        char ip[INET6_ADDRSTRLEN];
24
        evutil_inet_ntop(AF_INET6, &sin6.sin6_addr, ip, sizeof(ip));
25
        printf("Parsed IPv6: %s:%d\n", ip, ntohs(sin6.sin6_port));
26
    }
27

28
    // 比较地址
29
    struct sockaddr_in a1, a2;
30
    memset(&a1, 0, sizeof(a1));
31
    memset(&a2, 0, sizeof(a2));
32

33
    a1.sin_family = AF_INET;
34
    a1.sin_addr.s_addr = inet_addr("192.168.1.1");
35
    a1.sin_port = htons(80);
36

37
    a2.sin_family = AF_INET;
38
    a2.sin_addr.s_addr = inet_addr("192.168.1.1");
39
    a2.sin_port = htons(8080);
40

41
    int cmp = evutil_sockaddr_cmp((struct sockaddr *)&a1,
42
                                   (struct sockaddr *)&a2, 0);
43
    printf("Compare (ignore port): %s\n", cmp == 0 ? "equal" : "different");
44

45
    cmp = evutil_sockaddr_cmp((struct sockaddr *)&a1,
46
                               (struct sockaddr *)&a2, 1);
47
    printf("Compare (with port): %s\n", cmp == 0 ? "equal" : "different");
48

49
    return 0;
50
}

展开收起

四、字符串处理#

4.1 字符串API#

1
/* 字符串转长整型 */
2
ev_int64_t evutil_strtoll(const char *s, char **endptr, int base);
3

4
/* 安全的snprintf */
5
int evutil_snprintf(char *buf, size_t buflen, const char *format, ...);
6

7
/* 安全的vsnprintf */
8
int evutil_vsnprintf(char *buf, size_t buflen, const char *format, va_list ap);
9

10
/* 不区分大小写的字符串比较 */
11
int evutil_ascii_strcasecmp(const char *str1, const char *str2);
12
int evutil_ascii_strncasecmp(const char *str1, const char *str2, size_t n);
13

14
/* 字符串转小写 */
15
char *evutil_ascii_strtolower(char *str);
16

17
/* 字符串复制（跨平台） */
18
char *evutil_strtoll(const char *s, char **endptr, int base);

展开收起

4.2 字符串示例#

1
#include <stdio.h>
2
#include <event2/util.h>
3

4
int main() {
5
    // 字符串转数字
6
    const char *num_str = "12345abc";
7
    char *end;
8
    ev_int64_t num = evutil_strtoll(num_str, &end, 10);
9
    printf("Parsed: %lld, remaining: %s\n", num, end);
10

11
    // 安全格式化
12
    char buf[32];
13
    evutil_snprintf(buf, sizeof(buf), "Value: %d, String: %s", 42, "test");
14
    printf("%s\n", buf);
15

16
    // 不区分大小写比较
17
    const char *s1 = "Hello";
18
    const char *s2 = "HELLO";
19
    int cmp = evutil_ascii_strcasecmp(s1, s2);
20
    printf("Compare '%s' and '%s': %s\n", s1, s2, cmp == 0 ? "equal" : "different");
21

22
    // 转小写
23
    char str[] = "HELLO WORLD";
24
    evutil_ascii_strtolower(str);
25
    printf("Lowercase: %s\n", str);
26

27
    return 0;
28
}

展开收起

五、时间操作#

5.1 时间API#

1
/* 获取当前时间 */
2
int evutil_gettimeofday(struct timeval *tv, struct timezone *tz);
3

4
/* 清零时间 */
5
#define evutil_timerclear(tvp)      ((tvp)->tv_sec = (tvp)->tv_usec = 0)
6

7
/* 检查时间是否为0 */
8
int evutil_timerisset(const struct timeval *tvp);
9

10
/* 比较时间 */
11
#define evutil_timercmp(tvp, uvp, cmp)                     \
12
    (((tvp)->tv_sec == (uvp)->tv_sec) ?                    \
13
     ((tvp)->tv_usec cmp (uvp)->tv_usec) :                 \
14
     ((tvp)->tv_sec cmp (uvp)->tv_sec))
15

16
/* 时间加法 */
17
void evutil_timeradd(const struct timeval *a, const struct timeval *b,
18
                     struct timeval *res);
19

20
/* 时间减法 */
21
void evutil_timersub(const struct timeval *a, const struct timeval *b,
22
                     struct timeval *res);
23

24
/* 计算时间差（毫秒） */
25
ev_int64_t evutil_tv_to_msec(const struct timeval *tv);
26

27
/* 毫秒转时间 */
28
void evutil_msec_to_tv(ev_int64_t msec, struct timeval *tv);

展开收起

5.2 时间示例#

1
#include <stdio.h>
2
#include <event2/util.h>
3

4
int main() {
5
    struct timeval tv1, tv2, result;
6

7
    // 获取当前时间
8
    evutil_gettimeofday(&tv1, NULL);
9
    printf("Current time: %ld.%06ld\n", tv1.tv_sec, tv1.tv_usec);
10

11
    // 时间加法
12
    struct timeval delay = {2, 500000};  // 2.5秒
13
    evutil_timeradd(&tv1, &delay, &result);
14
    printf("After 2.5s: %ld.%06ld\n", result.tv_sec, result.tv_usec);
15

16
    // 时间比较
17
    evutil_gettimeofday(&tv2, NULL);
18
    if (evutil_timercmp(&tv2, &tv1, >)) {
19
        printf("tv2 > tv1\n");
20
    }
21

22
    // 时间差
23
    evutil_timersub(&tv2, &tv1, &result);
24
    printf("Time elapsed: %ld.%06ld seconds\n", result.tv_sec, result.tv_usec);
25

26
    // 转换为毫秒
27
    ev_int64_t msec = evutil_tv_to_msec(&result);
28
    printf("Time elapsed: %lld ms\n", msec);
29

30
    return 0;
31
}

展开收起

六、随机数#

6.1 随机数API#

1
/* 初始化安全随机数生成器 */
2
int evutil_secure_rng_init(void);
3

4
/* 设置随机数设备文件 */
5
int evutil_secure_rng_set_urandom_device_file(char *fname);
6

7
/* 获取安全随机字节 */
8
void evutil_secure_rng_get_bytes(void *buf, size_t n);
9

10
/* 检查是否支持安全随机数 */
11
int evutil_secure_rng_global_setup_locks_(int enable_locks);

6.2 随机数示例#

1
#include <stdio.h>
2
#include <event2/util.h>
3

4
int main() {
5
    // 初始化安全随机数
6
    if (evutil_secure_rng_init() < 0) {
7
        fprintf(stderr, "Failed to initialize secure RNG\n");
8
        return 1;
9
    }
10

11
    // 生成随机数
12
    unsigned char bytes[16];
13
    evutil_secure_rng_get_bytes(bytes, sizeof(bytes));
14

15
    printf("Random bytes: ");
16
    for (int i = 0; i < sizeof(bytes); i++) {
17
        printf("%02x", bytes[i]);
18
    }
19
    printf("\n");
20

21
    // 生成随机整数
22
    unsigned int random_int;
23
    evutil_secure_rng_get_bytes(&random_int, sizeof(random_int));
24
    printf("Random int: %u\n", random_int);
25

26
    return 0;
27
}

展开收起

七、错误处理#

7.1 错误API#

1
/* 获取最后错误码 */
2
#define evutil_socket_geterror(sock) ...
3

4
/* 获取错误字符串 */
5
const char *evutil_socket_error_to_string(int err);
6

7
/* 设置错误码 */
8
#define evutil_socket_seterror(err) ...
9

10
/* 错误码定义 */
11
#define EVUTIL_SOCKET_ERROR()    errno
12
#define EVUTIL_SET_SOCKET_ERROR(err) (errno = (err))

7.2 错误处理示例#

1
#include <stdio.h>
2
#include <event2/util.h>
3

4
int main() {
5
    evutil_socket_t fd = evutil_socket_(AF_INET, SOCK_STREAM, 0);
6

7
    if (fd < 0) {
8
        int err = EVUTIL_SOCKET_ERROR();
9
        printf("Socket error: %s\n", evutil_socket_error_to_string(err));
10
        return 1;
11
    }
12

13
    // 尝试连接一个无效地址
14
    struct sockaddr_in sin;
15
    sin.sin_family = AF_INET;
16
    sin.sin_port = htons(12345);
17
    sin.sin_addr.s_addr = inet_addr("0.0.0.0");
18

19
    if (connect(fd, (struct sockaddr *)&sin, sizeof(sin)) < 0) {
20
        int err = evutil_socket_geterror(fd);
21
        printf("Connect error (%d): %s\n", err, evutil_socket_error_to_string(err));
22
    }
23

24
    evutil_closesocket(fd);
25
    return 0;
26
}

展开收起

八、内存操作#

8.1 内存API#

1
/* 内存对齐分配 */
2
void *evutil_memalign_(size_t alignment, size_t size);
3

4
/* 内存比较（恒定时间） */
5
int evutil_memcmp_(const void *a, const void *b, size_t len);
6

7
/* 安全内存清零 */
8
void evutil_memclear_(void *mem, size_t len);

九、文件描述符操作#

9.1 文件描述符API#

1
/* 设置FD_CLOEXEC */
2
int evutil_make_fd_closeonexec(evutil_socket_t fd);
3

4
/* 复制文件描述符 */
5
evutil_socket_t evutil_dupfd_(evutil_socket_t fd);
6

7
/* 设置文件描述符标志 */
8
int evutil_fd_flag_set(evutil_socket_t fd, int flag, int on);

十、网络相关常量#

10.1 常用宏定义#

1
/* 地址族 */
2
#ifndef AF_INET6
3
#define AF_INET6 10
4
#endif
5

6
/* socket类型 */
7
#ifndef SOCK_NONBLOCK
8
#define SOCK_NONBLOCK 0
9
#endif
10

11
#ifndef SOCK_CLOEXEC
12
#define SOCK_CLOEXEC 0
13
#endif
14

15
/* 错误码 */
16
#ifndef EWOULDBLOCK
17
#define EWOULDBLOCK EAGAIN
18
#endif
19

20
#ifndef EINPROGRESS
21
#define EINPROGRESS WSAEINPROGRESS
22
#endif

展开收起

十一、跨平台宏#

11.1 平台检测#

1
#ifdef _WIN32
2
    // Windows平台
3
    #define EVUTIL_SOCKET_IS_INVALID(s) ((s) == INVALID_SOCKET)
4
    #define EVUTIL_SOCKET_ERROR() WSAGetLastError()
5
#else
6
    // Unix/Linux平台
7
    #define EVUTIL_SOCKET_IS_INVALID(s) ((s) < 0)
8
    #define EVUTIL_SOCKET_ERROR() (errno)
9
#endif

十二、完整示例：跨平台TCP客户端#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <event2/util.h>
5
#include <event2/event.h>
6
#include <event2/bufferevent.h>
7

8
#define SERVER_IP "127.0.0.1"
9
#define SERVER_PORT 8080
10

11
static void read_cb(struct bufferevent *bev, void *arg) {
12
    char buf[1024];
13
    size_t n;
14
    while ((n = bufferevent_read(bev, buf, sizeof(buf) - 1)) > 0) {
15
        buf[n] = '\0';
16
        printf("Received: %s", buf);
17
    }
18
}
19

20
static void event_cb(struct bufferevent *bev, short events, void *arg) {
21
    if (events & BEV_EVENT_CONNECTED) {
22
        printf("Connected to server\n");
23
        bufferevent_write(bev, "Hello, Server!\n", 15);
24
    } else if (events & (BEV_EVENT_EOF | BEV_EVENT_ERROR)) {
25
        if (events & BEV_EVENT_ERROR) {
26
            int err = evutil_socket_geterror(bufferevent_getfd(bev));
27
            printf("Error: %s\n", evutil_socket_error_to_string(err));
28
        }
29
        bufferevent_free(bev);
30
        event_base_loopexit((struct event_base *)arg, NULL);
31
    }
32
}
33

34
int main() {
35
    struct event_base *base = event_base_new();
36
    struct bufferevent *bev = bufferevent_socket_new(base, -1, BEV_OPT_CLOSE_ON_FREE);
37

38
    // 使用evutil解析地址
39
    struct sockaddr_storage ss;
40
    int ss_len = sizeof(ss);
41
    char addr_str[64];
42
    evutil_snprintf(addr_str, sizeof(addr_str), "%s:%d", SERVER_IP, SERVER_PORT);
43

44
    if (evutil_parse_sockaddr_port(addr_str, (struct sockaddr *)&ss, &ss_len) < 0) {
45
        fprintf(stderr, "Invalid address: %s\n", addr_str);
46
        return 1;
47
    }
48

49
    printf("Connecting to %s...\n", addr_str);
50

51
    bufferevent_setcb(bev, read_cb, NULL, event_cb, base);
52
    bufferevent_enable(bev, EV_READ | EV_WRITE);
53

54
    if (bufferevent_socket_connect(bev, (struct sockaddr *)&ss, ss_len) < 0) {
55
        int err = evutil_socket_geterror(bufferevent_getfd(bev));
56
        printf("Connect failed: %s\n", evutil_socket_error_to_string(err));
57
        bufferevent_free(bev);
58
        event_base_free(base);
59
        return 1;
60
    }
61

62
    event_base_dispatch(base);
63

64
    event_base_free(base);
65
    return 0;
66
}

展开收起

十三、工具函数速查表#

类别	函数	说明
Socket	`evutil_socket_`	创建socket
	`evutil_socketpair`	创建socket pair
	`evutil_make_socket_nonblocking`	设置非阻塞
	`evutil_closesocket`	关闭socket
地址	`evutil_parse_sockaddr_port`	解析地址
	`evutil_sockaddr_cmp`	比较地址
	`evutil_inet_ntop`	地址转字符串
	`evutil_inet_pton`	字符串转地址
字符串	`evutil_snprintf`	安全格式化
	`evutil_strtoll`	字符串转数字
	`evutil_ascii_strcasecmp`	不区分大小写比较
时间	`evutil_gettimeofday`	获取时间
	`evutil_timeradd`	时间加法
	`evutil_timersub`	时间减法
	`evutil_timercmp`	时间比较
随机数	`evutil_secure_rng_init`	初始化随机数
	`evutil_secure_rng_get_bytes`	获取随机字节
错误	`evutil_socket_geterror`	获取错误码
	`evutil_socket_error_to_string`	错误码转字符串

其他相关资料请移步到个人主页

❓ 常见问题FAQ - libevent源码深度解析系列（二十六）

Sat, 11 Apr 2026 00:00:00 GMT

❓ 常见问题FAQ#

一、编译与安装问题#

Q1: 找不到libevent头文件#

问题现象：

1
fatal error: event2/event.h: No such file or directory

解决方案：

Terminal window

1
# Ubuntu/Debian
2
sudo apt-get install libevent-dev
3

4
# CentOS/RHEL
5
sudo yum install libevent-devel
6

7
# macOS
8
brew install libevent
9

10
# 编译时指定路径
11
gcc -I/usr/local/include -L/usr/local/lib -levent main.c

Q2: 链接时找不到libevent库#

问题现象：

1
undefined reference to `event_base_new'

解决方案：

Terminal window

1
# 编译时添加 -levent
2
gcc main.c -levent
3

4
# 或使用 pkg-config
5
gcc main.c $(pkg-config --libs libevent)
6

7
# 动态库路径问题
8
export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
9

10
# 或添加到 /etc/ld.so.conf.d/
11
echo "/usr/local/lib" | sudo tee /etc/ld.so.conf.d/libevent.conf
12
sudo ldconfig

Q3: OpenSSL支持未编译#

问题现象：

1
bufferevent_openssl_socket_new: undefined reference

解决方案：

Terminal window

1
# 重新编译libevent时启用OpenSSL
2
./configure --enable-openssl
3
make && sudo make install
4

5
# 编译时同时链接OpenSSL
6
gcc main.c -levent -lssl -lcrypto

二、事件循环问题#

Q4: event_base_dispatch不返回#

问题现象： 程序卡在event_base_dispatch()无法退出。

解决方案：

1
// 方案1: 使用 event_base_loopbreak
2
event_base_loopbreak(base);
3

4
// 方案2: 使用 event_base_loopexit
5
struct timeval tv = {0, 0};
6
event_base_loopexit(base, &tv);
7

8
// 方案3: 使用非阻塞循环
9
while (running) {
10
    event_base_loop(base, EVLOOP_NONBLOCK);
11
    // 执行其他任务
12
}
13

14
// 方案4: 通过信号触发退出
15
void signal_handler(int sig) {
16
    event_base_loopbreak(base);
17
}
18
signal(SIGINT, signal_handler);

展开收起

Q5: 定时器不准确#

问题现象： 定时器触发时间与预期不符。

解决方案：

1
// 方案1: 使用 EV_PERSIST 持续定时
2
struct event *timer = event_new(base, -1, EV_PERSIST, timer_cb, NULL);
3
struct timeval tv = {1, 0};  // 1秒
4
event_add(timer, &tv);
5

6
// 方案2: 每次重新添加（更精确）
7
static void timer_cb(evutil_socket_t fd, short events, void *arg) {
8
    struct event *timer = arg;
9
    // 处理...
10

11
    // 重新添加
12
    struct timeval tv = {1, 0};
13
    event_add(timer, &tv);
14
}
15

16
// 方案3: 禁用时间缓存
17
struct event_config *cfg = event_config_new();
18
event_config_set_flag(cfg, EVENT_BASE_FLAG_NO_CACHE_TIME);
19
struct event_base *base = event_base_new_with_config(cfg);

展开收起

Q6: 事件丢失#

问题现象： 某些事件没有被触发。

解决方案：

1
// 检查事件是否活跃
2
if (!event_pending(ev, EV_READ, NULL)) {
3
    event_add(ev, NULL);
4
}
5

6
// 确保事件已启用
7
event_add(ev, NULL);
8

9
// 检查是否被删除
10
if (event_get_events(ev) == 0) {
11
    printf("Event is not active\n");
12
}

三、bufferevent问题#

Q7: 数据读取不完整#

问题现象： 读取的数据比预期少。

解决方案：

1
static void read_cb(struct bufferevent *bev, void *arg) {
2
    struct evbuffer *input = bufferevent_get_input(bev);
3

4
    // 方案1: 循环读取直到缓冲区空
5
    char buf[1024];
6
    size_t n;
7
    while ((n = bufferevent_read(bev, buf, sizeof(buf))) > 0) {
8
        process_data(buf, n);
9
    }
10

11
    // 方案2: 检查缓冲区长度
12
    size_t total = evbuffer_get_length(input);
13
    if (total < EXPECTED_SIZE) {
14
        return;  // 等待更多数据
15
    }
16

17
    // 方案3: 使用水位控制
18
    bufferevent_setwatermark(bev, EV_READ, EXPECTED_SIZE, 0);
19
}

展开收起

Q8: 写入数据丢失#

问题现象： 写入的数据对方没有收到。

解决方案：

1
// 方案1: 检查写入结果
2
int ret = bufferevent_write(bev, data, len);
3
if (ret < 0) {
4
    perror("bufferevent_write failed");
5
}
6

7
// 方案2: 使用写回调确认
8
static void write_cb(struct bufferevent *bev, void *arg) {
9
    printf("Data written successfully\n");
10
}
11

12
bufferevent_setcb(bev, read_cb, write_cb, event_cb, NULL);
13

14
// 方案3: 检查输出缓冲区
15
struct evbuffer *output = bufferevent_get_output(bev);
16
if (evbuffer_get_length(output) > MAX_BUFFER) {
17
    printf("Output buffer full, pausing\n");
18
    bufferevent_disable(bev, EV_WRITE);
19
}

展开收起

Q9: 连接超时处理#

问题现象： 连接长时间没有响应。

解决方案：

1
// 设置连接超时
2
struct timeval tv = {10, 0};  // 10秒
3
bufferevent_set_timeouts(bev, &tv, &tv);
4

5
static void event_cb(struct bufferevent *bev, short events, void *arg) {
6
    if (events & BEV_EVENT_TIMEOUT) {
7
        printf("Connection timeout\n");
8
        bufferevent_free(bev);
9
    } else if (events & BEV_EVENT_CONNECTED) {
10
        printf("Connected\n");
11
    } else if (events & (BEV_EVENT_EOF | BEV_EVENT_ERROR)) {
12
        printf("Connection closed/error\n");
13
        bufferevent_free(bev);
14
    }
15
}

展开收起

Q10: 内存泄漏#

问题现象： 程序内存持续增长。

解决方案：

1
// 1. 确保释放所有资源
2
void cleanup_connection(struct bufferevent *bev) {
3
    // 先禁用事件
4
    bufferevent_disable(bev, EV_READ | EV_WRITE);
5

6
    // 清空缓冲区
7
    struct evbuffer *input = bufferevent_get_input(bev);
8
    struct evbuffer *output = bufferevent_get_output(bev);
9
    evbuffer_drain(input, evbuffer_get_length(input));
10
    evbuffer_drain(output, evbuffer_get_length(output));
11

12
    // 释放bufferevent
13
    bufferevent_free(bev);
14
}
15

16
// 2. 使用 valgrind 检测
17
// valgrind --leak-check=full ./your_program
18

19
// 3. 检查回调是否正确设置
20
bufferevent_setcb(bev, read_cb, NULL, event_cb, arg);
21

22
// 4. 确保用户数据正确释放
23
typedef struct {
24
    char *buffer;
25
    size_t len;
26
} user_data_t;
27

28
static void event_cb(struct bufferevent *bev, short events, void *arg) {
29
    user_data_t *data = arg;
30
    free(data->buffer);
31
    free(data);
32
    bufferevent_free(bev);
33
}

展开收起

四、多线程问题#

Q11: 多线程崩溃#

问题现象： 多线程环境下程序崩溃。

解决方案：

1
// 1. 初始化线程支持
2
#include <event2/thread.h>
3

4
#ifdef _WIN32
5
    evthread_use_windows_threads();
6
#else
7
    evthread_use_pthreads();
8
#endif
9

10
// 2. 创建线程安全的event_base
11
struct event_config *cfg = event_config_new();
12
event_config_set_flag(cfg, 0);  // 不使用NOLOCK
13
struct event_base *base = event_base_new_with_config(cfg);
14

15
// 3. 使用锁保护共享资源
16
static pthread_mutex_t g_mutex = PTHREAD_MUTEX_INITIALIZER;
17

18
void thread_safe_operation(void) {
19
    pthread_mutex_lock(&g_mutex);
20
    // 操作共享资源
21
    pthread_mutex_unlock(&g_mutex);
22
}
23

24
// 4. 跨线程操作
25
void notify_main_thread(struct event_base *base) {
26
    event_base_loopbreak(base);  // 线程安全
27
}

展开收起

Q12: 跨线程事件触发#

问题现象： 需要从其他线程触发事件。

解决方案：

1
#include <event2/event.h>
2
#include <event2/thread.h>
3

4
// 方案1: 使用 event_active
5
static struct event *g_event = NULL;
6

7
void trigger_from_other_thread(void) {
8
    event_active(g_event, EV_READ, 0);  // 线程安全
9
}
10

11
// 方案2: 使用 self-pipe
12
int notify_pipe[2];
13

14
void setup_notify(struct event_base *base) {
15
    evutil_socketpair(AF_UNIX, SOCK_STREAM, 0, notify_pipe);
16

17
    struct event *ev = event_new(base, notify_pipe[0],
18
                                  EV_READ | EV_PERSIST, notify_cb, NULL);
19
    event_add(ev, NULL);
20
}
21

22
void notify_from_thread(void) {
23
    write(notify_pipe[1], "x", 1);
24
}
25

26
// 方案3: 使用 event_base_once
27
void thread_safe_callback(evutil_socket_t fd, short events, void *arg) {
28
    // 在主线程执行
29
}
30

31
void schedule_on_main_thread(struct event_base *base) {
32
    event_base_once(base, -1, EV_TIMEOUT, thread_safe_callback, NULL, NULL);
33
}

展开收起

五、网络问题#

Q13: 连接被拒绝#

问题现象：

1
Connection refused

解决方案：

1
static void event_cb(struct bufferevent *bev, short events, void *arg) {
2
    if (events & BEV_EVENT_ERROR) {
3
        int err = evutil_socket_geterror(bufferevent_getfd(bev));
4

5
        if (err == ECONNREFUSED) {
6
            printf("Connection refused, retrying...\n");
7
            // 重试逻辑
8
        } else if (err == ETIMEDOUT) {
9
            printf("Connection timeout\n");
10
        } else {
11
            printf("Connection error: %s\n",
12
                   evutil_socket_error_to_string(err));
13
        }
14
    }
15
}
16

17
// 检查服务器是否监听
18
// netstat -tlnp | grep <port>
19
// lsof -i :<port>

展开收起

Q14: 端口被占用#

问题现象：

1
Address already in use

解决方案：

1
// 方案1: 设置 SO_REUSEADDR
2
int reuse = 1;
3
setsockopt(fd, SOL_SOCKET, SO_REUSEADDR, &reuse, sizeof(reuse));
4

5
// 方案2: 使用 evconnlistener 的 REUSEABLE 标志
6
struct evconnlistener *listener = evconnlistener_new_bind(
7
    base, accept_cb, arg,
8
    LEV_OPT_CLOSE_ON_FREE | LEV_OPT_REUSEABLE,
9
    -1, (struct sockaddr *)&sin, sizeof(sin));
10

11
// 方案3: 查找占用进程
12
// lsof -i :<port>
13
// kill <pid>

Q15: DNS解析失败#

问题现象： DNS查询返回错误。

解决方案：

1
static void dns_cb(int result, char type, int count, int ttl,
2
                   void *addresses, void *arg) {
3
    if (result == DNS_ERR_NONE) {
4
        // 成功
5
    } else {
6
        printf("DNS error: %s\n", evdns_err_to_string(result));
7

8
        // 常见错误处理
9
        switch (result) {
10
            case DNS_ERR_TIMEOUT:
11
                printf("DNS timeout, retrying...\n");
12
                break;
13
            case DNS_ERR_NOTEXIST:
14
                printf("Domain does not exist\n");
15
                break;
16
            case DNS_ERR_SERVERFAILED:
17
                printf("DNS server failed\n");
18
                break;
19
        }
20
    }
21
}
22

23
// 配置多个DNS服务器
24
evdns_base_nameserver_ip_add(dns_base, "8.8.8.8");
25
evdns_base_nameserver_ip_add(dns_base, "1.1.1.1");
26

27
// 设置超时
28
evdns_base_set_option(dns_base, "timeout", "5");

展开收起

六、SSL/TLS问题#

Q16: SSL握手失败#

问题现象：

1
SSL handshake failed

解决方案：

1
static void event_cb(struct bufferevent *bev, short events, void *arg) {
2
    if (events & BEV_EVENT_ERROR) {
3
        unsigned long err;
4
        while ((err = bufferevent_get_openssl_error(bev))) {
5
            char msg[256];
6
            ERR_error_string_n(err, msg, sizeof(msg));
7
            fprintf(stderr, "SSL error: %s\n", msg);
8
        }
9
    }
10
}
11

12
// 常见原因及解决
13
// 1. 证书问题
14
SSL_CTX_load_verify_locations(ctx, "ca.crt", NULL);
15

16
// 2. 协议版本不匹配
17
SSL_CTX_set_min_proto_version(ctx, TLS1_2_VERSION);
18

19
// 3. 密码套件不支持
20
SSL_CTX_set_cipher_list(ctx, "HIGH:!aNULL:!MD5");
21

22
// 4. SNI未设置
23
SSL_set_tlsext_host_name(ssl, hostname);

展开收起

Q17: 证书验证失败#

问题现象：

1
certificate verify failed

解决方案：

1
// 1. 加载正确的CA证书
2
SSL_CTX_load_verify_locations(ctx, "/path/to/ca-bundle.crt", NULL);
3

4
// 2. 使用系统CA证书
5
SSL_CTX_set_default_verify_paths(ctx);
6

7
// 3. 设置验证模式
8
SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER, NULL);
9

10
// 4. 设置主机名验证
11
SSL_set1_host(ssl, "example.com");
12

13
// 5. 调试证书信息
14
void print_cert_info(SSL *ssl) {
15
    X509 *cert = SSL_get_peer_certificate(ssl);
16
    if (cert) {
17
        char *subject = X509_NAME_oneline(X509_get_subject_name(cert), NULL, 0);
18
        char *issuer = X509_NAME_oneline(X509_get_issuer_name(cert), NULL, 0);
19
        printf("Subject: %s\n", subject);
20
        printf("Issuer: %s\n", issuer);
21
        OPENSSL_free(subject);
22
        OPENSSL_free(issuer);
23
        X509_free(cert);
24
    }
25
}

展开收起

七、性能问题#

Q18: CPU占用过高#

问题现象： 程序CPU使用率接近100%。

解决方案：

1
// 1. 检查是否有空循环
2
while (running) {
3
    // 错误: 使用 EVLOOP_ONCE 而不是 EVLOOP_NONBLOCK
4
    event_base_loop(base, EVLOOP_ONCE);  // 阻塞等待事件
5
}
6

7
// 2. 减少不必要的回调
8
bufferevent_setwatermark(bev, EV_READ, 1024, 0);  // 积累到1KB再触发
9

10
// 3. 使用 EV_PERSIST 避免重复添加
11
struct event *ev = event_new(base, fd, EV_READ | EV_PERSIST, cb, arg);
12

13
// 4. 检查是否有大量短连接
14
// 考虑使用连接池

Q19: 内存占用过高#

问题现象： 程序内存持续增长。

解决方案：

1
// 1. 限制缓冲区大小
2
bufferevent_setwatermark(bev, EV_READ, 0, 1024 * 1024);  // 最大1MB
3

4
// 2. 及时清理缓冲区
5
evbuffer_drain(evbuffer, evbuffer_get_length(evbuffer));
6

7
// 3. 限制连接数
8
if (g_connection_count >= MAX_CONNECTIONS) {
9
    evutil_closesocket(fd);
10
    return;
11
}
12

13
// 4. 使用内存池
14
// 参见性能调优章节
15

16
// 5. 检查内存泄漏
17
// valgrind --leak-check=full ./your_program

展开收起

Q20: 响应延迟高#

问题现象： 请求处理延迟高。

解决方案：

1
// 1. 减少回调中的处理时间
2
static void read_cb(struct bufferevent *bev, void *arg) {
3
    // 将耗时操作放到线程池
4
    dispatch_to_thread_pool(process_data, bev);
5
}
6

7
// 2. 使用边缘触发（注意数据完整性）
8
// libevent默认使用水平触发
9

10
// 3. 批量处理
11
if (evbuffer_get_length(input) < BATCH_SIZE) {
12
    return;  // 等待更多数据
13
}
14

15
// 4. 优化DNS
16
// 使用DNS缓存
17

18
// 5. 检查网络延迟
19
// ping, traceroute

展开收起

八、调试技巧#

D1: 启用详细日志#

1
#include <event2/event.h>
2

3
void enable_debug_logging(void) {
4
    event_enable_debug_mode();
5
    event_set_log_callback(log_callback);
6
}
7

8
static void log_callback(int severity, const char *msg) {
9
    const char *level;
10
    switch (severity) {
11
        case EVENT_LOG_DEBUG: level = "DEBUG"; break;
12
        case EVENT_LOG_MSG:   level = "MSG";   break;
13
        case EVENT_LOG_WARN:  level = "WARN";  break;
14
        case EVENT_LOG_ERR:   level = "ERR";   break;
15
        default:              level = "???";   break;
16
    }
17
    fprintf(stderr, "[%s] %s\n", level, msg);
18
}

展开收起

D2: 使用GDB调试#

Terminal window

1
# 编译时添加调试符号
2
gcc -g -O0 main.c -levent
3

4
# 启动GDB
5
gdb ./your_program
6

7
# 常用命令 break event_base_dispatch
8
(gdb) break bufferevent_read
9
(gdb) run
10
(gdb) bt
11
(gdb) info threads
12
(gdb) thread apply all bt

D3: 检查事件状态#

1
void print_event_status(struct event *ev) {
2
    printf("Event fd: %d\n", event_get_fd(ev));
3
    printf("Event events: %d\n", event_get_events(ev));
4
    printf("Event pending: %d\n", event_pending(ev, EV_READ | EV_WRITE | EV_TIMEOUT, NULL));
5
    printf("Event base: %p\n", event_get_base(ev));
6
}
7

8
void print_bufferevent_status(struct bufferevent *bev) {
9
    printf("BufferEvent fd: %d\n", bufferevent_getfd(bev));
10
    printf("Input buffer: %zu bytes\n",
11
           evbuffer_get_length(bufferevent_get_input(bev)));
12
    printf("Output buffer: %zu bytes\n",
13
           evbuffer_get_length(bufferevent_get_output(bev)));
14
    printf("Enabled: %d\n", bufferevent_get_enabled(bev));
15
}

展开收起

其他相关资料请移步到个人主页

🌐 HTTP客户端 - libevent源码深度解析系列（二十一）

Sat, 11 Apr 2026 00:00:00 GMT

🌐 HTTP客户端#

一、概述#

libevent不仅支持HTTP服务器，还提供了完整的HTTP客户端功能。通过evhttp模块，可以方便地发送HTTP请求、处理响应，支持GET、POST等常见HTTP方法。

二、HTTP连接对象#

2.1 创建连接#

1
/* 创建HTTP连接对象
2
 * @param base      event_base
3
 * @param dns_base  DNS解析器，NULL表示阻塞解析
4
 * @param address   服务器地址
5
 * @param port      服务器端口
6
 */
7
struct evhttp_connection *evhttp_connection_base_new(
8
    struct event_base *base, struct evdns_base *dns_base,
9
    const char *address, ev_uint16_t port);
10

11
/* 创建HTTP连接对象（带地址族） */
12
struct evhttp_connection *evhttp_connection_base_bufferevent_new(
13
    struct event_base *base, struct evdns_base *dns_base,
14
    struct bufferevent *bev, const char *address, ev_uint16_t port);
15

16
/* 释放HTTP连接 */
17
void evhttp_connection_free(struct evhttp_connection *evcon);
18

19
/* 设置连接超时 */
20
void evhttp_connection_set_timeout(struct evhttp_connection *evcon, int timeout);
21
void evhttp_connection_set_timeout_tv(struct evhttp_connection *evcon,
22
    const struct timeval *tv);
23

24
/* 设置重试次数 */
25
void evhttp_connection_set_retries(struct evhttp_connection *evcon, int retry_max);
26

27
/* 设置最大连接数 */
28
void evhttp_connection_set_max_body_size(struct evhttp_connection *evcon,
29
    ev_ssize_t max_body_size);

展开收起

2.2 连接示例#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <event2/event.h>
4
#include <event2/http.h>
5
#include <event2/buffer.h>
6

7
int main() {
8
    struct event_base *base = event_base_new();
9
    struct evdns_base *dns_base = evdns_base_new(base, 1);
10

11
    // 创建HTTP连接
12
    struct evhttp_connection *conn = evhttp_connection_base_new(
13
        base, dns_base, "www.example.com", 80);
14

15
    if (!conn) {
16
        fprintf(stderr, "Failed to create connection\n");
17
        return 1;
18
    }
19

20
    // 设置超时
21
    evhttp_connection_set_timeout(conn, 10);
22

23
    printf("HTTP connection created\n");
24

25
    evhttp_connection_free(conn);
26
    evdns_base_free(dns_base, 0);
27
    event_base_free(base);
28

29
    return 0;
30
}

展开收起

三、HTTP请求对象#

3.1 创建请求#

1
/* 创建HTTP请求对象 */
2
struct evhttp_request *evhttp_request_new(
3
    void (*cb)(struct evhttp_request *, void *), void *arg);
4

5
/* 释放请求对象 */
6
void evhttp_request_free(struct evhttp_request *req);
7

8
/* 获取请求的输出缓冲区 */
9
struct evbuffer *evhttp_request_get_output_buffer(struct evhttp_request *req);
10

11
/* 获取请求的输入缓冲区 */
12
struct evbuffer *evhttp_request_get_input_buffer(struct evhttp_request *req);
13

14
/* 获取请求的输出头 */
15
struct evkeyvalq *evhttp_request_get_output_headers(struct evhttp_request *req);
16

17
/* 获取请求的输入头 */
18
struct evkeyvalq *evhttp_request_get_input_headers(struct evhttp_request *req);
19

20
/* 获取响应码 */
21
int evhttp_request_get_response_code(struct evhttp_request *req);
22
const char *evhttp_request_get_response_code_line(struct evhttp_request *req);
23

24
/* 获取请求的连接 */
25
struct evhttp_connection *evhttp_request_get_connection(struct evhttp_request *req);
26

27
/* 获取请求的host */
28
const char *evhttp_request_get_host(struct evhttp_request *req);
29

30
/* 获取请求的URI */
31
enum evhttp_cmd_type evhttp_request_get_command(struct evhttp_request *req);
32
const char *evhttp_request_get_uri(struct evhttp_request *req);
33

34
/* 取消请求 */
35
void evhttp_cancel_request(struct evhttp_request *req);

展开收起

3.2 请求方法#

1
enum evhttp_cmd_type {
2
    EVHTTP_REQ_GET     = 1 << 0,
3
    EVHTTP_REQ_POST    = 1 << 1,
4
    EVHTTP_REQ_HEAD    = 1 << 2,
5
    EVHTTP_REQ_PUT     = 1 << 3,
6
    EVHTTP_REQ_DELETE  = 1 << 4,
7
    EVHTTP_REQ_OPTIONS = 1 << 5,
8
    EVHTTP_REQ_TRACE   = 1 << 6,
9
    EVHTTP_REQ_CONNECT = 1 << 7,
10
    EVHTTP_REQ_PATCH   = 1 << 8
11
};

四、发送HTTP请求#

4.1 发送请求API#

1
/* 发送HTTP请求
2
 * @param evcon  HTTP连接
3
 * @param req    HTTP请求对象
4
 * @param type   请求方法
5
 * @param uri    请求URI
6
 * @return       0成功，-1失败
7
 */
8
int evhttp_make_request(struct evhttp_connection *evcon,
9
    struct evhttp_request *req, enum evhttp_cmd_type type, const char *uri);

4.2 GET请求示例#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <event2/event.h>
4
#include <event2/http.h>
5
#include <event2/buffer.h>
6

7
static void http_request_done(struct evhttp_request *req, void *arg) {
8
    if (!req) {
9
        printf("Request failed\n");
10
        event_base_loopbreak((struct event_base *)arg);
11
        return;
12
    }
13

14
    int response_code = evhttp_request_get_response_code(req);
15
    printf("Response code: %d\n", response_code);
16

17
    // 获取响应头
18
    struct evkeyvalq *headers = evhttp_request_get_input_headers(req);
19
    const char *content_type = evhttp_find_header(headers, "Content-Type");
20
    printf("Content-Type: %s\n", content_type ? content_type : "unknown");
21

22
    // 获取响应体
23
    struct evbuffer *buf = evhttp_request_get_input_buffer(req);
24
    size_t len = evbuffer_get_length(buf);
25
    printf("Response length: %zu bytes\n", len);
26

27
    // 打印响应内容
28
    char *data = malloc(len + 1);
29
    evbuffer_copyout(buf, data, len);
30
    data[len] = '\0';
31
    printf("Response body:\n%s\n", data);
32
    free(data);
33

34
    event_base_loopbreak((struct event_base *)arg);
35
}
36

37
int main() {
38
    struct event_base *base = event_base_new();
39
    struct evdns_base *dns_base = evdns_base_new(base, 1);
40

41
    // 创建连接
42
    struct evhttp_connection *conn = evhttp_connection_base_new(
43
        base, dns_base, "httpbin.org", 80);
44
    evhttp_connection_set_timeout(conn, 10);
45

46
    // 创建请求
47
    struct evhttp_request *req = evhttp_request_new(http_request_done, base);
48

49
    // 添加请求头
50
    struct evkeyvalq *output_headers = evhttp_request_get_output_headers(req);
51
    evhttp_add_header(output_headers, "Host", "httpbin.org");
52
    evhttp_add_header(output_headers, "User-Agent", "libevent-client/1.0");
53
    evhttp_add_header(output_headers, "Accept", "*/*");
54

55
    // 发送GET请求
56
    printf("Sending GET request to httpbin.org/get\n");
57
    evhttp_make_request(conn, req, EVHTTP_REQ_GET, "/get");
58

59
    event_base_dispatch(base);
60

61
    evhttp_connection_free(conn);
62
    evdns_base_free(dns_base, 0);
63
    event_base_free(base);
64

65
    return 0;
66
}

展开收起

五、POST请求#

5.1 POST请求示例#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <event2/event.h>
5
#include <event2/http.h>
6
#include <event2/buffer.h>
7

8
static void http_request_done(struct evhttp_request *req, void *arg) {
9
    if (!req) {
10
        printf("Request failed\n");
11
        event_base_loopbreak((struct event_base *)arg);
12
        return;
13
    }
14

15
    printf("Response code: %d\n", evhttp_request_get_response_code(req));
16

17
    struct evbuffer *buf = evhttp_request_get_input_buffer(req);
18
    size_t len = evbuffer_get_length(buf);
19

20
    char *data = malloc(len + 1);
21
    evbuffer_copyout(buf, data, len);
22
    data[len] = '\0';
23
    printf("Response:\n%s\n", data);
24
    free(data);
25

26
    event_base_loopbreak((struct event_base *)arg);
27
}
28

29
int main() {
30
    struct event_base *base = event_base_new();
31
    struct evdns_base *dns_base = evdns_base_new(base, 1);
32

33
    struct evhttp_connection *conn = evhttp_connection_base_new(
34
        base, dns_base, "httpbin.org", 80);
35
    evhttp_connection_set_timeout(conn, 10);
36

37
    struct evhttp_request *req = evhttp_request_new(http_request_done, base);
38

39
    // 设置请求头
40
    struct evkeyvalq *output_headers = evhttp_request_get_output_headers(req);
41
    evhttp_add_header(output_headers, "Host", "httpbin.org");
42
    evhttp_add_header(output_headers, "Content-Type", "application/x-www-form-urlencoded");
43
    evhttp_add_header(output_headers, "User-Agent", "libevent-client/1.0");
44

45
    // 设置POST数据
46
    struct evbuffer *output_buffer = evhttp_request_get_output_buffer(req);
47
    const char *post_data = "name=John&age=30&city=Beijing";
48
    evbuffer_add(output_buffer, post_data, strlen(post_data));
49

50
    printf("Sending POST request to httpbin.org/post\n");
51
    printf("Post data: %s\n", post_data);
52

53
    evhttp_make_request(conn, req, EVHTTP_REQ_POST, "/post");
54

55
    event_base_dispatch(base);
56

57
    evhttp_connection_free(conn);
58
    evdns_base_free(dns_base, 0);
59
    event_base_free(base);
60

61
    return 0;
62
}

展开收起

5.2 JSON POST请求#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <event2/event.h>
5
#include <event2/http.h>
6
#include <event2/buffer.h>
7

8
static void json_post_done(struct evhttp_request *req, void *arg) {
9
    if (!req) {
10
        printf("Request failed\n");
11
        event_base_loopbreak((struct event_base *)arg);
12
        return;
13
    }
14

15
    printf("Response code: %d\n", evhttp_request_get_response_code(req));
16

17
    struct evbuffer *buf = evhttp_request_get_input_buffer(req);
18
    size_t len = evbuffer_get_length(buf);
19

20
    char *data = malloc(len + 1);
21
    evbuffer_copyout(buf, data, len);
22
    data[len] = '\0';
23
    printf("Response:\n%s\n", data);
24
    free(data);
25

26
    event_base_loopbreak((struct event_base *)arg);
27
}
28

29
int main() {
30
    struct event_base *base = event_base_new();
31
    struct evdns_base *dns_base = evdns_base_new(base, 1);
32

33
    struct evhttp_connection *conn = evhttp_connection_base_new(
34
        base, dns_base, "httpbin.org", 80);
35
    evhttp_connection_set_timeout(conn, 10);
36

37
    struct evhttp_request *req = evhttp_request_new(json_post_done, base);
38

39
    struct evkeyvalq *headers = evhttp_request_get_output_headers(req);
40
    evhttp_add_header(headers, "Host", "httpbin.org");
41
    evhttp_add_header(headers, "Content-Type", "application/json");
42
    evhttp_add_header(headers, "Accept", "application/json");
43

44
    // JSON数据
45
    const char *json_data = "{\"username\":\"test\",\"password\":\"123456\"}";
46
    struct evbuffer *output = evhttp_request_get_output_buffer(req);
47
    evbuffer_add(output, json_data, strlen(json_data));
48

49
    printf("Sending JSON POST request\n");
50
    printf("JSON data: %s\n", json_data);
51

52
    evhttp_make_request(conn, req, EVHTTP_REQ_POST, "/post");
53

54
    event_base_dispatch(base);
55

56
    evhttp_connection_free(conn);
57
    evdns_base_free(dns_base, 0);
58
    event_base_free(base);
59

60
    return 0;
61
}

展开收起

六、HTTP头部操作#

6.1 头部API#

1
/* 添加头部 */
2
int evhttp_add_header(struct evkeyvalq *headers, const char *key, const char *value);
3

4
/* 查找头部 */
5
const char *evhttp_find_header(const struct evkeyvalq *headers, const char *key);
6

7
/* 删除头部 */
8
int evhttp_remove_header(struct evkeyvalq *headers, const char *key);
9

10
/* 清除所有头部 */
11
void evhttp_clear_headers(struct evkeyvalq *headers);

6.2 常用请求头#

头部	说明
`Host`	目标主机名
`User-Agent`	客户端标识
`Accept`	接受的内容类型
`Content-Type`	请求体类型
`Content-Length`	请求体长度
`Authorization`	认证信息
`Cookie`	Cookie数据
`Connection`	连接控制

七、HTTPS支持#

7.1 HTTPS连接#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <event2/event.h>
4
#include <event2/http.h>
5
#include <event2/buffer.h>
6
#include <openssl/ssl.h>
7

8
static void https_request_done(struct evhttp_request *req, void *arg) {
9
    if (!req) {
10
        printf("Request failed\n");
11
        event_base_loopbreak((struct event_base *)arg);
12
        return;
13
    }
14

15
    printf("Response code: %d\n", evhttp_request_get_response_code(req));
16

17
    struct evbuffer *buf = evhttp_request_get_input_buffer(req);
18
    size_t len = evbuffer_get_length(buf);
19

20
    char *data = malloc(len + 1);
21
    evbuffer_copyout(buf, data, len);
22
    data[len] = '\0';
23
    printf("Response:\n%s\n", data);
24
    free(data);
25

26
    event_base_loopbreak((struct event_base *)arg);
27
}
28

29
int main() {
30
    // 初始化OpenSSL
31
    SSL_library_init();
32
    SSL_load_error_strings();
33
    OpenSSL_add_all_algorithms();
34

35
    struct event_base *base = event_base_new();
36
    struct evdns_base *dns_base = evdns_base_new(base, 1);
37

38
    // 创建SSL上下文
39
    SSL_CTX *ssl_ctx = SSL_CTX_new(SSLv23_client_method());
40

41
    // 创建bufferevent
42
    struct bufferevent *bev = bufferevent_openssl_socket_new(
43
        base, -1, SSL_new(ssl_ctx), BUFFEREVENT_SSL_CONNECTING,
44
        BEV_OPT_CLOSE_ON_FREE | BEV_OPT_DEFER_CALLBACKS);
45

46
    // 创建HTTPS连接
47
    struct evhttp_connection *conn = evhttp_connection_base_bufferevent_new(
48
        base, dns_base, bev, "www.google.com", 443);
49

50
    struct evhttp_request *req = evhttp_request_new(https_request_done, base);
51

52
    struct evkeyvalq *headers = evhttp_request_get_output_headers(req);
53
    evhttp_add_header(headers, "Host", "www.google.com");
54
    evhttp_add_header(headers, "User-Agent", "libevent-https-client/1.0");
55

56
    printf("Sending HTTPS request to www.google.com/\n");
57
    evhttp_make_request(conn, req, EVHTTP_REQ_GET, "/");
58

59
    event_base_dispatch(base);
60

61
    evhttp_connection_free(conn);
62
    evdns_base_free(dns_base, 0);
63
    event_base_free(base);
64
    SSL_CTX_free(ssl_ctx);
65

66
    return 0;
67
}

展开收起

八、错误处理#

8.1 错误回调#

1
/* 设置连接错误回调 */
2
typedef void (*evhttp_conn_error_cb)(enum evhttp_request_error, void *);
3
void evhttp_connection_set_closecb(struct evhttp_connection *evcon,
4
    void (*cb)(struct evhttp_connection *, void *), void *cbarg);
5

6
/* 错误类型 */
7
enum evhttp_request_error {
8
    EVREQ_HTTP_TIMEOUT,         // 超时
9
    EVREQ_HTTP_EOF,             // 连接关闭
10
    EVREQ_HTTP_INVALID_HEADER,  // 无效头部
11
    EVREQ_HTTP_BUFFER_ERROR,    // 缓冲区错误
12
    EVREQ_HTTP_REQUEST_CANCEL,  // 请求取消
13
    EVREQ_HTTP_DATA_TOO_LONG    // 数据过长
14
};

8.2 错误处理示例#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <event2/event.h>
4
#include <event2/http.h>
5

6
static void connection_close_cb(struct evhttp_connection *conn, void *arg) {
7
    printf("Connection closed\n");
8
}
9

10
static void http_request_done(struct evhttp_request *req, void *arg) {
11
    if (!req) {
12
        // 获取错误类型
13
        enum evhttp_request_error err = EVREQ_HTTP_TIMEOUT;
14
        printf("Request error: %d\n", err);
15
        event_base_loopbreak((struct event_base *)arg);
16
        return;
17
    }
18

19
    int code = evhttp_request_get_response_code(req);
20
    if (code == 0) {
21
        printf("Connection failed\n");
22
    } else if (code >= 400) {
23
        printf("HTTP error: %d\n", code);
24
    } else {
25
        printf("Success: %d\n", code);
26
    }
27

28
    event_base_loopbreak((struct event_base *)arg);
29
}
30

31
int main() {
32
    struct event_base *base = event_base_new();
33
    struct evdns_base *dns_base = evdns_base_new(base, 1);
34

35
    struct evhttp_connection *conn = evhttp_connection_base_new(
36
        base, dns_base, "example.invalid", 80);  // 无效域名
37

38
    // 设置关闭回调
39
    evhttp_connection_set_closecb(conn, connection_close_cb, NULL);
40

41
    // 设置较短超时
42
    evhttp_connection_set_timeout(conn, 3);
43

44
    struct evhttp_request *req = evhttp_request_new(http_request_done, base);
45

46
    evhttp_make_request(conn, req, EVHTTP_REQ_GET, "/");
47

48
    event_base_dispatch(base);
49

50
    evhttp_connection_free(conn);
51
    evdns_base_free(dns_base, 0);
52
    event_base_free(base);
53

54
    return 0;
55
}

展开收起

九、连接池与重用#

9.1 连接重用#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <event2/event.h>
5
#include <event2/http.h>
6
#include <event2/buffer.h>
7

8
static int request_count = 0;
9
static const int MAX_REQUESTS = 3;
10

11
static void send_next_request(struct evhttp_connection *conn,
12
                               struct event_base *base);
13

14
static void http_request_done(struct evhttp_request *req, void *arg) {
15
    struct evhttp_connection *conn = evhttp_request_get_connection(req);
16
    struct event_base *base = arg;
17

18
    if (req) {
19
        printf("Request %d: Response code %d\n",
20
               request_count, evhttp_request_get_response_code(req));
21
    } else {
22
        printf("Request %d failed\n", request_count);
23
    }
24

25
    request_count++;
26

27
    if (request_count < MAX_REQUESTS) {
28
        send_next_request(conn, base);
29
    } else {
30
        evhttp_connection_free(conn);
31
        event_base_loopbreak(base);
32
    }
33
}
34

35
static void send_next_request(struct evhttp_connection *conn,
36
                               struct event_base *base) {
37
    char uri[64];
38
    snprintf(uri, sizeof(uri), "/get?id=%d", request_count);
39

40
    struct evhttp_request *req = evhttp_request_new(http_request_done, base);
41

42
    struct evkeyvalq *headers = evhttp_request_get_output_headers(req);
43
    evhttp_add_header(headers, "Host", "httpbin.org");
44

45
    printf("Sending request %d to %s\n", request_count, uri);
46
    evhttp_make_request(conn, req, EVHTTP_REQ_GET, uri);
47
}
48

49
int main() {
50
    struct event_base *base = event_base_new();
51
    struct evdns_base *dns_base = evdns_base_new(base, 1);
52

53
    // 创建一个连接，重用发送多个请求
54
    struct evhttp_connection *conn = evhttp_connection_base_new(
55
        base, dns_base, "httpbin.org", 80);
56
    evhttp_connection_set_timeout(conn, 10);
57

58
    send_next_request(conn, base);
59

60
    event_base_dispatch(base);
61

62
    evdns_base_free(dns_base, 0);
63
    event_base_free(base);
64

65
    return 0;
66
}

展开收起

十、完整示例：HTTP下载器#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <signal.h>
5
#include <event2/event.h>
6
#include <event2/http.h>
7
#include <event2/buffer.h>
8

9
typedef struct {
10
    struct event_base *base;
11
    struct evhttp_connection *conn;
12
    FILE *output_file;
13
    const char *url;
14
    const char *host;
15
    int port;
16
    const char *path;
17
    size_t total_bytes;
18
} download_context_t;
19

20
static void download_chunk_cb(struct evhttp_request *req, void *arg);
21

22
static void download_complete(struct evhttp_request *req, void *arg) {
23
    download_context_t *ctx = arg;
24

25
    if (!req) {
26
        printf("Download failed\n");
27
    } else {
28
        int code = evhttp_request_get_response_code(req);
29
        printf("\nDownload complete: HTTP %d, %zu bytes\n",
30
               code, ctx->total_bytes);
31
    }
32

33
    if (ctx->output_file) {
34
        fclose(ctx->output_file);
35
    }
36

37
    evhttp_connection_free(ctx->conn);
38
    event_base_loopbreak(ctx->base);
39
}
40

41
static void download_chunk_cb(struct evhttp_request *req, void *arg) {
42
    download_context_t *ctx = arg;
43

44
    if (!req) return;
45

46
    struct evbuffer *buf = evhttp_request_get_input_buffer(req);
47
    size_t len = evbuffer_get_length(buf);
48

49
    if (len > 0 && ctx->output_file) {
50
        char *data = malloc(len);
51
        evbuffer_remove(buf, data, len);
52
        fwrite(data, 1, len, ctx->output_file);
53
        free(data);
54

55
        ctx->total_bytes += len;
56
        printf("\rDownloaded: %zu bytes", ctx->total_bytes);
57
        fflush(stdout);
58
    }
59

60
    // 检查是否完成
61
    if (evbuffer_get_length(buf) == 0) {
62
        download_complete(req, arg);
63
    }
64
}
65

66
static void start_download(download_context_t *ctx) {
67
    struct evhttp_request *req = evhttp_request_new(download_chunk_cb, ctx);
68

69
    struct evkeyvalq *headers = evhttp_request_get_output_headers(req);
70
    evhttp_add_header(headers, "Host", ctx->host);
71
    evhttp_add_header(headers, "User-Agent", "libevent-downloader/1.0");
72
    evhttp_add_header(headers, "Connection", "close");
73

74
    printf("Downloading from %s:%d%s\n", ctx->host, ctx->port, ctx->path);
75

76
    evhttp_make_request(ctx->conn, req, EVHTTP_REQ_GET, ctx->path);
77
}
78

79
int main(int argc, char *argv[]) {
80
    if (argc < 2) {
81
        printf("Usage: %s <url> [output_file]\n", argv[0]);
82
        printf("Example: %s http://example.com/file.zip output.zip\n", argv[0]);
83
        return 1;
84
    }
85

86
    const char *url = argv[1];
87
    const char *output_filename = argc > 2 ? argv[2] : "download.bin";
88

89
    // 解析URL（简化版）
90
    char host[256] = {0};
91
    char path[1024] = {0};
92
    int port = 80;
93

94
    const char *host_start = strstr(url, "://");
95
    if (host_start) {
96
        host_start += 3;
97
    } else {
98
        host_start = url;
99
    }
100

101
    const char *path_start = strchr(host_start, '/');
102
    if (path_start) {
103
        strncpy(host, host_start, path_start - host_start);
104
        strcpy(path, path_start);
105
    } else {
106
        strcpy(host, host_start);
107
        strcpy(path, "/");
108
    }
109

110
    char *port_str = strchr(host, ':');
111
    if (port_str) {
112
        *port_str = '\0';
113
        port = atoi(port_str + 1);
114
    }
115

116
    printf("Host: %s, Port: %d, Path: %s\n", host, port, path);
117

118
    struct event_base *base = event_base_new();
119
    struct evdns_base *dns_base = evdns_base_new(base, 1);
120

121
    download_context_t ctx = {
122
        .base = base,
123
        .host = host,
124
        .port = port,
125
        .path = path,
126
        .total_bytes = 0
127
    };
128

129
    ctx.output_file = fopen(output_filename, "wb");
130
    if (!ctx.output_file) {
131
        printf("Failed to open output file: %s\n", output_filename);
132
        return 1;
133
    }
134

135
    ctx.conn = evhttp_connection_base_new(base, dns_base, host, port);
136
    evhttp_connection_set_timeout(ctx.conn, 30);
137

138
    start_download(&ctx);
139

140
    event_base_dispatch(base);
141

142
    evdns_base_free(dns_base, 0);
143
    event_base_free(base);
144

145
    return 0;
146
}

展开收起

十一、最佳实践#

场景	建议
连接重用	同一服务器的多个请求重用连接
超时设置	根据网络环境设置合理的超时时间
错误重试	对于临时错误实现重试机制
大文件下载	使用chunk回调逐步处理，避免内存溢出
HTTPS	生产环境优先使用HTTPS
User-Agent	设置合理的User-Agent避免被拦截

其他相关资料请移步到个人主页

🌍 HTTP服务器 - libevent源码深度解析系列（十一）

Sat, 11 Apr 2026 00:00:00 GMT

🌍 HTTP服务器#

一、概述#

libevent提供了HTTP支持，可以方便地构建HTTP服务器和客户端。HTTP模块封装了HTTP协议的解析和响应处理，开发者只需要关注业务逻辑。

二、创建HTTP服务器#

2.1 基本API#

1
/* 创建HTTP服务器 */
2
struct evhttp *evhttp_new(struct event_base *base);
3

4
/* 绑定地址和端口 */
5
int evhttp_bind_socket(struct evhttp *http, const char *address, ev_uint16_t port);
6

7
/* 绑定socket */
8
int evhttp_bind_socket_with_handle(struct evhttp *http, evutil_socket_t fd);
9

10
/* 释放HTTP服务器 */
11
void evhttp_free(struct evhttp *http);

2.2 请求处理#

1
/* 设置请求处理回调 */
2
void evhttp_set_gencb(struct evhttp *http,
3
    void (*cb)(struct evhttp_request *, void *), void *cbarg);
4

5
/* 设置特定路径的处理回调 */
6
int evhttp_set_cb(struct evhttp *http, const char *path,
7
    void (*cb)(struct evhttp_request *, void *), void *cbarg);
8

9
/* 移除路径处理回调 */
10
int evhttp_del_cb(struct evhttp *http, const char *path);

三、请求对象#

3.1 获取请求信息#

1
/* 获取请求方法 */
2
enum evhttp_cmd_type evhttp_request_get_command(struct evhttp_request *req);
3

4
/* 获取请求URI */
5
const char *evhttp_request_get_uri(struct evhttp_request *req);
6

7
/* 获取请求头 */
8
const char *evhttp_find_header(const struct evkeyvalq *headers, const char *key);
9
struct evkeyvalq *evhttp_request_get_input_headers(struct evhttp_request *req);
10

11
/* 获取请求体 */
12
struct evbuffer *evhttp_request_get_input_buffer(struct evhttp_request *req);
13

14
/* 获取客户端地址 */
15
void evhttp_request_get_peer(struct evhttp_request *req, char **address, ev_uint16_t *port);

展开收起

3.2 请求方法类型#

1
enum evhttp_cmd_type {
2
    EVHTTP_REQ_GET     = 1 << 0,
3
    EVHTTP_REQ_POST    = 1 << 1,
4
    EVHTTP_REQ_HEAD    = 1 << 2,
5
    EVHTTP_REQ_PUT     = 1 << 3,
6
    EVHTTP_REQ_DELETE  = 1 << 4,
7
    EVHTTP_REQ_OPTIONS = 1 << 5,
8
    EVHTTP_REQ_TRACE   = 1 << 6,
9
    EVHTTP_REQ_CONNECT = 1 << 7,
10
    EVHTTP_REQ_PATCH   = 1 << 8
11
};

四、响应对象#

4.1 设置响应#

1
/* 创建响应buffer */
2
struct evbuffer *evbuffer_new(void);
3
void evbuffer_free(struct evbuffer *buf);
4

5
/* 添加响应内容 */
6
int evbuffer_add(struct evbuffer *buf, const void *data, size_t datlen);
7
int evbuffer_add_printf(struct evbuffer *buf, const char *fmt, ...);
8
int evbuffer_add_buffer(struct evbuffer *dst, struct evbuffer *src);
9

10
/* 设置响应头 */
11
int evhttp_add_header(struct evkeyvalq *headers, const char *key, const char *value);
12
struct evkeyvalq *evhttp_request_get_output_headers(struct evhttp_request *req);
13

14
/* 设置响应状态码 */
15
void evhttp_send_reply(struct evhttp_request *req, int code, const char *reason, struct evbuffer *buf);
16
void evhttp_send_reply_start(struct evhttp_request *req, int code, const char *reason);
17
void evhttp_send_reply_chunk(struct evhttp_request *req, struct evbuffer *buf);
18
void evhttp_send_reply_end(struct evhttp_request *req);
19

20
/* 发送错误响应 */
21
void evhttp_send_error(struct evhttp_request *req, int error, const char *reason);

展开收起

4.3 HTTP状态码#

状态码	说明
HTTP_OK	200 成功
HTTP_NOCONTENT	204 无内容
HTTP_MOVEPERM	301 永久移动
HTTP_MOVETEMP	302 临时移动
HTTP_NOTMODIFIED	304 未修改
HTTP_BADREQUEST	400 错误请求
HTTP_NOTFOUND	404 未找到
HTTP_BADMETHOD	405 方法不允许
HTTP_INTERNAL	500 服务器错误
HTTP_SERVUNAVAIL	503 服务不可用

五、完整示例#

5.1 基本HTTP服务器#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <signal.h>
5
#include <event2/event.h>
6
#include <event2/http.h>
7
#include <event2/buffer.h>
8
#include <event2/http_struct.h>
9

10
static void generic_cb(struct evhttp_request *req, void *arg) {
11
    struct evbuffer *buf = evbuffer_new();
12
    if (!buf) {
13
        evhttp_send_error(req, HTTP_INTERNAL, "Failed to create buffer");
14
        return;
15
    }
16

17
    evbuffer_add_printf(buf, "<html><body>");
18
    evbuffer_add_printf(buf, "<h1>Hello, libevent HTTP Server!</h1>");
19
    evbuffer_add_printf(buf, "<p>Request URI: %s</p>", evhttp_request_get_uri(req));
20
    evbuffer_add_printf(buf, "</body></html>");
21

22
    evhttp_add_header(evhttp_request_get_output_headers(req), "Content-Type", "text/html");
23
    evhttp_send_reply(req, HTTP_OK, "OK", buf);
24

25
    evbuffer_free(buf);
26
}
27

28
static void api_cb(struct evhttp_request *req, void *arg) {
29
    struct evbuffer *buf = evbuffer_new();
30

31
    const char *uri = evhttp_request_get_uri(req);
32
    struct evkeyvalq params;
33
    evhttp_parse_query(uri, &params);
34

35
    const char *name = evhttp_find_header(&params, "name");
36
    const char *age = evhttp_find_header(&params, "age");
37

38
    evbuffer_add_printf(buf, "{\n");
39
    evbuffer_add_printf(buf, "  \"status\": \"success\",\n");
40
    evbuffer_add_printf(buf, "  \"name\": \"%s\",\n", name ? name : "unknown");
41
    evbuffer_add_printf(buf, "  \"age\": %s\n", age ? age : "0");
42
    evbuffer_add_printf(buf, "}\n");
43

44
    evhttp_add_header(evhttp_request_get_output_headers(req), "Content-Type", "application/json");
45
    evhttp_send_reply(req, HTTP_OK, "OK", buf);
46

47
    evhttp_clear_headers(&params);
48
    evbuffer_free(buf);
49
}
50

51
static void post_cb(struct evhttp_request *req, void *arg) {
52
    if (evhttp_request_get_command(req) != EVHTTP_REQ_POST) {
53
        evhttp_send_error(req, HTTP_BADMETHOD, "Method not allowed");
54
        return;
55
    }
56

57
    struct evbuffer *input = evhttp_request_get_input_buffer(req);
58
    struct evbuffer *output = evbuffer_new();
59

60
    size_t len = evbuffer_get_length(input);
61
    char *data = malloc(len + 1);
62
    evbuffer_copyout(input, data, len);
63
    data[len] = '\0';
64

65
    printf("Received POST data: %s\n", data);
66

67
    evbuffer_add_printf(output, "{\n");
68
    evbuffer_add_printf(output, "  \"received\": true,\n");
69
    evbuffer_add_printf(output, "  \"length\": %zu,\n", len);
70
    evbuffer_add_printf(output, "  \"data\": \"%s\"\n", data);
71
    evbuffer_add_printf(output, "}\n");
72

73
    evhttp_add_header(evhttp_request_get_output_headers(req), "Content-Type", "application/json");
74
    evhttp_send_reply(req, HTTP_OK, "OK", output);
75

76
    free(data);
77
    evbuffer_free(output);
78
}
79

80
static void signal_cb(evutil_socket_t fd, short events, void *arg) {
81
    struct event_base *base = arg;
82
    printf("Caught signal, exiting...\n");
83
    event_base_loopbreak(base);
84
}
85

86
int main(int argc, char **argv) {
87
    struct event_base *base = event_base_new();
88
    struct evhttp *http = evhttp_new(base);
89

90
    if (!http) {
91
        fprintf(stderr, "Failed to create HTTP server\n");
92
        return 1;
93
    }
94

95
    if (evhttp_bind_socket(http, "0.0.0.0", 8080) != 0) {
96
        fprintf(stderr, "Failed to bind to port 8080\n");
97
        evhttp_free(http);
98
        return 1;
99
    }
100

101
    // 设置路由
102
    evhttp_set_cb(http, "/api", api_cb, NULL);
103
    evhttp_set_cb(http, "/post", post_cb, NULL);
104
    evhttp_set_gencb(http, generic_cb, NULL);
105

106
    // 信号处理
107
    struct event *sigint = evsignal_new(base, SIGINT, signal_cb, base);
108
    event_add(sigint, NULL);
109

110
    printf("HTTP server running on http://0.0.0.0:8080\n");
111
    printf("Routes:\n");
112
    printf("  GET  /           - Hello page\n");
113
    printf("  GET  /api?name=xxx&age=xxx - API endpoint\n");
114
    printf("  POST /post       - POST handler\n");
115

116
    event_base_dispatch(base);
117

118
    event_free(sigint);
119
    evhttp_free(http);
120
    event_base_free(base);
121

122
    printf("Server shutdown complete\n");
123
    return 0;
124
}

展开收起

5.2 静态文件服务器#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <signal.h>
5
#include <sys/stat.h>
6
#include <event2/event.h>
7
#include <event2/http.h>
8
#include <event2/buffer.h>
9

10
#define WWW_ROOT "./www"
11

12
static const char *get_content_type(const char *path) {
13
    const char *ext = strrchr(path, '.');
14
    if (!ext) return "application/octet-stream";
15

16
    if (strcmp(ext, ".html") == 0 || strcmp(ext, ".htm") == 0) return "text/html";
17
    if (strcmp(ext, ".css") == 0) return "text/css";
18
    if (strcmp(ext, ".js") == 0) return "application/javascript";
19
    if (strcmp(ext, ".json") == 0) return "application/json";
20
    if (strcmp(ext, ".png") == 0) return "image/png";
21
    if (strcmp(ext, ".jpg") == 0 || strcmp(ext, ".jpeg") == 0) return "image/jpeg";
22
    if (strcmp(ext, ".gif") == 0) return "image/gif";
23
    if (strcmp(ext, ".txt") == 0) return "text/plain";
24

25
    return "application/octet-stream";
26
}
27

28
static void file_cb(struct evhttp_request *req, void *arg) {
29
    const char *uri = evhttp_request_get_uri(req);
30

31
    char path[1024];
32
    snprintf(path, sizeof(path), "%s%s", WWW_ROOT, uri);
33

34
    // 处理目录请求
35
    struct stat st;
36
    if (stat(path, &st) == 0 && S_ISDIR(st.st_mode)) {
37
        strcat(path, "/index.html");
38
    }
39

40
    FILE *fp = fopen(path, "rb");
41
    if (!fp) {
42
        evhttp_send_error(req, HTTP_NOTFOUND, "File not found");
43
        return;
44
    }
45

46
    fseek(fp, 0, SEEK_END);
47
    long size = ftell(fp);
48
    fseek(fp, 0, SEEK_SET);
49

50
    struct evbuffer *buf = evbuffer_new();
51
    evbuffer_add_file(buf, fileno(fp), 0, size);
52

53
    evhttp_add_header(evhttp_request_get_output_headers(req),
54
                      "Content-Type", get_content_type(path));
55
    evhttp_send_reply(req, HTTP_OK, "OK", buf);
56

57
    evbuffer_free(buf);
58
}
59

60
int main() {
61
    struct event_base *base = event_base_new();
62
    struct evhttp *http = evhttp_new(base);
63

64
    evhttp_bind_socket(http, "0.0.0.0", 8080);
65
    evhttp_set_gencb(http, file_cb, NULL);
66

67
    printf("Static file server running on http://0.0.0.0:8080\n");
68
    printf("Serving files from %s\n", WWW_ROOT);
69

70
    event_base_dispatch(base);
71

72
    evhttp_free(http);
73
    event_base_free(base);
74

75
    return 0;
76
}

展开收起

六、编译运行#

Terminal window

1
# 编译
2
gcc -o http_server http_server.c -levent
3

4
# 运行
5
./http_server
6

7
# 测试
8
curl http://127.0.0.1:8080/
9
curl http://127.0.0.1:8080/api?name=test&age=20
10
curl -X POST -d "hello" http://127.0.0.1:8080/post

其他相关资料请移步到个人主页

🛠️ 安装与编译 - libevent源码深度解析系列（二）

Sat, 11 Apr 2026 00:00:00 GMT

🛠️ 安装与编译#

一、下载源码#

进入 libevent 官方网站下载最新稳定版本。

下载页面

这里选择最新版本 libevent-2.1.12-stable.tar.gz 下载。下载后传入到linux服务器中。

二、编译脚本#

直接编写一个shell编译脚本进行编译，方便编译参数设置。

1
#!/bin/bash
2
# 获取当前目录
3
cur_dir=`pwd`
4

5
# 解压libevent
6
tar -xzf libevent-2.1.12-stable.tar.gz
7

8
# 进入源码目录
9
cd libevent-2.1.12-stable
10

11
# 生成configure文件
12
./autogen.sh
13

14
# 配置编译选项
15
# --prefix=$cur_dir/libevent_build 设置编译安装路径
16
# --enable-shared=no 不编译动态库
17
# --enable-static=yes 编译静态库
18
# --disable-openssl 不启用openssl
19
./configure --prefix=$cur_dir/libevent_build \
20
            --enable-shared=no \
21
            --enable-static=yes \
22
            --disable-openssl
23

24
# 编译安装
25
make -j
26
make install

展开收起

三、执行编译#

Terminal window

1
chmod +x build.sh
2
./build.sh

等待编译完成后，可以看到当前路径中内容如下：

Terminal window

1
ls -hlt
2
total 1.1M
3
drwxr-xr-x  5 xutopia xutopia 4.0K Sep  6 22:50 libevent_build
4
drwxr-xr-x 13 xutopia xutopia 4.0K Sep  6 22:50 libevent-2.1.12-stable
5
-rwxr-xr-x  1 xutopia xutopia  558 Sep  6 22:50 build.sh
6
-rw-r--r--r--  1 xutopia xutopia 1.1M Sep  6 22:41 libevent-2.1.12-stable.tar.gz

四、程序验证#

编译完成后，可以通过编译一个简单的示例程序来验证 libevent 是否正确安装。

4.1 测试代码#

1
/**
2
 * @brief 测试验证libevent程序
3
 *          编译测试程序
4
 *          gcc main.c -I./libevent_build/include -o main -L./libevent_build/lib -levent
5
 */
6
#include <stdio.h>
7
#include <stdlib.h>
8
#include <unistd.h>
9
#include <event2/event.h>
10

11
static void timer_callback(evutil_socket_t fd, short event, void *arg) {
12
    printf("Timer run!\n");
13
}
14

15
int main() {
16
    struct event_base *base;
17
    struct event *timer;
18

19
    base = event_base_new();
20
    if (!base) {
21
        fprintf(stderr, "Failed to create event base\n");
22
        return 1;
23
    }
24

25
    timer = event_new(base, -1, EV_PERSIST, timer_callback, base);
26
    if (!timer) {
27
        fprintf(stderr, "Failed to create timer event\n");
28
        event_base_free(base);
29
        return 1;
30
    }
31

32
    // 设置定时器时间为 2 秒
33
    struct timeval delay = {2, 0};
34
    event_add(timer, &delay);
35

36
    // 启动事件循环
37
    event_base_dispatch(base);
38

39
    // 清理资源
40
    event_free(timer);
41
    event_base_free(base);
42

43
    return 0;
44
}

展开收起

4.2 编译命令#

Terminal window

1
gcc main.c -I./libevent_build/include -o main -L./libevent_build/lib -levent

4.3 运行结果#

./main

1
Timer run!
2
Timer run!
3
Timer run!

五、编译产物说明#

库文件	说明
`libevent_core`	所有核心的事件和缓冲功能，包含了所有的 event_base、evbuffer、bufferevent和工具函数
`libevent_extra`	定义了程序可能需要，也可能不需要的协议特定功能，包括 HTTP、DNS和 RPC
`libevent`	这个库因为历史原因而存在，它包含 libevent_core和 libevent_extra的内容
`libevent_pthreads`	添加基于 pthread可移植线程库的线程和锁定实现
`libevent_openssl`	为使用 bufferevent和 OpenSSL进行加密的通信提供支持

六、Windows平台安装#

6.1 使用vcpkg安装#

Terminal window

1
# 安装vcpkg（如果尚未安装）
2
git clone https://github.com/Microsoft/vcpkg.git
3
cd vcpkg
4
.\bootstrap-vcpkg.bat
5

6
# 安装libevent
7
.\vcpkg install libevent:x64-windows
8
.\vcpkg integrate install

6.2 使用CMake编译#

Terminal window

1
# 下载源码
2
git clone https://github.com/libevent/libevent.git
3
cd libevent
4

5
# 创建构建目录
6
mkdir build && cd build
7

8
# 配置和编译
9
cmake .. -G "Visual Studio 17 2022" -A x64
10
cmake --build . --config Release
11
cmake --install . --prefix ./install

6.3 Visual Studio配置#

在Visual Studio项目中配置libevent：

1
<!-- 包含目录 -->
2
C:\libevent\include
3

4
<!-- 库目录 -->
5
C:\libevent\lib
6

7
<!-- 链接库 -->
8
libevent.lib
9
ws2_32.lib

6.4 Windows测试代码#

1
#ifdef _WIN32
2
#include <winsock2.h>
3
#include <ws2tcpip.h>
4
#pragma comment(lib, "ws2_32.lib")
5
#endif
6

7
#include <stdio.h>
8
#include <event2/event.h>
9

10
int main() {
11
#ifdef _WIN32
12
    WSADATA wsa_data;
13
    WSAStartup(MAKEWORD(2, 2), &wsa_data);
14
#endif
15

16
    struct event_base *base = event_base_new();
17
    if (base) {
18
        printf("libevent initialized successfully!\n");
19
        printf("Using method: %s\n", event_base_get_method(base));
20
        event_base_free(base);
21
    }
22

23
#ifdef _WIN32
24
    WSACleanup();
25
#endif
26
    return 0;
27
}

展开收起

七、macOS平台安装#

7.1 使用Homebrew安装#

Terminal window

1
# 安装libevent
2
brew install libevent
3

4
# 查看安装信息
5
brew info libevent

7.2 使用MacPorts安装#

Terminal window

1
sudo port install libevent

7.3 源码编译（macOS）#

Terminal window

1
# 下载源码
2
curl -O https://github.com/libevent/libevent/releases/download/release-2.1.12-stable/libevent-2.1.12-stable.tar.gz
3
tar -xzf libevent-2.1.12-stable.tar.gz
4
cd libevent-2.1.12-stable
5

6
# 配置和编译
7
./configure --prefix=/usr/local/libevent
8
make -j$(sysctl -n hw.ncpu)
9
sudo make install

7.4 macOS编译测试程序#

Terminal window

1
gcc main.c -I/usr/local/include -L/usr/local/lib -levent -o main
2
./main

八、常见安装问题#

问题	解决方案
`openssl/ssl.h not found`	安装OpenSSL开发包：`apt install libssl-dev`
`event2/event.h not found`	检查include路径是否正确配置
`undefined reference to event_base_new`	添加链接选项 `-levent`
Windows下WSA错误	确保调用 `WSAStartup()` 初始化
macOS下找不到库	设置 `DYLD_LIBRARY_PATH` 或使用 `install_name_tool`

其他相关资料请移步到个人主页

📖 序言与简介 - libevent源码深度解析系列（一）

Sat, 11 Apr 2026 00:00:00 GMT

🚀 序言与简介#

一、高性能服务器编程#

1.1 高性能服务器特点#

目前网络应用程序大多是C/S架构的，例如：

🍪 日常使用的邮箱，聊天软件QQ、微信
🍪 看视频的网站B站、腾讯视频
🍪 浏览网页用的浏览器

他们的基本特点就是，客户端软件从向服务端请求资源，服务端做一些处理之后，把资源返回给客户端。

高性能服务器的关键需求至少有如下几点：

👉 效率高：既然是高性能，那处理客户端请求的效率当然要很高了
👉 高可用：不能随便就挂掉了
👉 编程简单：基于此服务器进行业务开发需要足够简单
👉 可扩展：可方便的扩展功能（微服务）
👉 可伸缩：可简单的通过部署的方式进行容量的伸缩，也就是服务需要无状态

1.2 传统网络编程的局限#

从上面描述也可以知道，高性能服务器的重要基石就是接受客户端的连接，处理客户端发送的网络请求。下面我们看一下基本的网络编程方式。

1
while(1){
2
    listen(listen_socket);
3
    cli_socket = accept(listen_socket);
4
    while(read(cli_socket) > 0){
5
        //do something, cost some time
6
        write(cli_socket);
7
    }
8
    //peer close or peer err
9
    close(cli_socket)
10
}

服务端监听一个网络套接字，然后接受客户端的连接请求，并从客户端读取请求数据，然后做出响应。

上面程序中，accept和read的系统接口一般都是阻塞的，所以上面的编程示例同一时刻只能处理一个客户端的请求。但是我们知道，这在现实中基本还是不可使用的，例如B站，同一时刻不可能只为一个网络用户提供视频服务。

改进方案：每一个客户端连接上来就为他分配一个线程，处理这个客户的请求，然后主线程继续等待客户端的连接。

1
void workThread(int cli_socket){
2
    while(read(cli_socket) > 0){
3
        //do something, cost some time
4
        write(cli_socket);
5
    }
6
    close(cli_socket)
7
}
8

9
main(){
10
    while(1){
11
        listen(listen_socket);
12
        cli_socket = accept(listen_socket);
13
        create_thread(workThread, listen_socket);
14
    }
15
}

展开收起

问题：每一个客户端就需要一个线程，如果面对大量用户，那就需要创建大量线程，可是服务器的硬件资源是有限制的。具体问题详见 The C10K Problem。

针对这个问题可以使用linux的多路复用机制来解决。

二、Reactor模型#

从上述的demo中可以看出，在wait的地方阻塞等待，直到有事件触发，然后就可以调用事件的回调进行处理。这就是Reactor网络编程模型。

2.1 Reactor模型结构#

下面这个模型图片在计算机业内的公认讲Reactor模型最好的论文。

Reactor模型

简单解释一下这个模型图：

组件	说明
Synchronous Event Demultiplexer	同步事件分离器，用于监听各种事件，调用方调用监听方法的时候会被阻塞，直到有事件发生，才会返回。对于Linux来说，同步事件分离器指的就是IO多路复用模型，比如epoll，poll，select 等。
Handler	本质上是文件描述符，是一个抽象的概念，可以简单的理解为一个一个事件，该事件可以来自于外部，比如客户端连接事件，客户端的写事件等等，也可以是内部的事件，比如操作系统产生的定时器事件等等。
Event Handler	事件处理器，本质上是回调方法，当有事件发生后，框架会根据Handler调用对应的回调方法，在大多数情况下，是虚函数，需要用户自己实现接口，实现具体的方法。
Concrete Event Handler	具体的事件处理器，是Event Handler的具体实现。
Initiation Dispatcher	初始化事件分发器，实际上就是Reactor角色，提供了一系列方法，对Event Handler进行注册和移除；还会调用Synchronous Event Demultiplexer监听各种事件；当有事件发生后，还要调用对应的Event Handler。

2.2 简化的Reactor模型图#

简化Reactor模型

这是一个最简单的Reactor网络模型，Reactor处理多个client的连接处理请求，Reactor模型负责把产生的事件（连接，可读，可写，异常等）通过dispatch分发给各回调函数进行处理。

注意：上述是单线程的Reactor处理模型，单线程的Reactor要求每个处理回调不能卡死，业务处理尽可能快，否则会影响后续的事件处理，导致事件队列阻塞。

三、libevent简介#

3.1 libevent特点#

Libevent 是一个用C语言编写的、轻量级的开源高性能事件通知库，主要有以下几个亮点：

🔷 事件驱动（event-driven），高性能
🔷 轻量级，专注于网络，不如 ACE 那么臃肿庞大
🔷 源代码相当精炼、易读
🔷 跨平台，支持 Windows、Linux、*BSD 和 Mac Os
🔷 支持多种 I/O 多路复用技术，epoll、poll、dev/poll、select 和 kqueue 等
🔷 支持 I/O，定时器和信号等事件
🔷 注册事件优先级

Libevent 已经被广泛的应用，作为底层的网络库；比如 memcached、Vomit、Nylon、Netchat等等。

3.2 libevent组件#

libevent包括事件管理、缓存管理、DNS、HTTP、缓存事件几大部分：

组件	说明
事件管理	包括各种IO（socket）、定时器、信号等事件
缓存管理	evbuffer功能
DNS	libevent提供的一个异步DNS查询功能
HTTP	libevent的一个轻量级http实现，包括服务器和客户端

libevent也支持ssl，这对于有安全需求的网络程序非常的重要，但是其支持不是很完善，比如http server的实现就不支持ssl。

3.3 libevent的历史背景#

libevent 的起源可以追溯到 2003 年，由美国加州大学伯克利分校的研究员 Brad Fitzpatrick 开发。最初，它是为了解决在构建高性能网络应用时面临的挑战，特别是在 Linux 和 BSD 系统上实现高效的事件处理机制。Fitzpatrick 在开发 LiveJournal 项目的过程中遇到了性能瓶颈，传统的同步 I/O 模型无法满足大规模并发访问的需求。因此，他设计并实现了 libevent，以提供一种更为灵活和高效的事件处理框架。

最初的 libevent 实现基于 select() 系统调用，但很快就转向了更为先进的 poll() 和 kqueue()（针对 BSD 系统）。随着 Linux 内核的发展，特别是引入了 epoll 机制之后，libevent 迅速采用了这一新技术，进一步提升了性能。

3.4 libevent的API基本使用步骤#

1
event_base_new()    // 创建初始化event_base
2
event_new()         // 创建事件
3
event_add()         // 将event添加到事件链表上，注册事件
4
event_base_dispatch() // 循环、检测、分发事件

四、事件驱动编程#

4.1 事件驱动编程概述#

事件驱动编程（Event-Driven Programming，EDP）是一种编程范式，因其高效率和灵活性而受到广泛关注，它强调程序的执行是由外部事件触发的，而非通过预定的顺序流程控制。

事件驱动编程的核心思想是”被动等待”和”主动响应”。程序在大部分时间内处于等待状态，一旦检测到某个感兴趣的事件发生，就会触发相应的处理逻辑。这种方法不仅减少了不必要的计算开销，还能显著提高系统的响应速度和整体性能。

4.2 事件驱动编程的优势#

高效性：事件驱动编程模型允许程序在没有事件发生时处于休眠状态，这大大减少了 CPU 的空闲时间，提高了系统的整体效率。
可扩展性：由于事件驱动模型可以同时处理多个并发事件，因此非常适合构建高并发的应用程序。
灵活性：事件驱动编程模型允许开发者更灵活地组织代码结构，通过注册不同的事件处理函数来实现模块化的设计。
异步处理：事件驱动模型天然支持异步处理方式，这意味着程序可以同时处理多个任务，无需等待某个操作完成后再继续执行后续逻辑。

其他相关资料请移步到个人主页

📝 日志模块 - libevent源码深度解析系列（八）

Sat, 11 Apr 2026 00:00:00 GMT

📝 日志模块#

一、概述#

libevent提供了日志功能，允许用户自定义日志输出方式。默认情况下，日志输出到标准错误输出（stderr）。

二、日志级别#

1
#define EVENT_LOG_DEBUG  0
2
#define EVENT_LOG_MSG    1
3
#define EVENT_LOG_WARN   2
4
#define EVENT_LOG_ERR    3

三、日志回调函数#

3.1 回调函数类型#

1
typedef void (*event_log_cb)(int severity, const char *msg);

3.2 设置日志回调#

1
/* 设置日志回调函数，设置为NULL恢复默认行为 */
2
void event_set_log_callback(event_log_cb cb);

3.3 示例#

1
#include <stdio.h>
2
#include <event2/event.h>
3

4
static void my_log_cb(int severity, const char *msg) {
5
    const char *level;
6
    switch (severity) {
7
        case EVENT_LOG_DEBUG: level = "DEBUG"; break;
8
        case EVENT_LOG_MSG:   level = "MSG";   break;
9
        case EVENT_LOG_WARN:  level = "WARN";  break;
10
        case EVENT_LOG_ERR:   level = "ERR";   break;
11
        default:              level = "???";   break;
12
    }
13
    fprintf(stderr, "[libevent][%s] %s\n", level, msg);
14
}
15

16
int main() {
17
    event_set_log_callback(my_log_cb);
18
    // ... 其他代码
19
    return 0;
20
}

展开收起

四、致命错误处理#

4.1 设置致命错误回调#

1
typedef void (*event_fatal_cb)(int err);
2

3
/* 设置致命错误回调函数
4
 * 设置后，libevent遇到内部错误时调用此回调，而不是退出
5
 * 注意：回调函数不应该返回
6
 */
7
void event_set_fatal_callback(event_fatal_cb cb);

4.2 示例#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <event2/event.h>
4

5
static void my_fatal_cb(int err) {
6
    fprintf(stderr, "Fatal error: %d\n", err);
7
    abort();
8
}
9

10
int main() {
11
    event_set_fatal_callback(my_fatal_cb);
12
    // ... 其他代码
13
    return 0;
14
}

五、调试日志#

5.1 启用调试日志#

1
/* 启用调试日志
2
 * 启用后，libevent会输出详细的调试信息
3
 * 注意：这会降低性能，仅用于调试
4
 */
5
void event_enable_debug_mode(void);

5.2 调试事件#

1
/* 记录事件添加的调试信息 */
2
void event_enable_debug_logging(int which);
3

4
#define EVENT_DBG_NONE  0x00
5
#define EVENT_DBG_ALL   0xffffffff

六、内存调试#

6.1 内存分配函数#

1
/* 设置自定义内存分配函数 */
2
void event_set_mem_functions(void *(*malloc_fn)(size_t sz),
3
                            void *(*realloc_fn)(void *ptr, size_t sz),
4
                            void (*free_fn)(void *ptr));

6.2 示例#

1
#include <stdlib.h>
2
#include <event2/event.h>
3

4
static void *my_malloc(size_t sz) {
5
    void *p = malloc(sz);
6
    printf("malloc(%zu) = %p\n", sz, p);
7
    return p;
8
}
9

10
static void *my_realloc(void *ptr, size_t sz) {
11
    void *p = realloc(ptr, sz);
12
    printf("realloc(%p, %zu) = %p\n", ptr, sz, p);
13
    return p;
14
}
15

16
static void my_free(void *ptr) {
17
    printf("free(%p)\n", ptr);
18
    free(ptr);
19
}
20

21
int main() {
22
    event_set_mem_functions(my_malloc, my_realloc, my_free);
23
    // ... 其他代码
24
    return 0;
25
}

展开收起

七、完整示例#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <unistd.h>
4
#include <time.h>
5
#include <event2/event.h>
6

7
static const char* get_time_str(void) {
8
    static char buf[64];
9
    time_t t = time(NULL);
10
    struct tm *tm = localtime(&t);
11
    strftime(buf, sizeof(buf), "%Y-%m-%d %H:%M:%S", tm);
12
    return buf;
13
}
14

15
static void my_log_cb(int severity, const char *msg) {
16
    const char *level;
17
    switch (severity) {
18
        case EVENT_LOG_DEBUG: level = "DEBUG"; break;
19
        case EVENT_LOG_MSG:   level = "INFO";  break;
20
        case EVENT_LOG_WARN:  level = "WARN";  break;
21
        case EVENT_LOG_ERR:   level = "ERROR"; break;
22
        default:              level = "UNKNOWN"; break;
23
    }
24
    fprintf(stderr, "[%s][libevent][%s] %s\n", get_time_str(), level, msg);
25
}
26

27
static void timer_cb(evutil_socket_t fd, short events, void *arg) {
28
    printf("Timer triggered\n");
29
}
30

31
int main() {
32
    event_set_log_callback(my_log_cb);
33
    event_enable_debug_mode();
34

35
    struct event_base *base = event_base_new();
36
    if (!base) {
37
        fprintf(stderr, "Failed to create event base\n");
38
        return 1;
39
    }
40

41
    printf("Using method: %s\n", event_base_get_method(base));
42

43
    struct event *timer = event_new(base, -1, EV_PERSIST, timer_cb, NULL);
44
    struct timeval tv = {2, 0};
45
    event_add(timer, &tv);
46

47
    // 运行5秒后退出
48
    struct timeval exit_tv = {5, 0};
49
    event_base_loopexit(base, &exit_tv);
50

51
    event_base_dispatch(base);
52

53
    event_free(timer);
54
    event_base_free(base);
55

56
    return 0;
57
}

展开收起

八、日志使用建议#

场景	建议
开发调试	启用调试日志，输出详细信息
生产环境	只记录警告和错误级别日志
内存泄漏排查	使用自定义内存分配函数跟踪内存分配
崩溃分析	设置致命错误回调，记录错误信息

其他相关资料请移步到个人主页

🧵 多线程编程 - libevent源码深度解析系列（十四）

Sat, 11 Apr 2026 00:00:00 GMT

🔀 多线程编程#

一、概述#

libevent本身是单线程设计，但提供了多线程支持。在多线程环境中使用libevent需要遵循特定的规则，否则会导致数据竞争和未定义行为。

二、多线程原则#

2.1 基本原则#

原则	说明
一个event_base一个线程	每个event_base只能在创建它的线程中使用
线程间通信	使用socket pair或bufferevent_pair进行线程间通信
锁保护	多线程共享资源需要使用锁保护
避免阻塞	回调函数中不要执行阻塞操作

2.2 线程安全初始化#

1
#include <event2/event.h>
2
#include <event2/thread.h>
3

4
int main() {
5
    // 初始化线程支持（必须在event_base_new之前调用）
6
#ifdef _WIN32
7
    evthread_use_windows_threads();
8
#else
9
    evthread_use_pthreads();
10
#endif
11

12
    // 现在可以创建线程安全的event_base
13
    struct event_config *cfg = event_config_new();
14
    event_config_set_flag(cfg, EVENT_BASE_FLAG_NOLOCK);  // 单线程可禁用锁提高性能
15

16
    struct event_base *base = event_base_new_with_config(cfg);
17
    event_config_free(cfg);
18

19
    // ...
20

21
    return 0;
22
}

展开收起

三、线程API#

3.1 线程支持初始化#

1
/* 使用pthreads（Linux/Unix） */
2
int evthread_use_pthreads(void);
3

4
/* 使用Windows线程 */
5
int evthread_use_windows_threads(void);
6

7
/* 自定义锁实现 */
8
int evthread_set_lock_callbacks(const struct evthread_lock_callbacks *cbs);
9
int evthread_set_condition_callbacks(const struct evthread_condition_callbacks *cbs);
10
int evthread_set_id_callback(unsigned long (*id_fn)(void));

3.2 锁回调结构体#

1
struct evthread_lock_callbacks {
2
    int lock_api_version;     // EVTHREAD_LOCK_API_VERSION
3
    unsigned supported_locktypes;  // 支持的锁类型
4
    void *(*alloc)(unsigned locktype);  // 分配锁
5
    void (*free)(void *lock, unsigned locktype);  // 释放锁
6
    int (*lock)(unsigned mode, void *lock);   // 加锁
7
    int (*unlock)(unsigned mode, void *lock); // 解锁
8
};
9

10
/* 锁模式 */
11
#define EVTHREAD_LOCK    0x01
12
#define EVTHREAD_TRY     0x02
13
#define EVTHREAD_UNLOCK  0x04
14

15
/* 锁类型 */
16
#define EVTHREAD_LOCKTYPE_RECURSIVE 1
17
#define EVTHREAD_LOCKTYPE_READWRITE 2

展开收起

四、线程间通信#

4.1 使用socket pair#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <pthread.h>
5
#include <unistd.h>
6
#include <event2/event.h>
7
#include <event2/buffer.h>
8
#include <event2/bufferevent.h>
9

10
static struct event_base *main_base = NULL;
11
static struct bufferevent *main_bev = NULL;
12

13
static void notify_cb(struct bufferevent *bev, void *arg) {
14
    struct evbuffer *input = bufferevent_get_input(bev);
15

16
    char buf[1024];
17
    size_t n;
18
    while ((n = bufferevent_read(bev, buf, sizeof(buf) - 1)) > 0) {
19
        buf[n] = '\0';
20
        printf("Received from worker: %s", buf);
21
    }
22
}
23

24
void *worker_thread(void *arg) {
25
    int notify_fd = *(int *)arg;
26

27
    // 模拟工作
28
    sleep(2);
29

30
    // 通知主线程
31
    const char *msg = "Work done!\n";
32
    write(notify_fd, msg, strlen(msg));
33

34
    return NULL;
35
}
36

37
int main() {
38
    evthread_use_pthreads();
39

40
    main_base = event_base_new();
41

42
    // 创建socket pair
43
    int pair[2];
44
    evutil_socketpair(AF_UNIX, SOCK_STREAM, 0, pair);
45

46
    // 主线程监听pair[0]
47
    main_bev = bufferevent_socket_new(main_base, pair[0], BEV_OPT_CLOSE_ON_FREE);
48
    bufferevent_setcb(main_bev, notify_cb, NULL, NULL, NULL);
49
    bufferevent_enable(main_bev, EV_READ);
50

51
    // 创建工作线程，传递pair[1]
52
    pthread_t tid;
53
    pthread_create(&tid, NULL, worker_thread, &pair[1]);
54

55
    // 设置5秒后退出
56
    struct timeval tv = {5, 0};
57
    event_base_loopexit(main_base, &tv);
58

59
    event_base_dispatch(main_base);
60

61
    pthread_join(tid, NULL);
62

63
    bufferevent_free(main_bev);
64
    event_base_free(main_base);
65

66
    return 0;
67
}

展开收起

4.2 使用bufferevent_pair#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <pthread.h>
4
#include <event2/event.h>
5
#include <event2/buffer.h>
6
#include <event2/bufferevent.h>
7

8
struct thread_data {
9
    struct event_base *base;
10
    struct bufferevent *bev;
11
};
12

13
static void worker_read_cb(struct bufferevent *bev, void *arg) {
14
    struct evbuffer *input = bufferevent_get_input(bev);
15

16
    char buf[1024];
17
    size_t n;
18
    while ((n = bufferevent_read(bev, buf, sizeof(buf) - 1)) > 0) {
19
        buf[n] = '\0';
20
        printf("Worker received: %s", buf);
21

22
        // 回复
23
        bufferevent_write(bev, "ACK\n", 4);
24
    }
25
}
26

27
void *worker_thread(void *arg) {
28
    struct thread_data *data = arg;
29

30
    bufferevent_setcb(data->bev, worker_read_cb, NULL, NULL, NULL);
31
    bufferevent_enable(data->bev, EV_READ | EV_WRITE);
32

33
    event_base_dispatch(data->base);
34

35
    return NULL;
36
}
37

38
int main() {
39
    evthread_use_pthreads();
40

41
    struct event_base *main_base = event_base_new();
42
    struct event_base *worker_base = event_base_new();
43

44
    // 创建bufferevent pair
45
    struct bufferevent *pair[2];
46
    bufferevent_pair_new(worker_base, BEV_OPT_THREADSAFE, pair);
47

48
    // pair[0]给工作线程
49
    struct thread_data data = {worker_base, pair[0]};
50

51
    // pair[1]给主线程
52
    struct bufferevent *main_bev = bufferevent_pair_new(main_base, BEV_OPT_THREADSAFE, pair);
53

54
    // 启动工作线程
55
    pthread_t tid;
56
    pthread_create(&tid, NULL, worker_thread, &data);
57

58
    // 主线程发送消息
59
    sleep(1);
60
    bufferevent_write(pair[1], "Hello from main\n", 16);
61

62
    // 等待回复
63
    sleep(1);
64

65
    // 退出
66
    event_base_loopexit(worker_base, NULL);
67
    event_base_loopexit(main_base, NULL);
68

69
    pthread_join(tid, NULL);
70

71
    bufferevent_free(pair[0]);
72
    bufferevent_free(pair[1]);
73
    event_base_free(worker_base);
74
    event_base_free(main_base);
75

76
    return 0;
77
}

展开收起

五、HTTP服务器C++封装#

1
#include <iostream>
2
#include <string>
3
#include <vector>
4
#include <queue>
5
#include <thread>
6
#include <mutex>
7
#include <condition_variable>
8
#include <memory>
9
#include <event2/event.h>
10
#include <event2/http.h>
11
#include <event2/buffer.h>
12

13
class HttpServer {
14
public:
15
    HttpServer(int port, int thread_num = 4)
16
        : port_(port), thread_num_(thread_num), base_(nullptr) {
17
        evthread_use_pthreads();
18
    }
19

20
    ~HttpServer() {
21
        stop();
22
    }
23

24
    bool start() {
25
        base_ = event_base_new();
26
        if (!base_) return false;
27

28
        http_ = evhttp_new(base_);
29
        if (!http_) return false;
30

31
        if (evhttp_bind_socket(http_, "0.0.0.0", port_) != 0) {
32
            return false;
33
        }
34

35
        evhttp_set_gencb(http_, HttpServer::generic_callback, this);
36

37
        // 启动工作线程
38
        for (int i = 0; i < thread_num_; i++) {
39
            threads_.emplace_back(&HttpServer::worker_loop, this);
40
        }
41

42
        std::cout << "HTTP server started on port " << port_ << std::endl;
43

44
        event_base_dispatch(base_);
45

46
        return true;
47
    }
48

49
    void stop() {
50
        if (base_) {
51
            event_base_loopbreak(base_);
52
        }
53

54
        for (auto& t : threads_) {
55
            if (t.joinable()) {
56
                t.join();
57
            }
58
        }
59

60
        if (http_) {
61
            evhttp_free(http_);
62
            http_ = nullptr;
63
        }
64

65
        if (base_) {
66
            event_base_free(base_);
67
            base_ = nullptr;
68
        }
69
    }
70

71
private:
72
    static void generic_callback(struct evhttp_request *req, void *arg) {
73
        HttpServer *server = static_cast<HttpServer*>(arg);
74
        server->handle_request(req);
75
    }
76

77
    void handle_request(struct evhttp_request *req) {
78
        struct evbuffer *buf = evbuffer_new();
79

80
        evbuffer_add_printf(buf, "<html><body>");
81
        evbuffer_add_printf(buf, "<h1>Hello from libevent HTTP Server</h1>");
82
        evbuffer_add_printf(buf, "<p>URI: %s</p>", evhttp_request_get_uri(req));
83
        evbuffer_add_printf(buf, "</body></html>");
84

85
        evhttp_add_header(evhttp_request_get_output_headers(req),
86
                          "Content-Type", "text/html");
87
        evhttp_send_reply(req, HTTP_OK, "OK", buf);
88

89
        evbuffer_free(buf);
90
    }
91

92
    void worker_loop() {
93
        // 工作线程可以处理其他任务
94
        while (true) {
95
            // 这里可以添加任务队列处理逻辑
96
            std::this_thread::sleep_for(std::chrono::milliseconds(100));
97
        }
98
    }
99

100
    int port_;
101
    int thread_num_;
102
    struct event_base *base_;
103
    struct evhttp *http_;
104
    std::vector<std::thread> threads_;
105
};
106

107
int main() {
108
    HttpServer server(8080, 4);
109

110
    if (!server.start()) {
111
        std::cerr << "Failed to start server" << std::endl;
112
        return 1;
113
    }
114

115
    return 0;
116
}

展开收起

六、最佳实践#

建议	说明
初始化顺序	先调用evthread_use_pthreads()，再创建event_base
锁粒度	尽量减少锁的持有时间
避免死锁	注意锁的获取顺序
线程池	对于CPU密集型任务使用线程池
资源清理	确保线程退出前释放所有资源

其他相关资料请移步到个人主页

🚀 性能调优指南 - libevent源码深度解析系列（二十五）

Sat, 11 Apr 2026 00:00:00 GMT

🚀 性能调优指南#

一、概述#

在生产环境中使用libevent时，性能调优至关重要。本章将从多个维度介绍libevent的性能优化策略，包括性能瓶颈分析、事件循环优化、内存管理、多线程扩展、系统调优等方面。

二、性能瓶颈分析#

2.1 常见性能瓶颈#

瓶颈类型	表现症状	原因分析	优化方向
事件循环阻塞	CPU使用率低，响应延迟高	回调函数执行时间过长	缩短回调处理时间，使用线程池
系统调用频繁	系统调用次数高	事件频繁触发，缓冲区水位设置不当	调整缓冲区水位，使用changelist
内存分配频繁	内存碎片多，GC压力大	频繁的小内存分配	使用内存池，自定义内存分配器
锁竞争严重	多线程场景下性能下降	线程间共享资源竞争	减少锁范围，使用无锁数据结构
DNS解析延迟	连接建立时间长	同步DNS解析，DNS服务器响应慢	使用异步DNS，实现DNS缓存
网络I/O瓶颈	网络吞吐量低	TCP参数配置不当，缓冲区大小不合理	优化TCP参数，调整缓冲区大小

2.2 性能分析工具#

Terminal window展开收起

1
# 使用strace分析系统调用
2
strace -c -p <pid>
3

4
# 使用perf分析CPU使用情况
5
perf record -g -p <pid>
6
perf report
7

8
# 使用valgrind分析内存使用
9
valgrind --tool=massif ./your_program
10

11
# 使用pmap分析内存映射
12
pmap -x <pid>
13

14
# 使用netstat分析网络连接
15
netstat -ant | grep ESTABLISHED

展开收起

2.3 性能瓶颈定位方法#

系统层面：使用 top、vmstat、iostat 监控系统资源使用
进程层面：使用 ps、pmap 监控进程状态和内存使用
网络层面：使用 netstat、tcpdump 监控网络连接和流量
应用层面：实现自定义监控，统计关键指标

三、事件循环优化#

3.1 选择合适的后端#

1
#include <stdio.h>
2
#include <event2/event.h>
3

4
void print_available_backends(void) {
5
    const char **methods = event_get_supported_methods();
6

7
    printf("Supported backends:\n");
8
    for (int i = 0; methods[i] != NULL; i++) {
9
        printf("  - %s\n", methods[i]);
10
    }
11
}
12

13
struct event_base *create_optimized_base(void) {
14
    struct event_config *cfg = event_config_new();
15

16
    // 优先使用epoll（Linux）
17
    event_config_avoid_method(cfg, "select");
18
    event_config_avoid_method(cfg, "poll");
19

20
    // 或明确指定后端
21
    // event_config_set_flag(cfg, EVENT_BASE_FLAG_EPOLL_USE_CHANGELIST);
22

23
    struct event_base *base = event_base_new_with_config(cfg);
24
    event_config_free(cfg);
25

26
    printf("Using backend: %s\n", event_base_get_method(base));
27
    return base;
28
}

展开收起

3.2 event_config标志#

1
#include <event2/event.h>
2

3
struct event_base *create_base_with_flags(void) {
4
    struct event_config *cfg = event_config_new();
5

6
    // 使用changelist优化（减少系统调用）
7
    event_config_set_flag(cfg, EVENT_BASE_FLAG_EPOLL_USE_CHANGELIST);
8

9
    // 忽略SIGPIPE
10
    event_config_set_flag(cfg, EVENT_BASE_FLAG_IGNORE_ENV);
11

12
    // 不使用eventfd（某些场景）
13
    // event_config_set_flag(cfg, EVENT_BASE_FLAG_NOLOCK);
14

15
    struct event_base *base = event_base_new_with_config(cfg);
16
    event_config_free(cfg);
17

18
    return base;
19
}

展开收起

3.3 配置标志说明#

标志	说明	适用场景
`EVENT_BASE_FLAG_NOLOCK`	禁用锁	单线程环境
`EVENT_BASE_FLAG_IGNORE_ENV`	忽略环境变量	生产环境
`EVENT_BASE_FLAG_STARTUP_IOCP`	启用IOCP	Windows
`EVENT_BASE_FLAG_NO_CACHE_TIME`	不缓存时间	高精度计时
`EVENT_BASE_FLAG_EPOLL_USE_CHANGELIST`	使用changelist	Linux高并发

3.4 事件循环性能优化策略#

减少事件触发频率：合理设置缓冲区水位，避免频繁的读写事件
优化事件回调：回调函数应简洁，避免阻塞操作
批量处理：使用批量读取和处理，减少系统调用
合理使用超时：设置适当的超时时间，避免资源泄漏
避免事件风暴：使用背压机制，控制事件处理速率

四、内存管理优化#

1
#include <stdio.h>
2
#include <event2/event.h>
3

4
void print_available_backends(void) {
5
    const char **methods = event_get_supported_methods();
6

7
    printf("Supported backends:\n");
8
    for (int i = 0; methods[i] != NULL; i++) {
9
        printf("  - %s\n", methods[i]);
10
    }
11
}
12

13
struct event_base *create_optimized_base(void) {
14
    struct event_config *cfg = event_config_new();
15

16
    // 优先使用epoll（Linux）
17
    event_config_avoid_method(cfg, "select");
18
    event_config_avoid_method(cfg, "poll");
19

20
    // 或明确指定后端
21
    // event_config_set_flag(cfg, EVENT_BASE_FLAG_EPOLL_USE_CHANGELIST);
22

23
    struct event_base *base = event_base_new_with_config(cfg);
24
    event_config_free(cfg);
25

26
    printf("Using backend: %s\n", event_base_get_method(base));
27
    return base;
28
}

展开收起

2.2 event_config标志#

1
#include <event2/event.h>
2

3
struct event_base *create_base_with_flags(void) {
4
    struct event_config *cfg = event_config_new();
5

6
    // 使用changelist优化（减少系统调用）
7
    event_config_set_flag(cfg, EVENT_BASE_FLAG_EPOLL_USE_CHANGELIST);
8

9
    // 忽略SIGPIPE
10
    event_config_set_flag(cfg, EVENT_BASE_FLAG_IGNORE_ENV);
11

12
    // 不使用eventfd（某些场景）
13
    // event_config_set_flag(cfg, EVENT_BASE_FLAG_NOLOCK);
14

15
    struct event_base *base = event_base_new_with_config(cfg);
16
    event_config_free(cfg);
17

18
    return base;
19
}

展开收起

2.3 配置标志说明#

标志	说明	适用场景
`EVENT_BASE_FLAG_NOLOCK`	禁用锁	单线程环境
`EVENT_BASE_FLAG_IGNORE_ENV`	忽略环境变量	生产环境
`EVENT_BASE_FLAG_STARTUP_IOCP`	启用IOCP	Windows
`EVENT_BASE_FLAG_NO_CACHE_TIME`	不缓存时间	高精度计时
`EVENT_BASE_FLAG_EPOLL_USE_CHANGELIST`	使用changelist	Linux高并发

三、内存管理优化#

3.1 自定义内存分配器#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <event2/event.h>
4

5
static size_t g_total_allocated = 0;
6

7
static void *my_malloc(size_t size) {
8
    void *ptr = malloc(size);
9
    if (ptr) {
10
        g_total_allocated += size;
11
    }
12
    return ptr;
13
}
14

15
static void *my_realloc(void *ptr, size_t size) {
16
    return realloc(ptr, size);
17
}
18

19
static void my_free(void *ptr) {
20
    free(ptr);
21
}
22

23
void setup_custom_allocator(void) {
24
    event_set_mem_functions(my_malloc, my_realloc, my_free);
25
    printf("Custom memory allocator installed\n");
26
}

展开收起

3.2 内存池模式#

1
#include <stdlib.h>
2
#include <string.h>
3

4
#define POOL_SIZE 1024
5
#define BLOCK_SIZE 4096
6

7
typedef struct {
8
    char blocks[POOL_SIZE][BLOCK_SIZE];
9
    int free_list[POOL_SIZE];
10
    int free_count;
11
} memory_pool_t;
12

13
static memory_pool_t g_pool;
14

15
void pool_init(void) {
16
    g_pool.free_count = POOL_SIZE;
17
    for (int i = 0; i < POOL_SIZE; i++) {
18
        g_pool.free_list[i] = i;
19
    }
20
}
21

22
void *pool_alloc(size_t size) {
23
    if (size > BLOCK_SIZE || g_pool.free_count == 0) {
24
        return malloc(size);
25
    }
26

27
    int idx = g_pool.free_list[--g_pool.free_count];
28
    return g_pool.blocks[idx];
29
}
30

31
void pool_free(void *ptr) {
32
    char *p = (char *)ptr;
33

34
    if (p >= (char *)g_pool.blocks &&
35
        p < (char *)g_pool.blocks + POOL_SIZE * BLOCK_SIZE) {
36
        int idx = (p - (char *)g_pool.blocks) / BLOCK_SIZE;
37
        g_pool.free_list[g_pool.free_count++] = idx;
38
    } else {
39
        free(ptr);
40
    }
41
}

展开收起

四、bufferevent优化#

4.1 缓冲区大小调整#

1
#include <event2/bufferevent.h>
2

3
void optimize_bufferevent(struct bufferevent *bev) {
4
    // 设置读写缓冲区水位
5
    bufferevent_setwatermark(bev, EV_READ, 0, 65536);   // 读高水位64KB
6
    bufferevent_setwatermark(bev, EV_WRITE, 4096, 0);   // 写低水位4KB
7

8
    // 设置超时
9
    struct timeval tv = {30, 0};  // 30秒
10
    bufferevent_set_timeouts(bev, &tv, &tv);
11

12
    // 启用延迟回调（减少锁竞争）
13
    bufferevent_setcb(bev, read_cb, write_cb, event_cb, NULL);
14
}

4.2 批量数据处理#

1
#include <event2/bufferevent.h>
2
#include <event2/buffer.h>
3

4
static void optimized_read_cb(struct bufferevent *bev, void *arg) {
5
    struct evbuffer *input = bufferevent_get_input(bev);
6
    size_t total_len = evbuffer_get_length(input);
7

8
    // 批量处理，避免多次小读取
9
    if (total_len < 4096) {
10
        return;  // 等待更多数据
11
    }
12

13
    // 使用peek避免数据复制
14
    struct evbuffer_iovec vec[4];
15
    int n = evbuffer_peek(input, -1, NULL, vec, 4);
16

17
    for (int i = 0; i < n; i++) {
18
        process_data(vec[i].iov_base, vec[i].iov_len);
19
    }
20

21
    // 丢弃已处理的数据
22
    evbuffer_drain(input, total_len);
23
}

展开收起

五、多线程优化#

5.1 线程池模型#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <pthread.h>
4
#include <event2/event.h>
5
#include <event2/thread.h>
6

7
#define NUM_WORKERS 4
8

9
typedef struct {
10
    pthread_t thread;
11
    struct event_base *base;
12
    int notify_fd[2];
13
    struct event *notify_event;
14
} worker_t;
15

16
static worker_t workers[NUM_WORKERS];
17

18
static void *worker_loop(void *arg) {
19
    worker_t *worker = arg;
20
    event_base_dispatch(worker->base);
21
    return NULL;
22
}
23

24
static void notify_cb(evutil_socket_t fd, short events, void *arg) {
25
    char buf[1];
26
    read(fd, buf, 1);
27
    // 处理任务
28
}
29

30
void init_thread_pool(void) {
31
    evthread_use_pthreads();
32

33
    for (int i = 0; i < NUM_WORKERS; i++) {
34
        workers[i].base = event_base_new();
35

36
        // 创建通知管道
37
        evutil_socketpair(AF_UNIX, SOCK_STREAM, 0, workers[i].notify_fd);
38
        evutil_make_socket_nonblocking(workers[i].notify_fd[0]);
39
        evutil_make_socket_nonblocking(workers[i].notify_fd[1]);
40

41
        // 监听通知
42
        workers[i].notify_event = event_new(workers[i].base,
43
            workers[i].notify_fd[0], EV_READ | EV_PERSIST, notify_cb, &workers[i]);
44
        event_add(workers[i].notify_event, NULL);
45

46
        pthread_create(&workers[i].thread, NULL, worker_loop, &workers[i]);
47
    }
48
}
49

50
void dispatch_to_worker(int worker_id, void (*task)(void *), void *arg) {
51
    // 发送通知到worker
52
    write(workers[worker_id].notify_fd[1], "T", 1);
53
}

展开收起

5.2 连接分发策略#

1
#include <stdatomic.h>
2

3
static atomic_int g_next_worker = 0;
4

5
int get_next_worker(void) {
6
    return atomic_fetch_add(&g_next_worker, 1) % NUM_WORKERS;
7
}
8

9
void accept_cb(struct evconnlistener *listener, evutil_socket_t fd,
10
               struct sockaddr *addr, int len, void *arg) {
11
    int worker_id = get_next_worker();
12

13
    // 将连接分发给worker
14
    dispatch_connection_to_worker(worker_id, fd, addr, len);
15
}

展开收起

六、I/O多路复用调优#

6.1 文件描述符限制#

Terminal window

1
# 查看当前限制
2
ulimit -n
3

4
# 临时修改
5
ulimit -n 65535
6

7
# 永久修改（/etc/security/limits.conf）
8
* soft nofile 65535
9
* hard nofile 65535

6.2 内核参数调优#

/etc/sysctl.conf展开收起

1
# 最大文件描述符
2
fs.file-max = 1000000
3

4
# TCP连接队列
5
net.core.somaxconn = 65535
6
net.ipv4.tcp_max_syn_backlog = 65535
7

8
# TCP缓冲区
9
net.core.rmem_max = 16777216
10
net.core.wmem_max = 16777216
11
net.ipv4.tcp_rmem = 4096 87380 16777216
12
net.ipv4.tcp_wmem = 4096 65536 16777216
13

14
# TIME_WAIT优化
15
net.ipv4.tcp_tw_reuse = 1
16
net.ipv4.tcp_fin_timeout = 30
17

18
# 应用配置
19
sysctl -p

展开收起

七、DNS优化#

7.1 DNS缓存#

1
#include <stdio.h>
2
#include <string.h>
3
#include <time.h>
4
#include <event2/event.h>
5
#include <event2/dns.h>
6

7
#define DNS_CACHE_SIZE 1024
8
#define DNS_CACHE_TTL 300  // 5分钟
9

10
typedef struct {
11
    char hostname[256];
12
    struct in_addr addr;
13
    time_t expire;
14
} dns_cache_entry_t;
15

16
static dns_cache_entry_t dns_cache[DNS_CACHE_SIZE];
17
static int dns_cache_count = 0;
18

19
struct in_addr *dns_cache_lookup(const char *hostname) {
20
    time_t now = time(NULL);
21

22
    for (int i = 0; i < dns_cache_count; i++) {
23
        if (strcmp(dns_cache[i].hostname, hostname) == 0) {
24
            if (dns_cache[i].expire > now) {
25
                return &dns_cache[i].addr;
26
            }
27
            // 过期，移除
28
            dns_cache[i] = dns_cache[--dns_cache_count];
29
            return NULL;
30
        }
31
    }
32
    return NULL;
33
}
34

35
void dns_cache_store(const char *hostname, struct in_addr addr) {
36
    if (dns_cache_count >= DNS_CACHE_SIZE) {
37
        return;  // 缓存满
38
    }
39

40
    strncpy(dns_cache[dns_cache_count].hostname, hostname, 255);
41
    dns_cache[dns_cache_count].addr = addr;
42
    dns_cache[dns_cache_count].expire = time(NULL) + DNS_CACHE_TTL;
43
    dns_cache_count++;
44
}

展开收起

7.2 DNS配置优化#

1
#include <event2/dns.h>
2

3
void optimize_dns(struct evdns_base *dns_base) {
4
    // 设置超时
5
    evdns_base_set_option(dns_base, "timeout", "2");
6

7
    // 设置重试次数
8
    evdns_base_set_option(dns_base, "attempts", "2");
9

10
    // 添加多个DNS服务器
11
    evdns_base_nameserver_ip_add(dns_base, "8.8.8.8");
12
    evdns_base_nameserver_ip_add(dns_base, "8.8.4.4");
13
    evdns_base_nameserver_ip_add(dns_base, "1.1.1.1");
14

15
    // 启用DNS缓存（应用层实现）
16
}

展开收起

八、HTTP优化#

8.1 连接复用#

1
#include <event2/http.h>
2
#include <event2/http_connection.h>
3

4
static struct evhttp_connection *g_http_conn = NULL;
5

6
struct evhttp_connection *get_http_connection(struct event_base *base,
7
                                               struct evdns_base *dns_base) {
8
    if (!g_http_conn) {
9
        g_http_conn = evhttp_connection_base_new(base, dns_base,
10
                                                  "api.example.com", 80);
11
        evhttp_connection_set_timeout(g_http_conn, 30);
12
        evhttp_connection_set_retries(g_http_conn, 3);
13
    }
14
    return g_http_conn;
15
}

展开收起

8.2 HTTP服务器优化#

1
#include <event2/http.h>
2

3
void optimize_http_server(struct evhttp *http) {
4
    // 设置最大body大小
5
    evhttp_set_max_body_size(http, 10 * 1024 * 1024);  // 10MB
6

7
    // 设置最大headers大小
8
    evhttp_set_max_headers_size(http, 8192);
9

10
    // 设置超时
11
    evhttp_set_timeout(http, 30);
12

13
    // 设置支持的Content-Type
14
    evhttp_set_allowed_methods(http,
15
        EVHTTP_REQ_GET | EVHTTP_REQ_POST | EVHTTP_REQ_PUT | EVHTTP_REQ_DELETE);
16
}

展开收起

九、监控与统计#

9.1 性能统计#

1
#include <stdio.h>
2
#include <time.h>
3
#include <stdatomic.h>
4

5
typedef struct {
6
    atomic_ulong connections_total;
7
    atomic_ulong connections_active;
8
    atomic_ulong bytes_read;
9
    atomic_ulong bytes_written;
10
    atomic_ulong requests_total;
11
    atomic_ulong requests_failed;
12
    time_t start_time;
13
} server_stats_t;
14

15
static server_stats_t g_stats = {0};
16

17
void stats_init(void) {
18
    g_stats.start_time = time(NULL);
19
}
20

21
void stats_print(void) {
22
    time_t now = time(NULL);
23
    double uptime = difftime(now, g_stats.start_time);
24

25
    printf("\n=== Server Statistics ===\n");
26
    printf("Uptime: %.0f seconds\n", uptime);
27
    printf("Total connections: %lu\n", g_stats.connections_total);
28
    printf("Active connections: %lu\n", g_stats.connections_active);
29
    printf("Bytes read: %lu (%.2f MB)\n",
30
           g_stats.bytes_read, (double)g_stats.bytes_read / (1024 * 1024));
31
    printf("Bytes written: %lu (%.2f MB)\n",
32
           g_stats.bytes_written, (double)g_stats.bytes_written / (1024 * 1024));
33
    printf("Requests: %lu total, %lu failed\n",
34
           g_stats.requests_total, g_stats.requests_failed);
35
    printf("Throughput: %.2f req/s, %.2f KB/s read, %.2f KB/s write\n",
36
           g_stats.requests_total / uptime,
37
           (double)g_stats.bytes_read / uptime / 1024,
38
           (double)g_stats.bytes_written / uptime / 1024);
39
    printf("=========================\n\n");
40
}

展开收起

9.2 定时统计输出#

1
#include <event2/event.h>
2

3
static void stats_timer_cb(evutil_socket_t fd, short events, void *arg) {
4
    stats_print();
5
}
6

7
void setup_stats_timer(struct event_base *base) {
8
    struct event *timer = event_new(base, -1, EV_PERSIST, stats_timer_cb, NULL);
9
    struct timeval interval = {60, 0};  // 每分钟
10
    event_add(timer, &interval);
11
}

十、性能测试工具#

10.1 基准测试#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <time.h>
5
#include <event2/event.h>
6
#include <event2/bufferevent.h>
7

8
#define NUM_ITERATIONS 1000000
9

10
static struct event_base *g_base = NULL;
11
static struct bufferevent *g_pair[2] = {NULL, NULL};
12
static atomic_int g_counter = 0;
13
static struct timespec g_start_time;
14

15
static void read_cb(struct bufferevent *bev, void *arg) {
16
    char buf[64];
17
    bufferevent_read(bev, buf, sizeof(buf));
18

19
    if (++g_counter >= NUM_ITERATIONS) {
20
        struct timespec end_time;
21
        clock_gettime(CLOCK_MONOTONIC, &end_time);
22

23
        double elapsed = (end_time.tv_sec - g_start_time.tv_sec) +
24
                         (end_time.tv_nsec - g_start_time.tv_nsec) / 1e9;
25

26
        printf("Benchmark completed:\n");
27
        printf("  Iterations: %d\n", NUM_ITERATIONS);
28
        printf("  Time: %.3f seconds\n", elapsed);
29
        printf("  Throughput: %.0f ops/s\n", NUM_ITERATIONS / elapsed);
30

31
        event_base_loopbreak(g_base);
32
    } else {
33
        bufferevent_write(g_pair[0], "ping", 4);
34
    }
35
}
36

37
void run_benchmark(void) {
38
    g_base = event_base_new();
39
    bufferevent_pair_new(g_base, 0, g_pair);
40

41
    bufferevent_setcb(g_pair[1], read_cb, NULL, NULL, NULL);
42
    bufferevent_enable(g_pair[1], EV_READ);
43

44
    clock_gettime(CLOCK_MONOTONIC, &g_start_time);
45
    bufferevent_write(g_pair[0], "ping", 4);
46

47
    event_base_dispatch(g_base);
48

49
    bufferevent_free(g_pair[0]);
50
    bufferevent_free(g_pair[1]);
51
    event_base_free(g_base);
52
}

展开收起

十一、性能优化清单#

11.1 启动前检查#

项目	检查项	建议
系统限制	`ulimit -n`	>= 65535
内核参数	`sysctl`	按需调整
后端选择	epoll/kqueue	优先使用
线程安全	`evthread_use_pthreads`	多线程必须

11.2 运行时优化#

项目	优化项	说明
缓冲区	设置合适的水位	避免频繁回调
超时	设置合理的超时	避免资源泄漏
DNS	使用缓存	减少DNS查询
连接	复用连接	减少连接开销

11.3 监控指标#

指标	说明	告警阈值
连接数	当前活跃连接	> 80% 容量
内存	进程内存使用	> 80% 限制
延迟	请求处理时间	> 100ms
错误率	请求失败比例	> 1%

十二、生产环境优化最佳实践#

12.1 部署策略#

多实例部署：使用多个进程实例，充分利用多核CPU
负载均衡：使用Nginx或HAProxy进行负载均衡
容器化：使用Docker容器化部署，便于水平扩展
自动扩缩容：根据负载自动调整实例数量

12.2 配置管理#

/etc/libevent-server.conf展开收起

1
# 生产环境配置文件示例
2
# 服务器配置
3
PORT=8080
4
WORKER_PROCESSES=4
5
MAX_CONNECTIONS=10000
6

7
# 性能配置
8
BUFFER_SIZE=65536
9
READ_TIMEOUT=30
10
WRITE_TIMEOUT=30
11

12
# 日志配置
13
LOG_LEVEL=info
14
LOG_FILE=/var/log/libevent-server.log
15

16
# 监控配置
17
STATS_INTERVAL=60
18
METRICS_PORT=9100

展开收起

12.3 故障恢复#

优雅重启：支持平滑重启，不中断服务
健康检查：定期检查服务状态
自动恢复：进程崩溃后自动重启
数据持久化：关键数据定期持久化

12.4 安全优化#

连接限制：防止DoS攻击，限制单IP连接数
输入验证：严格验证输入数据，防止注入攻击
SSL/TLS：使用HTTPS，保护数据传输
权限控制：最小权限原则，限制进程权限

12.5 性能测试与基准#

Terminal window

1
# 使用wrk进行性能测试
2
wrk -t12 -c400 -d30s http://localhost:8080/
3

4
# 使用ab进行基准测试
5
ab -n 10000 -c 100 http://localhost:8080/
6

7
# 使用siege进行压力测试
8
siege -c 100 -t 30S http://localhost:8080/

12.6 常见问题排查#

问题	症状	排查方法	解决方案
连接数过多	系统负载高，响应慢	`netstat -ant	grep ESTABLISHED
内存泄漏	内存使用持续增长	`pmap -x <pid>`, `valgrind`	检查内存分配，使用内存池
CPU使用率高	系统负载高	`top`, `perf`	分析热点函数，优化算法
网络延迟高	响应时间长	`ping`, `traceroute`	检查网络链路，优化TCP参数

十三、性能调优案例#

13.1 高并发Web服务器优化#

场景：处理10000+并发连接的Web服务器

优化措施：

使用epoll后端，启用changelist
设置合理的缓冲区水位：读高水位64KB，写低水位4KB
使用线程池处理CPU密集型任务
实现连接池，复用HTTP连接
启用DNS缓存，减少DNS查询

效果：

并发连接数提升300%
响应时间降低60%
系统资源使用率降低40%

13.2 实时聊天服务器优化#

场景：实时消息推送，要求低延迟

优化措施：

使用kqueue后端（FreeBSD/macOS）
减少事件回调处理时间，使用非阻塞IO
批量处理消息，减少系统调用
使用无锁数据结构，减少锁竞争
优化内存分配，使用内存池

效果：

消息延迟降低70%
系统吞吐量提升250%
内存使用降低30%

其他相关资料请移步到个人主页

⚡ 速率限制 - libevent源码深度解析系列（二十三）

Sat, 11 Apr 2026 00:00:00 GMT

⚡ 速率限制#

一、概述#

libevent提供了速率限制（Rate Limiting）功能，用于控制数据传输的带宽。这对于防止服务器过载、公平分配资源、实现流量整形等场景非常有用。

二、速率限制结构体#

2.1 ev_token_bucket_cfg#

1
struct ev_token_bucket_cfg {
2
    size_t read_rate;       // 读取速率（字节/秒）
3
    size_t read_burst;      // 读取突发大小（字节）
4
    size_t write_rate;      // 写入速率（字节/秒）
5
    size_t write_burst;     // 写入突发大小（字节）
6
    struct timeval tick_len; // 时间片长度
7
};

2.2 bufferevent_rate_limit_group#

1
struct bufferevent_rate_limit_group {
2
    struct event_base *base;
3
    struct ev_token_bucket_cfg cfg;
4
    struct ev_token_bucket bucket;
5
    struct bufferevent **members;
6
    int n_members;
7
    // ...
8
};

三、令牌桶配置#

3.1 创建配置#

1
#include <event2/bufferevent.h>
2

3
/* 创建令牌桶配置
4
 * @param read_rate   读取速率（字节/秒），0表示无限制
5
 * @param read_burst  读取突发大小（字节）
6
 * @param write_rate  写入速率（字节/秒），0表示无限制
7
 * @param write_burst 写入突发大小（字节）
8
 * @param tick_len    时间片长度（NULL使用默认值）
9
 */
10
struct ev_token_bucket_cfg *ev_token_bucket_cfg_new(
11
    size_t read_rate, size_t read_burst,
12
    size_t write_rate, size_t write_burst,
13
    const struct timeval *tick_len);
14

15
/* 释放配置 */
16
void ev_token_bucket_cfg_free(struct ev_token_bucket_cfg *cfg);
17

18
/* 设置时间片长度 */
19
int ev_token_bucket_cfg_set_tick_len(struct ev_token_bucket_cfg *cfg,
20
    const struct timeval *tick_len);

展开收起

3.2 配置示例#

1
#include <stdio.h>
2
#include <event2/event.h>
3
#include <event2/bufferevent.h>
4

5
int main() {
6
    // 创建配置：限制读取100KB/s，写入50KB/s
7
    struct ev_token_bucket_cfg *cfg = ev_token_bucket_cfg_new(
8
        102400,    // 读取速率：100KB/s
9
        102400,    // 读取突发：100KB
10
        51200,     // 写入速率：50KB/s
11
        51200,     // 写入突发：50KB
12
        NULL       // 使用默认时间片
13
    );
14

15
    if (!cfg) {
16
        fprintf(stderr, "Failed to create token bucket config\n");
17
        return 1;
18
    }
19

20
    printf("Token bucket config created\n");
21
    printf("Read rate: 100KB/s, Write rate: 50KB/s\n");
22

23
    ev_token_bucket_cfg_free(cfg);
24
    return 0;
25
}

展开收起

四、单个bufferevent限速#

4.1 设置限速#

1
/* 为bufferevent设置速率限制 */
2
int bufferevent_set_rate_limit(struct bufferevent *bev,
3
    struct ev_token_bucket_cfg *cfg);
4

5
/* 取消速率限制 */
6
int bufferevent_set_rate_limit(struct bufferevent *bev, NULL);
7

8
/* 获取速率限制状态 */
9
ev_ssize_t bufferevent_get_read_limit(struct bufferevent *bev);
10
ev_ssize_t bufferevent_get_write_limit(struct bufferevent *bev);
11

12
/* 获取当前速率 */
13
ev_ssize_t bufferevent_get_max_to_read(struct bufferevent *bev);
14
ev_ssize_t bufferevent_get_max_to_write(struct bufferevent *bev);
15

16
/* 获取已传输字节数 */
17
ev_uint64_t bufferevent_get_bytes_read(struct bufferevent *bev);
18
ev_uint64_t bufferevent_get_bytes_written(struct bufferevent *bev);

展开收起

4.2 单连接限速示例#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <event2/event.h>
5
#include <event2/listener.h>
6
#include <event2/bufferevent.h>
7

8
static struct ev_token_bucket_cfg *g_rate_cfg = NULL;
9

10
static void read_cb(struct bufferevent *bev, void *arg) {
11
    char buf[4096];
12
    size_t n;
13

14
    while ((n = bufferevent_read(bev, buf, sizeof(buf))) > 0) {
15
        // 回显数据
16
        bufferevent_write(bev, buf, n);
17
    }
18

19
    // 打印统计信息
20
    printf("Bytes read: %llu, written: %llu\n",
21
           (unsigned long long)bufferevent_get_bytes_read(bev),
22
           (unsigned long long)bufferevent_get_bytes_written(bev));
23
}
24

25
static void event_cb(struct bufferevent *bev, short events, void *arg) {
26
    if (events & (BEV_EVENT_EOF | BEV_EVENT_ERROR)) {
27
        printf("Connection closed\n");
28
        bufferevent_free(bev);
29
    }
30
}
31

32
static void accept_cb(struct evconnlistener *listener, evutil_socket_t fd,
33
                      struct sockaddr *addr, int len, void *arg) {
34
    struct event_base *base = arg;
35

36
    printf("New connection\n");
37

38
    struct bufferevent *bev = bufferevent_socket_new(base, fd, BEV_OPT_CLOSE_ON_FREE);
39

40
    // 应用速率限制
41
    bufferevent_set_rate_limit(bev, g_rate_cfg);
42

43
    bufferevent_setcb(bev, read_cb, NULL, event_cb, NULL);
44
    bufferevent_enable(bev, EV_READ | EV_WRITE);
45
}
46

47
int main() {
48
    struct event_base *base = event_base_new();
49

50
    // 创建速率限制配置：限制每个连接100KB/s
51
    g_rate_cfg = ev_token_bucket_cfg_new(
52
        102400, 102400,  // 读取：100KB/s
53
        102400, 102400,  // 写入：100KB/s
54
        NULL
55
    );
56

57
    struct sockaddr_in sin;
58
    memset(&sin, 0, sizeof(sin));
59
    sin.sin_family = AF_INET;
60
    sin.sin_port = htons(8080);
61
    sin.sin_addr.s_addr = INADDR_ANY;
62

63
    struct evconnlistener *listener = evconnlistener_new_bind(
64
        base, accept_cb, base,
65
        LEV_OPT_CLOSE_ON_FREE | LEV_OPT_REUSEABLE,
66
        -1, (struct sockaddr *)&sin, sizeof(sin));
67

68
    printf("Server listening on port 8080\n");
69
    printf("Rate limit: 100KB/s per connection\n");
70

71
    event_base_dispatch(base);
72

73
    evconnlistener_free(listener);
74
    ev_token_bucket_cfg_free(g_rate_cfg);
75
    event_base_free(base);
76

77
    return 0;
78
}

展开收起

五、速率限制组#

5.1 创建速率限制组#

1
/* 创建速率限制组 */
2
struct bufferevent_rate_limit_group *bufferevent_rate_limit_group_new(
3
    struct event_base *base,
4
    const struct ev_token_bucket_cfg *cfg);
5

6
/* 释放速率限制组 */
7
void bufferevent_rate_limit_group_free(struct bufferevent_rate_limit_group *grp);
8

9
/* 将bufferevent加入组 */
10
int bufferevent_add_to_rate_limit_group(struct bufferevent *bev,
11
    struct bufferevent_rate_limit_group *grp);
12

13
/* 将bufferevent从组中移除 */
14
int bufferevent_remove_from_rate_limit_group(struct bufferevent *bev);
15

16
/* 获取组成员数量 */
17
int bufferevent_rate_limit_group_get_members(
18
    struct bufferevent_rate_limit_group *grp,
19
    struct bufferevent **members, int n_members);

展开收起

5.2 组级别限速示例#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <event2/event.h>
5
#include <event2/listener.h>
6
#include <event2/bufferevent.h>
7

8
static struct bufferevent_rate_limit_group *g_rate_group = NULL;
9

10
static void read_cb(struct bufferevent *bev, void *arg) {
11
    char buf[4096];
12
    size_t n;
13

14
    while ((n = bufferevent_read(bev, buf, sizeof(buf))) > 0) {
15
        bufferevent_write(bev, buf, n);
16
    }
17
}
18

19
static void event_cb(struct bufferevent *bev, short events, void *arg) {
20
    if (events & (BEV_EVENT_EOF | BEV_EVENT_ERROR)) {
21
        printf("Connection closed\n");
22
        bufferevent_remove_from_rate_limit_group(bev);
23
        bufferevent_free(bev);
24
    }
25
}
26

27
static void accept_cb(struct evconnlistener *listener, evutil_socket_t fd,
28
                      struct sockaddr *addr, int len, void *arg) {
29
    struct event_base *base = arg;
30

31
    printf("New connection\n");
32

33
    struct bufferevent *bev = bufferevent_socket_new(base, fd, BEV_OPT_CLOSE_ON_FREE);
34

35
    // 加入速率限制组
36
    bufferevent_add_to_rate_limit_group(bev, g_rate_group);
37

38
    bufferevent_setcb(bev, read_cb, NULL, event_cb, NULL);
39
    bufferevent_enable(bev, EV_READ | EV_WRITE);
40
}
41

42
int main() {
43
    struct event_base *base = event_base_new();
44

45
    // 创建组级别速率限制：总带宽1MB/s
46
    struct ev_token_bucket_cfg *cfg = ev_token_bucket_cfg_new(
47
        1048576, 1048576,  // 读取：1MB/s
48
        1048576, 1048576,  // 写入：1MB/s
49
        NULL
50
    );
51

52
    g_rate_group = bufferevent_rate_limit_group_new(base, cfg);
53

54
    struct sockaddr_in sin;
55
    memset(&sin, 0, sizeof(sin));
56
    sin.sin_family = AF_INET;
57
    sin.sin_port = htons(8080);
58
    sin.sin_addr.s_addr = INADDR_ANY;
59

60
    struct evconnlistener *listener = evconnlistener_new_bind(
61
        base, accept_cb, base,
62
        LEV_OPT_CLOSE_ON_FREE | LEV_OPT_REUSEABLE,
63
        -1, (struct sockaddr *)&sin, sizeof(sin));
64

65
    printf("Server listening on port 8080\n");
66
    printf("Total rate limit: 1MB/s for all connections\n");
67

68
    event_base_dispatch(base);
69

70
    evconnlistener_free(listener);
71
    bufferevent_rate_limit_group_free(g_rate_group);
72
    ev_token_bucket_cfg_free(cfg);
73
    event_base_free(base);
74

75
    return 0;
76
}

展开收起

六、动态调整速率#

6.1 调整API#

1
/* 获取组当前的令牌桶状态 */
2
void bufferevent_rate_limit_group_get_totals(
3
    struct bufferevent_rate_limit_group *grp,
4
    ev_uint64_t *total_read, ev_uint64_t *total_written);
5

6
/* 设置最小传输速率（保证最低带宽） */
7
int bufferevent_rate_limit_group_set_min_share(
8
    struct bufferevent_rate_limit_group *grp, size_t min_share);

6.2 动态调整示例#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <signal.h>
5
#include <event2/event.h>
6
#include <event2/bufferevent.h>
7

8
static struct bufferevent_rate_limit_group *g_rate_group = NULL;
9
static struct ev_token_bucket_cfg *g_cfg = NULL;
10
static struct event_base *g_base = NULL;
11
static int g_rate_level = 0;
12

13
static void adjust_rate(evutil_socket_t fd, short events, void *arg) {
14
    static const size_t rates[] = {102400, 512000, 1048576, 2097152};  // 100KB, 500KB, 1MB, 2MB
15
    g_rate_level = (g_rate_level + 1) % 4;
16

17
    // 创建新的配置
18
    struct ev_token_bucket_cfg *new_cfg = ev_token_bucket_cfg_new(
19
        rates[g_rate_level], rates[g_rate_level],
20
        rates[g_rate_level], rates[g_rate_level],
21
        NULL
22
    );
23

24
    // 更新组的配置
25
    bufferevent_rate_limit_group_set_cfg(g_rate_group, new_cfg);
26

27
    printf("Rate adjusted to: %zu KB/s\n", rates[g_rate_level] / 1024);
28

29
    ev_token_bucket_cfg_free(g_cfg);
30
    g_cfg = new_cfg;
31
}
32

33
static void print_stats(evutil_socket_t fd, short events, void *arg) {
34
    ev_uint64_t total_read, total_written;
35
    bufferevent_rate_limit_group_get_totals(g_rate_group, &total_read, &total_written);
36

37
    printf("Total read: %llu bytes, written: %llu bytes\n",
38
           (unsigned long long)total_read, (unsigned long long)total_written);
39
}

展开收起

七、令牌桶原理#

7.1 工作原理#

1
                    ┌─────────────────┐
2
                    │   令牌桶        │
3
                    │   (Burst)       │
4
                    │   容量: B       │
5
                    └────────┬────────┘
6
                             │
7
                             │ 令牌消耗
8
                             ▼
9
    ┌──────────────┐    ┌─────────────┐    ┌──────────────┐
10
    │  令牌生成    │───▶│  数据传输   │───▶│  数据包发送  │
11
    │  速率: R/s   │    │  检查令牌   │    │              │
12
    └──────────────┘    └─────────────┘    └──────────────┘
13

14
    R = Rate (速率，字节/秒)
15
    B = Burst (突发大小，字节)

展开收起

7.2 参数说明#

参数	说明	建议值
`read_rate`	平均读取速率	根据业务需求
`read_burst`	最大突发读取	通常等于rate或稍大
`write_rate`	平均写入速率	根据业务需求
`write_burst`	最大突发写入	通常等于rate或稍大
`tick_len`	时间片长度	默认1秒，可设更小

八、公平共享#

8.1 公平共享机制#

当多个连接共享一个速率限制组时，libevent会自动实现公平共享：

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <event2/event.h>
5
#include <event2/listener.h>
6
#include <event2/bufferevent.h>
7

8
static struct bufferevent_rate_limit_group *g_group = NULL;
9

10
static void read_cb(struct bufferevent *bev, void *arg) {
11
    int id = *(int *)arg;
12
    char buf[4096];
13
    size_t n;
14

15
    while ((n = bufferevent_read(bev, buf, sizeof(buf))) > 0) {
16
        bufferevent_write(bev, buf, n);
17
        printf("Connection %d: read %zu bytes\n", id, n);
18
    }
19
}
20

21
static void event_cb(struct bufferevent *bev, short events, void *arg) {
22
    if (events & (BEV_EVENT_EOF | BEV_EVENT_ERROR)) {
23
        int id = *(int *)arg;
24
        printf("Connection %d closed\n", id);
25
        free(arg);
26
        bufferevent_remove_from_rate_limit_group(bev);
27
        bufferevent_free(bev);
28
    }
29
}
30

31
static int g_conn_id = 0;
32

33
static void accept_cb(struct evconnlistener *listener, evutil_socket_t fd,
34
                      struct sockaddr *addr, int len, void *arg) {
35
    struct event_base *base = arg;
36

37
    int *id = malloc(sizeof(int));
38
    *id = ++g_conn_id;
39

40
    printf("New connection %d\n", *id);
41

42
    struct bufferevent *bev = bufferevent_socket_new(base, fd, BEV_OPT_CLOSE_ON_FREE);
43

44
    bufferevent_add_to_rate_limit_group(bev, g_group);
45

46
    bufferevent_setcb(bev, read_cb, NULL, event_cb, id);
47
    bufferevent_enable(bev, EV_READ | EV_WRITE);
48
}
49

50
int main() {
51
    struct event_base *base = event_base_new();
52

53
    // 总带宽限制为1MB/s，所有连接共享
54
    struct ev_token_bucket_cfg *cfg = ev_token_bucket_cfg_new(
55
        1048576, 1048576,
56
        1048576, 1048576,
57
        NULL
58
    );
59

60
    g_group = bufferevent_rate_limit_group_new(base, cfg);
61

62
    // 设置每个连接的最小保证带宽（可选）
63
    bufferevent_rate_limit_group_set_min_share(g_group, 10240);  // 10KB/s
64

65
    struct sockaddr_in sin;
66
    memset(&sin, 0, sizeof(sin));
67
    sin.sin_family = AF_INET;
68
    sin.sin_port = htons(8080);
69
    sin.sin_addr.s_addr = INADDR_ANY;
70

71
    struct evconnlistener *listener = evconnlistener_new_bind(
72
        base, accept_cb, base,
73
        LEV_OPT_CLOSE_ON_FREE | LEV_OPT_REUSEABLE,
74
        -1, (struct sockaddr *)&sin, sizeof(sin));
75

76
    printf("Server listening on port 8080\n");
77
    printf("Total bandwidth: 1MB/s, min per connection: 10KB/s\n");
78

79
    event_base_dispatch(base);
80

81
    evconnlistener_free(listener);
82
    bufferevent_rate_limit_group_free(g_group);
83
    ev_token_bucket_cfg_free(cfg);
84
    event_base_free(base);
85

86
    return 0;
87
}

展开收起

九、完整示例：带宽控制服务器#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <signal.h>
5
#include <event2/event.h>
6
#include <event2/listener.h>
7
#include <event2/bufferevent.h>
8

9
#define TOTAL_BANDWIDTH (2 * 1024 * 1024)  // 2MB/s
10
#define PER_CONN_BANDWIDTH (100 * 1024)    // 100KB/s
11
#define MIN_SHARE (10 * 1024)              // 10KB/s
12

13
static struct event_base *g_base = NULL;
14
static struct bufferevent_rate_limit_group *g_group = NULL;
15
static struct ev_token_bucket_cfg *g_conn_cfg = NULL;
16

17
static void print_stats(evutil_socket_t fd, short events, void *arg) {
18
    ev_uint64_t total_read, total_written;
19
    bufferevent_rate_limit_group_get_totals(g_group, &total_read, &total_written);
20

21
    printf("\n=== Statistics ===\n");
22
    printf("Total read: %llu bytes (%.2f MB)\n",
23
           (unsigned long long)total_read, (double)total_read / (1024 * 1024));
24
    printf("Total written: %llu bytes (%.2f MB)\n",
25
           (unsigned long long)total_written, (double)total_written / (1024 * 1024));
26
    printf("==================\n\n");
27
}
28

29
static void read_cb(struct bufferevent *bev, void *arg) {
30
    char buf[8192];
31
    size_t n;
32

33
    while ((n = bufferevent_read(bev, buf, sizeof(buf))) > 0) {
34
        bufferevent_write(bev, buf, n);
35
    }
36
}
37

38
static void event_cb(struct bufferevent *bev, short events, void *arg) {
39
    if (events & BEV_EVENT_CONNECTED) {
40
        printf("Client connected\n");
41
    } else if (events & (BEV_EVENT_EOF | BEV_EVENT_ERROR)) {
42
        printf("Client disconnected\n");
43
        bufferevent_remove_from_rate_limit_group(bev);
44
        bufferevent_free(bev);
45
    }
46
}
47

48
static void accept_cb(struct evconnlistener *listener, evutil_socket_t fd,
49
                      struct sockaddr *addr, int len, void *arg) {
50
    struct event_base *base = arg;
51

52
    struct bufferevent *bev = bufferevent_socket_new(base, fd, BEV_OPT_CLOSE_ON_FREE);
53

54
    // 设置单个连接的速率限制
55
    bufferevent_set_rate_limit(bev, g_conn_cfg);
56

57
    // 加入组级别限制
58
    bufferevent_add_to_rate_limit_group(bev, g_group);
59

60
    bufferevent_setcb(bev, read_cb, NULL, event_cb, NULL);
61
    bufferevent_enable(bev, EV_READ | EV_WRITE);
62
}
63

64
static void signal_cb(evutil_socket_t fd, short events, void *arg) {
65
    printf("\nShutting down...\n");
66
    event_base_loopbreak(g_base);
67
}
68

69
int main() {
70
    g_base = event_base_new();
71

72
    // 单连接速率限制配置
73
    g_conn_cfg = ev_token_bucket_cfg_new(
74
        PER_CONN_BANDWIDTH, PER_CONN_BANDWIDTH,
75
        PER_CONN_BANDWIDTH, PER_CONN_BANDWIDTH,
76
        NULL
77
    );
78

79
    // 组级别速率限制配置
80
    struct ev_token_bucket_cfg *group_cfg = ev_token_bucket_cfg_new(
81
        TOTAL_BANDWIDTH, TOTAL_BANDWIDTH,
82
        TOTAL_BANDWIDTH, TOTAL_BANDWIDTH,
83
        NULL
84
    );
85

86
    g_group = bufferevent_rate_limit_group_new(g_base, group_cfg);
87
    bufferevent_rate_limit_group_set_min_share(g_group, MIN_SHARE);
88

89
    // 设置信号处理
90
    struct event *sigint = evsignal_new(g_base, SIGINT, signal_cb, NULL);
91
    event_add(sigint, NULL);
92

93
    // 设置定时器打印统计信息
94
    struct event *stats_timer = event_new(g_base, -1, EV_PERSIST, print_stats, NULL);
95
    struct timeval stats_interval = {5, 0};  // 每5秒
96
    event_add(stats_timer, &stats_interval);
97

98
    // 创建监听器
99
    struct sockaddr_in sin;
100
    memset(&sin, 0, sizeof(sin));
101
    sin.sin_family = AF_INET;
102
    sin.sin_port = htons(8080);
103
    sin.sin_addr.s_addr = INADDR_ANY;
104

105
    struct evconnlistener *listener = evconnlistener_new_bind(
106
        g_base, accept_cb, g_base,
107
        LEV_OPT_CLOSE_ON_FREE | LEV_OPT_REUSEABLE,
108
        -1, (struct sockaddr *)&sin, sizeof(sin));
109

110
    printf("Bandwidth-limited echo server\n");
111
    printf("Listening on port 8080\n");
112
    printf("Total bandwidth: %d KB/s\n", TOTAL_BANDWIDTH / 1024);
113
    printf("Per connection: %d KB/s\n", PER_CONN_BANDWIDTH / 1024);
114
    printf("Min share: %d KB/s\n", MIN_SHARE / 1024);
115
    printf("Press Ctrl+C to stop\n\n");
116

117
    event_base_dispatch(g_base);
118

119
    evconnlistener_free(listener);
120
    event_free(stats_timer);
121
    event_free(sigint);
122
    bufferevent_rate_limit_group_free(g_group);
123
    ev_token_bucket_cfg_free(group_cfg);
124
    ev_token_bucket_cfg_free(g_conn_cfg);
125
    event_base_free(g_base);
126

127
    return 0;
128
}

展开收起

十、最佳实践#

场景	建议
单连接限制	使用`bufferevent_set_rate_limit`
全局限制	使用速率限制组
突发处理	设置合理的burst值
公平分配	设置min_share保证最小带宽
动态调整	根据负载动态调整速率
监控统计	定期打印统计信息

其他相关资料请移步到个人主页

📚 libevent源码深度解析

Sat, 11 Apr 2026 00:00:00 GMT

libevent源码深度解析#

Libevent 是一个用C语言编写的、轻量级的开源高性能事件通知库，支持跨平台、多种I/O多路复用机制，广泛应用于高性能网络服务器开发。

� libevent整体架构#

1
┌────────────────────────────────────────────────────────────────────────┐
2
│                          应用层                                     │
3
├────────────────────────────────────────────────────────────────────────┤
4
│  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌───────────┐         │
5
│  │ HTTP      │  │ DNS       │  │ 信号处理  │  │ 定时器    │         │
6
│  └────┬──────┘  └────┬──────┘  └────┬──────┘  └────┬──────┘         │
7
│       │              │              │              │                   │
8
├───────┼──────────────┼──────────────┼──────────────┼───────────────────┤
9
│                          核心层                                     │
10
├────────────────────────────────────────────────────────────────────────┤
11
│  ┌────────────────────────────────────────────────────────────────┐   │
12
│  │                     event_base                               │   │
13
│  ├────────────────────────────────────────────────────────────────┤   │
14
│  │  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐         │   │
15
│  │  │  event  │  │bufferev│  │ 事件队列 │  │ 定时器堆 │         │   │
16
│  │  └─────────┘  └─────────┘  └─────────┘  └─────────┘         │   │
17
│  └────────────────────────────────────────────────────────────────┘   │
18
├────────────────────────────────────────────────────────────────────────┤
19
│                          底层驱动                                   │
20
├────────────────────────────────────────────────────────────────────────┤
21
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │
22
│  │  epoll  │  │  kqueue │  │  poll   │  │ select  │  │  IOCP   │    │
23
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘  └─────────┘    │
24
└────────────────────────────────────────────────────────────────────────┘

展开收起

🔍 架构说明#

应用层：提供HTTP、DNS、信号处理、定时器等高级功能
核心层：event_base作为核心，管理event、bufferevent、事件队列和定时器堆
底层驱动：自动选择最优的I/O多路复用机制（epoll、kqueue、poll、select、IOCP）

�📚 文章目录#

一、基础入门#

序号	文章	说明
01	序言与简介	高性能服务器、Reactor模型、libevent特点
02	安装与编译	libevent下载、编译、安装步骤
03	源码文件组织	源码目录结构、文件分类说明
04	核心概念与API	事件驱动模型、核心概念介绍

二、核心组件#

序号	文章	说明
05	event_base详解	事件基结构体、API、使用方法
06	event详解	事件结构体、API、使用方法
07	bufferevent详解	缓冲事件、水位机制、API
08	日志模块	日志级别、回调设置、调试方法

三、网络编程#

序号	文章	说明
09	TCP监听器	evconnlistener使用、TCP服务端
10	TCP服务端与客户端	完整的TCP回射程序示例
11	HTTP服务器	HTTP服务端实现、请求处理

四、事件类型#

序号	文章	说明
12	定时器使用	定时器事件创建与使用
13	信号事件	信号事件处理

五、高级特性#

序号	文章	说明
14	多线程编程	多线程使用原则、HTTP服务器C++封装
15	事件触发流程	事件循环内部流程分析
16	watch模块	事件循环监控、prepare/check回调
17	事件数量分析	虚拟事件、事件计数

六、扩展模块#

序号	文章	说明
18	evbuffer详解	缓冲区操作完整API、零拷贝、回调机制
19	evdns异步DNS	DNS查询与服务器、正向/反向解析
20	evutil工具函数	跨平台工具函数、Socket/地址/时间操作
21	HTTP客户端	evhttp客户端编程、GET/POST请求

七、安全与优化#

序号	文章	说明
22	SSL/TLS加密通信	安全通信实现、OpenSSL集成
23	速率限制	带宽控制、令牌桶算法
24	bufferevent高级特性	pair/filter/链式过滤器
25	性能调优指南	生产环境优化、多线程扩展

八、问题排查#

序号	文章	说明
26	常见问题FAQ	编译安装、事件循环、网络问题排查

🔗 参考资料#

其他相关资料请移步到个人主页

📡 信号事件 - libevent源码深度解析系列（十三）

Sat, 11 Apr 2026 00:00:00 GMT

📡 信号事件#

一、概述#

libevent支持信号事件处理，允许在接收到特定信号时执行回调函数。这对于优雅地关闭服务器、重新加载配置等场景非常有用。

二、信号API#

2.1 创建信号事件#

1
/* 创建信号事件（宏定义）
2
 * @param base  event_base
3
 * @param x     信号值
4
 * @param cb    回调函数
5
 * @param arg   回调参数
6
 */
7
#define evsignal_new(base, x, cb, arg) \
8
    event_new((base), (x), EV_SIGNAL|EV_PERSIST, (cb), (arg))
9

10
/* 分配信号事件到现有结构体 */
11
#define evsignal_assign(ev, base, x, cb, arg) \
12
    event_assign((ev), (base), (x), EV_SIGNAL|EV_PERSIST, (cb), (arg))

2.2 添加和删除#

1
/* 添加信号事件 */
2
#define evsignal_add(ev, tv) event_add((ev), (tv))
3

4
/* 删除信号事件 */
5
#define evsignal_del(ev) event_del(ev)

2.3 检查状态#

1
/* 检查信号事件是否pending */
2
#define evsignal_pending(ev, tv) event_pending((ev), EV_SIGNAL, (tv))
3

4
/* 检查信号事件是否已初始化 */
5
#define evsignal_initialized(ev) event_initialized(ev)

三、常用信号#

信号	值	说明
SIGINT	2	中断信号（Ctrl+C）
SIGTERM	15	终止信号
SIGUSR1	10	用户自定义信号1
SIGUSR2	12	用户自定义信号2
SIGHUP	1	挂起信号（重载配置）
SIGPIPE	13	管道破裂（通常忽略）

四、基本示例#

4.1 捕获SIGINT#

1
#include <stdio.h>
2
#include <signal.h>
3
#include <event2/event.h>
4

5
static void signal_cb(evutil_socket_t fd, short events, void *arg) {
6
    struct event_base *base = arg;
7
    printf("Caught SIGINT (Ctrl+C), shutting down...\n");
8
    event_base_loopexit(base, NULL);
9
}
10

11
int main() {
12
    struct event_base *base = event_base_new();
13

14
    // 创建信号事件
15
    struct event *signal_int = evsignal_new(base, SIGINT, signal_cb, base);
16
    event_add(signal_int, NULL);
17

18
    printf("Press Ctrl+C to exit\n");
19

20
    event_base_dispatch(base);
21

22
    event_free(signal_int);
23
    event_base_free(base);
24

25
    printf("Server shutdown complete\n");
26
    return 0;
27
}

展开收起

4.2 捕获多个信号#

1
#include <stdio.h>
2
#include <signal.h>
3
#include <event2/event.h>
4

5
static volatile int running = 1;
6

7
static void sigint_cb(evutil_socket_t fd, short events, void *arg) {
8
    struct event_base *base = arg;
9
    printf("Caught SIGINT, graceful shutdown...\n");
10
    event_base_loopexit(base, NULL);
11
}
12

13
static void sigterm_cb(evutil_socket_t fd, short events, void *arg) {
14
    struct event_base *base = arg;
15
    printf("Caught SIGTERM, immediate shutdown...\n");
16
    event_base_loopbreak(base);
17
}
18

19
static void sighup_cb(evutil_socket_t fd, short events, void *arg) {
20
    printf("Caught SIGHUP, reloading configuration...\n");
21
    // 这里可以重新加载配置
22
}
23

24
static void sigusr1_cb(evutil_socket_t fd, short events, void *arg) {
25
    printf("Caught SIGUSR1, custom action...\n");
26
    // 自定义操作
27
}
28

29
int main() {
30
    struct event_base *base = event_base_new();
31

32
    // 创建多个信号事件
33
    struct event *sigint = evsignal_new(base, SIGINT, sigint_cb, base);
34
    struct event *sigterm = evsignal_new(base, SIGTERM, sigterm_cb, base);
35
    struct event *sighup = evsignal_new(base, SIGHUP, sighup_cb, base);
36
    struct event *sigusr1 = evsignal_new(base, SIGUSR1, sigusr1_cb, base);
37

38
    event_add(sigint, NULL);
39
    event_add(sigterm, NULL);
40
    event_add(sighup, NULL);
41
    event_add(sigusr1, NULL);
42

43
    printf("Signal handlers installed:\n");
44
    printf("  SIGINT (Ctrl+C)  - Graceful shutdown\n");
45
    printf("  SIGTERM          - Immediate shutdown\n");
46
    printf("  SIGHUP           - Reload config\n");
47
    printf("  SIGUSR1          - Custom action\n");
48

49
    event_base_dispatch(base);
50

51
    event_free(sigint);
52
    event_free(sigterm);
53
    event_free(sighup);
54
    event_free(sigusr1);
55
    event_base_free(base);
56

57
    return 0;
58
}

展开收起

五、忽略SIGPIPE#

在网络编程中，当向已关闭的socket写入数据时，会触发SIGPIPE信号，默认行为是终止程序。通常需要忽略这个信号：

1
#include <stdio.h>
2
#include <signal.h>
3
#include <event2/event.h>
4

5
static void ignore_sigpipe(void) {
6
    struct event_base *base = event_base_new();
7
    struct event *sigpipe = evsignal_new(base, SIGPIPE, NULL, NULL);
8
    event_add(sigpipe, NULL);
9

10
    // 或者直接使用系统调用
11
    signal(SIGPIPE, SIG_IGN);
12

13
    event_free(sigpipe);
14
    event_base_free(base);
15
}
16

17
// 更简单的方法
18
static void setup_signals(void) {
19
    // 忽略SIGPIPE
20
    signal(SIGPIPE, SIG_IGN);
21
}

展开收起

六、完整服务器示例#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <signal.h>
5
#include <unistd.h>
6
#include <arpa/inet.h>
7
#include <event2/buffer.h>
8
#include <event2/bufferevent.h>
9
#include <event2/listener.h>
10
#include <event2/event.h>
11

12
#define PORT 8080
13

14
static struct event_base *g_base = NULL;
15
static int g_reload_config = 0;
16

17
static void read_cb(struct bufferevent *bev, void *ctx) {
18
    struct evbuffer *input = bufferevent_get_input(bev);
19
    struct evbuffer *output = bufferevent_get_output(bev);
20
    evbuffer_add_buffer(output, input);
21
}
22

23
static void event_cb(struct bufferevent *bev, short events, void *ctx) {
24
    if (events & (BEV_EVENT_EOF | BEV_EVENT_ERROR)) {
25
        bufferevent_free(bev);
26
    }
27
}
28

29
static void accept_cb(struct evconnlistener *listener,
30
    evutil_socket_t fd, struct sockaddr *addr, int socklen, void *ctx) {
31

32
    struct event_base *base = evconnlistener_get_base(listener);
33
    struct bufferevent *bev = bufferevent_socket_new(base, fd, BEV_OPT_CLOSE_ON_FREE);
34

35
    bufferevent_setcb(bev, read_cb, NULL, event_cb, NULL);
36
    bufferevent_enable(bev, EV_READ | EV_WRITE);
37
}
38

39
static void sigint_cb(evutil_socket_t fd, short events, void *arg) {
40
    printf("\nCaught SIGINT, shutting down gracefully...\n");
41
    event_base_loopexit(g_base, NULL);
42
}
43

44
static void sigterm_cb(evutil_socket_t fd, short events, void *arg) {
45
    printf("\nCaught SIGTERM, shutting down...\n");
46
    event_base_loopexit(g_base, NULL);
47
}
48

49
static void sighup_cb(evutil_socket_t fd, short events, void *arg) {
50
    printf("\nCaught SIGHUP, reloading configuration...\n");
51
    g_reload_config = 1;
52
    // 在实际应用中，这里可以重新读取配置文件
53
}
54

55
int main() {
56
    // 忽略SIGPIPE
57
    signal(SIGPIPE, SIG_IGN);
58

59
    g_base = event_base_new();
60

61
    // 设置信号处理
62
    struct event *sigint = evsignal_new(g_base, SIGINT, sigint_cb, NULL);
63
    struct event *sigterm = evsignal_new(g_base, SIGTERM, sigterm_cb, NULL);
64
    struct event *sighup = evsignal_new(g_base, SIGHUP, sighup_cb, NULL);
65

66
    event_add(sigint, NULL);
67
    event_add(sigterm, NULL);
68
    event_add(sighup, NULL);
69

70
    // 创建监听器
71
    struct sockaddr_in sin;
72
    memset(&sin, 0, sizeof(sin));
73
    sin.sin_family = AF_INET;
74
    sin.sin_port = htons(PORT);
75
    sin.sin_addr.s_addr = htonl(INADDR_ANY);
76

77
    struct evconnlistener *listener = evconnlistener_new_bind(g_base,
78
        accept_cb, NULL, LEV_OPT_REUSEABLE | LEV_OPT_CLOSE_ON_FREE,
79
        -1, (struct sockaddr *)&sin, sizeof(sin));
80

81
    if (!listener) {
82
        fprintf(stderr, "Failed to create listener\n");
83
        return 1;
84
    }
85

86
    printf("Server running on port %d\n", PORT);
87
    printf("Press Ctrl+C to shutdown\n");
88
    printf("Send SIGHUP to reload config (kill -HUP %d)\n", getpid());
89

90
    event_base_dispatch(g_base);
91

92
    printf("Cleaning up...\n");
93

94
    evconnlistener_free(listener);
95
    event_free(sigint);
96
    event_free(sigterm);
97
    event_free(sighup);
98
    event_base_free(g_base);
99

100
    printf("Server shutdown complete\n");
101
    return 0;
102
}

展开收起

七、使用注意事项#

注意事项	说明
单event_base限制	每个进程只能有一个event_base监控信号
信号自动恢复	libevent会自动恢复信号处理
EV_PERSIST	信号事件通常需要EV_PERSIST标志
SIGPIPE	网络编程中通常需要忽略SIGPIPE
线程安全	信号处理函数中避免调用非异步安全函数

其他相关资料请移步到个人主页

📁 源码文件组织 - libevent源码深度解析系列（三）

Sat, 11 Apr 2026 00:00:00 GMT

📁 源码文件组织#

一、源码目录结构#

libevent 源码目录结构如下所示：

1
libevent/
2
├── include/                # 包含头文件
3
│   ├── event2/
4
│   │   ├── event.h         # 核心API头文件
5
│   │   ├── event-config.h  # 配置宏定义
6
│   │   ├── bufferevent.h   # 缓冲事件
7
│   │   ├── buffer.h        # 缓冲区
8
│   │   ├── http.h          # HTTP支持
9
│   │   ├── dns.h           # DNS支持
10
│   │   ├── rpc.h           # RPC支持
11
│   │   └── util.h          # 工具函数
12
│   └── event.h             # 旧版本兼容头文件
13
├── src/                    # 源代码文件
14
│   ├── event.c             # 事件核心实现
15
│   ├── evmap.c             # 事件映射
16
│   ├── evthread.c          # 线程支持
17
│   ├── evutil.c            # 工具函数
18
│   ├── buffer.c            # 缓冲区实现
19
│   ├── bufferevent.c       # 缓冲事件实现
20
│   ├── http.c              # HTTP实现
21
│   ├── evdns.c             # DNS实现
22
│   ├── evrpc.c             # RPC实现
23
│   └── ...
24
├── test/                   # 测试代码
25
├── sample/                 # 示例代码
26
├── configure               # 自动配置脚本
27
├── Makefile                # 编译规则
28
└── README                  # 项目说明文档

展开收起

二、头文件分类#

新版本使用的头文件是在 include/event2 文件夹中，但是旧版本的头文件仍然存在。

新版本头文件	旧版本头文件
event2/event.h, event2/buffer.h, event2/bufferevent.h, event2/tag.h	event.h
event2/dns*.h	evdns.h
event2/rpc*.h	evrpc.h
event2/http*.h	evhttp.h
event2/util*.h	evutil.h

三、源码文件分类#

3.1 I/O多路复用机制封装#

文件	说明
epoll.c	对linux I/O复用机制 epoll 的封装
select.c	对 linux I/O复用机制 select 的封装
poll.c	对 linux I/O复用机制 poll 的封装
devpoll.c	对 dev/poll 的封装
kqueue.c	对 kqueue 的封装
evport.c	Solaris 10 的新增加的特性

3.2 基本数据结构#

compat/sys 下的两个源文件：queue.h 是 libevent 基本数据结构的实现，包括链表，双向链表，队列等。

3.3 信号管理#

signal.c：对信号事件的处理。

3.4 辅助功能函数#

文件	说明
evutil.c	一些辅助功能函数，包括创建 socket pair 和一些时间操作函数
arc4random.c, evutil_rand.c	随机数的封装
evutil_time.c	时间函数的封装

3.5 日志#

log.h 和 log.c：log 日志函数。

3.6 线程#

evthread.c、evthread_pthread.c、evthread_win32.c：对系统的线程使用的封装。

3.7 事件的实现与管理#

文件	说明
event.c	event 整体框架的代码实现，包含event和event_base
evmap.c	将每个文件描述符或者信号映射为事件，私有函数

3.8 缓冲区管理#

bufferevent.c、bufferevent_async.c、bufferevent_filter.c、bufferevent_openssl.c、bufferevent_pair.c、bufferevent_ratelim.c、bufferevent_sock.c 和 buffer.c：libevent 对缓冲区的封装。

3.9 定时事件管理#

min-heap.h：其实就是一个以时间作为 key 的小根堆结构。

3.10 网络库#

文件	说明
evdns.c	异步 dns 查询库
http.c	http 服务器的实现
evrpc.c	rpc的实现

四、官方示例#

1
sample/
2
├── dns-example.c
3
├── event-read-fifo.c
4
├── hello-world.c
5
├── hostcheck.c
6
├── hostcheck.h
7
├── http-connect.c
8
├── https-client.c
9
├── http-server.c
10
├── le-proxy.c
11
├── openssl_hostname_validation.c
12
├── openssl_hostname_validation.h
13
├── signal-test.c
14
└── time-test.c

五、模块划分#

5.1 事件基 (event_base)#

事件基是 libevent 的核心组件，它负责管理事件的调度。event_base 提供了事件的注册、取消、启动事件循环等功能。

5.2 事件 (event)#

事件代表了一个可以被监控的对象，如文件描述符或信号。事件可以设置为监听读、写、定时器等不同的事件类型，并且可以指定事件触发时的回调函数。

5.3 缓冲区 (evbuffer)#

evbuffer 是一个灵活的缓冲区管理工具，用于在网络通信中处理数据流。

5.4 线程安全 (evthread)#

提供了线程安全的支持，使得 libevent 可以在多线程环境中安全使用。

5.5 I/O 多路复用机制封装#

libevent 支持多种 I/O 多路复用机制，如 epoll、kqueue、select 等。这些机制在不同操作系统上的实现略有不同，因此 libevent 通过条件编译选择最适合当前操作系统的实现。

六、跨平台兼容性#

libevent 的设计考虑到了跨平台兼容性，因此源码中包含了许多条件编译指令来适应不同的操作系统和编译器特性。例如：

1
#if defined(EVENT__HAVE_EPOLL)
2
// 使用 epoll 的实现
3
#elif defined(EVENT__HAVE_KQUEUE)
4
// 使用 kqueue 的实现
5
#else
6
// 使用 select 或其他机制的实现
7
#endif

这种条件编译允许 libevent 在不同的平台上选择最适合的事件驱动机制。

其他相关资料请移步到个人主页

🔐 SSL/TLS加密通信 - libevent源码深度解析系列（二十二）

Sat, 11 Apr 2026 00:00:00 GMT

🔐 SSL/TLS加密通信#

一、概述#

libevent通过OpenSSL库提供SSL/TLS加密通信支持。通过bufferevent_openssl模块，可以轻松地为网络连接添加安全层，实现数据加密传输。

二、SSL/TLS基础#

2.1 SSL/TLS协议版本#

版本	说明	安全性
SSLv2	已废弃	不安全
SSLv3	已废弃	POODLE攻击
TLSv1.0	已弃用	BEAST攻击
TLSv1.1	已弃用	较弱
TLSv1.2	推荐	安全
TLSv1.3	最新	最安全

2.2 常用加密套件#

1
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
2
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
3
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
4
TLS_AES_128_GCM_SHA256 (TLS 1.3)
5
TLS_AES_256_GCM_SHA384 (TLS 1.3)

三、OpenSSL初始化#

3.1 初始化API#

1
#include <openssl/ssl.h>
2
#include <openssl/err.h>
3
#include <openssl/rand.h>
4

5
/* 初始化OpenSSL库 */
6
void SSL_library_init(void);
7

8
/* 加载错误字符串 */
9
void SSL_load_error_strings(void);
10

11
/* 加载算法 */
12
void OpenSSL_add_all_algorithms(void);
13

14
/* 清理资源 */
15
void EVP_cleanup(void);
16
void ERR_free_strings(void);

展开收起

3.2 初始化示例#

1
#include <stdio.h>
2
#include <openssl/ssl.h>
3
#include <openssl/err.h>
4

5
void init_openssl(void) {
6
    SSL_library_init();
7
    SSL_load_error_strings();
8
    OpenSSL_add_all_algorithms();
9

10
    printf("OpenSSL initialized, version: %s\n",
11
           SSLeay_version(SSLEAY_VERSION));
12
}
13

14
void cleanup_openssl(void) {
15
    EVP_cleanup();
16
    ERR_free_strings();
17
}
18

19
int main() {
20
    init_openssl();
21

22
    printf("SSL/TLS support ready\n");
23

24
    cleanup_openssl();
25
    return 0;
26
}

展开收起

四、SSL上下文#

4.1 创建SSL_CTX#

1
/* 创建SSL上下文 */
2
SSL_CTX *SSL_CTX_new(const SSL_METHOD *method);
3

4
/* 释放SSL上下文 */
5
void SSL_CTX_free(SSL_CTX *ctx);
6

7
/* 获取TLS方法 */
8
const SSL_METHOD *TLS_server_method(void);    // 服务器端
9
const SSL_METHOD *TLS_client_method(void);    // 客户端
10
const SSL_METHOD *TLS_method(void);           // 通用（推荐）
11

12
/* 设置协议版本 */
13
int SSL_CTX_set_min_proto_version(SSL_CTX *ctx, int version);
14
int SSL_CTX_set_max_proto_version(SSL_CTX *ctx, int version);
15

16
/* 协议版本常量 */
17
#define TLS1_VERSION       0x0301
18
#define TLS1_1_VERSION     0x0302
19
#define TLS1_2_VERSION     0x0303
20
#define TLS1_3_VERSION     0x0304

展开收起

4.2 配置SSL_CTX#

1
/* 设置证书 */
2
int SSL_CTX_use_certificate_file(SSL_CTX *ctx, const char *file, int type);
3
int SSL_CTX_use_certificate_chain_file(SSL_CTX *ctx, const char *file);
4

5
/* 设置私钥 */
6
int SSL_CTX_use_PrivateKey_file(SSL_CTX *ctx, const char *file, int type);
7
int SSL_CTX_check_private_key(SSL_CTX *ctx);
8

9
/* 设置CA证书 */
10
int SSL_CTX_load_verify_locations(SSL_CTX *ctx, const char *CAfile,
11
                                   const char *CApath);
12

13
/* 设置验证模式 */
14
void SSL_CTX_set_verify(SSL_CTX *ctx, int mode,
15
                        int (*verify_callback)(int, X509_STORE_CTX *));
16

17
/* 验证模式 */
18
#define SSL_VERIFY_NONE                 0x00
19
#define SSL_VERIFY_PEER                 0x01
20
#define SSL_VERIFY_FAIL_IF_NO_PEER_CERT 0x02
21
#define SSL_VERIFY_CLIENT_ONCE          0x04
22

23
/* 设置验证深度 */
24
void SSL_CTX_set_verify_depth(SSL_CTX *ctx, int depth);
25

26
/* 设置密码套件 */
27
int SSL_CTX_set_cipher_list(SSL_CTX *ctx, const char *str);
28
int SSL_CTX_set_ciphersuites(SSL_CTX *ctx, const char *str);

展开收起

4.3 SSL_CTX示例#

1
#include <stdio.h>
2
#include <openssl/ssl.h>
3

4
SSL_CTX *create_server_context(void) {
5
    SSL_CTX *ctx = SSL_CTX_new(TLS_server_method());
6
    if (!ctx) {
7
        perror("SSL_CTX_new");
8
        return NULL;
9
    }
10

11
    // 设置最低TLS版本为1.2
12
    SSL_CTX_set_min_proto_version(ctx, TLS1_2_VERSION);
13

14
    // 加载证书
15
    if (SSL_CTX_use_certificate_file(ctx, "server.crt", SSL_FILETYPE_PEM) != 1) {
16
        fprintf(stderr, "Failed to load certificate\n");
17
        SSL_CTX_free(ctx);
18
        return NULL;
19
    }
20

21
    // 加载私钥
22
    if (SSL_CTX_use_PrivateKey_file(ctx, "server.key", SSL_FILETYPE_PEM) != 1) {
23
        fprintf(stderr, "Failed to load private key\n");
24
        SSL_CTX_free(ctx);
25
        return NULL;
26
    }
27

28
    // 验证私钥
29
    if (SSL_CTX_check_private_key(ctx) != 1) {
30
        fprintf(stderr, "Private key check failed\n");
31
        SSL_CTX_free(ctx);
32
        return NULL;
33
    }
34

35
    // 设置密码套件
36
    SSL_CTX_set_cipher_list(ctx,
37
        "ECDHE-ECDSA-AES128-GCM-SHA256:"
38
        "ECDHE-RSA-AES128-GCM-SHA256:"
39
        "ECDHE-ECDSA-AES256-GCM-SHA384:"
40
        "ECDHE-RSA-AES256-GCM-SHA384");
41

42
    printf("Server SSL context created\n");
43
    return ctx;
44
}
45

46
SSL_CTX *create_client_context(void) {
47
    SSL_CTX *ctx = SSL_CTX_new(TLS_client_method());
48
    if (!ctx) {
49
        perror("SSL_CTX_new");
50
        return NULL;
51
    }
52

53
    // 设置最低TLS版本
54
    SSL_CTX_set_min_proto_version(ctx, TLS1_2_VERSION);
55

56
    // 设置验证模式
57
    SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER, NULL);
58

59
    // 加载CA证书
60
    if (SSL_CTX_load_verify_locations(ctx, "ca.crt", NULL) != 1) {
61
        fprintf(stderr, "Failed to load CA certificate\n");
62
        SSL_CTX_free(ctx);
63
        return NULL;
64
    }
65

66
    printf("Client SSL context created\n");
67
    return ctx;
68
}

展开收起

五、bufferevent_openssl#

5.1 创建SSL bufferevent#

1
#include <event2/bufferevent_ssl.h>
2

3
/* 创建SSL bufferevent（基于socket） */
4
struct bufferevent *bufferevent_openssl_socket_new(
5
    struct event_base *base,
6
    evutil_socket_t fd,
7
    SSL *ssl,
8
    enum bufferevent_ssl_state state,
9
    int options);
10

11
/* 创建SSL bufferevent（基于底层bufferevent） */
12
struct bufferevent *bufferevent_openssl_filter_new(
13
    struct event_base *base,
14
    struct bufferevent *underlying,
15
    SSL *ssl,
16
    enum bufferevent_ssl_state state,
17
    int options);
18

19
/* SSL状态 */
20
enum bufferevent_ssl_state {
21
    BUFFEREVENT_SSL_CONNECTING = 0,  // 正在握手
22
    BUFFEREVENT_SSL_ACCEPTING,       // 服务器接受连接
23
    BUFFEREVENT_SSL_OPEN             // SSL连接已建立
24
};
25

26
/* 获取SSL对象 */
27
SSL *bufferevent_openssl_get_ssl(struct bufferevent *bufev);
28

29
/* 允许底层缓冲区重新协商 */
30
int bufferevent_openssl_get_allow_dirty_shutdown(struct bufferevent *bev);
31
void bufferevent_openssl_set_allow_dirty_shutdown(struct bufferevent *bev,
32
    int allow_dirty_shutdown);

展开收起

5.2 选项标志#

1
#define BEV_OPT_CLOSE_ON_FREE        0x01  // 释放时关闭底层
2
#define BEV_OPT_THREADSAFE           0x02  // 线程安全
3
#define BEV_OPT_DEFER_CALLBACKS      0x04  // 延迟回调
4
#define BEV_OPT_UNLOCK_CALLBACKS     0x08  // 回调时不加锁

六、SSL客户端#

6.1 客户端示例#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <signal.h>
5
#include <event2/event.h>
6
#include <event2/bufferevent.h>
7
#include <event2/bufferevent_ssl.h>
8
#include <openssl/ssl.h>
9
#include <openssl/err.h>
10

11
static void event_cb(struct bufferevent *bev, short events, void *arg);
12
static void read_cb(struct bufferevent *bev, void *arg);
13

14
static void init_openssl(void) {
15
    SSL_library_init();
16
    SSL_load_error_strings();
17
    OpenSSL_add_all_algorithms();
18
}
19

20
static SSL_CTX *create_client_ssl_ctx(void) {
21
    SSL_CTX *ctx = SSL_CTX_new(TLS_client_method());
22
    if (!ctx) return NULL;
23

24
    SSL_CTX_set_min_proto_version(ctx, TLS1_2_VERSION);
25

26
    // 使用系统默认CA证书
27
    SSL_CTX_set_default_verify_paths(ctx);
28
    SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER, NULL);
29

30
    return ctx;
31
}
32

33
static void event_cb(struct bufferevent *bev, short events, void *arg) {
34
    struct event_base *base = arg;
35

36
    if (events & BEV_EVENT_CONNECTED) {
37
        printf("SSL connection established\n");
38

39
        // 发送HTTP请求
40
        const char *request =
41
            "GET / HTTP/1.1\r\n"
42
            "Host: www.google.com\r\n"
43
            "Connection: close\r\n"
44
            "\r\n";
45
        bufferevent_write(bev, request, strlen(request));
46

47
    } else if (events & BEV_EVENT_ERROR) {
48
        unsigned long err;
49
        while ((err = bufferevent_get_openssl_error(bev))) {
50
            char msg[256];
51
            ERR_error_string_n(err, msg, sizeof(msg));
52
            fprintf(stderr, "SSL error: %s\n", msg);
53
        }
54
        event_base_loopexit(base, NULL);
55

56
    } else if (events & (BEV_EVENT_EOF | BEV_EVENT_TIMEOUT)) {
57
        printf("Connection closed\n");
58
        bufferevent_free(bev);
59
        event_base_loopexit(base, NULL);
60
    }
61
}
62

63
static void read_cb(struct bufferevent *bev, void *arg) {
64
    char buf[4096];
65
    size_t n;
66

67
    while ((n = bufferevent_read(bev, buf, sizeof(buf) - 1)) > 0) {
68
        buf[n] = '\0';
69
        printf("%s", buf);
70
    }
71
}
72

73
int main() {
74
    init_openssl();
75

76
    struct event_base *base = event_base_new();
77
    SSL_CTX *ssl_ctx = create_client_ssl_ctx();
78

79
    if (!ssl_ctx) {
80
        fprintf(stderr, "Failed to create SSL context\n");
81
        return 1;
82
    }
83

84
    SSL *ssl = SSL_new(ssl_ctx);
85
    SSL_set_tlsext_host_name(ssl, "www.google.com");  // SNI
86

87
    struct bufferevent *bev = bufferevent_openssl_socket_new(
88
        base, -1, ssl, BUFFEREVENT_SSL_CONNECTING,
89
        BEV_OPT_CLOSE_ON_FREE | BEV_OPT_DEFER_CALLBACKS);
90

91
    bufferevent_setcb(bev, read_cb, NULL, event_cb, base);
92
    bufferevent_enable(bev, EV_READ | EV_WRITE);
93

94
    // 连接服务器
95
    struct sockaddr_in sin;
96
    memset(&sin, 0, sizeof(sin));
97
    sin.sin_family = AF_INET;
98
    sin.sin_port = htons(443);
99
    inet_pton(AF_INET, "142.250.185.68", &sin.sin_addr);  // google.com
100

101
    if (bufferevent_socket_connect(bev, (struct sockaddr *)&sin, sizeof(sin)) < 0) {
102
        perror("connect");
103
        bufferevent_free(bev);
104
        SSL_CTX_free(ssl_ctx);
105
        event_base_free(base);
106
        return 1;
107
    }
108

109
    printf("Connecting to www.google.com:443...\n");
110
    event_base_dispatch(base);
111

112
    SSL_CTX_free(ssl_ctx);
113
    event_base_free(base);
114

115
    return 0;
116
}

展开收起

七、SSL服务器#

7.1 服务器示例#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <signal.h>
5
#include <event2/event.h>
6
#include <event2/listener.h>
7
#include <event2/bufferevent.h>
8
#include <event2/bufferevent_ssl.h>
9
#include <openssl/ssl.h>
10
#include <openssl/err.h>
11

12
static SSL_CTX *g_ssl_ctx = NULL;
13

14
static void init_openssl(void) {
15
    SSL_library_init();
16
    SSL_load_error_strings();
17
    OpenSSL_add_all_algorithms();
18
}
19

20
static SSL_CTX *create_server_ssl_ctx(void) {
21
    SSL_CTX *ctx = SSL_CTX_new(TLS_server_method());
22
    if (!ctx) return NULL;
23

24
    SSL_CTX_set_min_proto_version(ctx, TLS1_2_VERSION);
25

26
    // 加载证书和私钥
27
    if (SSL_CTX_use_certificate_file(ctx, "server.crt", SSL_FILETYPE_PEM) != 1) {
28
        fprintf(stderr, "Failed to load certificate\n");
29
        SSL_CTX_free(ctx);
30
        return NULL;
31
    }
32

33
    if (SSL_CTX_use_PrivateKey_file(ctx, "server.key", SSL_FILETYPE_PEM) != 1) {
34
        fprintf(stderr, "Failed to load private key\n");
35
        SSL_CTX_free(ctx);
36
        return NULL;
37
    }
38

39
    if (SSL_CTX_check_private_key(ctx) != 1) {
40
        fprintf(stderr, "Private key check failed\n");
41
        SSL_CTX_free(ctx);
42
        return NULL;
43
    }
44

45
    // 设置密码套件
46
    SSL_CTX_set_cipher_list(ctx,
47
        "ECDHE-RSA-AES128-GCM-SHA256:"
48
        "ECDHE-RSA-AES256-GCM-SHA384");
49

50
    // 可选：要求客户端证书
51
    // SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER | SSL_VERIFY_FAIL_IF_NO_PEER_CERT, NULL);
52
    // SSL_CTX_load_verify_locations(ctx, "ca.crt", NULL);
53

54
    return ctx;
55
}
56

57
static void read_cb(struct bufferevent *bev, void *arg) {
58
    char buf[1024];
59
    size_t n;
60

61
    while ((n = bufferevent_read(bev, buf, sizeof(buf) - 1)) > 0) {
62
        buf[n] = '\0';
63
        printf("Received: %s", buf);
64

65
        // 回显
66
        bufferevent_write(bev, buf, n);
67
    }
68
}
69

70
static void event_cb(struct bufferevent *bev, short events, void *arg) {
71
    if (events & BEV_EVENT_CONNECTED) {
72
        printf("SSL handshake completed\n");
73
    } else if (events & BEV_EVENT_ERROR) {
74
        unsigned long err;
75
        while ((err = bufferevent_get_openssl_error(bev))) {
76
            char msg[256];
77
            ERR_error_string_n(err, msg, sizeof(msg));
78
            fprintf(stderr, "SSL error: %s\n", msg);
79
        }
80
        bufferevent_free(bev);
81
    } else if (events & BEV_EVENT_EOF) {
82
        printf("Client disconnected\n");
83
        bufferevent_free(bev);
84
    }
85
}
86

87
static void accept_cb(struct evconnlistener *listener, evutil_socket_t fd,
88
                      struct sockaddr *addr, int len, void *arg) {
89
    struct event_base *base = arg;
90

91
    printf("New connection from %s:%d\n",
92
           inet_ntoa(((struct sockaddr_in *)addr)->sin_addr),
93
           ntohs(((struct sockaddr_in *)addr)->sin_port));
94

95
    SSL *ssl = SSL_new(g_ssl_ctx);
96

97
    struct bufferevent *bev = bufferevent_openssl_socket_new(
98
        base, fd, ssl, BUFFEREVENT_SSL_ACCEPTING,
99
        BEV_OPT_CLOSE_ON_FREE | BEV_OPT_DEFER_CALLBACKS);
100

101
    bufferevent_setcb(bev, read_cb, NULL, event_cb, NULL);
102
    bufferevent_enable(bev, EV_READ | EV_WRITE);
103
}
104

105
int main() {
106
    init_openssl();
107

108
    g_ssl_ctx = create_server_ssl_ctx();
109
    if (!g_ssl_ctx) {
110
        fprintf(stderr, "Failed to create SSL context\n");
111
        return 1;
112
    }
113

114
    struct event_base *base = event_base_new();
115

116
    struct sockaddr_in sin;
117
    memset(&sin, 0, sizeof(sin));
118
    sin.sin_family = AF_INET;
119
    sin.sin_port = htons(8443);
120
    sin.sin_addr.s_addr = INADDR_ANY;
121

122
    struct evconnlistener *listener = evconnlistener_new_bind(
123
        base, accept_cb, base,
124
        LEV_OPT_CLOSE_ON_FREE | LEV_OPT_REUSEABLE,
125
        -1, (struct sockaddr *)&sin, sizeof(sin));
126

127
    if (!listener) {
128
        fprintf(stderr, "Failed to create listener\n");
129
        SSL_CTX_free(g_ssl_ctx);
130
        event_base_free(base);
131
        return 1;
132
    }
133

134
    printf("SSL server listening on port 8443\n");
135

136
    event_base_dispatch(base);
137

138
    evconnlistener_free(listener);
139
    SSL_CTX_free(g_ssl_ctx);
140
    event_base_free(base);
141

142
    return 0;
143
}

展开收起

八、证书验证#

8.1 自定义验证回调#

1
#include <stdio.h>
2
#include <openssl/ssl.h>
3
#include <openssl/x509.h>
4
#include <openssl/x509v3.h>
5

6
static int verify_callback(int preverify_ok, X509_STORE_CTX *ctx) {
7
    X509 *cert = X509_STORE_CTX_get_current_cert(ctx);
8
    int depth = X509_STORE_CTX_get_error_depth(ctx);
9
    int err = X509_STORE_CTX_get_error(ctx);
10

11
    char subject[256];
12
    X509_NAME_oneline(X509_get_subject_name(cert), subject, sizeof(subject));
13

14
    printf("Certificate depth %d: %s\n", depth, subject);
15

16
    if (!preverify_ok) {
17
        printf("Verification failed: %s\n",
18
               X509_verify_cert_error_string(err));
19

20
        // 可以在这里实现自定义验证逻辑
21
        // 返回1继续验证，返回0终止
22
        return 0;
23
    }
24

25
    printf("Verification passed\n");
26
    return 1;
27
}
28

29
void setup_verification(SSL_CTX *ctx) {
30
    SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER, verify_callback);
31
    SSL_CTX_set_verify_depth(ctx, 4);
32

33
    // 加载CA证书
34
    SSL_CTX_load_verify_locations(ctx, "ca-bundle.crt", NULL);
35

36
    // 或使用系统默认CA
37
    SSL_CTX_set_default_verify_paths(ctx);
38
}

展开收起

8.2 获取证书信息#

1
#include <stdio.h>
2
#include <openssl/ssl.h>
3
#include <openssl/x509.h>
4

5
void print_certificate_info(SSL *ssl) {
6
    X509 *cert = SSL_get_peer_certificate(ssl);
7
    if (!cert) {
8
        printf("No peer certificate\n");
9
        return;
10
    }
11

12
    char subject[256];
13
    char issuer[256];
14

15
    X509_NAME_oneline(X509_get_subject_name(cert), subject, sizeof(subject));
16
    X509_NAME_oneline(X509_get_issuer_name(cert), issuer, sizeof(issuer));
17

18
    printf("Subject: %s\n", subject);
19
    printf("Issuer: %s\n", issuer);
20

21
    // 检查证书有效期
22
    const ASN1_TIME *not_before = X509_get0_notBefore(cert);
23
    const ASN1_TIME *not_after = X509_get0_notAfter(cert);
24

25
    // 验证结果
26
    long verify_result = SSL_get_verify_result(ssl);
27
    if (verify_result == X509_V_OK) {
28
        printf("Certificate verified successfully\n");
29
    } else {
30
        printf("Certificate verification failed: %s\n",
31
               X509_verify_cert_error_string(verify_result));
32
    }
33

34
    X509_free(cert);
35
}

展开收起

九、SNI支持#

9.1 客户端SNI#

1
#include <openssl/ssl.h>
2

3
void set_sni(SSL *ssl, const char *hostname) {
4
    // 设置SNI（Server Name Indication）
5
    SSL_set_tlsext_host_name(ssl, hostname);
6

7
    // 设置主机名验证
8
    SSL_set1_host(ssl, hostname);
9
}

9.2 服务器SNI回调#

1
#include <stdio.h>
2
#include <string.h>
3
#include <openssl/ssl.h>
4

5
static int sni_callback(SSL *ssl, int *al, void *arg) {
6
    const char *servername = SSL_get_servername(ssl, TLSEXT_NAMETYPE_host_name);
7

8
    if (servername) {
9
        printf("SNI: %s\n", servername);
10

11
        // 根据域名选择不同的证书
12
        if (strcmp(servername, "example.com") == 0) {
13
            SSL_set_SSL_CTX(ssl, get_example_com_ctx());
14
        } else if (strcmp(servername, "test.com") == 0) {
15
            SSL_set_SSL_CTX(ssl, get_test_com_ctx());
16
        }
17
    }
18

19
    return SSL_TLSEXT_ERR_OK;
20
}
21

22
void setup_sni_callback(SSL_CTX *ctx) {
23
    SSL_CTX_set_tlsext_servername_callback(ctx, sni_callback);
24
}

展开收起

十、ALPN支持#

10.1 ALPN协商#

1
#include <openssl/ssl.h>
2

3
// 客户端设置ALPN
4
static int alpn_client_select_proto(SSL *ssl, unsigned char **out,
5
                                     unsigned char *outlen,
6
                                     const unsigned char *server,
7
                                     unsigned int server_len, void *arg) {
8
    const unsigned char *client = (const unsigned char *)"\x02h2\x08http/1.1";
9
    unsigned int client_len = 12;
10

11
    if (SSL_select_next_proto(out, outlen, server, server_len,
12
                               client, client_len) == OPENSSL_NPN_NEGOTIATED) {
13
        return SSL_TLSEXT_ERR_OK;
14
    }
15

16
    return SSL_TLSEXT_ERR_ALERT_FATAL;
17
}
18

19
void setup_client_alpn(SSL_CTX *ctx) {
20
    SSL_CTX_set_alpn_protos(ctx,
21
        (const unsigned char *)"\x02h2\x08http/1.1", 12);
22
}
23

24
// 服务器设置ALPN回调
25
static int alpn_server_select_proto(SSL *ssl, const unsigned char **out,
26
                                     unsigned char *outlen,
27
                                     const unsigned char *in,
28
                                     unsigned int inlen, void *arg) {
29
    // 优先选择h2
30
    if (SSL_select_next_proto((unsigned char **)out, outlen,
31
                               (const unsigned char *)"\x02h2\x08http/1.1", 12,
32
                               in, inlen) == OPENSSL_NPN_NEGOTIATED) {
33
        return SSL_TLSEXT_ERR_OK;
34
    }
35

36
    *out = (const unsigned char *)"http/1.1";
37
    *outlen = 8;
38
    return SSL_TLSEXT_ERR_OK;
39
}
40

41
void setup_server_alpn(SSL_CTX *ctx) {
42
    SSL_CTX_set_alpn_select_cb(ctx, alpn_server_select_proto, NULL);
43
}

展开收起

十一、错误处理#

11.1 SSL错误处理#

1
#include <stdio.h>
2
#include <openssl/ssl.h>
3
#include <openssl/err.h>
4

5
void print_ssl_error(SSL *ssl, int ret) {
6
    int err = SSL_get_error(ssl, ret);
7

8
    switch (err) {
9
        case SSL_ERROR_NONE:
10
            printf("No error\n");
11
            break;
12
        case SSL_ERROR_ZERO_RETURN:
13
            printf("SSL connection closed cleanly\n");
14
            break;
15
        case SSL_ERROR_WANT_READ:
16
            printf("SSL needs more data to read\n");
17
            break;
18
        case SSL_ERROR_WANT_WRITE:
19
            printf("SSL needs to write more data\n");
20
            break;
21
        case SSL_ERROR_WANT_CONNECT:
22
            printf("SSL connect not completed\n");
23
            break;
24
        case SSL_ERROR_WANT_ACCEPT:
25
            printf("SSL accept not completed\n");
26
            break;
27
        case SSL_ERROR_WANT_X509_LOOKUP:
28
            printf("SSL certificate lookup needed\n");
29
            break;
30
        case SSL_ERROR_SYSCALL:
31
            printf("SSL I/O error: %s\n", strerror(errno));
32
            break;
33
        case SSL_ERROR_SSL:
34
            printf("SSL protocol error\n");
35
            ERR_print_errors_fp(stderr);
36
            break;
37
        default:
38
            printf("Unknown SSL error: %d\n", err);
39
    }
40
}
41

42
void print_all_ssl_errors(void) {
43
    unsigned long err;
44
    while ((err = ERR_get_error())) {
45
        char msg[256];
46
        ERR_error_string_n(err, msg, sizeof(msg));
47
        fprintf(stderr, "SSL Error: %s\n", msg);
48
    }
49
}

展开收起

十二、完整示例：HTTPS服务器#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <signal.h>
5
#include <event2/event.h>
6
#include <event2/listener.h>
7
#include <event2/bufferevent.h>
8
#include <event2/bufferevent_ssl.h>
9
#include <event2/http.h>
10
#include <openssl/ssl.h>
11
#include <openssl/err.h>
12

13
static SSL_CTX *g_ssl_ctx = NULL;
14
static struct event_base *g_base = NULL;
15

16
static void signal_cb(evutil_socket_t fd, short events, void *arg) {
17
    printf("\nShutting down...\n");
18
    event_base_loopbreak(g_base);
19
}
20

21
static void init_openssl(void) {
22
    SSL_library_init();
23
    SSL_load_error_strings();
24
    OpenSSL_add_all_algorithms();
25
}
26

27
static SSL_CTX *create_ssl_ctx(void) {
28
    SSL_CTX *ctx = SSL_CTX_new(TLS_server_method());
29
    if (!ctx) return NULL;
30

31
    SSL_CTX_set_min_proto_version(ctx, TLS1_2_VERSION);
32

33
    // 加载证书链
34
    if (SSL_CTX_use_certificate_chain_file(ctx, "server.crt") != 1) {
35
        fprintf(stderr, "Failed to load certificate chain\n");
36
        SSL_CTX_free(ctx);
37
        return NULL;
38
    }
39

40
    // 加载私钥
41
    if (SSL_CTX_use_PrivateKey_file(ctx, "server.key", SSL_FILETYPE_PEM) != 1) {
42
        fprintf(stderr, "Failed to load private key\n");
43
        SSL_CTX_free(ctx);
44
        return NULL;
45
    }
46

47
    // 设置ECDH自动选择曲线
48
    SSL_CTX_set_ecdh_auto(ctx, 1);
49

50
    // 设置密码套件
51
    SSL_CTX_set_cipher_list(ctx,
52
        "ECDHE-ECDSA-AES128-GCM-SHA256:"
53
        "ECDHE-RSA-AES128-GCM-SHA256:"
54
        "ECDHE-ECDSA-AES256-GCM-SHA384:"
55
        "ECDHE-RSA-AES256-GCM-SHA384:"
56
        "ECDHE-ECDSA-CHACHA20-POLY1305:"
57
        "ECDHE-RSA-CHACHA20-POLY1305");
58

59
    printf("SSL context configured\n");
60
    return ctx;
61
}
62

63
static void http_request_cb(struct evhttp_request *req, void *arg) {
64
    struct evbuffer *buf = evbuffer_new();
65

66
    evbuffer_add_printf(buf,
67
        "<html><body>"
68
        "<h1>HTTPS Server</h1>"
69
        "<p>This is a secure connection!</p>"
70
        "<p>Protocol: %s</p>"
71
        "<p>Cipher: %s</p>"
72
        "</body></html>",
73
        SSL_get_version(SSL_get_current_compression(SSL_get_current_compression(NULL))),
74
        SSL_get_cipher_name(SSL_get_current_compression(SSL_get_current_compression(NULL))));
75

76
    evhttp_add_header(evhttp_request_get_output_headers(req),
77
                      "Content-Type", "text/html");
78
    evhttp_send_reply(req, HTTP_OK, "OK", buf);
79

80
    evbuffer_free(buf);
81
}
82

83
int main() {
84
    init_openssl();
85

86
    g_ssl_ctx = create_ssl_ctx();
87
    if (!g_ssl_ctx) {
88
        fprintf(stderr, "Failed to create SSL context\n");
89
        return 1;
90
    }
91

92
    g_base = event_base_new();
93

94
    // 设置信号处理
95
    struct event *sigint = evsignal_new(g_base, SIGINT, signal_cb, NULL);
96
    event_add(sigint, NULL);
97

98
    // 创建HTTP服务器
99
    struct evhttp *http = evhttp_new(g_base);
100

101
    evhttp_set_cb(http, "/", http_request_cb, NULL);
102

103
    // 绑定地址
104
    if (evhttp_bind_socket(http, "0.0.0.0", 8443) != 0) {
105
        fprintf(stderr, "Failed to bind socket\n");
106
        return 1;
107
    }
108

109
    printf("HTTPS server listening on https://0.0.0.0:8443/\n");
110
    printf("Press Ctrl+C to stop\n");
111

112
    event_base_dispatch(g_base);
113

114
    evhttp_free(http);
115
    event_free(sigint);
116
    SSL_CTX_free(g_ssl_ctx);
117
    event_base_free(g_base);
118

119
    EVP_cleanup();
120
    ERR_free_strings();
121

122
    return 0;
123
}

展开收起

十三、最佳实践#

场景	建议
协议版本	禁用SSLv3和TLS1.0，使用TLS1.2+
密码套件	优先使用ECDHE和AES-GCM
证书验证	始终验证服务器证书
SNI	客户端设置SNI以支持虚拟主机
错误处理	详细记录SSL错误信息
证书更新	自动化证书续期流程
HSTS	服务器启用HSTS头部

其他相关资料请移步到个人主页

🔌 TCP监听器 - libevent源码深度解析系列（九）

Sat, 11 Apr 2026 00:00:00 GMT

🔌 TCP监听器#

一、概述#

evconnlistener是libevent提供的高级抽象，用于监听TCP连接。它封装了底层的socket创建、绑定、监听和接受连接的过程，使得开发者可以更方便地创建TCP服务端。

二、创建监听器#

2.1 创建函数#

1
/* 创建监听器（已绑定socket）
2
 * @param base     event_base
3
 * @param cb       接受连接的回调函数
4
 * @param ptr      回调函数的参数
5
 * @param flags    选项标志
6
 * @param backlog  listen()的backlog参数，-1表示使用默认值
7
 * @param sa       绑定的地址
8
 * @param socklen  地址长度
9
 */
10
struct evconnlistener *evconnlistener_new_bind(struct event_base *base,
11
    evconnlistener_cb cb, void *ptr, unsigned flags, int backlog,
12
    const struct sockaddr *sa, int socklen);
13

14
/* 创建监听器（已有socket）
15
 * @param fd       已绑定的socket
16
 */
17
struct evconnlistener *evconnlistener_new(struct event_base *base,
18
    evconnlistener_cb cb, void *ptr, unsigned flags, int backlog,
19
    evutil_socket_t fd);
20

21
/* 释放监听器 */
22
void evconnlistener_free(struct evconnlistener *lev);

展开收起

2.2 选项标志#

1
#define LEV_OPT_LEAVE_SOCKETS_BLOCKED  0x01  // 不设置非阻塞
2
#define LEV_OPT_CLOSE_ON_FREE          0x02  // 释放时关闭socket
3
#define LEV_OPT_CLOSE_ON_EXEC          0x04  // 设置FD_CLOEXEC
4
#define LEV_OPT_REUSEABLE              0x08  // 设置SO_REUSEADDR
5
#define LEV_OPT_THREADSAFE             0x10  // 线程安全
6
#define LEV_OPT_DISABLED               0x20  // 创建时禁用
7
#define LEV_OPT_DEFERRED_ACCEPT        0x40  // 延迟accept（Linux）

三、回调函数#

3.1 回调函数类型#

1
/**
2
 * @param listener  监听器
3
 * @param fd        新连接的socket
4
 * @param addr      客户端地址
5
 * @param socklen   地址长度
6
 * @param userarg   用户参数
7
 */
8
typedef void (*evconnlistener_cb)(struct evconnlistener *listener,
9
    evutil_socket_t fd, struct sockaddr *addr, int socklen, void *userarg);

3.2 错误回调#

1
typedef void (*evconnlistener_errorcb)(struct evconnlistener *lis, void *ptr);
2

3
/* 设置错误回调 */
4
void evconnlistener_set_error_cb(struct evconnlistener *lev,
5
    evconnlistener_errorcb errorcb);

四、监听器操作#

4.1 启用和禁用#

1
/* 启用监听器 */
2
int evconnlistener_enable(struct evconnlistener *lev);
3

4
/* 禁用监听器 */
5
int evconnlistener_disable(struct evconnlistener *lev);

4.2 获取信息#

1
/* 获取监听socket */
2
evutil_socket_t evconnlistener_get_fd(struct evconnlistener *lev);
3

4
/* 获取所属的event_base */
5
struct event_base *evconnlistener_get_base(struct evconnlistener *lev);

五、完整示例#

5.1 回射服务器#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <unistd.h>
5
#include <signal.h>
6
#include <event2/buffer.h>
7
#include <event2/bufferevent.h>
8
#include <event2/listener.h>
9
#include <event2/event.h>
10

11
static const int PORT = 8080;
12

13
static void echo_read_cb(struct bufferevent *bev, void *ctx) {
14
    struct evbuffer *input = bufferevent_get_input(bev);
15
    struct evbuffer *output = bufferevent_get_output(bev);
16

17
    evbuffer_add_buffer(output, input);
18
}
19

20
static void echo_event_cb(struct bufferevent *bev, short events, void *ctx) {
21
    if (events & BEV_EVENT_ERROR) {
22
        perror("Error from bufferevent");
23
    }
24
    if (events & (BEV_EVENT_EOF | BEV_EVENT_ERROR)) {
25
        bufferevent_free(bev);
26
    }
27
}
28

29
static void accept_conn_cb(struct evconnlistener *listener,
30
    evutil_socket_t fd, struct sockaddr *address, int socklen, void *ctx) {
31

32
    printf("New connection: fd=%d\n", fd);
33

34
    struct event_base *base = evconnlistener_get_base(listener);
35
    struct bufferevent *bev = bufferevent_socket_new(base, fd, BEV_OPT_CLOSE_ON_FREE);
36

37
    bufferevent_setcb(bev, echo_read_cb, NULL, echo_event_cb, NULL);
38
    bufferevent_enable(bev, EV_READ | EV_WRITE);
39
}
40

41
static void accept_error_cb(struct evconnlistener *listener, void *ctx) {
42
    struct event_base *base = evconnlistener_get_base(listener);
43
    int err = EVUTIL_SOCKET_ERROR();
44
    fprintf(stderr, "Got an error %d (%s) on the listener. Shutting down.\n",
45
            err, evutil_socket_error_to_string(err));
46
    event_base_loopexit(base, NULL);
47
}
48

49
static void signal_cb(evutil_socket_t sig, short events, void *user_data) {
50
    struct event_base *base = user_data;
51
    printf("Caught signal %d, shutting down.\n", sig);
52
    event_base_loopexit(base, NULL);
53
}
54

55
int main(int argc, char **argv) {
56
    struct event_base *base;
57
    struct evconnlistener *listener;
58
    struct event *signal_event;
59
    struct sockaddr_in sin;
60

61
    base = event_base_new();
62
    if (!base) {
63
        fprintf(stderr, "Could not initialize libevent!\n");
64
        return 1;
65
    }
66

67
    memset(&sin, 0, sizeof(sin));
68
    sin.sin_family = AF_INET;
69
    sin.sin_port = htons(PORT);
70
    sin.sin_addr.s_addr = htonl(INADDR_ANY);
71

72
    listener = evconnlistener_new_bind(base, accept_conn_cb, NULL,
73
        LEV_OPT_REUSEABLE | LEV_OPT_CLOSE_ON_FREE, -1,
74
        (struct sockaddr*)&sin, sizeof(sin));
75

76
    if (!listener) {
77
        fprintf(stderr, "Could not create a listener!\n");
78
        return 1;
79
    }
80

81
    evconnlistener_set_error_cb(listener, accept_error_cb);
82

83
    signal_event = evsignal_new(base, SIGINT, signal_cb, (void*)base);
84
    if (!signal_event || event_add(signal_event, NULL) < 0) {
85
        fprintf(stderr, "Could not create/add a signal event!\n");
86
        return 1;
87
    }
88

89
    printf("Server listening on port %d\n", PORT);
90
    event_base_dispatch(base);
91

92
    evconnlistener_free(listener);
93
    event_free(signal_event);
94
    event_base_free(base);
95

96
    printf("Server shutdown complete\n");
97
    return 0;
98
}

展开收起

5.2 编译运行#

Terminal window

1
# 编译
2
gcc -o echo_server echo_server.c -levent
3

4
# 运行
5
./echo_server
6

7
# 测试
8
telnet 127.0.0.1 8080
9
# 或
10
nc 127.0.0.1 8080

六、多端口监听#

1
#include <stdio.h>
2
#include <string.h>
3
#include <event2/buffer.h>
4
#include <event2/bufferevent.h>
5
#include <event2/listener.h>
6
#include <event2/event.h>
7

8
static void read_cb(struct bufferevent *bev, void *ctx) {
9
    struct evbuffer *input = bufferevent_get_input(bev);
10
    struct evbuffer *output = bufferevent_get_output(bev);
11
    evbuffer_add_buffer(output, input);
12
}
13

14
static void event_cb(struct bufferevent *bev, short events, void *ctx) {
15
    if (events & (BEV_EVENT_EOF | BEV_EVENT_ERROR)) {
16
        bufferevent_free(bev);
17
    }
18
}
19

20
static void accept_cb(struct evconnlistener *listener,
21
    evutil_socket_t fd, struct sockaddr *addr, int socklen, void *ctx) {
22

23
    int port = *(int*)ctx;
24
    printf("Connection on port %d, fd=%d\n", port, fd);
25

26
    struct event_base *base = evconnlistener_get_base(listener);
27
    struct bufferevent *bev = bufferevent_socket_new(base, fd, BEV_OPT_CLOSE_ON_FREE);
28

29
    bufferevent_setcb(bev, read_cb, NULL, event_cb, NULL);
30
    bufferevent_enable(bev, EV_READ | EV_WRITE);
31
}
32

33
int main() {
34
    struct event_base *base = event_base_new();
35

36
    int ports[] = {8080, 8081, 8082};
37
    struct evconnlistener *listeners[3];
38

39
    for (int i = 0; i < 3; i++) {
40
        struct sockaddr_in sin;
41
        memset(&sin, 0, sizeof(sin));
42
        sin.sin_family = AF_INET;
43
        sin.sin_port = htons(ports[i]);
44
        sin.sin_addr.s_addr = htonl(INADDR_ANY);
45

46
        listeners[i] = evconnlistener_new_bind(base, accept_cb, &ports[i],
47
            LEV_OPT_REUSEABLE | LEV_OPT_CLOSE_ON_FREE, -1,
48
            (struct sockaddr*)&sin, sizeof(sin));
49

50
        printf("Listening on port %d\n", ports[i]);
51
    }
52

53
    event_base_dispatch(base);
54

55
    for (int i = 0; i < 3; i++) {
56
        evconnlistener_free(listeners[i]);
57
    }
58
    event_base_free(base);
59

60
    return 0;
61
}

展开收起

七、使用注意事项#

注意事项	说明
backlog参数	-1使用默认值128，高并发场景建议设置更大的值
SO_REUSEADDR	建议启用，允许端口重用
错误处理	必须设置错误回调，处理监听错误
资源释放	使用LEV_OPT_CLOSE_ON_FREE自动关闭socket
线程安全	多线程环境下使用LEV_OPT_THREADSAFE

其他相关资料请移步到个人主页

🌐 TCP服务端与客户端 - libevent源码深度解析系列（十）

Sat, 11 Apr 2026 00:00:00 GMT

🌐 TCP服务端与客户端#

一、TCP服务端#

1.1 使用event实现#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <unistd.h>
5
#include <arpa/inet.h>
6
#include <event2/event.h>
7
#include <event2/listener.h>
8

9
#define PORT 8080
10
#define BUFFER_SIZE 1024
11

12
struct connection {
13
    struct event *read_event;
14
    struct event *write_event;
15
    char buffer[BUFFER_SIZE];
16
    size_t buffer_len;
17
};
18

19
static void read_cb(evutil_socket_t fd, short events, void *arg) {
20
    struct connection *conn = (struct connection *)arg;
21
    ssize_t n = recv(fd, conn->buffer, BUFFER_SIZE - 1, 0);
22

23
    if (n <= 0) {
24
        if (n == 0) {
25
            printf("Client disconnected\n");
26
        } else {
27
            perror("recv");
28
        }
29
        event_free(conn->read_event);
30
        close(fd);
31
        free(conn);
32
        return;
33
    }
34

35
    conn->buffer[n] = '\0';
36
    printf("Received: %s", conn->buffer);
37

38
    // 回显
39
    send(fd, conn->buffer, n, 0);
40
}
41

42
static void accept_cb(evutil_socket_t fd, short events, void *arg) {
43
    struct event_base *base = (struct event_base *)arg;
44
    struct sockaddr_in client_addr;
45
    socklen_t client_len = sizeof(client_addr);
46

47
    int client_fd = accept(fd, (struct sockaddr *)&client_addr, &client_len);
48
    if (client_fd < 0) {
49
        perror("accept");
50
        return;
51
    }
52

53
    printf("New connection from %s:%d\n",
54
           inet_ntoa(client_addr.sin_addr), ntohs(client_addr.sin_port));
55

56
    evutil_make_socket_nonblocking(client_fd);
57

58
    struct connection *conn = calloc(1, sizeof(struct connection));
59
    conn->read_event = event_new(base, client_fd, EV_READ | EV_PERSIST, read_cb, conn);
60
    event_add(conn->read_event, NULL);
61
}
62

63
int main() {
64
    struct event_base *base = event_base_new();
65

66
    int listen_fd = socket(AF_INET, SOCK_STREAM, 0);
67
    evutil_make_socket_nonblocking(listen_fd);
68

69
    int reuse = 1;
70
    setsockopt(listen_fd, SOL_SOCKET, SO_REUSEADDR, &reuse, sizeof(reuse));
71

72
    struct sockaddr_in server_addr;
73
    memset(&server_addr, 0, sizeof(server_addr));
74
    server_addr.sin_family = AF_INET;
75
    server_addr.sin_port = htons(PORT);
76
    server_addr.sin_addr.s_addr = INADDR_ANY;
77

78
    bind(listen_fd, (struct sockaddr *)&server_addr, sizeof(server_addr));
79
    listen(listen_fd, 10);
80

81
    printf("Server listening on port %d\n", PORT);
82

83
    struct event *accept_event = event_new(base, listen_fd, EV_READ | EV_PERSIST, accept_cb, base);
84
    event_add(accept_event, NULL);
85

86
    event_base_dispatch(base);
87

88
    event_free(accept_event);
89
    close(listen_fd);
90
    event_base_free(base);
91

92
    return 0;
93
}

展开收起

1.2 使用bufferevent实现#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <unistd.h>
5
#include <signal.h>
6
#include <arpa/inet.h>
7
#include <event2/buffer.h>
8
#include <event2/bufferevent.h>
9
#include <event2/listener.h>
10
#include <event2/event.h>
11

12
#define PORT 8080
13

14
static void read_cb(struct bufferevent *bev, void *ctx) {
15
    struct evbuffer *input = bufferevent_get_input(bev);
16
    struct evbuffer *output = bufferevent_get_output(bev);
17

18
    char *line;
19
    size_t len;
20
    while ((line = evbuffer_readln(input, &len, EVBUFFER_EOL_LF)) != NULL) {
21
        printf("Received: %s\n", line);
22
        evbuffer_add_printf(output, "Echo: %s\n", line);
23
        free(line);
24
    }
25
}
26

27
static void event_cb(struct bufferevent *bev, short events, void *ctx) {
28
    if (events & BEV_EVENT_EOF) {
29
        printf("Connection closed.\n");
30
    } else if (events & BEV_EVENT_ERROR) {
31
        printf("Got an error on the connection: %s\n", strerror(errno));
32
    }
33
    bufferevent_free(bev);
34
}
35

36
static void accept_conn_cb(struct evconnlistener *listener,
37
    evutil_socket_t fd, struct sockaddr *address, int socklen, void *ctx) {
38

39
    struct sockaddr_in *sin = (struct sockaddr_in *)address;
40
    printf("New connection from %s:%d\n",
41
           inet_ntoa(sin->sin_addr), ntohs(sin->sin_port));
42

43
    struct event_base *base = evconnlistener_get_base(listener);
44
    struct bufferevent *bev = bufferevent_socket_new(base, fd, BEV_OPT_CLOSE_ON_FREE);
45

46
    bufferevent_setcb(bev, read_cb, NULL, event_cb, NULL);
47
    bufferevent_enable(bev, EV_READ | EV_WRITE);
48
}
49

50
static void accept_error_cb(struct evconnlistener *listener, void *ctx) {
51
    struct event_base *base = evconnlistener_get_base(listener);
52
    int err = EVUTIL_SOCKET_ERROR();
53
    fprintf(stderr, "Listener error %d: %s\n", err, evutil_socket_error_to_string(err));
54
    event_base_loopexit(base, NULL);
55
}
56

57
static void signal_cb(evutil_socket_t sig, short events, void *ctx) {
58
    struct event_base *base = ctx;
59
    printf("Caught signal %d, exiting...\n", sig);
60
    event_base_loopexit(base, NULL);
61
}
62

63
int main() {
64
    struct event_base *base = event_base_new();
65

66
    struct sockaddr_in sin;
67
    memset(&sin, 0, sizeof(sin));
68
    sin.sin_family = AF_INET;
69
    sin.sin_port = htons(PORT);
70
    sin.sin_addr.s_addr = htonl(INADDR_ANY);
71

72
    struct evconnlistener *listener = evconnlistener_new_bind(base,
73
        accept_conn_cb, NULL, LEV_OPT_REUSEABLE | LEV_OPT_CLOSE_ON_FREE,
74
        -1, (struct sockaddr *)&sin, sizeof(sin));
75

76
    if (!listener) {
77
        perror("Couldn't create listener");
78
        return 1;
79
    }
80

81
    evconnlistener_set_error_cb(listener, accept_error_cb);
82

83
    struct event *signal_event = evsignal_new(base, SIGINT, signal_cb, base);
84
    event_add(signal_event, NULL);
85

86
    printf("Server listening on port %d\n", PORT);
87
    event_base_dispatch(base);
88

89
    evconnlistener_free(listener);
90
    event_free(signal_event);
91
    event_base_free(base);
92

93
    return 0;
94
}

展开收起

二、TCP客户端#

2.1 使用bufferevent实现#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <unistd.h>
5
#include <arpa/inet.h>
6
#include <event2/buffer.h>
7
#include <event2/bufferevent.h>
8
#include <event2/event.h>
9

10
#define SERVER_IP "127.0.0.1"
11
#define SERVER_PORT 8080
12

13
static void read_cb(struct bufferevent *bev, void *ctx) {
14
    struct evbuffer *input = bufferevent_get_input(bev);
15

16
    char buffer[1024];
17
    size_t n;
18
    while ((n = evbuffer_remove(input, buffer, sizeof(buffer) - 1)) > 0) {
19
        buffer[n] = '\0';
20
        printf("Server: %s", buffer);
21
    }
22
}
23

24
static void event_cb(struct bufferevent *bev, short events, void *ctx) {
25
    struct event_base *base = ctx;
26

27
    if (events & BEV_EVENT_CONNECTED) {
28
        printf("Connected to server!\n");
29

30
        // 发送消息
31
        bufferevent_write(bev, "Hello, Server!\n", 15);
32

33
        // 设置读回调
34
        bufferevent_setcb(bev, read_cb, NULL, event_cb, base);
35
    } else if (events & BEV_EVENT_EOF) {
36
        printf("Connection closed.\n");
37
        event_base_loopexit(base, NULL);
38
    } else if (events & BEV_EVENT_ERROR) {
39
        printf("Connection error: %s\n", strerror(errno));
40
        event_base_loopexit(base, NULL);
41
    }
42
}
43

44
int main() {
45
    struct event_base *base = event_base_new();
46
    struct bufferevent *bev = bufferevent_socket_new(base, -1, BEV_OPT_CLOSE_ON_FREE);
47

48
    struct sockaddr_in sin;
49
    memset(&sin, 0, sizeof(sin));
50
    sin.sin_family = AF_INET;
51
    sin.sin_port = htons(SERVER_PORT);
52
    inet_pton(AF_INET, SERVER_IP, &sin.sin_addr);
53

54
    bufferevent_setcb(bev, NULL, NULL, event_cb, base);
55
    bufferevent_enable(bev, EV_READ | EV_WRITE);
56

57
    if (bufferevent_socket_connect(bev, (struct sockaddr *)&sin, sizeof(sin)) < 0) {
58
        perror("Connection failed");
59
        bufferevent_free(bev);
60
        event_base_free(base);
61
        return 1;
62
    }
63

64
    event_base_dispatch(base);
65

66
    bufferevent_free(bev);
67
    event_base_free(base);
68

69
    return 0;
70
}

展开收起

2.2 交互式客户端#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <unistd.h>
5
#include <arpa/inet.h>
6
#include <event2/buffer.h>
7
#include <event2/bufferevent.h>
8
#include <event2/event.h>
9

10
#define SERVER_IP "127.0.0.1"
11
#define SERVER_PORT 8080
12

13
static struct bufferevent *g_bev = NULL;
14

15
static void stdin_cb(evutil_socket_t fd, short events, void *arg) {
16
    char buffer[1024];
17
    ssize_t n = read(fd, buffer, sizeof(buffer) - 1);
18
    if (n > 0) {
19
        buffer[n] = '\0';
20
        if (g_bev) {
21
            bufferevent_write(g_bev, buffer, n);
22
        }
23
    }
24
}
25

26
static void server_read_cb(struct bufferevent *bev, void *ctx) {
27
    struct evbuffer *input = bufferevent_get_input(bev);
28

29
    char buffer[1024];
30
    size_t n;
31
    while ((n = evbuffer_remove(input, buffer, sizeof(buffer) - 1)) > 0) {
32
        buffer[n] = '\0';
33
        printf("%s", buffer);
34
    }
35
    printf("> ");
36
    fflush(stdout);
37
}
38

39
static void server_event_cb(struct bufferevent *bev, short events, void *ctx) {
40
    struct event_base *base = ctx;
41

42
    if (events & BEV_EVENT_CONNECTED) {
43
        printf("Connected to server!\n");
44
        printf("> ");
45
        fflush(stdout);
46
    } else if (events & (BEV_EVENT_EOF | BEV_EVENT_ERROR)) {
47
        printf("\nConnection closed.\n");
48
        event_base_loopexit(base, NULL);
49
    }
50
}
51

52
int main() {
53
    struct event_base *base = event_base_new();
54
    g_bev = bufferevent_socket_new(base, -1, BEV_OPT_CLOSE_ON_FREE);
55

56
    struct sockaddr_in sin;
57
    memset(&sin, 0, sizeof(sin));
58
    sin.sin_family = AF_INET;
59
    sin.sin_port = htons(SERVER_PORT);
60
    inet_pton(AF_INET, SERVER_IP, &sin.sin_addr);
61

62
    bufferevent_setcb(g_bev, server_read_cb, NULL, server_event_cb, base);
63
    bufferevent_enable(g_bev, EV_READ | EV_WRITE);
64

65
    // 监听标准输入
66
    struct event *stdin_event = event_new(base, STDIN_FILENO, EV_READ | EV_PERSIST, stdin_cb, NULL);
67
    event_add(stdin_event, NULL);
68

69
    if (bufferevent_socket_connect(g_bev, (struct sockaddr *)&sin, sizeof(sin)) < 0) {
70
        perror("Connection failed");
71
        return 1;
72
    }
73

74
    event_base_dispatch(base);
75

76
    event_free(stdin_event);
77
    bufferevent_free(g_bev);
78
    event_base_free(base);
79

80
    return 0;
81
}

展开收起

三、编译运行#

Terminal window

1
# 编译服务端
2
gcc -o server server.c -levent
3

4
# 编译客户端
5
gcc -o client client.c -levent
6

7
# 运行服务端
8
./server
9

10
# 运行客户端
11
./client

四、测试方法#

Terminal window

1
# 使用telnet测试
2
telnet 127.0.0.1 8080
3

4
# 使用nc测试
5
nc 127.0.0.1 8080
6

7
# 使用自定义客户端
8
./client

五、高级实践案例#

5.1 带配置管理的TCP服务器#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <unistd.h>
5
#include <signal.h>
6
#include <arpa/inet.h>
7
#include <event2/buffer.h>
8
#include <event2/bufferevent.h>
9
#include <event2/listener.h>
10
#include <event2/event.h>
11

12
// 服务器配置
13
struct server_config {
14
    int port;
15
    int backlog;
16
    int max_connections;
17
    int timeout;
18
};
19

20
// 连接管理
21
struct connection {
22
    int fd;
23
    struct bufferevent *bev;
24
    struct sockaddr_in addr;
25
    time_t last_activity;
26
};
27

28
static struct server_config config = {
29
    .port = 8080,
30
    .backlog = 10,
31
    .max_connections = 100,
32
    .timeout = 300 // 5分钟超时
33
};
34

35
static int connection_count = 0;
36

37
static void read_cb(struct bufferevent *bev, void *ctx) {
38
    struct connection *conn = (struct connection *)ctx;
39
    struct evbuffer *input = bufferevent_get_input(bev);
40
    struct evbuffer *output = bufferevent_get_output(bev);
41

42
    char *line;
43
    size_t len;
44
    while ((line = evbuffer_readln(input, &len, EVBUFFER_EOL_LF)) != NULL) {
45
        printf("Received from %s:%d: %s\n",
46
               inet_ntoa(conn->addr.sin_addr), ntohs(conn->addr.sin_port), line);
47

48
        // 处理命令
49
        if (strcmp(line, "ping") == 0) {
50
            evbuffer_add_printf(output, "pong\n");
51
        } else if (strcmp(line, "info") == 0) {
52
            evbuffer_add_printf(output, "Server: libevent TCP server\n");
53
            evbuffer_add_printf(output, "Connections: %d\n", connection_count);
54
        } else {
55
            evbuffer_add_printf(output, "Echo: %s\n", line);
56
        }
57
        free(line);
58
    }
59

60
    // 更新活动时间
61
    conn->last_activity = time(NULL);
62
}
63

64
static void event_cb(struct bufferevent *bev, short events, void *ctx) {
65
    struct connection *conn = (struct connection *)ctx;
66

67
    if (events & BEV_EVENT_EOF) {
68
        printf("Connection closed by %s:%d\n",
69
               inet_ntoa(conn->addr.sin_addr), ntohs(conn->addr.sin_port));
70
    } else if (events & BEV_EVENT_ERROR) {
71
        int err = EVUTIL_SOCKET_ERROR();
72
        printf("Error on connection from %s:%d: %s\n",
73
               inet_ntoa(conn->addr.sin_addr), ntohs(conn->addr.sin_port),
74
               evutil_socket_error_to_string(err));
75
    } else if (events & BEV_EVENT_TIMEOUT) {
76
        printf("Connection timeout from %s:%d\n",
77
               inet_ntoa(conn->addr.sin_addr), ntohs(conn->addr.sin_port));
78
    }
79

80
    bufferevent_free(conn->bev);
81
    free(conn);
82
    connection_count--;
83
    printf("Connection count: %d\n", connection_count);
84
}
85

86
static void accept_conn_cb(struct evconnlistener *listener,
87
    evutil_socket_t fd, struct sockaddr *address, int socklen, void *ctx) {
88

89
    struct event_base *base = evconnlistener_get_base(listener);
90
    struct connection *conn = calloc(1, sizeof(struct connection));
91

92
    if (!conn) {
93
        perror("calloc");
94
        close(fd);
95
        return;
96
    }
97

98
    // 检查连接数限制
99
    if (connection_count >= config.max_connections) {
100
        printf("Connection limit reached, rejecting connection\n");
101
        close(fd);
102
        free(conn);
103
        return;
104
    }
105

106
    conn->fd = fd;
107
    memcpy(&conn->addr, address, sizeof(struct sockaddr_in));
108
    conn->last_activity = time(NULL);
109

110
    // 创建bufferevent
111
    conn->bev = bufferevent_socket_new(base, fd, BEV_OPT_CLOSE_ON_FREE);
112
    if (!conn->bev) {
113
        perror("bufferevent_socket_new");
114
        close(fd);
115
        free(conn);
116
        return;
117
    }
118

119
    // 设置回调
120
    bufferevent_setcb(conn->bev, read_cb, NULL, event_cb, conn);
121

122
    // 设置超时
123
    struct timeval tv = {config.timeout, 0};
124
    bufferevent_set_timeouts(conn->bev, &tv, NULL);
125

126
    // 启用读写
127
    bufferevent_enable(conn->bev, EV_READ | EV_WRITE);
128

129
    connection_count++;
130
    printf("New connection from %s:%d, count: %d\n",
131
           inet_ntoa(conn->addr.sin_addr), ntohs(conn->addr.sin_port), connection_count);
132
}
133

134
static void accept_error_cb(struct evconnlistener *listener, void *ctx) {
135
    struct event_base *base = evconnlistener_get_base(listener);
136
    int err = EVUTIL_SOCKET_ERROR();
137
    fprintf(stderr, "Listener error %d: %s\n", err, evutil_socket_error_to_string(err));
138
    event_base_loopexit(base, NULL);
139
}
140

141
static void signal_cb(evutil_socket_t sig, short events, void *ctx) {
142
    struct event_base *base = ctx;
143
    printf("Caught signal %d, shutting down...\n", sig);
144
    event_base_loopexit(base, NULL);
145
}
146

147
static void load_config(const char *config_file) {
148
    // 这里可以实现从配置文件加载配置
149
    // 简化版本，使用默认配置
150
    printf("Loaded config: port=%d, backlog=%d, max_conn=%d, timeout=%d\n",
151
           config.port, config.backlog, config.max_connections, config.timeout);
152
}
153

154
int main(int argc, char **argv) {
155
    // 加载配置
156
    if (argc > 1) {
157
        load_config(argv[1]);
158
    } else {
159
        load_config(NULL);
160
    }
161

162
    struct event_base *base = event_base_new();
163
    if (!base) {
164
        fprintf(stderr, "Failed to create event base\n");
165
        return 1;
166
    }
167

168
    struct sockaddr_in sin;
169
    memset(&sin, 0, sizeof(sin));
170
    sin.sin_family = AF_INET;
171
    sin.sin_port = htons(config.port);
172
    sin.sin_addr.s_addr = htonl(INADDR_ANY);
173

174
    struct evconnlistener *listener = evconnlistener_new_bind(base,
175
        accept_conn_cb, NULL,
176
        LEV_OPT_REUSEABLE | LEV_OPT_CLOSE_ON_FREE,
177
        config.backlog,
178
        (struct sockaddr *)&sin, sizeof(sin));
179

180
    if (!listener) {
181
        perror("Couldn't create listener");
182
        event_base_free(base);
183
        return 1;
184
    }
185

186
    evconnlistener_set_error_cb(listener, accept_error_cb);
187

188
    // 信号处理
189
    struct event *signal_event = evsignal_new(base, SIGINT, signal_cb, base);
190
    event_add(signal_event, NULL);
191

192
    printf("TCP server started on port %d\n", config.port);
193
    printf("Max connections: %d\n", config.max_connections);
194
    printf("Connection timeout: %d seconds\n", config.timeout);
195
    printf("Press Ctrl+C to exit\n");
196

197
    event_base_dispatch(base);
198

199
    printf("Server shutdown, cleaning up...\n");
200

201
    evconnlistener_free(listener);
202
    event_free(signal_event);
203
    event_base_free(base);
204

205
    printf("Server shutdown complete\n");
206
    return 0;
207
}

展开收起

5.2 多线程TCP服务器#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <unistd.h>
5
#include <pthread.h>
6
#include <signal.h>
7
#include <arpa/inet.h>
8
#include <event2/buffer.h>
9
#include <event2/bufferevent.h>
10
#include <event2/listener.h>
11
#include <event2/event.h>
12
#include <event2/thread.h>
13

14
#define THREAD_COUNT 4
15
#define PORT 8080
16

17
struct thread_info {
18
    pthread_t thread_id;
19
    struct event_base *base;
20
    int pipefd[2];
21
    struct event *pipe_event;
22
};
23

24
static struct thread_info *threads;
25
static int next_thread = 0;
26
static pthread_mutex_t thread_lock = PTHREAD_MUTEX_INITIALIZER;
27

28
static void read_cb(struct bufferevent *bev, void *ctx) {
29
    struct evbuffer *input = bufferevent_get_input(bev);
30
    struct evbuffer *output = bufferevent_get_output(bev);
31

32
    char *line;
33
    size_t len;
34
    while ((line = evbuffer_readln(input, &len, EVBUFFER_EOL_LF)) != NULL) {
35
        printf("Thread %ld: Received: %s\n", pthread_self(), line);
36
        evbuffer_add_printf(output, "Echo: %s\n", line);
37
        free(line);
38
    }
39
}
40

41
static void event_cb(struct bufferevent *bev, short events, void *ctx) {
42
    if (events & BEV_EVENT_EOF) {
43
        printf("Thread %ld: Connection closed\n", pthread_self());
44
    } else if (events & BEV_EVENT_ERROR) {
45
        printf("Thread %ld: Connection error\n", pthread_self());
46
    }
47
    bufferevent_free(bev);
48
}
49

50
static void pipe_cb(evutil_socket_t fd, short events, void *arg) {
51
    struct thread_info *info = (struct thread_info *)arg;
52
    int client_fd;
53

54
    // 从管道读取客户端fd
55
    ssize_t n = read(fd, &client_fd, sizeof(client_fd));
56
    if (n != sizeof(client_fd)) {
57
        fprintf(stderr, "Error reading from pipe\n");
58
        return;
59
    }
60

61
    // 创建bufferevent
62
    struct bufferevent *bev = bufferevent_socket_new(info->base, client_fd, BEV_OPT_CLOSE_ON_FREE);
63
    if (!bev) {
64
        fprintf(stderr, "Error creating bufferevent\n");
65
        close(client_fd);
66
        return;
67
    }
68

69
    // 设置回调
70
    bufferevent_setcb(bev, read_cb, NULL, event_cb, NULL);
71
    bufferevent_enable(bev, EV_READ | EV_WRITE);
72
}
73

74
static void *thread_main(void *arg) {
75
    struct thread_info *info = (struct thread_info *)arg;
76
    printf("Thread %ld started\n", info->thread_id);
77
    event_base_dispatch(info->base);
78
    printf("Thread %ld exiting\n", info->thread_id);
79
    return NULL;
80
}
81

82
static void accept_conn_cb(struct evconnlistener *listener,
83
    evutil_socket_t fd, struct sockaddr *address, int socklen, void *ctx) {
84
    // 轮询选择线程
85
    pthread_mutex_lock(&thread_lock);
86
    struct thread_info *info = &threads[next_thread];
87
    next_thread = (next_thread + 1) % THREAD_COUNT;
88
    pthread_mutex_unlock(&thread_lock);
89

90
    // 发送fd到线程
91
    ssize_t n = write(info->pipefd[1], &fd, sizeof(fd));
92
    if (n != sizeof(fd)) {
93
        fprintf(stderr, "Error writing to pipe\n");
94
        close(fd);
95
    }
96
}
97

98
static void signal_cb(evutil_socket_t sig, short events, void *ctx) {
99
    struct event_base *base = ctx;
100
    printf("Caught signal %d, shutting down...\n", sig);
101

102
    // 停止所有线程
103
    for (int i = 0; i < THREAD_COUNT; i++) {
104
        event_base_loopbreak(threads[i].base);
105
    }
106

107
    event_base_loopbreak(base);
108
}
109

110
int main() {
111
    // 初始化线程支持
112
    if (evthread_use_pthreads() != 0) {
113
        fprintf(stderr, "Failed to initialize thread support\n");
114
        return 1;
115
    }
116

117
    // 创建主线程的event_base
118
    struct event_base *base = event_base_new();
119
    if (!base) {
120
        fprintf(stderr, "Failed to create event base\n");
121
        return 1;
122
    }
123

124
    // 创建工作线程
125
    threads = calloc(THREAD_COUNT, sizeof(struct thread_info));
126
    for (int i = 0; i < THREAD_COUNT; i++) {
127
        // 创建管道用于传递fd
128
        if (pipe(threads[i].pipefd) == -1) {
129
            perror("pipe");
130
            return 1;
131
        }
132

133
        // 设置管道非阻塞
134
        evutil_make_socket_nonblocking(threads[i].pipefd[0]);
135
        evutil_make_socket_nonblocking(threads[i].pipefd[1]);
136

137
        // 创建线程的event_base
138
        threads[i].base = event_base_new();
139
        if (!threads[i].base) {
140
            fprintf(stderr, "Failed to create thread event base\n");
141
            return 1;
142
        }
143

144
        // 创建管道事件
145
        threads[i].pipe_event = event_new(threads[i].base, threads[i].pipefd[0],
146
            EV_READ | EV_PERSIST, pipe_cb, &threads[i]);
147
        event_add(threads[i].pipe_event, NULL);
148

149
        // 创建线程
150
        pthread_create(&threads[i].thread_id, NULL, thread_main, &threads[i]);
151
    }
152

153
    // 创建监听器
154
    struct sockaddr_in sin;
155
    memset(&sin, 0, sizeof(sin));
156
    sin.sin_family = AF_INET;
157
    sin.sin_port = htons(PORT);
158
    sin.sin_addr.s_addr = htonl(INADDR_ANY);
159

160
    struct evconnlistener *listener = evconnlistener_new_bind(base,
161
        accept_conn_cb, NULL,
162
        LEV_OPT_REUSEABLE | LEV_OPT_CLOSE_ON_FREE,
163
        -1,
164
        (struct sockaddr *)&sin, sizeof(sin));
165

166
    if (!listener) {
167
        perror("Couldn't create listener");
168
        return 1;
169
    }
170

171
    // 信号处理
172
    struct event *signal_event = evsignal_new(base, SIGINT, signal_cb, base);
173
    event_add(signal_event, NULL);
174

175
    printf("Multi-threaded TCP server started on port %d\n", PORT);
176
    printf("Thread count: %d\n", THREAD_COUNT);
177
    printf("Press Ctrl+C to exit\n");
178

179
    event_base_dispatch(base);
180

181
    // 等待所有线程退出
182
    for (int i = 0; i < THREAD_COUNT; i++) {
183
        pthread_join(threads[i].thread_id, NULL);
184
        event_free(threads[i].pipe_event);
185
        event_base_free(threads[i].base);
186
        close(threads[i].pipefd[0]);
187
        close(threads[i].pipefd[1]);
188
    }
189

190
    free(threads);
191
    evconnlistener_free(listener);
192
    event_free(signal_event);
193
    event_base_free(base);
194

195
    printf("Server shutdown complete\n");
196
    return 0;
197
}

展开收起

5.3 带超时处理的TCP客户端#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <unistd.h>
5
#include <arpa/inet.h>
6
#include <event2/buffer.h>
7
#include <event2/bufferevent.h>
8
#include <event2/event.h>
9

10
#define SERVER_IP "127.0.0.1"
11
#define SERVER_PORT 8080
12
#define CONNECT_TIMEOUT 5
13
#define READ_TIMEOUT 30
14

15
static int g_connected = 0;
16

17
static void read_cb(struct bufferevent *bev, void *ctx) {
18
    struct evbuffer *input = bufferevent_get_input(bev);
19

20
    char buffer[1024];
21
    size_t n;
22
    while ((n = evbuffer_remove(input, buffer, sizeof(buffer) - 1)) > 0) {
23
        buffer[n] = '\0';
24
        printf("Server: %s", buffer);
25
    }
26
}
27

28
static void event_cb(struct bufferevent *bev, short events, void *ctx) {
29
    struct event_base *base = ctx;
30

31
    if (events & BEV_EVENT_CONNECTED) {
32
        printf("Connected to server!\n");
33
        g_connected = 1;
34

35
        // 发送测试命令
36
        bufferevent_write(bev, "ping\n", 5);
37
        bufferevent_write(bev, "info\n", 5);
38
    } else if (events & BEV_EVENT_EOF) {
39
        printf("Connection closed by server\n");
40
        event_base_loopexit(base, NULL);
41
    } else if (events & BEV_EVENT_ERROR) {
42
        int err = EVUTIL_SOCKET_ERROR();
43
        printf("Connection error: %s\n", evutil_socket_error_to_string(err));
44
        event_base_loopexit(base, NULL);
45
    } else if (events & BEV_EVENT_TIMEOUT) {
46
        if (events & BEV_EVENT_READING) {
47
            printf("Read timeout\n");
48
        } else if (events & BEV_EVENT_WRITING) {
49
            printf("Write timeout\n");
50
        }
51
        event_base_loopexit(base, NULL);
52
    }
53
}
54

55
static void stdin_cb(evutil_socket_t fd, short events, void *arg) {
56
    struct bufferevent *bev = (struct bufferevent *)arg;
57
    char buffer[1024];
58
    ssize_t n = read(fd, buffer, sizeof(buffer) - 1);
59

60
    if (n > 0) {
61
        buffer[n] = '\0';
62
        if (g_connected) {
63
            bufferevent_write(bev, buffer, n);
64
        } else {
65
            printf("Not connected yet\n");
66
        }
67
    }
68
}
69

70
int main() {
71
    struct event_base *base = event_base_new();
72
    struct bufferevent *bev = bufferevent_socket_new(base, -1, BEV_OPT_CLOSE_ON_FREE);
73

74
    // 设置超时
75
    struct timeval connect_tv = {CONNECT_TIMEOUT, 0};
76
    struct timeval read_tv = {READ_TIMEOUT, 0};
77
    bufferevent_set_timeouts(bev, &read_tv, NULL);
78

79
    // 设置回调
80
    bufferevent_setcb(bev, read_cb, NULL, event_cb, base);
81
    bufferevent_enable(bev, EV_READ | EV_WRITE);
82

83
    // 连接服务器
84
    struct sockaddr_in sin;
85
    memset(&sin, 0, sizeof(sin));
86
    sin.sin_family = AF_INET;
87
    sin.sin_port = htons(SERVER_PORT);
88
    inet_pton(AF_INET, SERVER_IP, &sin.sin_addr);
89

90
    printf("Connecting to %s:%d...\n", SERVER_IP, SERVER_PORT);
91
    printf("Connect timeout: %d seconds\n", CONNECT_TIMEOUT);
92
    printf("Read timeout: %d seconds\n", READ_TIMEOUT);
93

94
    if (bufferevent_socket_connect(bev, (struct sockaddr *)&sin, sizeof(sin)) < 0) {
95
        fprintf(stderr, "Connection failed\n");
96
        bufferevent_free(bev);
97
        event_base_free(base);
98
        return 1;
99
    }
100

101
    // 监听标准输入
102
    struct event *stdin_event = event_new(base, STDIN_FILENO, EV_READ | EV_PERSIST, stdin_cb, bev);
103
    event_add(stdin_event, NULL);
104

105
    // 设置连接超时
106
    struct timeval tv = {CONNECT_TIMEOUT, 0};
107
    struct event *timeout_event = evtimer_new(base,
108
        [](evutil_socket_t fd, short events, void *arg) {
109
            struct event_base *base = arg;
110
            if (!g_connected) {
111
                printf("Connection timeout\n");
112
                event_base_loopexit(base, NULL);
113
            }
114
        }, base);
115
    event_add(timeout_event, &tv);
116

117
    event_base_dispatch(base);
118

119
    event_free(stdin_event);
120
    event_free(timeout_event);
121
    bufferevent_free(bev);
122
    event_base_free(base);
123

124
    return 0;
125
}

展开收起

六、编译与运行#

6.1 编译高级示例#

Terminal window

1
# 编译带配置管理的TCP服务器
2
gcc -o tcp_server_config tcp_server_config.c -levent
3

4
# 编译多线程TCP服务器
5
gcc -o tcp_server_threaded tcp_server_threaded.c -levent -lpthread
6

7
# 编译带超时处理的TCP客户端
8
gcc -o tcp_client_timeout tcp_client_timeout.c -levent

6.2 运行示例#

Terminal window

1
# 运行带配置管理的服务器
2
./tcp_server_config
3

4
# 运行多线程服务器
5
./tcp_server_threaded
6

7
# 运行带超时处理的客户端
8
./tcp_client_timeout

其他相关资料请移步到个人主页

⏰ 定时器使用 - libevent源码深度解析系列（十二）

Sat, 11 Apr 2026 00:00:00 GMT

⏰ 定时器使用#

一、概述#

libevent提供了定时器功能，允许在指定的时间后执行回调函数。定时器可以是一次性的，也可以是周期性的。

二、定时器API#

2.1 创建定时器#

1
/* 创建定时器事件（宏定义）
2
 * @param base  event_base
3
 * @param cb    回调函数
4
 * @param arg   回调参数
5
 */
6
#define evtimer_new(base, cb, arg) event_new((base), -1, 0, (cb), (arg))
7

8
/* 分配定时器到现有结构体 */
9
#define evtimer_assign(ev, base, cb, arg) \
10
    event_assign((ev), (base), -1, 0, (cb), (arg))

2.2 添加和删除#

1
/* 添加定时器
2
 * @param tv 超时时间，NULL表示永不超时
3
 */
4
#define evtimer_add(ev, tv) event_add((ev), (tv))
5

6
/* 删除定时器 */
7
#define evtimer_del(ev) event_del(ev)

2.3 检查状态#

1
/* 检查定时器是否pending */
2
#define evtimer_pending(ev, tv) event_pending((ev), EV_TIMEOUT, (tv))
3

4
/* 检查定时器是否已初始化 */
5
#define evtimer_initialized(ev) event_initialized(ev)

三、时间结构体#

1
struct timeval {
2
    time_t      tv_sec;   // 秒
3
    suseconds_t tv_usec;  // 微秒
4
};
5

6
/* 辅助宏 */
7
#define EVUTIL_SEC_TO_USEC(sec) ((sec) * 1000000)

四、基本示例#

4.1 一次性定时器#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <event2/event.h>
4

5
static void timer_cb(evutil_socket_t fd, short events, void *arg) {
6
    printf("Timer fired!\n");
7

8
    // 事件循环会自动退出，因为没有其他事件
9
}
10

11
int main() {
12
    struct event_base *base = event_base_new();
13

14
    // 创建一次性定时器（不带EV_PERSIST）
15
    struct event *timer = evtimer_new(base, timer_cb, NULL);
16

17
    // 设置3秒后触发
18
    struct timeval tv = {3, 0};
19
    evtimer_add(timer, &tv);
20

21
    printf("Timer set for 3 seconds...\n");
22

23
    event_base_dispatch(base);
24

25
    event_free(timer);
26
    event_base_free(base);
27

28
    return 0;
29
}

展开收起

4.2 周期性定时器#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <signal.h>
4
#include <event2/event.h>
5

6
static int counter = 0;
7

8
static void timer_cb(evutil_socket_t fd, short events, void *arg) {
9
    counter++;
10
    printf("Timer fired! Count: %d\n", counter);
11

12
    if (counter >= 5) {
13
        printf("Reached 5 ticks, exiting...\n");
14
        struct event_base *base = arg;
15
        event_base_loopexit(base, NULL);
16
    }
17
}
18

19
static void signal_cb(evutil_socket_t fd, short events, void *arg) {
20
    struct event_base *base = arg;
21
    printf("Caught signal, exiting...\n");
22
    event_base_loopexit(base, NULL);
23
}
24

25
int main() {
26
    struct event_base *base = event_base_new();
27

28
    // 创建周期性定时器（带EV_PERSIST）
29
    struct event *timer = event_new(base, -1, EV_PERSIST, timer_cb, base);
30

31
    // 设置每1秒触发一次
32
    struct timeval tv = {1, 0};
33
    event_add(timer, &tv);
34

35
    // 信号处理
36
    struct event *sig = evsignal_new(base, SIGINT, signal_cb, base);
37
    event_add(sig, NULL);
38

39
    printf("Periodic timer started (1 second interval)\n");
40
    printf("Press Ctrl+C to exit\n");
41

42
    event_base_dispatch(base);
43

44
    event_free(sig);
45
    event_free(timer);
46
    event_base_free(base);
47

48
    return 0;
49
}

展开收起

五、高级用法#

5.1 精确定时器#

1
#include <stdio.h>
2
#include <event2/event.h>
3

4
static void precise_timer_cb(evutil_socket_t fd, short events, void *arg) {
5
    struct timeval now;
6
    evutil_gettimeofday(&now, NULL);
7

8
    printf("Timer at %ld.%06ld\n", now.tv_sec, now.tv_usec);
9
}
10

11
int main() {
12
    struct event_config *cfg = event_config_new();
13
    event_config_set_flag(cfg, EVENT_BASE_FLAG_PRECISE_TIMER);
14

15
    struct event_base *base = event_base_new_with_config(cfg);
16
    event_config_free(cfg);
17

18
    struct event *timer = event_new(base, -1, EV_PERSIST, precise_timer_cb, NULL);
19

20
    // 每100毫秒触发
21
    struct timeval tv = {0, 100000};
22
    event_add(timer, &tv);
23

24
    // 5秒后退出
25
    struct timeval exit_tv = {5, 0};
26
    event_base_loopexit(base, &exit_tv);
27

28
    event_base_dispatch(base);
29

30
    event_free(timer);
31
    event_base_free(base);
32

33
    return 0;
34
}

展开收起

5.2 多个定时器#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <event2/event.h>
4

5
static void timer1_cb(evutil_socket_t fd, short events, void *arg) {
6
    printf("Timer 1: 1 second\n");
7
}
8

9
static void timer2_cb(evutil_socket_t fd, short events, void *arg) {
10
    printf("Timer 2: 2 seconds\n");
11
}
12

13
static void timer3_cb(evutil_socket_t fd, short events, void *arg) {
14
    printf("Timer 3: 3 seconds\n");
15
}
16

17
static void exit_cb(evutil_socket_t fd, short events, void *arg) {
18
    printf("Exit timer: exiting...\n");
19
    struct event_base *base = arg;
20
    event_base_loopexit(base, NULL);
21
}
22

23
int main() {
24
    struct event_base *base = event_base_new();
25

26
    struct event *t1 = event_new(base, -1, EV_PERSIST, timer1_cb, NULL);
27
    struct event *t2 = event_new(base, -1, EV_PERSIST, timer2_cb, NULL);
28
    struct event *t3 = event_new(base, -1, EV_PERSIST, timer3_cb, NULL);
29
    struct event *exit_timer = evtimer_new(base, exit_cb, base);
30

31
    struct timeval tv1 = {1, 0};
32
    struct timeval tv2 = {2, 0};
33
    struct timeval tv3 = {3, 0};
34
    struct timeval tv_exit = {10, 0};
35

36
    event_add(t1, &tv1);
37
    event_add(t2, &tv2);
38
    event_add(t3, &tv3);
39
    event_add(exit_timer, &tv_exit);
40

41
    printf("Multiple timers started, will run for 10 seconds...\n");
42

43
    event_base_dispatch(base);
44

45
    event_free(t1);
46
    event_free(t2);
47
    event_free(t3);
48
    event_free(exit_timer);
49
    event_base_free(base);
50

51
    return 0;
52
}

展开收起

5.3 动态调整定时器#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <event2/event.h>
4

5
static int interval = 1;
6

7
static void dynamic_timer_cb(evutil_socket_t fd, short events, void *arg) {
8
    struct event *timer = arg;
9

10
    printf("Timer fired with interval %d second(s)\n", interval);
11

12
    // 动态调整间隔
13
    interval++;
14
    if (interval > 5) {
15
        interval = 1;
16
    }
17

18
    // 重新设置定时器
19
    struct timeval tv = {interval, 0};
20
    event_add(timer, &tv);
21
}
22

23
int main() {
24
    struct event_base *base = event_base_new();
25

26
    // 注意：不带EV_PERSIST，手动重新添加
27
    struct event *timer = event_new(base, -1, 0, dynamic_timer_cb, NULL);
28

29
    // 设置回调参数为timer本身
30
    event_assign(event_get_assignment(timer, &base, NULL, NULL, NULL, NULL),
31
                 base, -1, 0, dynamic_timer_cb, timer);
32

33
    struct timeval tv = {interval, 0};
34
    event_add(timer, &tv);
35

36
    // 20秒后退出
37
    struct timeval exit_tv = {20, 0};
38
    event_base_loopexit(base, &exit_tv);
39

40
    event_base_dispatch(base);
41

42
    event_free(timer);
43
    event_base_free(base);
44

45
    return 0;
46
}

展开收起

六、定时器精度#

因素	影响
系统时钟精度	通常为毫秒级
事件循环负载	高负载可能导致延迟
回调执行时间	长时间回调影响后续定时器
EVENT_BASE_FLAG_PRECISE_TIMER	启用高精度定时器

七、最佳实践#

建议	说明
避免阻塞回调	回调函数应尽快返回
合理设置间隔	避免过于频繁的定时器
使用EV_PERSIST	周期性定时器使用EV_PERSIST更高效
及时清理	不再使用的定时器应及时删除

其他相关资料请移步到个人主页

👁️ watch模块 - libevent源码深度解析系列（十六）

Sat, 11 Apr 2026 00:00:00 GMT

👁️ watch模块#

一、概述#

libevent的watch模块提供了在事件循环的不同阶段执行回调的能力。这对于监控、调试或在特定时机执行操作非常有用。

二、watch回调类型#

回调类型	触发时机
prepare	在调用I/O复用机制（如epoll_wait）之前
check	在I/O复用机制返回之后，处理活跃事件之前
fork	在fork子进程之后

三、API#

3.1 添加watch回调#

1
/* 添加prepare回调
2
 * 在每次调用I/O复用机制之前执行
3
 */
4
int event_base_add_virtual_event_(struct event_base *base, struct event *ev);
5

6
/* 添加check回调
7
 * 在I/O复用机制返回之后执行
8
 */
9
int event_base_add_virtual_event_(struct event_base *base, struct event *ev);

3.2 结构体#

1
struct evwatch {
2
    struct event_base *base;
3
    struct evwatch_callback callback;
4
    void *arg;
5
    TAILQ_ENTRY(evwatch) next;
6
};
7

8
typedef void (*evwatch_callback)(struct evwatch *, const struct evwatch_callbacks *, void *);

四、使用示例#

4.1 监控事件循环#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <unistd.h>
4
#include <event2/event.h>
5

6
static int loop_count = 0;
7
static struct timeval last_time;
8

9
static void prepare_cb(struct evwatch *watcher, const struct evwatch_callbacks *cbs, void *arg) {
10
    struct timeval now;
11
    evutil_gettimeofday(&now, NULL);
12

13
    printf("[PREPARE] Loop iteration %d\n", loop_count);
14

15
    // 计算距离上次循环的时间
16
    if (last_time.tv_sec != 0) {
17
        long diff = (now.tv_sec - last_time.tv_sec) * 1000000 +
18
                    (now.tv_usec - last_time.tv_usec);
19
        printf("[PREPARE] Time since last loop: %ld us\n", diff);
20
    }
21

22
    last_time = now;
23
}
24

25
static void check_cb(struct evwatch *watcher, const struct evwatch_callbacks *cbs, void *arg) {
26
    struct event_base *base = arg;
27

28
    int active_count = event_base_get_num_events(base, EVENT_BASE_COUNT_ACTIVE);
29
    int total_count = event_base_get_num_events(base, EVENT_BASE_COUNT_ADDED);
30

31
    printf("[CHECK] Active events: %d, Total events: %d\n", active_count, total_count);
32

33
    loop_count++;
34
}
35

36
static void timer_cb(evutil_socket_t fd, short events, void *arg) {
37
    printf("Timer fired!\n");
38
}
39

40
int main() {
41
    struct event_base *base = event_base_new();
42

43
    // 添加watch回调
44
    struct evwatch *prepare_watcher = evwatch_prepare_new(base, prepare_cb, NULL);
45
    struct evwatch *check_watcher = evwatch_check_new(base, check_cb, base);
46

47
    // 创建定时器
48
    struct event *timer = event_new(base, -1, EV_PERSIST, timer_cb, NULL);
49
    struct timeval tv = {1, 0};
50
    event_add(timer, &tv);
51

52
    // 5秒后退出
53
    struct timeval exit_tv = {5, 0};
54
    event_base_loopexit(base, &exit_tv);
55

56
    event_base_dispatch(base);
57

58
    evwatch_free(prepare_watcher);
59
    evwatch_free(check_watcher);
60
    event_free(timer);
61
    event_base_free(base);
62

63
    printf("Total loop iterations: %d\n", loop_count);
64
    return 0;
65
}

展开收起

4.2 性能监控#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <unistd.h>
4
#include <event2/event.h>
5

6
struct perf_stats {
7
    long total_loops;
8
    long total_events;
9
    long max_latency;
10
    struct timeval last_prepare;
11
};
12

13
static void prepare_cb(struct evwatch *watcher, const struct evwatch_callbacks *cbs, void *arg) {
14
    struct perf_stats *stats = arg;
15
    evutil_gettimeofday(&stats->last_prepare, NULL);
16
}
17

18
static void check_cb(struct evwatch *watcher, const struct evwatch_callbacks *cbs, void *arg) {
19
    struct perf_stats *stats = arg;
20
    struct event_base *base = evwatch_get_base(watcher);
21

22
    struct timeval now;
23
    evutil_gettimeofday(&now, NULL);
24

25
    // 计算I/O复用耗时
26
    long latency = (now.tv_sec - stats->last_prepare.tv_sec) * 1000000 +
27
                   (now.tv_usec - stats->last_prepare.tv_usec);
28

29
    if (latency > stats->max_latency) {
30
        stats->max_latency = latency;
31
    }
32

33
    stats->total_loops++;
34
    stats->total_events += event_base_get_num_events(base, EVENT_BASE_COUNT_ACTIVE);
35
}
36

37
int main() {
38
    struct event_base *base = event_base_new();
39

40
    struct perf_stats stats = {0};
41

42
    struct evwatch *prepare = evwatch_prepare_new(base, prepare_cb, &stats);
43
    struct evwatch *check = evwatch_check_new(base, check_cb, &stats);
44

45
    // 创建一些事件
46
    struct event *timer = event_new(base, -1, EV_PERSIST,
47
        [](evutil_socket_t fd, short events, void *arg) {}, NULL);
48
    struct timeval tv = {0, 100000};  // 100ms
49
    event_add(timer, &tv);
50

51
    // 运行10秒
52
    struct timeval exit_tv = {10, 0};
53
    event_base_loopexit(base, &exit_tv);
54

55
    event_base_dispatch(base);
56

57
    printf("Performance Statistics:\n");
58
    printf("  Total loops: %ld\n", stats.total_loops);
59
    printf("  Total events processed: %ld\n", stats.total_events);
60
    printf("  Max I/O latency: %ld us\n", stats.max_latency);
61
    printf("  Avg events per loop: %.2f\n",
62
           (double)stats.total_events / stats.total_loops);
63

64
    evwatch_free(prepare);
65
    evwatch_free(check);
66
    event_free(timer);
67
    event_base_free(base);
68

69
    return 0;
70
}

展开收起

五、实际应用场景#

场景	说明
性能监控	统计事件循环次数、延迟等指标
调试	在关键点打印调试信息
资源管理	在循环前后检查资源状态
心跳检测	检测事件循环是否正常运行
动态调整	根据负载动态调整参数

六、注意事项#

注意事项	说明
回调效率	watch回调在每次循环都会执行，应尽量高效
避免阻塞	回调中不应执行阻塞操作
资源释放	使用evwatch_free释放watcher
线程安全	多线程环境下需要加锁保护

其他相关资料请移步到个人主页

把人生活成一家盈利的"一人公司"：从内耗迷茫到清醒自洽的经营哲学

Fri, 10 Apr 2026 00:00:00 GMT

把人生活成一家盈利的“一人公司”：从内耗迷茫到清醒自洽的经营哲学

凌晨1点，刷完最后一条短视频，放下手机的瞬间，一阵空虚席卷而来——今天又在无效忙碌中度过：工作没做完，计划没执行，说好的健身、读书全被拖延取代；月底对账，工资刚到账就被房租、花呗、人情往来消耗一空，存款余额始终停留在三位数；和家人拌了嘴，明明是小事，却因为情绪失控吵得不可开交，冷战了一整天；看着身边的人要么升职加薪，要么经营起自己的小事业，而自己却在迷茫中反复内耗，不知道未来的方向在哪里。

这样的场景，是不是戳中了很多人的日常？我们总在抱怨生活混乱、命运不公，却从未意识到：人生本就是一场长期经营，而我们自己，就是这家“一人公司”的唯一创始人、CEO与终极责任人。就像彼得·德鲁克在90岁高龄时写下的《管理自己》中所言：“在这个时代，你不需要成为管理别人的CEO，但你必须成为自己的CEO。” 所谓“个人公司化”，从来不是让我们变得功利、冷漠、精于算计，而是用企业经营的理性思维，梳理人生的混乱，明确目标的方向，守住生活的底线，最终实现“人生盈利”——这里的盈利，无关金钱的多少，而是健康、快乐、成长、财富与家庭幸福的综合平衡。

在这个不确定性加剧的时代，“铁饭碗”早已不复存在，远程办公成为常态，个体崛起成为趋势，越来越多的人开始意识到：把自己当成一家公司来经营，才是对抗迷茫、抵御风险的最佳方式。它不是一句空洞的口号，而是一套可落地、可复盘、可优化的人生管理体系，早在百年前，就被无数先贤与商业大佬践行，如今更是成为普通人破局内耗的核心逻辑。

一、先搞懂：什么是“个人公司化”？（不是功利，是清醒）

很多人一听到“公司化”，就会联想到“算计”“利益至上”，甚至觉得“把人生当公司，会失去生活的温度”。但事实上，个人公司化的核心，是“用理性框架托住感性生活”，本质是将企业管理中的“目标管理、资源配置、风险控制、复盘优化”等逻辑，迁移到个人生活、家庭经营中，让我们从“被动应付”走向“主动掌控”。

企业经营的核心逻辑是“活下去、谋发展、创价值”，而人生经营的核心逻辑，是“活得健康、活得清醒、活得有价值、活得不后悔”——两者看似无关，底层逻辑却高度一致：都是“明确目标→整合资源→执行落地→风控止损→复盘优化”的闭环。

稻盛和夫在《心法》中提到：“经营企业，其实就是在经营‘做人的准则’。” 这句话同样适用于个人公司化：经营自己这家“公司”，本质上就是经营自己的人生准则——守住底线，明确方向，持续成长，懂得取舍。我们的“公司”，没有董事会，没有股东，所有的决策都由自己做出，所有的结果都由自己承担：你敷衍经营，人生就会给你“亏损”的反馈；你用心打磨，人生就会给你“盈利”的回报。

举个最现实的例子：同样是月薪8000，有的人把工资当成“全部收入”，月光消费、毫无规划，几年后依旧原地踏步，甚至负债累累——这就是“经营不善”的表现；而有的人，把工资当成“初始资金”，一部分用于日常开销，一部分用于“投资自己”（学习技能、提升认知），一部分用于“资产积累”（储蓄、理财），同时合理分配时间，兼顾健康与社交，几年后要么升职加薪，要么拥有了副业收入，生活越来越从容——这就是“科学经营”的成果。

央行的调研数据显示，56.6%的受访者近两年没有储蓄行为，超四成家庭面临较重债务负担，每四个家庭中就有一个无法应对三倍月收入的意外支出。这些数据背后，藏着的正是“人生经营能力的缺失”：不懂资源配置，不懂风险控制，不懂长期规划，最终在生活的洪流中随波逐流，陷入被动。

二、个人公司化的核心框架：你的“人生公司”，该如何搭建？

一家正规公司，有明确的组织架构、资产负债、经营目标与风控体系；同样，你的“人生公司”，也需要搭建清晰的框架，才能有序经营、持续盈利。结合德鲁克的自我管理理论与稻盛和夫的阿米巴经营思维，我们可以从“个人”与“家庭”两个维度，搭建属于自己的“人生公司”体系。

（一）个人层面：打造“一人有限公司”，做自己的CEO

你是这家“一人有限公司”的唯一股东、CEO与执行者，公司的“注册资本”，是你与生俱来的时间、健康、原生家庭资源与初始认知；公司的“主营业务”，是你的工作、事业、学习与创造价值的过程；公司的“经营期限”，是你的一生；公司的“核心使命”，是实现自我价值，收获幸福与自由。

组织架构：给人生“分部门”，告别混乱内耗

很多人之所以内耗，核心是“眉毛胡子一把抓”，分不清优先级，把时间和精力浪费在无效的事情上。就像一家没有部门分工的公司，所有人都在打杂，效率低下、漏洞百出。你的“人生公司”，需要搭建以下9个核心“部门”，各司其职、协同运转：

战略部：核心职责是“定方向、立目标”，对应人生的规划与定位。就像德鲁克强调的，真正厉害的人，都懂得找到自己的优势与方向，而不是盲目努力。这个部门的核心工作，是制定3年长期目标、1年中期目标、季度短期目标，明确“什么该做，什么不该做”，避免瞎忙。比如：3年后成为行业内的资深人士，1年内掌握一项新技能，这个季度完成2次深度阅读。考核KPI：目标完成率、方向不跑偏，避免“努力错了方向”。
研发部：核心职责是“提能力、涨认知”，对应人生的学习与成长。稻盛和夫说：“付出不亚于任何人的努力，不是蛮干，是愿力先行”，而学习与成长，就是这份“愿力”的落地。这个部门的核心工作，是持续学习新技能、提升认知水平、沉淀经验，让自己的“核心竞争力”不断升级。比如：每天阅读1小时，每月学习1门课程，每季度总结1次经验。考核KPI：阅读量、技能熟练度、认知提升幅度。
生产部：核心职责是“创价值、赚收入”，对应人生的工作与变现。德鲁克说：“不要问‘我想要什么’，要问‘我能贡献什么’”，这个部门的核心工作，就是通过自己的能力，为社会、为企业创造价值，从而换取收入（工资、副业收入等）。比如：认真完成本职工作，提升工作效率，开发副业，实现多渠道收入。考核KPI：收入水平、工作效率、成果交付质量。
财务部：核心职责是“管 money、控成本”，对应人生的财富管理。央行数据显示，40%的30岁以下群体成为月光核心，三四五线城市单身青年月光率超70%，本质是财务部门“失职”。这个部门的核心工作，是制定预算、控制消费、储蓄理财、抵御财务风险，避免“月光”“负债”。比如：每月收入的30%用于储蓄，20%用于投资自己，50%用于日常开销；拒绝超前消费，远离网贷。考核KPI：储蓄率、资产增值幅度、无负债。
行政部：核心职责是“保秩序、提效率”，对应人生的日常琐事与生活管理。这个部门的核心工作，是安排日常作息、处理家务琐事、优化生活流程，让生活变得有序高效。比如：规律作息（早睡早起），整理房间，合理安排饮食，避免被琐事消耗精力。考核KPI：作息规律度、环境整洁度、琐事处理效率。
风控部：核心职责是“防风险、护根基”，对应人生的健康、情绪与安全。健康是“人生公司”的“本金”，情绪是“人生公司”的“软实力”，安全是“人生公司”的“底线”。这个部门的核心工作，是守护健康（体检、运动、睡眠）、管控情绪（避免内耗、焦虑、抱怨）、防范意外（安全出行、购买保险）。比如：每周运动3次，定期体检，学会情绪调节，避免冲动决策。考核KPI：体检指标、情绪稳定度、无意外发生。
市场部：核心职责是“拓人脉、树口碑”，对应人生的社交与人际关系。稻盛和夫说：“活着就要感谢，这份感恩能唤醒人内心的善意，也能收获他人的认可”。这个部门的核心工作，是维护优质人脉、拓展社交圈子、传递自己的价值，打造良好的个人口碑。比如：定期和朋友联系，参与有意义的社交活动，真诚待人，乐于助人。考核KPI：有效社交数量、人脉质量、个人口碑。
品牌部：核心职责是“塑形象、立标签”，对应人生的个人形象与自我认同。你的“个人品牌”，就是别人提到你时的第一印象，也是你“人生公司”的核心竞争力之一。这个部门的核心工作，是打造个人形象（外在穿搭、内在气质）、明确个人标签（比如“靠谱”“专业”“乐观”），提升自我认可度。考核KPI：他人评价、自我认同度、个人标签清晰度。
监事会：核心职责是“守底线、明是非”，对应人生的良知、原则与底线。稻盛和夫在拯救日航时，反复强调“作为人何为正确”，这正是监事会的核心作用。这个部门的核心工作，是监督自己的行为，坚守道德底线，避免做后悔的事，保持内心的自洽。比如：不欺骗他人、不敷衍工作、不伤害身边的人，坚守自己的原则。考核KPI：不做违背良知的事、内心自洽度、无后悔决策。

资产与负债：分清“增值项”与“消耗项”，避免人生“破产”

一家公司的兴衰，取决于资产与负债的平衡；一个人的人生质量，同样取决于“人生资产”与“人生负债”的博弈。很多人之所以活得疲惫、迷茫，就是因为不断积累“人生负债”，却忽视了“人生资产”的培育。

核心人生资产（越用越值钱，是人生盈利的基础）：

时间资产：最稀缺、最不可再生的资产，也是所有资产的基础。德鲁克说，管理自己，本质是管理自己的时间，懂得分配时间，就是懂得经营人生。
健康资产：人生的“本金”，没有健康，再多的财富、再高的地位，都是空谈。就像稻盛和夫所说，努力的前提，是拥有健康的身体，才能支撑长期的奋斗。
认知资产：决定你决策的质量，认知越高，越能看清事物的本质，避免走弯路。德鲁克的反馈分析法，就是提升认知的有效方法——通过记录预期与结果的差距，看清自己的优势与不足。
技能资产：变现的核心工具，也是你“生产部”创造价值的基础，技能越熟练，收入上限越高。比如：文案写作、编程、设计、沟通能力等，都是可不断升级的技能资产。
信用资产：人脉与口碑的核心，一个人有信用，才能获得他人的信任，才能拥有更多的机会。就像装修行业的书友，坚守“用最好的材料，收合理的价”，反而赢得了更多回头客。
情绪资产：稳定的心态，是高效执行、良好社交的基础，情绪稳定的人，才能在困境中保持清醒，做出正确的决策。

致命人生负债（越积累越拖累，是人生亏损的根源）：

时间负债：刷短视频、无效社交、拖延、浪费时间，这些行为都会消耗你的时间资产，让你陷入“越忙越乱”的循环。
健康负债：熬夜、暴饮暴食、不运动、过度消耗身体，这些行为会透支你的健康资产，最终让你付出沉重的代价。
情绪负债：内耗、焦虑、抱怨、敏感、易怒，这些负面情绪会消耗你的精力，影响你的决策与社交，甚至拖垮你的家庭关系。
金钱负债：超前消费、网贷、乱投资、盲目攀比，这些行为会让你陷入财务危机，失去生活的主动权。就像超半数月光族，看似享受了当下，实则积累了沉重的金钱负债。
关系负债：垃圾人、消耗型关系、虚伪的社交，这些关系会消耗你的精力与情绪，让你变得消极、内耗。

人生“破产”的标志，从来不是没钱，而是健康没了、情绪崩了、关系碎了、内心空了。经营自己的“人生公司”，就是要不断增加“人生资产”，剥离“人生负债”，实现资产增值、负债清零。

营收与利润：人生的“盈利”，从来不是只看金钱

企业的营收是销售额，利润是营收减去成本；而你“人生公司”的营收，是你在生活中获得的一切美好——工资、副业收入、成长、快乐、成就感、亲情、友情；成本，是你付出的时间、精力、健康、情绪；净利润，就是你真正的幸福、自由与安全感。

很多人陷入了一个误区：把金钱当成人生唯一的“营收”，为了赚钱，牺牲健康、消耗情绪、忽略家庭，最终赚了钱，却失去了更珍贵的东西——这就是“盈利失衡”。就像有些创业者，为了公司盈利，熬夜加班、透支身体，最终公司做大了，自己却患上了重病，得不偿失。

真正健康的“人生盈利”，是“多元营收、平衡成本”：既有金钱收入，也有成长与快乐；既付出努力，也懂得善待自己；既追求事业，也兼顾家庭。就像长江读书会的书友，每天早起半小时共读，既提升了认知（成长营收），也收获了同频的友谊（关系营收），还保持了规律的作息（健康资产），这就是“人生盈利”的最佳状态。

（二）家庭层面：打造“家族集团公司”，协同经营幸福

如果说个人是“一人有限公司”，那么家庭，就是“家族集团公司”——夫妻是联合创始人、双CEO，股权各50%，平等共治；孩子是“子公司”“储备人才”，需要精心培育、助力成长；父母是“独立董事”“顾问团”，只提供建议，不干预决策；家庭整体，就是“集团总部”，核心目标是实现“长期存续、共同盈利”。

很多家庭之所以矛盾不断、鸡飞狗跳，核心是“没有经营思维”——把家庭当成“凑活过”的地方，没有明确的目标、合理的分工、清晰的规则，最终陷入“内耗不断、互相消耗”的困境。而把家庭当成“集团公司”来经营，就是要明确家庭目标、合理分工、坚守规则、协同成长，让家庭成为“人生公司”的坚强后盾。

股权结构与核心目标：平等共治，共赢共生

家庭“集团公司”的核心目标，不是“赚多少钱”，而是：财务安全（不缺钱、抗风险）、情绪稳定（不内耗、不吵架）、成员成长（夫妻进步、孩子成才）、长期存续（白头偕老、家风传承）——这就像企业的“百年老店”目标，需要夫妻双方共同努力、长期经营。

夫妻作为“联合创始人”，股权平等、地位平等，没有“谁主导、谁服从”，只有“协同合作、互相包容”。就像济南装修公司的刘总，借鉴阿米巴经营思维，将团队拆分成独立小组，让每个小组自主经营，最终激发了员工的积极性；夫妻之间，也需要“分工协作、各展所长”，而不是互相指责、互相推诿。

家庭部门分工：各司其职，避免内耗

就像企业需要部门分工，家庭也需要明确的“部门”与职责，避免“谁多做、谁少做”的争论。结合家庭实际，可搭建以下5个核心“部门”：

战略委员会：由夫妻共同组成，核心职责是制定家庭的长期规划与短期目标，比如：3年后买房、孩子的教育规划、父母的养老规划、家庭的财务目标等，共同决策、共同执行。
财务中心：由夫妻一方主导、双方监督，核心职责是统一家庭收支、制定家庭预算、储蓄理财、配置保险，实现财务透明、风险可控。比如：每月统一记账，明确收支明细，共同制定储蓄目标，避免大额消费不沟通的问题。
运营中心：由夫妻双方分工负责，核心职责是处理家务、照顾孩子、赡养老人，安排家庭日常事务。比如：一方负责做饭、打扫卫生，一方负责接送孩子、辅导作业，合理分工、互相配合，避免“一个人包揽所有”的疲惫。
风控中心：由夫妻共同负责，核心职责是守护家庭成员的健康、防范家庭风险（比如意外、疾病、财务危机），配置家庭保险，建立应急金（6-12个月的生活费），应对突发情况。
文化中心：由夫妻共同主导，核心职责是营造良好的家庭氛围、培养家庭仪式感、传递正确的价值观，比如：每周家庭聚餐、每月家庭出游、节日互相祝福，让家庭充满温暖与爱。

家庭红线制度：守住底线，稳定发展

一家公司有规章制度，才能有序经营；一个家庭有“红线制度”，才能稳定和谐。结合现实中的家庭矛盾，我们可以设定以下4条“家庭红线”，任何人都不能触碰：

禁止家暴、冷暴力、出轨：这是家庭“集团公司”的“生死线”，触碰这条线，就会导致家庭“破产”。
禁止大额消费不沟通：任何大额消费（比如超过5000元），必须夫妻双方共同决策，避免“单方面挥霍”导致的财务矛盾。
禁止辱骂、翻旧账、人身攻击：吵架可以，但不能人身攻击、翻旧账，避免伤害彼此的感情，消耗家庭情绪资产。
财务透明，共同决策：不隐瞒收入、不藏匿私房钱，家庭财务公开透明，重大财务决策（比如投资、买房）共同商量。

就像稻盛和夫在经营企业时，坚守“作为人何为正确”的底线，家庭经营也需要坚守底线，才能实现长期稳定、共同幸福。

三、个人公司化的落地法则：从“知道”到“做到”，拒绝空谈

很多人看完“个人公司化”的逻辑，觉得“很有道理”，但就是不知道如何落地。其实，个人公司化的核心，不是“搞复杂的体系”，而是“把简单的事情做到极致”，结合企业管理的PDCA循环（Plan-Do-Check-Act），我们可以从以下5个方面，逐步落地，实现人生的持续优化。

战略规划：每年做一次“年度经营计划”

企业有年度预算、年度计划，你的“人生公司”也需要。每年年底，花1-2天时间，复盘今年的“经营情况”（目标完成率、资产增值情况、负债情况、家庭关系等），然后制定下一年的“年度经营计划”，明确核心目标，拆解到季度、月度、每周。

比如：明年的核心目标是“提升技能、增加储蓄、改善家庭氛围”，那么季度目标可以是“第一季度掌握一项新技能的基础内容，储蓄2万元，每月组织一次家庭聚餐”；月度目标可以是“每月阅读2本书，储蓄5000元，每周和家人深度沟通1次”；每周目标可以是“每天阅读1小时，每周运动3次，周末陪孩子出去玩1次”。

制定计划时，要遵循德鲁克的“优势原则”，聚焦自己的优势，不要盲目跟风——比如你擅长写作，就不要强迫自己去做直播；你适合独自学习，就不要强迫自己去参加无意义的社交，找到适合自己的节奏，才能高效执行。

预算管理：给人生做“成本控制”

企业的成本控制，是盈利的关键；人生的“成本控制”，是实现财务安全、避免内耗的核心。我们可以从“时间、金钱、情绪”三个维度，做好预算管理：

时间预算：每天规划好自己的时间，明确“什么时间做什么事”，避免时间浪费。比如：每天8小时工作，1小时阅读，1小时运动，2小时陪伴家人，1小时处理琐事，保证7-8小时睡眠。可以借鉴每周个人预算模板的思路，每天记录时间消耗，每周复盘，优化时间分配。
金钱预算：遵循“收入-储蓄=消费”的原则，而不是“收入-消费=储蓄”。每月工资到账后，先拿出30%-50%用于储蓄或理财，再拿出20%-30%用于投资自己（学习、健身等），剩下的用于日常开销。同时，记录每天的消费，避免冲动消费，远离网贷、信用卡透支。
情绪预算：每天给自己设定“情绪额度”，允许自己有短暂的不开心，但不能让负面情绪持续蔓延。比如：每天允许自己抱怨5分钟，之后就必须调整心态，做一些能让自己开心的事情（比如听音乐、运动、和朋友聊天），避免情绪内耗。

绩效考核：每月给自己“打分”

企业会定期考核员工，你的“人生公司”，也需要定期考核自己，了解自己的“经营情况”，及时发现问题、调整方向。每月月底，给自己做一次“绩效考核”，从9个“部门”的角度，分别打分（满分100分），低于60分的“部门”，就是“经营不善”，需要制定整改计划。

比如：这个月“研发部”打分50分，因为没有完成阅读计划，那么下个月的整改计划就是“每天固定1小时阅读，周末不拖延”；“财务部”打分70分，因为有冲动消费，那么下个月的整改计划就是“严格执行预算，不买非必要物品”。

考核的目的，不是“苛责自己”，而是“客观认识自己”，持续优化，让自己的“人生公司”经营得越来越好。就像企业的绩效考核，不是为了惩罚员工，而是为了提升效率、实现共赢。

PDCA循环：持续优化，迭代成长

企业的发展，是一个“计划-执行-检查-改进”的循环；人生的成长，也是一个持续迭代、不断优化的过程。遵循PDCA循环，让自己的“人生公司”不断升级：

Plan（计划）：制定明确的目标与计划（年度、季度、月度）。
Do（执行）：脚踏实地，认真执行计划，不拖延、不敷衍。
Check（检查）：定期复盘（每周、每月、每季度），检查目标完成情况，分析问题所在。
Act（改进）：针对检查中发现的问题，制定整改计划，优化流程、调整方向，避免再犯同样的错误。

比如：你计划每周运动3次，但这个月只运动了2次，检查后发现，是因为下班太晚、拖延导致的，那么改进计划就是“每天提前1小时下班，到家后立即运动，不拖延”。持续循环这个过程，你会发现，自己的执行力越来越强，人生也越来越有序。

止损机制：人生也要“裁员”和“剥离不良资产”

企业经营中，会及时“裁员”（淘汰不合格的员工）、“剥离不良资产”（处置亏损的业务），才能轻装上阵；人生经营中，也需要学会“止损”，剥离消耗自己的人、事、物，才能避免内耗，聚焦核心。

裁掉无效社交：远离那些只会抱怨、消耗你、不懂得感恩的人，把时间和精力留给真正值得的人（家人、朋友、同频的人）。就像远程办公的企业，会筛选能独当一面、自驱动的员工，我们也要筛选自己的社交圈，留下优质人脉。
剥离消耗你的事：停止那些无意义、不开心、不成长的事情，比如：刷无营养的短视频、熬夜追剧、和别人盲目攀比，把时间用在能提升自己、让自己开心的事情上。
放弃错误的目标：如果某个目标，你努力了很久，还是没有进展，而且让你感到疲惫、内耗，说明这个目标可能不适合你，学会放弃，及时调整方向，不要一条路走到黑。德鲁克说，找到自己属于哪里，比盲目努力重要100倍，放弃错误的目标，才能找到正确的方向。

四、个人公司化的常见误区：别让“经营”变成“内耗”

很多人在践行“个人公司化”的过程中，容易走入一些误区，反而让自己变得更加内耗、功利，违背了“个人公司化”的初衷。结合现实中的案例，我们总结了4个最常见的误区，帮你避开坑，正确经营自己的人生。

误区1：把“公司化”当成“功利化”，一切向钱看

很多人认为，“个人公司化”就是“赚钱至上”，为了赚钱，牺牲健康、忽略家庭、消耗情绪，甚至做违背良知的事情。但事实上，个人公司化的核心是“多元盈利”，金钱只是“营收”的一部分，健康、快乐、成长、家庭幸福，才是“人生公司”的核心利润。

就像稻盛和夫经营企业，从来不是“唯利润论”，而是强调“利他之心”，坚守“作为人何为正确”的底线，最终反而实现了企业的长期盈利。经营人生也是一样，懂得平衡金钱与生活，才能实现真正的“人生盈利”。

误区2：追求“完美执行”，不允许自己犯错

很多人制定了计划，就要求自己必须100%完成，一旦没有完成，就自责、内耗，甚至放弃。但企业经营中，也会有亏损、有失误，重要的不是“不犯错”，而是“及时整改、持续优化”。

人生经营也是一样，允许自己有失误、有拖延，允许自己偶尔“偷懒”，重要的是，不要因为一次失误，就否定自己，而是要及时复盘、调整，继续前行。就像长江读书会的书友，每天坚持读书，偶尔偷懒没读，也不会自责，而是第二天继续坚持，长期坚持下来，反而收获满满。

误区3：用“公司化”控制家人，忽视家庭温度

有些夫妻，把“家庭公司化”当成“控制对方”的工具，用“绩效考核”要求家人，用“规则”束缚家人，忽视了家庭的温度与包容。比如：要求伴侣必须每天完成多少家务，要求孩子必须考多少分，一旦没有达到，就指责、批评，反而让家庭矛盾越来越多。

记住，家庭“集团公司”的核心是“协同经营、共同幸福”，规则是为了“减少内耗”，而不是“控制对方”；分工是为了“互相配合”，而不是“互相指责”。就像阿米巴经营的核心，是激发员工的主动性，而不是控制员工，家庭经营也需要包容与理解，才能充满温暖。

误区4：只注重“执行”，忽视“复盘与优化”

很多人制定了计划，也认真执行了，但就是不懂得复盘，导致自己一直在重复犯同样的错误，成长缓慢。就像有些企业，只注重生产，不注重复盘优化，最终被市场淘汰。

复盘是“人生公司”迭代成长的关键，每周、每月、每季度，都要花时间复盘自己的“经营情况”，分析问题、总结经验，优化计划与流程，才能不断提升自己的经营能力，实现人生的持续盈利。

五、结语：人生最好的经营，是清醒自洽，长期主义

我们每个人，都是自己人生的“CEO”，经营自己这家“公司”，没有标准答案，没有捷径可走，只有脚踏实地、持续优化、坚守底线。个人公司化，不是让我们变得冷漠、功利，而是让我们用理性的思维，梳理人生的混乱，用坚定的行动，追逐自己的目标，用温暖的初心，守护自己的家庭。

德鲁克说：“管理自己，是21世纪生存的核心能力。” 稻盛和夫说：“不是因为看到希望才坚持，而是坚持了才会看到希望。” 经营人生，就像经营一家企业，需要有长期主义的耐心，需要有直面问题的勇气，需要有持续优化的决心。

不必羡慕别人的“人生公司”盈利丰厚，每个人的“注册资本”不同，“经营节奏”不同，只要你认真经营、持续成长，剥离负债、积累资产，平衡好工作与生活、金钱与幸福，你的“人生公司”，终将实现属于自己的“盈利”——清醒、自洽、自由、幸福。

愿我们都能学会经营自己，把潦草的人生，活成一家稳健、长期、有价值的“好公司”，不负时光，不负自己，不负身边的人。

SOP全维度详细讲解：从核心定义到实战落地的完整指南

Fri, 10 Apr 2026 00:00:00 GMT

SOP（Standard Operating Procedure）全维度详细讲解#

一、SOP 核心定义（精准、官方）#

SOP 全称：Standard Operating Procedure

中文标准译名为：标准作业程序，也常称标准操作规程、标准作业指导流程。

官方精准定义：

SOP 是为了完成特定工作任务，将常规、重复、关键的操作步骤，按照统一的标准、固定的顺序、明确的要求，进行规范化、文字化、流程化、可量化的书面/电子文件规定。

核心目的是：让不同执行者，在不同时间、不同场景下，都能以相同的方式完成同一项工作，最终实现结果统一、质量稳定、风险可控、效率提升。

简单理解：把“怎么做一件事”写成固定说明书，所有人照做不走样。

二、SOP 的核心本质与关键特征#

SOP 不是普通的工作笔记，而是具备强约束性、标准化的管理文件，核心特征如下：

标准化

动作、步骤、参数、标准统一，无主观随意性，杜绝“凭经验做事”。

可复制性

新人、老员工、不同班组/门店，都能复刻相同操作，实现规模化落地。

可量化

拒绝模糊描述（如“适量”“大概”），全部用数据、指标、时间、规格定义。

可追溯

配套记录、表单、签字，出现问题可回溯到具体步骤、责任人。

可培训

是新人入职、岗位轮岗的核心培训教材，降低学习成本。

稳定性

固化成熟流程，减少人为失误，保障工作结果一致性。

合规性

符合行业法规、企业制度、质量体系（如ISO、GMP、HACCP）要求。

三、SOP 的起源与发展#

起源

源于工业革命+泰勒科学管理理论，福特汽车首创流水线作业，将汽车组装拆解为固定步骤，是现代SOP雏形。

普及

二战期间军工生产大规模应用SOP，保障武器生产质量统一；后续推广至制造业、医疗、餐饮、物流、政务、互联网等全行业。

体系化

成为ISO9001质量管理体系、GMP药品生产管理、HACCP食品安全体系的核心组成部分，是企业合规运营的基础文件。

四、SOP 的分类（全面维度划分）#

（一）按管理层级划分#

公司级SOP：全公司通用，如财务报销、公章使用、安全管理SOP；
部门级SOP：部门专属，如人力资源招聘、市场推广、生产车间SOP；
岗位级SOP：单个岗位具体操作，如客服接线、仓库分拣、设备操作SOP。

（二）按功能用途划分#

操作执行类：核心干活流程，如产品组装、奶茶制作、设备开机；
管理管控类：流程审批、人员管理、资源调配，如采购审批SOP；
质量检验类：产品检测、验收标准，如成品出厂检验SOP；
应急处置类：突发情况处理，如火灾应急、设备故障停机SOP；
合规风控类：满足法规要求，如医疗消毒、食品留样SOP。

（三）按呈现形式划分#

纯文字版：步骤文字描述，适合简单操作；
流程图版：Visio/ProcessOn绘制流程框图，直观展示逻辑；
图文并茂版：步骤+实拍图/示意图，适合复杂操作；
视频版SOP：实操演示视频，适合高难度、高风险岗位；
电子表单版：嵌入OA/飞书/钉钉，流程自动流转。

（四）按行业场景划分#

制造业、医疗医药、餐饮连锁、物流快递、互联网、政务行政、金融、教育等全行业均有专属SOP。

五、SOP 的核心作用与价值（全场景覆盖）#

1. 统一作业标准，杜绝人为差异#

避免“10个人做同一件事，做出10种结果”，保障输出一致性。

2. 降低失误与风险#

关键步骤标准化，减少操作失误、安全事故、质量缺陷、合规处罚。

3. 提升工作效率#

省去反复沟通、试错成本，流程固定后执行速度大幅提升。

4. 新人快速上手#

无需老员工手把手带教，新人按SOP即可独立上岗，降低培训成本。

5. 质量稳定可控#

量化验收标准，产品/服务质量可稳定达标，提升客户满意度。

6. 知识沉淀与传承#

把老员工经验、优秀流程固化为文件，避免人员流失导致经验断层。

7. 合规审计必备#

应对政府检查、体系认证、客户验厂，SOP是核心佐证文件。

8. 优化管理与绩效考核#

明确岗位职责、操作标准，为绩效考核提供客观依据。

9. 跨部门协作顺畅#

统一流程接口，减少部门推诿、沟通内耗。

六、完整SOP的标准结构（官方通用模板，最核心部分）#

一份规范、可落地、合规的SOP，必须包含11大核心模块，缺一不可：

1. 文件头部（基础信息，唯一标识）#

SOP编号：企业统一编码（如SOP-HR-001）
版本号：V1.0/V2.0（迭代管理）
生效日期：YYYY-MM-DD
编制人/审核人/批准人：三级签字，明确责任
适用范围：适用部门、岗位、场景
归口管理部门：负责修订、更新的部门

2. 目的#

明确为什么要制定本SOP，如“规范XX操作，保障质量，降低风险”。

3. 术语与定义#

对专业名词、缩写、设备名称进行解释，避免理解偏差。

4. 职责分工#

明确谁来做：执行人、复核人、监督人、责任人，杜绝权责不清。

5. 前置条件/资源准备#

操作前必备条件：

人员资质：是否需持证上岗
设备工具：设备型号、状态、校准情况
物料耗材：规格、数量、质量要求
环境要求：温度、湿度、洁净度
表单记录：需填写的单据

6. 详细作业步骤（SOP核心主体）#

按时间顺序/操作逻辑拆解，步骤编号1、2、3…
动作拆解到最小单元，无跳跃、无模糊描述
关键步骤标注关键控制点（CCP），重点强调

7. 质量标准/验收标准#

明确做到什么程度算合格，量化指标：

时间标准：XX分钟内完成
数值标准：温度±1℃、重量±5g
外观标准：无划痕、无破损
功能标准：运行正常、无故障

8. 异常情况与应急处理#

操作中出现问题的处置方案：

常见异常：设备故障、物料不合格、操作失误
处理步骤：停机→上报→排查→整改→恢复
应急措施：安全事故、突发风险的紧急操作

9. 记录与表单#

操作过程需填写的记录：如操作记录表、检验单、异常报告单，明确留存期限、存放位置。

10. 相关引用文件#

关联的制度、国标、其他SOP、设备说明书，形成文件体系。

11. 附则#

修订规则：何时更新、如何更新
废止说明：旧版本自动失效
解释权：归口部门解释

七、SOP 的编写方法与原则（可直接落地）#

（一）编写核心原则#

5W1H原则

What（做什么）、Why（为什么做）、Who（谁做）、When（何时做）、Where（在哪做）、How（怎么做）

SMART原则

具体、可衡量、可实现、相关、有时限

MECE原则

步骤相互独立、完全穷尽，无遗漏、无重叠

可执行性原则

拒绝空话、套话，贴合实际工作，不纸上谈兵

简洁直观原则

能用图不用字，能用短句不用长句

（二）标准编写流程#

需求调研：梳理岗位工作，识别重复、关键、高风险操作
流程梳理：绘制现有流程，优化不合理环节
步骤拆解：把流程拆分为最小操作单元
标准制定：量化参数、明确标准、划分职责
初稿撰写：按标准结构编写SOP文本
评审修订：一线员工、主管、质量部门联合评审，修改不合理内容
审批发布：正式签字生效，纳入企业文件体系
培训宣贯：全员学习，考核通过方可上岗

（三）编写避坑技巧#

禁用模糊词：把“适量”改为“50ml”，“尽快”改为“3分钟内”
关键步骤加粗/标红，重点提醒
复杂操作配实拍图/流程图，降低理解成本
避免过度繁琐，简单操作简化步骤

八、SOP 的落地执行与使用方法（从“写出来”到“用起来”）#

1. 发布与归档#

纸质版：张贴在操作现场（车间、工位、门店）
电子版：上传企业知识库（飞书/钉钉/OA），全员可查阅
版本管理：统一归档，禁止私自修改、传播旧版本

2. 培训与考核#

新员工：SOP为岗前培训核心内容
老员工：定期复训，更新迭代后专项培训
考核：笔试+实操，考核通过方可上岗，不合格禁止操作

3. 现场执行#

严格按SOP步骤操作，禁止擅自更改流程
关键岗位双人复核，保障执行到位
实时填写操作记录，留存痕迹

4. 监督与检查#

日常巡检：主管现场核查执行情况
定期审计：质量/管理部门月度/季度 audit
纠偏整改：发现不按SOP操作，立即整改并追责

5. 考核挂钩#

将SOP执行情况纳入员工绩效考核，与奖惩、晋升挂钩。

九、SOP 的优化与迭代（PDCA循环）#

SOP 不是一成不变的，需跟随业务迭代更新，遵循PDCA循环：

Plan（计划）：规划SOP框架与标准
Do（执行）：落地执行SOP
Check（检查）：核查执行效果、问题、效率
Act（处理）：优化不合理步骤，修订SOP，形成新版本

迭代触发场景#

设备更新、工艺升级
法规/行业标准变更
频繁出现操作失误、质量问题
业务流程优化、效率提升需求
客户/市场新要求

迭代规范#

修订需走审批流程，禁止私自修改
新版本发布后，旧版本立即废止
迭代后重新培训，确保全员知晓

十、SOP 与易混淆概念的区别（精准区分）#

| 概念 | 核心区别 |

|------|----------|

| SOP 标准作业程序 | 侧重完整流程+执行步骤+标准，强约束、可落地 |

| WI 作业指导书 | 侧重单一操作细节（如设备按钮操作），是SOP的补充 |

| 管理制度 | 侧重规则、权责、奖惩，宏观约束，不讲具体操作 |

| 流程图 | 仅展示逻辑框架，无具体标准、参数、要求 |

| 质量手册 | 企业质量体系纲领文件，SOP是其落地执行文件 |

十一、不同行业SOP实战案例（具象化理解）#

案例1：餐饮连锁·奶茶制作SOP#

前置准备：杯具消毒、物料称重（珍珠50g、茶汤200ml）
步骤1：取杯→贴标签→加珍珠
步骤2：倒入茶汤→加冰150g→加糖25g
步骤3：雪克杯摇晃10秒→倒入杯中
质量标准：温度5℃，甜度标准，无洒漏
异常处理：物料不足立即上报，禁止私自更改配比

案例2：制造业·产品组装SOP#

人员：持证上岗，穿戴防静电服
设备：流水线开机自检，参数校准
步骤：上料→插件→焊接→检测→封装
检验：电阻值±0.1Ω，外观无虚焊
记录：填写组装记录表，留存3年

案例3：互联网·客服接待SOP#

响铃3秒内接听
话术：您好，XX客服，请问有什么可以帮您？
步骤：倾听需求→记录问题→解答→确认解决→礼貌挂机
标准：通话时长≤3分钟，满意度≥95%

案例4：医疗·静脉输液SOP#

核对患者信息→消毒皮肤→穿刺→固定→调节滴速
标准：滴速60滴/分钟，无菌操作，无回血外渗
应急：肿胀/过敏立即拔针，上报医生

十二、SOP 实施的常见误区与避坑#

形式主义，只写不用

避免SOP锁在抽屉，必须现场落地、监督执行

过于繁琐，无法执行

流程过度复杂，员工抵触，需简化实用

长期不更新，脱离实际

业务变化后SOP未迭代，变成“废纸”

无量化标准，模糊不清

全是定性描述，无法判断是否合格

缺乏培训，全员不懂

编写后不培训，员工不知道标准

只重步骤，不重结果

忽略验收标准，步骤对了结果错了

十三、SOP 常用工具与模板#

常用工具#

文字编写：Word、WPS
流程图：Visio、ProcessOn、XMind
在线协同：飞书文档、石墨文档、腾讯文档
体系管理：ISO文件管理系统、企业OA

通用简易模板#

1
【SOP编号】XXX
2

3
【版本】V1.0
4

5
【适用范围】XXX
6

7
【目的】XXX
8

9
【职责】XXX
10

11
【准备工作】XXX
12

13
【操作步骤】
14

15
1.XXX
16

17
2.XXX
18

19
【质量标准】XXX
20

21
【异常处理】XXX
22

23
【记录表单】XXX
24

25
【编制/审核/批准】XXX

展开收起

总结#

SOP 本质是企业/岗位的“操作宪法”，是标准化管理的基础工具，覆盖从生产到服务、从基层到管理的全场景。

其核心价值是统一标准、降低风险、提升效率、沉淀经验，编写时要贴合实际、量化清晰，执行时要严格落地、持续迭代，才能真正发挥作用。

🔧 现代CMake最佳实践：权限最小化与依赖管理完全指南

Thu, 09 Apr 2026 00:00:00 GMT

🔧 现代CMake最佳实践：权限最小化与依赖管理完全指南#

现代CMake（3.14+）的核心设计理念是基于目标的依赖管理，通过精确控制每个目标的依赖可见性，实现权限最小化、编译效率最大化。本文将系统讲解现代CMake的最佳实践，帮助你告别全局变量的混乱时代。

一、核心概念：PRIVATE/PUBLIC/INTERFACE#

1. 三种依赖可见性详解#

现代CMake通过三个关键字精确控制依赖的传播范围：

关键字	当前目标	依赖当前目标的其他目标	典型场景
PRIVATE	✅ 可见	❌ 不可见	内部实现依赖，如第三方库、内部工具
PUBLIC	✅ 可见	✅ 可见	接口依赖，如导出头文件中使用的库
INTERFACE	❌ 不可见	✅ 可见	纯头文件库，仅对使用者生效

依赖传播示意图：

1
A 依赖 B (PUBLIC)  →  使用 A 的目标也能看到 B
2
A 依赖 B (PRIVATE) →  使用 A 的目标看不到 B
3
A 依赖 B (INTERFACE) → A 自己看不到 B，但使用 A 的目标能看到 B

2. 依赖传播的实际例子#

1
# libA 是一个网络库，内部使用 libuv 实现
2
add_library(libA STATIC libA.cpp)
3

4
# libuv 是内部实现细节，不应该暴露给 libA 的使用者
5
target_link_libraries(libA PRIVATE libuv)
6

7
# libA 的公共头文件中使用了 libB 的类型
8
# 所以 libB 必须是 PUBLIC 依赖
9
target_link_libraries(libA PUBLIC libB)
10

11
# libA 提供了一个纯头文件的插件接口
12
# 插件实现者需要这个接口，但 libA 自己不需要
13
target_link_libraries(libA INTERFACE libA_plugin_interface)

3. 包含目录的可见性控制#

1
add_library(mylib STATIC mylib.cpp)
2

3
# 私有包含目录 - 仅 mylib.cpp 可见
4
target_include_directories(mylib PRIVATE
5
    ${CMAKE_CURRENT_SOURCE_DIR}/src/internal
6
    ${CMAKE_CURRENT_SOURCE_DIR}/third_party
7
)
8

9
# 公共包含目录 - mylib 和使用 mylib 的目标都可见
10
target_include_directories(mylib PUBLIC
11
    ${CMAKE_CURRENT_SOURCE_DIR}/include
12
)
13

14
# 接口包含目录 - 仅使用 mylib 的目标可见
15
target_include_directories(mylib INTERFACE
16
    ${CMAKE_CURRENT_SOURCE_DIR}/include/mylib/plugins
17
)

展开收起

4. 编译定义的可见性控制#

1
add_library(mylib STATIC mylib.cpp)
2

3
# 私有定义 - 仅影响当前目标的编译
4
target_compile_definitions(mylib PRIVATE
5
    DEBUG_MODE=1
6
    INTERNAL_VERSION="2.0"
7
)
8

9
# 公共定义 - 当前目标和使用者都会获得
10
target_compile_definitions(mylib PUBLIC
11
    MYLIB_API_VERSION=3
12
)
13

14
# 接口定义 - 仅使用者获得
15
target_compile_definitions(mylib INTERFACE
16
    MYLIB_PLUGIN_SUPPORT
17
)

展开收起

二、传统方式 vs 现代方式#

❌ 传统方式（不推荐）#

1
# 全局设置，影响所有后续目标
2
cmake_minimum_required(VERSION 3.10)
3
project(myproject)
4

5
# 全局包含目录 - 所有目标都能看到
6
include_directories(${CMAKE_SOURCE_DIR}/include)
7
include_directories(${CMAKE_SOURCE_DIR}/third_party/libuv/include)
8
include_directories(${CMAKE_SOURCE_DIR}/third_party/openssl/include)
9

10
# 全局库目录
11
link_directories(${CMAKE_SOURCE_DIR}/third_party/lib)
12
link_directories(/usr/local/lib)
13

14
# 全局编译选项
15
add_definitions(-DDEBUG)
16
add_definitions(-DVERSION="1.0")
17

18
# 全局编译标志
19
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -Wextra -O2")
20

21
# 链接时不指定可见性
22
add_executable(myapp main.cpp)
23
target_link_libraries(myapp uv ssl crypto pthread)

展开收起

传统方式的问题：

污染全局命名空间 - 所有目标都继承相同的设置
隐藏依赖关系 - 无法从 CMakeLists.txt 看出真实依赖
编译效率低 - 修改任何头文件都会触发大量重编译
难以维护 - 多模块项目容易产生冲突
不可移植 - 硬编码路径在其他环境无法工作

✅ 现代方式（推荐）#

1
cmake_minimum_required(VERSION 3.14)
2
project(myproject VERSION 1.0.0 LANGUAGES CXX)
3

4
# 设置 C++ 标准
5
set(CMAKE_CXX_STANDARD 17)
6
set(CMAKE_CXX_STANDARD_REQUIRED ON)
7
set(CMAKE_CXX_EXTENSIONS OFF)
8

9
# ========== 第三方库配置 ==========
10
find_package(OpenSSL REQUIRED)
11
find_package(Threads REQUIRED)
12

13
# ========== 内部库：网络模块 ==========
14
add_library(network STATIC
15
    src/network/tcp_client.cpp
16
    src/network/tcp_server.cpp
17
    src/network/ssl_wrapper.cpp
18
)
19

20
target_include_directories(network
21
    PUBLIC
22
        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/network>
23
        $<INSTALL_INTERFACE:include/network>
24
    PRIVATE
25
        ${CMAKE_CURRENT_SOURCE_DIR}/src/network/internal
26
)
27

28
target_link_libraries(network
29
    PUBLIC
30
        OpenSSL::SSL
31
        OpenSSL::Crypto
32
    PRIVATE
33
        Threads::Threads
34
)
35

36
target_compile_features(network PUBLIC cxx_std_17)
37

38
# ========== 主程序 ==========
39
add_executable(myapp
40
    src/main.cpp
41
    src/app.cpp
42
)
43

44
target_include_directories(myapp PRIVATE
45
    ${CMAKE_CURRENT_SOURCE_DIR}/src
46
)
47

48
target_link_libraries(myapp PRIVATE
49
    network
50
)
51

52
target_compile_options(myapp PRIVATE
53
    $<$<CONFIG:Debug>:-Wall -Wextra -g>
54
    $<$<CONFIG:Release>:-O3 -DNDEBUG>
55
)

展开收起

三、现代CMake项目结构示例#

根目录 CMakeLists.txt#

1
cmake_minimum_required(VERSION 3.14)
2

3
project(MyProject
4
    VERSION 1.0.0
5
    DESCRIPTION "A modern CMake project example"
6
    LANGUAGES CXX
7
)
8

9
# 全局设置（仅设置必要的）
10
set(CMAKE_CXX_STANDARD 17)
11
set(CMAKE_CXX_STANDARD_REQUIRED ON)
12
set(CMAKE_CXX_EXTENSIONS OFF)
13
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
14

15
# 设置默认构建类型
16
if(NOT CMAKE_BUILD_TYPE)
17
    set(CMAKE_BUILD_TYPE Release CACHE STRING "Build type" FORCE)
18
endif()
19

20
# 添加子目录
21
add_subdirectory(src)
22
add_subdirectory(tests)
23

24
# 安装配置
25
include(GNUInstallDirs)
26
include(CMakePackageConfigHelpers)
27

28
# 安装头文件
29
install(DIRECTORY include/mylib
30
    DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
31
)
32

33
# 生成版本配置文件
34
write_basic_package_version_file(
35
    "${CMAKE_CURRENT_BINARY_DIR}/MyProjectConfigVersion.cmake"
36
    VERSION ${PROJECT_VERSION}
37
    COMPATIBILITY SameMajorVersion
38
)
39

40
# 安装 CMake 配置文件
41
install(FILES
42
    "${CMAKE_CURRENT_BINARY_DIR}/MyProjectConfigVersion.cmake"
43
    DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MyProject
44
)

展开收起

库的 CMakeLists.txt#

src/CMakeLists.txt展开收起

1
# 收集源文件
2
add_library(mylib
3
    mylib/core.cpp
4
    mylib/utils.cpp
5
    mylib/network.cpp
6
)
7

8
# 设置目标属性
9
set_target_properties(mylib PROPERTIES
10
    VERSION ${PROJECT_VERSION}
11
    SOVERSION 1
12
    OUTPUT_NAME mylib
13
    POSITION_INDEPENDENT_CODE ON
14
)
15

16
# 包含目录
17
target_include_directories(mylib
18
    PUBLIC
19
        $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/include>
20
        $<INSTALL_INTERFACE:include>
21
    PRIVATE
22
        ${CMAKE_CURRENT_SOURCE_DIR}/mylib/internal
23
)
24

25
# 编译定义
26
target_compile_definitions(mylib
27
    PUBLIC
28
        MYLIB_VERSION_MAJOR=${PROJECT_VERSION_MAJOR}
29
        MYLIB_VERSION_MINOR=${PROJECT_VERSION_MINOR}
30
    PRIVATE
31
        MYLIB_BUILDING
32
)
33

34
# 编译选项
35
target_compile_options(mylib
36
    PRIVATE
37
        $<$<CXX_COMPILER_ID:GNU,Clang,AppleClang>:-Wall -Wextra -Wpedantic>
38
        $<$<CXX_COMPILER_ID:MSVC>:/W4>
39
)
40

41
# 链接依赖
42
find_package(Threads REQUIRED)
43
find_package(OpenSSL REQUIRED)
44

45
target_link_libraries(mylib
46
    PUBLIC
47
        OpenSSL::SSL
48
    PRIVATE
49
        Threads::Threads
50
        OpenSSL::Crypto
51
)
52

53
# 安装目标
54
install(TARGETS mylib
55
    EXPORT mylibTargets
56
    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
57
    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
58
    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
59
    INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
60
)
61

62
install(EXPORT mylibTargets
63
    FILE mylibTargets.cmake
64
    NAMESPACE MyProject::
65
    DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MyProject
66
)

展开收起

测试的 CMakeLists.txt#

tests/CMakeLists.txt展开收起

1
# 使用 FetchContent 获取 Google Test
2
include(FetchContent)
3
FetchContent_Declare(
4
    googletest
5
    GIT_REPOSITORY https://github.com/google/googletest.git
6
    GIT_TAG v1.14.0
7
)
8
FetchContent_MakeAvailable(googletest)
9

10
# 禁用 Google Test 的 C++17 警告
11
set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
12

13
# 测试可执行文件
14
add_executable(unit_tests
15
    test_core.cpp
16
    test_utils.cpp
17
    test_network.cpp
18
)
19

20
target_include_directories(unit_tests PRIVATE
21
    ${CMAKE_CURRENT_SOURCE_DIR}
22
)
23

24
target_link_libraries(unit_tests PRIVATE
25
    mylib
26
    GTest::gtest
27
    GTest::gtest_main
28
)
29

30
# 注册测试
31
include(GoogleTest)
32
gtest_discover_tests(unit_tests)

展开收起

四、find_package 的现代用法#

1. 使用导入目标（Imported Targets）#

1
# ✅ 推荐：使用导入目标
2
find_package(OpenSSL REQUIRED)
3
target_link_libraries(myapp PRIVATE OpenSSL::SSL OpenSSL::Crypto)
4

5
# ✅ 推荐：使用导入目标
6
find_package(Threads REQUIRED)
7
target_link_libraries(myapp PRIVATE Threads::Threads)
8

9
# ✅ 推荐：Boost 使用导入目标
10
find_package(Boost 1.70 REQUIRED COMPONENTS filesystem system)
11
target_link_libraries(myapp PRIVATE Boost::filesystem Boost::system)
12

13
# ❌ 不推荐：使用变量
14
find_package(OpenSSL REQUIRED)
15
target_link_libraries(myapp PRIVATE ${OPENSSL_LIBRARIES})
16
target_include_directories(myapp PRIVATE ${OPENSSL_INCLUDE_DIR})

展开收起

2. 自定义 Find 模块#

cmake/FindMyLib.cmake展开收起

1
find_path(MYLIB_INCLUDE_DIR
2
    NAMES mylib/api.h
3
    PATHS
4
        /usr/local/include
5
        /opt/mylib/include
6
)
7

8
find_library(MYLIB_LIBRARY
9
    NAMES mylib mylibd
10
    PATHS
11
        /usr/local/lib
12
        /opt/mylib/lib
13
)
14

15
include(FindPackageHandleStandardArgs)
16
find_package_handle_standard_args(MyLib
17
    REQUIRED_VARS MYLIB_LIBRARY MYLIB_INCLUDE_DIR
18
    VERSION_VAR MYLIB_VERSION
19
)
20

21
if(MyLib_FOUND AND NOT TARGET MyLib::MyLib)
22
    add_library(MyLib::MyLib UNKNOWN IMPORTED)
23
    set_target_properties(MyLib::MyLib PROPERTIES
24
        IMPORTED_LOCATION "${MYLIB_LIBRARY}"
25
        INTERFACE_INCLUDE_DIRECTORIES "${MYLIB_INCLUDE_DIR}"
26
    )
27
endif()
28

29
mark_as_advanced(MYLIB_INCLUDE_DIR MYLIB_LIBRARY)

展开收起

3. 使用 FetchContent 管理依赖#

1
include(FetchContent)
2

3
# 下载并配置第三方库
4
FetchContent_Declare(
5
    json
6
    GIT_REPOSITORY https://github.com/nlohmann/json.git
7
    GIT_TAG v3.11.2
8
)
9

10
FetchContent_Declare(
11
    spdlog
12
    GIT_REPOSITORY https://github.com/gabime/spdlog.git
13
    GIT_TAG v1.12.0
14
)
15

16
# 一次性获取所有依赖
17
FetchContent_MakeAvailable(json spdlog)
18

19
# 使用
20
target_link_libraries(myapp PRIVATE nlohmann_json::nlohmann_json spdlog::spdlog)

展开收起

五、生成器表达式#

生成器表达式允许在构建时（而非配置时）计算值，是实现跨平台、跨配置构建的关键。

1. 常用生成器表达式#

1
# 根据构建类型设置编译选项
2
target_compile_options(myapp PRIVATE
3
    $<$<CONFIG:Debug>:-g -O0 -Wall>
4
    $<$<CONFIG:Release>:-O3 -DNDEBUG>
5
    $<$<CONFIG:RelWithDebInfo>:-O2 -g>
6
)
7

8
# 根据编译器设置选项
9
target_compile_options(myapp PRIVATE
10
    $<$<CXX_COMPILER_ID:GNU>:-Wall -Wextra -Wpedantic>
11
    $<$<CXX_COMPILER_ID:Clang>:-Wall -Wextra -Weverything>
12
    $<$<CXX_COMPILER_ID:MSVC>:/W4 /utf-8>
13
)
14

15
# 根据平台设置选项
16
target_compile_definitions(myapp PRIVATE
17
    $<$<PLATFORM_ID:Windows>:WINDOWS_BUILD>
18
    $<$<PLATFORM_ID:Linux>:LINUX_BUILD>
19
    $<$<PLATFORM_ID:Darwin>:MACOS_BUILD>
20
)
21

22
# 根据语言版本设置
23
target_compile_features(myapp PRIVATE
24
    $<$<CXX_COMPILER_ID:GNU,Clang>:cxx_std_20>
25
)
26

27
# 条件链接库
28
target_link_libraries(myapp PRIVATE
29
    $<$<PLATFORM_ID:Windows>:ws2_32>
30
    $<$<PLATFORM_ID:Linux>:rt>
31
)

展开收起

2. 包含目录的生成器表达式#

1
target_include_directories(mylib PUBLIC
2
    # 构建时使用源码目录
3
    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
4
    # 安装后使用安装目录
5
    $<INSTALL_INTERFACE:include>
6
)

3. 自定义命令的条件执行#

1
add_custom_command(TARGET myapp POST_BUILD
2
    COMMAND $<$<CONFIG:Debug>:${CMAKE_COMMAND}>
3
        -E copy_if_different
4
        $<TARGET_FILE:mylib>
5
        $<TARGET_FILE_DIR:myapp>
6
    COMMENT "Copy library to output directory (Debug only)"
7
)

六、预编译头（PCH）#

预编译头可以显著提高编译速度，特别是对于大型项目。

1
# 添加预编译头
2
target_precompile_headers(mylib PRIVATE
3
    <vector>
4
    <string>
5
    <map>
6
    <memory>
7
    <algorithm>
8
    <iostream>
9
    "mylib/common.h"
10
)
11

12
# 重用其他目标的预编译头
13
target_precompile_headers(myapp REUSE_FROM mylib)
14

15
# 禁用特定文件的预编译头
16
set_source_files_properties(special.cpp PROPERTIES SKIP_PRECOMPILE_HEADERS ON)

展开收起

七、CMakePresets.json#

CMakePresets.json 是 CMake 3.19+ 引入的配置预设文件，可以统一管理构建配置。

1
{
2
    "version": 3,
3
    "configurePresets": [
4
        {
5
            "name": "default",
6
            "displayName": "Default Config",
7
            "description": "Default build configuration",
8
            "binaryDir": "${sourceDir}/build/${presetName}",
9
            "cacheVariables": {
10
                "CMAKE_BUILD_TYPE": "Release",
11
                "CMAKE_CXX_STANDARD": "17",
12
                "BUILD_TESTS": "ON"
13
            }
14
        },
15
        {
16
            "name": "debug",
17
            "displayName": "Debug Config",
18
            "inherits": "default",
19
            "cacheVariables": {
20
                "CMAKE_BUILD_TYPE": "Debug",
21
                "CMAKE_CXX_FLAGS_DEBUG": "-Wall -Wextra -g -fsanitize=address"
22
            }
23
        },
24
        {
25
            "name": "release",
26
            "displayName": "Release Config",
27
            "inherits": "default",
28
            "cacheVariables": {
29
                "CMAKE_BUILD_TYPE": "Release",
30
                "CMAKE_CXX_FLAGS_RELEASE": "-O3 -march=native"
31
            }
32
        },
33
        {
34
            "name": "msvc",
35
            "displayName": "MSVC Config",
36
            "inherits": "default",
37
            "generator": "Visual Studio 17 2022",
38
            "cacheVariables": {
39
                "CMAKE_CXX_COMPILER": "cl.exe"
40
            }
41
        }
42
    ],
43
    "buildPresets": [
44
        {
45
            "name": "default",
46
            "configurePreset": "default"
47
        },
48
        {
49
            "name": "debug",
50
            "configurePreset": "debug"
51
        },
52
        {
53
            "name": "release",
54
            "configurePreset": "release"
55
        }
56
    ],
57
    "testPresets": [
58
        {
59
            "name": "default",
60
            "configurePreset": "default",
61
            "output": {
62
                "outputOnFailure": true
63
            }
64
        }
65
    ]
66
}

展开收起

使用方式：

Terminal window

1
# 配置
2
cmake --preset debug
3

4
# 构建
5
cmake --build --preset debug
6

7
# 测试
8
ctest --preset default

八、常见陷阱与解决方案#

1. 循环依赖#

1
# ❌ 错误：A 依赖 B，B 也依赖 A
2
target_link_libraries(A PUBLIC B)
3
target_link_libraries(B PUBLIC A)
4

5
# ✅ 解决：将公共部分提取为独立库
6
add_library(common STATIC common.cpp)
7
target_link_libraries(A PRIVATE common B)
8
target_link_libraries(B PRIVATE common)

2. 头文件路径问题#

1
# ❌ 错误：使用相对路径
2
#include "mylib/internal/impl.h"
3

4
# ✅ 正确：使用从包含目录开始的路径
5
target_include_directories(mylib PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src)
6
#include "mylib/internal/impl.h"

3. 静态库的传递依赖#

1
# 静态库的 PRIVATE 依赖不会自动传递
2
add_library(static_lib STATIC lib.cpp)
3
target_link_libraries(static_lib PRIVATE dependency)
4

5
# 使用者需要显式链接
6
add_executable(app main.cpp)
7
target_link_libraries(app PRIVATE static_lib dependency)
8

9
# ✅ 更好的方式：使用对象库
10
add_library(obj_lib OBJECT lib.cpp)
11
target_link_libraries(obj_lib PUBLIC dependency)
12

13
add_library(static_lib STATIC $<TARGET_OBJECTS:obj_lib>)
14
target_link_libraries(static_lib PUBLIC dependency)

4. 全局变量污染#

1
# ❌ 错误：修改全局变量影响所有目标
2
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall")
3

4
# ✅ 正确：使用 target_compile_options
5
target_compile_options(myapp PRIVATE -Wall)

九、最佳实践清单#

✅ 必须做的#

实践	说明
使用 `target_*` 命令	替代全局命令，精确控制依赖
明确指定依赖可见性	PRIVATE/PUBLIC/INTERFACE 三选一
使用导入目标	`find_package` 后使用 `Lib::Lib` 形式
设置 C++ 标准	使用 `CMAKE_CXX_STANDARD` 或 `target_compile_features`
使用生成器表达式	实现跨平台、跨配置的构建

❌ 必须避免的#

实践	替代方案
`include_directories()`	`target_include_directories()`
`link_directories()`	`target_link_directories()` 或使用导入目标
`add_definitions()`	`target_compile_definitions()`
`add_compile_options()`	`target_compile_options()`
全局修改 `CMAKE_CXX_FLAGS`	使用 `target_compile_options()`
`aux_source_directory()`	显式列出源文件
`file(GLOB ...)`	显式列出源文件（除非配合配置时检查）

📋 推荐的 CMakeLists.txt 模板#

1
cmake_minimum_required(VERSION 3.14)
2

3
project(MyProject
4
    VERSION 1.0.0
5
    LANGUAGES CXX
6
)
7

8
# ========== 全局配置 ==========
9
set(CMAKE_CXX_STANDARD 17)
10
set(CMAKE_CXX_STANDARD_REQUIRED ON)
11
set(CMAKE_CXX_EXTENSIONS OFF)
12
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
13

14
# ========== 依赖 ==========
15
find_package(Threads REQUIRED)
16

17
# ========== 目标 ==========
18
add_library(mylib STATIC
19
    src/lib.cpp
20
)
21

22
target_include_directories(mylib
23
    PUBLIC
24
        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
25
        $<INSTALL_INTERFACE:include>
26
    PRIVATE
27
        ${CMAKE_CURRENT_SOURCE_DIR}/src
28
)
29

30
target_compile_features(mylib PUBLIC cxx_std_17)
31

32
target_compile_options(mylib PRIVATE
33
    $<$<CXX_COMPILER_ID:GNU,Clang>:-Wall -Wextra -Wpedantic>
34
    $<$<CXX_COMPILER_ID:MSVC>:/W4>
35
)
36

37
target_link_libraries(mylib
38
    PUBLIC
39
        Threads::Threads
40
)
41

42
# ========== 安装 ==========
43
include(GNUInstallDirs)
44
install(TARGETS mylib
45
    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
46
    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
47
)
48
install(DIRECTORY include/mylib
49
    DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
50
)

展开收起

🏁 总结#

现代 CMake 的核心理念是基于目标的依赖管理，通过精确控制每个目标的依赖可见性，实现：

权限最小化 - 只暴露必要的接口
编译效率最大化 - 减少不必要的重编译
依赖关系清晰 - 从 CMakeLists.txt 一目了然
可移植性强 - 使用导入目标，避免硬编码路径
易于维护 - 模块化设计，职责明确

记住核心原则：能用 target_ 就不用全局命令，能明确指定可见性就不用默认值*。

更多 C++ 开发经验分享，欢迎访问我的博客 xutopia77 - 见字如面。