【C++/Qt】Qt 实现 POP3/IMAP 邮件测试工具：连接邮箱服务器、登录与读取邮件

本文基于 C++/Qt 实现一个 POP3/IMAP 邮件测试工具，支持选择邮件协议、连接邮箱服务器、登录邮箱账号、读取指定邮件、显示通信日志和邮件内容。本文重点不是堆代码，而是从 POP3/IMAP 的基本概念出发，讲清楚邮件接收协议的实现思路，以及如何使用 QSslSocket 完成加密连接、命令发送、响应解析和状态控制。

一、POP3/IMAP 是什么？为什么收邮件有两种协议？

平时使用邮箱时，其实涉及两类协议：

复制代码

SMTP：负责发邮件
POP3 / IMAP：负责收邮件、读取邮件

这篇文章主要讨论的是 POP3 和 IMAP，也就是"如何从邮箱服务器读取邮件"。

可以先这样简单理解：

复制代码

POP3：更像是把邮件从服务器下载下来
IMAP：更像是在线查看和管理服务器上的邮箱

POP3 的特点是比较简单，常见操作就是：

复制代码

连接服务器
输入账号
输入密码或授权码
读取第几封邮件
退出

它适合做一个简单的"读取邮件内容"测试工具。

IMAP 相比 POP3 更复杂一些，它不仅能读取邮件，还更适合管理邮箱，例如选择收件箱、读取邮件头、同步邮件状态等。

两者可以这样对比：

复制代码

POP3：流程简单，适合下载邮件
IMAP：功能更完整，适合在线管理邮箱

在当前邮件测试模块中，界面支持在 POP3 和 IMAP 之间切换。默认 POP3 使用 pop.qq.com:995，IMAP 使用 imap.qq.com:993，并且密码输入框提示 QQ 邮箱建议填写授权码。代码中也使用了 QSslSocket，说明这个模块主要面向加密端口连接。

二、实现邮件测试工具前，先构思界面和整体流程

写 POP3/IMAP 工具之前，先不要急着写协议命令，而是先想清楚：用户测试邮箱时，需要输入什么？又需要看到什么？

基本功能可以设计成这样：

复制代码

选择协议：POP3 或 IMAP
填写服务器地址和端口
填写邮箱账号和授权码/密码
点击连接服务器
点击登录邮箱
输入邮件编号
读取指定邮件
显示邮件内容和通信日志

所以界面上至少需要这些控件：

复制代码

协议选择框：POP3 / IMAP
服务器地址输入框：pop.qq.com / imap.qq.com
端口输入框：995 / 993
邮箱账号输入框
密码或授权码输入框
邮件序号输入框
连接、登录、读取、断开、清空、复制按钮
日志显示区
邮件内容显示区

从程序结构上看，这个模块最核心的不是某一个按钮，而是"状态控制"。

因为邮件协议不是一次请求就结束，而是一步一步来的：

复制代码

未连接
  ↓
正在连接
  ↓
已连接，等待服务器问候
  ↓
登录中
  ↓
已登录
  ↓
读取邮件
  ↓
断开连接

所以类里面需要保存当前连接状态、登录状态和协议状态。当前实现中定义了 MailProtocol 区分 POP3/IMAP，又定义了 MailState 表示连接、登录、读取、退出等不同阶段，同时使用 QSslSocket、接收缓冲区、日志缓存和 IMAP 标签序号来管理整个邮件测试流程。

可以简化理解为：

cpp 复制代码

当前是 PopUser 状态：说明 USER 命令已经发出去了，下一步应该等服务器回复后再发 PASS
当前是 PopRetr 状态：说明正在读取邮件正文，要等待完整多行响应
当前是 ImapLogin 状态：说明正在等待 IMAP 登录结果

cpp 复制代码

private:
    // SSL Socket，用于连接 POP3/IMAP 加密端口
    QSslSocket *m_socket = nullptr;

    // 接收缓冲区，保存服务器返回的数据
    QByteArray m_buffer;

    // 当前是否已经连接服务器
    bool m_connected = false;

    // 当前是否已经登录邮箱
    bool m_loggedIn = false;

    // 当前邮件协议状态，用来判断下一步该做什么
    MailState m_state = MailState::Idle;

    // IMAP 命令标签序号，例如 A001、A002
    int m_imapTagIndex = 1;

这里最关键的是 m_state。

它就像一个"流程标记"，告诉程序当前处在哪一步。

比如：

cpp 复制代码

当前是 PopUser 状态：说明 USER 命令已经发出去了，下一步应该等服务器回复后再发 PASS
当前是 PopRetr 状态：说明正在读取邮件正文，要等待完整多行响应
当前是 ImapLogin 状态：说明正在等待 IMAP 登录结果

没有这个状态标记，程序收到服务器返回的数据时，就不知道该把这段数据当成登录结果、邮件内容，还是退出响应。

三、为什么使用 QSslSocket？连接和登录是两回事

邮件服务器通常涉及账号和密码，所以不能像普通 TCP 一样直接明文传输。为了安全，常用的是 SSL 加密端口：

cpp 复制代码

POP3 SSL：通常使用 995
IMAP SSL：通常使用 993

所以当前实现中使用的是 QSslSocket，并通过：

cpp 复制代码

m_socket->connectToHostEncrypted(host, port);

连接服务器。

这句代码的意思是：
连接指定邮件服务器，并建立 SSL 加密通道。

但是要注意一个很重要的点：

cpp 复制代码

SSL 连接成功，不代表邮箱登录成功。

邮件测试工具的流程应该分成两层：

cpp 复制代码

第一层：网络连接成功
第二层：协议登录成功

比如 POP3 的完整流程大概是：

cpp 复制代码

连接 pop.qq.com:995
        ↓
SSL 握手成功
        ↓
服务器返回 +OK 问候语
        ↓
发送 USER 邮箱账号
        ↓
发送 PASS 授权码
        ↓
服务器返回 +OK，才算登录成功

IMAP 也是类似：

cpp 复制代码

连接 imap.qq.com:993
        ↓
SSL 握手成功
        ↓
服务器返回问候语
        ↓
发送 LOGIN 命令
        ↓
服务器返回 A001 OK，才算登录成功

所以代码中连接按钮只负责建立 SSL 连接：

cpp 复制代码

void FormMailTester::onConnectClicked()
{
    // 读取服务器地址和端口
    const QString host = ui->lineEdit_MailHost->text().trimmed();
    const int port = ui->spinBox_MailPort->value();

    // 清空旧数据，重置状态
    m_buffer.clear();
    m_state = MailState::Connecting;
    m_connected = false;
    m_loggedIn = false;

    // 建立 SSL 加密连接
    m_socket->connectToHostEncrypted(host, port);
}

连接成功后，程序会等待服务器返回问候语。收到服务器数据时，统一进入 onReadyRead()：

cpp 复制代码

void FormMailTester::onReadyRead()
{
    // 读取服务器返回的数据，先放到缓冲区
    m_buffer.append(m_socket->readAll());

    // 根据当前协议，选择不同的解析方式
    if (currentProtocol() == MailProtocol::POP3) {
        processPop3Data();
    } else {
        processImapData();
    }
}

这个设计比较清晰：
QSslSocket 只负责底层数据收发，真正怎么解释这些数据，要交给 POP3 或 IMAP 的处理函数。

四、POP3 实现思路：命令简单，重点是按行解析和多行结束符

POP3 的命令比较直观，适合先实现。

常见命令如下：

cpp 复制代码

USER 邮箱账号
PASS 授权码或密码
RETR 邮件编号
QUIT

服务器返回结果一般是：

cpp 复制代码

+OK   表示成功
-ERR  表示失败

比如登录流程可以这样理解：

cpp 复制代码

客户端：USER xxx@qq.com
服务器：+OK

客户端：PASS 授权码
服务器：+OK 登录成功

读取邮件时：

cpp 复制代码

客户端：RETR 1
服务器：返回第 1 封邮件内容

这里 POP3 有一个需要注意的地方：

普通响应是一行一行返回的，但是邮件正文可能是多行的。

POP3 多行响应一般以这一段作为结束标志：

cpp 复制代码

\r\n.\r\n

也就是说，程序读取邮件内容时，不能看到一点数据就立刻显示，而是要等到完整邮件内容接收完。

当前实现中就是这样判断的：

cpp 复制代码

// 判断 POP3 多行响应是否完整
bool FormMailTester::hasPop3MultiLineFinished() const
{
    return m_buffer.contains("\r\n.\r\n");
}

整个 POP3 处理思路可以概括为：

cpp 复制代码

连接阶段：等待服务器 +OK 问候
登录阶段：先发 USER，再发 PASS
读取阶段：发送 RETR 邮件编号
解析阶段：等待多行响应结束符
退出阶段：发送 QUIT

代码里通过状态判断下一步该做什么：

cpp 复制代码

if (m_state == MailState::PopUser) {
    // USER 成功后，继续发送 PASS
    sendLine("PASS " + ui->lineEdit_MailPassword->text());
} else if (m_state == MailState::PopPass) {
    // PASS 成功后，说明 POP3 登录成功
    setLoggedInState(true);
} else if (m_state == MailState::PopRetr) {
    // RETR 阶段要等待完整邮件内容
    showMailContent(content);
}

所以 POP3 的实现重点不是命令有多复杂，而是要清楚它的顺序：

cpp 复制代码

服务器问候 → USER → PASS → RETR → QUIT

只要状态控制清楚，POP3 就比较容易跑通。

五、IMAP 实现思路：命令带标签，登录后先选择邮箱再读取

IMAP 比 POP3 稍微复杂一点，因为 IMAP 命令前面通常会带一个"标签"。

比如：

cpp 复制代码

A001 LOGIN "xxx@qq.com" "授权码"
A002 SELECT INBOX
A003 FETCH 1 BODY.PEEK[HEADER]
A004 LOGOUT

这里的 A001、A002、A003 就是 IMAP 标签。

为什么需要标签？

因为 IMAP 支持更复杂的命令交互，服务器返回时也会带回对应标签。这样客户端就能知道：这次返回结果对应的是哪一条命令。

比如：

cpp 复制代码

客户端：A001 LOGIN "xxx@qq.com" "授权码"
服务器：A001 OK LOGIN completed

看到 A001 OK，程序就知道 A001 这条登录命令完成了。

当前实现中用 nextImapTag() 生成标签：

cpp 复制代码

// 生成 IMAP 命令标签，例如 A001、A002、A003
QString FormMailTester::nextImapTag()
{
    return QString("A%1").arg(m_imapTagIndex++, 3, 10, QChar('0'));
}

IMAP 登录成功后，还不能马上读取邮件，一般要先选择邮箱目录，例如收件箱：

cpp 复制代码

SELECT INBOX

所以 IMAP 的整体流程是：

cpp 复制代码

连接 IMAP 服务器
        ↓
等待服务器问候
        ↓
发送 LOGIN
        ↓
登录成功后发送 SELECT INBOX
        ↓
选择收件箱成功后发送 FETCH
        ↓
显示邮件内容
        ↓
发送 LOGOUT 退出

当前实现中读取邮件使用的是：

cpp 复制代码

FETCH 邮件编号 BODY.PEEK[HEADER]

也就是说，它主要读取邮件头信息，而不是完整正文。这样做比较轻量，适合先验证 IMAP 登录和读取流程是否正常。登录、选择 INBOX、FETCH 和 LOGOUT 等流程在 processImapData() 中通过当前命令标签和状态进行判断处理。

IMAP 的处理思路可以简单总结为：

cpp 复制代码

每发一条命令，都带一个标签
收到响应后，检查当前标签是否出现 OK / NO / BAD
如果是 OK，说明当前命令成功
如果是 NO 或 BAD，说明命令失败

比如程序判断命令是否完成，大致就是这个思路：

cpp 复制代码

// 判断当前 IMAP 命令是否已经返回最终结果
const bool commandFinished =
    text.contains(m_currentImapTag + " OK") ||
    text.contains(m_currentImapTag + " NO") ||
    text.contains(m_currentImapTag + " BAD");

这里体现了 IMAP 和 POP3 的一个核心区别：

cpp 复制代码

POP3：主要看 +OK / -ERR
IMAP：主要看 当前标签 + OK / NO / BAD

所以 IMAP 的代码不是单纯读一行，而是要围绕"标签"和"状态"来判断当前命令是否结束。

总结

POP3/IMAP 邮件测试工具的核心，不是界面有多少按钮，也不是代码写得多复杂，而是要理解邮件接收协议的流程。

整体实现思路可以概括为：

cpp 复制代码

1. POP3 和 IMAP 都是用于接收邮件的协议
2. POP3 更简单，适合按编号下载邮件
3. IMAP 更完整，适合在线管理邮箱和读取指定邮箱目录
4. 使用 QSslSocket 连接加密端口，保护账号和授权码
5. 连接成功不等于登录成功，需要继续发送协议命令
6. POP3 通过 USER、PASS、RETR、QUIT 完成读取流程
7. IMAP 通过 LOGIN、SELECT INBOX、FETCH、LOGOUT 完成读取流程
8. 程序需要通过状态机判断当前处于连接、登录、读取还是退出阶段

从代码结构上看，几个关键函数可以这样理解：

cpp 复制代码

initUi()：初始化协议选择、账号输入、端口和显示区域
onConnectClicked()：建立 SSL 连接
onLoginClicked()：根据 POP3/IMAP 发送不同登录命令
onFetchClicked()：根据协议读取指定邮件
onReadyRead()：接收服务器返回数据
processPop3Data()：解析 POP3 响应
processImapData()：解析 IMAP 响应
sendLine()：统一发送邮件协议命令
setConnectedState() / setLoggedInState()：控制界面状态

需要注意的是，这个模块目前更适合做"基础邮件协议测试"：验证服务器是否能连接、账号是否能登录、指定邮件是否能读取。如果后续继续完善，可以再加入邮件正文 MIME 解码、中文标题解析、附件识别、邮件列表查询等功能。

对于网络调试助手来说，POP3/IMAP 模块补充的是"邮件接收协议测试能力"。HTTP 更偏接口请求，WebSocket 更偏实时通信，MQTT 更偏发布订阅，而 POP3/IMAP 则对应邮箱服务器读取邮件这一类应用场景。

0voice · GitHub