简介面向电子与嵌入式开发者的TCP调试助手安卓App基于Qt编写同时支持TCP客户端与服务器模式可用于网络通信调试、设备联调与服务器并发连接测试适合需要快速验证网络协议与排查通信问题的工程师。压缩包共38个文件大小约10.07MB包含cpp/h源码、pro工程文件、ui界面文件、qrc资源与css样式以及png图片、ttf字体和可直接安装的apk安装包目录结构清晰既便于阅读源码也方便直接部署运行。该资源已有1603人浏览学习。通过源码可了解Qt在Android平台下实现TCP通信的完整流程包括界面布局、服务器多客户端管理、循环发送策略、横屏适配等关键点能在此基础上扩展自定义功能是学习Qt网络编程与移动端调试工具开发的实用参考。1. 拿到“TCP调试助手源码(QT编写)”这包压缩包先弄清楚它解决什么问题串口调试助手大家都很熟但 TCP 报文一旦收发频繁、连接一断一重连能随手用的调试工具就没那么多。标题带“(QT编写)”的 TCP 调试助手源码本质是一份用 Qt 跨平台框架写出的网络调试工具工程在同一个窗口里放进客户端、服务端、收/发、十六进制和 ASCII 显示。它要解决的不只是“能发能收”而是连接状态不透明、断线原因看不清、二进制帧拆不开、日志没有时间戳这四类问题。对于要对接 Modbus TCP、PLC、工业相机或自研协议的工程师这类源码最合适的用法不是装完就跑而是把收发骨架抽出来改成自己的协议帧。2. TCP调试助手源码的核心模块从 QTcpSocket 到收发缓冲区2.1 调试助手和串口调试助手的不同点在哪里串口调试助手的模型是设置串口号、波特率、数据位打开后就把串口当成一根管子收发。TCP 调试助手虽然界面长得像底层变化很大连接建立前要经过 TCP 三次握手建立后数据是按流进来的没有串口那种“设备一帧”的边界。所以代码里真正该关心的不是“发送按钮怎么触发”而是 QTcpSocket 的状态从 Unconnected 走到 Connected 再回到 Unconnected 的完整路径以及 readyRead 信号触发时如何从内核缓冲区读出数据。连接状态这块是很多自写 TCP 调试工具做不明白的地方。串口打开失败通常会立刻报错而 TCP 的 connectToHost 是非阻塞的调用完只是个“开始连接”的动作结果要通过 connected、errorOccurred、disconnected 这三个信号去收。源码里如果只写了一个线程塞住等 connect 返回十有八九会在界面线程里把事件循环卡死。正确做法是让 socket 自己上报状态界面只做状态刷新。2.2 源码类怎么拆连接封装、接收缓冲、协议解析解压出来的源码不管叫什么名字我建议先按三个责任区去读QMainWindow 承担输入和显示一个连接类封装 QTcpSocket 和接收缓冲一个协议解析类把 QByteArray 切成完整报文。把这三个混在一起是最常见的改造失误一旦要加心跳或重连逻辑就全堆在一个槽函数里。下面是连接类里最容易出现的接收骨架void TcpConnection::handleReadyRead() { // readAll() 会一次性取出当前内核缓冲区可读的数据 m_buffer.append(m_socket-readAll()); while (true) { int frameLen frameLength(m_buffer); if (frameLen 0) // 数据不完整等下一次 readyRead break; QByteArray frame m_buffer.left(frameLen); m_buffer.remove(0, frameLen); emit frameReceived(frame); } }这段代码的关键是 m_buffer 不能被清空。TCP 的 readyRead 什么时候触发由内核决定一个完整的报文可能被拆成两个 readyRead 到达两个报文也可能粘在一次 readyRead 里。frameLength 的返回值有三种约定-1 表示等更多数据0 表示帧头或长度字段非法大于 0 表示这一帧的总长度。等下一次 readyRead 时m_buffer 里还留着上一次没消费完的字节。典型源码的类结构可以按下表去对号入座组件常见位置最容易写坏的地方UI 层MainWindow、Dialog把 socket 收发直接写进按钮槽函数连接层TcpClient、TcpServer生命周期错乱socket 销毁后信号仍被触发协议层FrameParser、Protocol只处理完整帧不处理残帧和粘帧日志层LogWidget、FileLogger时间戳缺失无法复现问题2.3 收数据时为什么不能写耗时操作readyRead 信号默认是在 socket 所属线程的事件循环里触发的。大多数调试助手的 socket 都建立在 UI 线程所以只要你在 readyRead 里做 CRC 校验、正则匹配、数据库写入、界面刷新这些事就会拖住 Qt 的事件循环。表现是收包一快发送按钮反应变慢界面像是卡住。要把解析和显示拆开常见做法是让 handleReadyRead 只负责把字节放进缓冲区并切帧然后通过队列信号把完整的 frame 交给另一个对象。跨线程时注意连接方式信号槽自动使用 Qt::QueuedConnection但帧的发送方和接收方必须分属不同线程。不要在一个槽函数里既解析协议又刷新 QTextEdit这两个动作的频率完全不同。3. 最小可跑通的 Qt TCP 调试助手客户端与服务端骨架代码3.1 先写客户端connectToHost、abort 与四个信号一个能交互的 TCP 客户端至少要有地址、端口、连接按钮、发送框和接收区。核心对象是 QTcpSocket完整流程可以用下面这段精简代码表达TcpClient::TcpClient(QObject *parent) : QObject(parent), m_socket(new QTcpSocket(this)) { connect(m_socket, QTcpSocket::connected, this, [this]() { QString peer m_socket-peerAddress().toString(); quint16 port m_socket-peerPort(); emit stateChanged(QString(connected %1:%2).arg(peer).arg(port)); }); connect(m_socket, QTcpSocket::disconnected, this, [this]() { emit stateChanged(disconnected); }); connect(m_socket, QTcpSocket::errorOccurred, this, [this](QAbstractSocket::SocketError) { emit errorString(m_socket-errorString()); }); } void TcpClient::connectTo(const QString host, quint16 port) { m_socket-abort(); // 结束上一次未完成的连接状态 m_socket-connectToHost(host, port); } void TcpClient::sendData(const QByteArray data) { if (m_socket-state() ! QAbstractSocket::ConnectedState) return; m_socket-write(data); }connectToHost 是异步的调用后立刻返回。abort 的作用是清掉之前可能残留的连接再把状态机重置到 Unconnected。write 也不是直接写进网卡而是交给 Qt 内部写缓冲区实际发送由事件循环调度。所以不要写一帧数据后马上 close那会丢数据。errorOccurred 只负责上报错误原因客户端是否还活着要看 connected 和 disconnected。3.2 服务端QTcpServer 的每连接一个 socket 模式服务端代码比客户端多一点因为每个客户端都对应一个独立的 QTcpSocketvoid TcpServer::onNewConnection() { while (m_server-hasPendingConnections()) { QTcpSocket *s m_server-nextPendingConnection(); connect(s, QTcpSocket::readyRead, this, [this, s]() { QByteArray data s-readAll(); emit dataReceived(s-peerPort(), data); }); connect(s, QTcpSocket::disconnected, s, QObject::deleteLater); emit clientConnected(s-peerAddress().toString(), s-peerPort()); } }nextPendingConnection 从已经完成三次握手的内核队列里取一个 socket。每个连接必须单独 connect readyRead不能像 QTcpServer 那样共用一个信号。disconnected 之后用 deleteLater 而不是 delete是因为当前可能还处在信号处理上下文中立刻 delete 会留下悬空的 receiver。服务器端要限制最大连接数最简单的办法是在这个函数里维护一个 QList超过阈值就主动 disconnectFromHost。3.3 常用参数表地址、端口、超时、缓冲区参数或 API说明注意点connectToHost(host, port)发起异步 TCP 连接返回后不等于连接成功abort()立即断开并释放连接不发送 FIN 包直接重置disconnectFromHost()等待输出缓冲写完后断开适合主动结束业务连接waitForConnected(ms)阻塞等待连接结果只能在非 UI 线程或测试代码里用peerPort()对方端口服务器端按端口区分连接来源errorString()人类可读错误不同平台返回文本不一致端口是 quint16不要用 int 硬塞。地址输入本来可能带空格或协议前缀调用前用 QHostAddress 做一次解析解析失败就不要发起连接。UI 上最常见的越界错误是把文本框里的值直接转整型没有做 1 到 65535 的钳制。4. 把 TCP 调试助手从“能收发”做到“能排错”粘包、十六进制、断线重连4.1 处理 TCP 半包和粘包按长度字段切帧TCP 是字节流协议发送方的两次 write 在接收方可能被合并成一次读出来也可能一次 write 被拆成两个 TCP 段。调试助手源码里如果没有专门的拆帧逻辑在局域网低负载下看起来“正常”一旦对端是真实设备帧边界就会乱。可靠做法是给每个业务帧定义固定头推荐格式2 字节魔数、2 字节负载长度、按需扩展。bool FrameParser::tryParse(QByteArray buf, QByteArray frame) { if (buf.size() 6) // 2魔数 2长度 2校验 return false; const uchar *p reinterpret_castconst uchar *(buf.constData()); quint16 bodyLen qFromBigEndianquint16(p 2); int total 6 bodyLen; if (buf.size() total) return false; frame buf.left(total); buf.remove(0, total); return true; }qFromBigEndian 保证了在不同架构上读出的长度字段一致。解析时必须先把总长度算出来再判断 buf.size否则会拿一个不完整的帧做校验。这个函数要放在 while(true) 里循环调用因为一次 readAll 里可能包含多个完整帧。MODBUS TCP 报文头也用类似方式前 7 个字节里带 2 字节长度域你只需要把这里的魔数和长度偏移换成 MODBUS 的格式其余骨架不用改。4.2 十六进制视图与 ASCII 视图并存调试网络报文时十六进制视图和字符串视图缺一不可。接收区不能直接显示 QByteArray 的原生内容必须把每个字节映射成两个十六进制字符QString toHexView(const QByteArray raw) { QString out; out.reserve(raw.size() * 3); for (char c : raw) { uchar ch static_castuchar(c); out.append(0123456789ABCDEF[ch 4]); out.append(0123456789ABCDEF[ch 0xF]); out.append( ); } return out; }逐字节处理时先把 char 转成 uchar避免负数 char 右移后补满 1结果变成 FFFFFF。out.reserve 可以预分配空间高频收包时能减少 QString 反复扩容。对应的发送输入框要提供“hex 解析”开关常见写法是用 QRegularExpression 去掉空格后按每两个字符一组转字节不要直接用 fromHex 处理带空格的文本。4.3 断线重连、心跳与重试间隔真实设备不会一直在线调试助手源码里至少要有“重连”和“心跳”两个可配置项。只需要在 disconnected 里挂一个 QTimer::singleShot按指数退避方式重连void TcpClient::onDisconnected() { if (!m_reconnectEnabled) return; m_retryMs qMin(m_retryMs * 2, 15000); // 指数退避上限15秒 QTimer::singleShot(m_retryMs, this, [this]() { m_socket-connectToHost(m_host, m_port); }); } void TcpClient::onConnected() { m_retryMs 1000; // 连接成功恢复初值 }重连的坑在于 disconnected 可能在 connectToHost 还没完成时又触发导致两个 singleShot 排队。更稳妥的办法是记录当前重连定时器的 active 状态或者直接把重连逻辑收敛到一个 QTimer 里而不是每次都 new 一个一次性定时器。心跳可以用 QTimer 周期性发送自定义心跳包间隔一般取网络设备超时时间的三分之一TCP keepalive 在这些小工具里不要依赖超时时间由内核决定对应用层来说太不可控。配置项建议值原因连接超时35 秒局域网设备通常 1 秒内响应心跳间隔310 秒低于设备断链判定时间重连上限可配置或关闭防止日志刷爆单帧最大长度按协议设定防止非法长度让缓冲区涨上天5. 手改这套 TCP 调试助手源码时最容易踩的 Qt 细节5.1 连接状态只信 QAbstractSocket 枚举别信自己维护的 bool初学者喜欢在 connected 里置 true、disconnected 里置 false然后再用这个 bool 判断是否显示“已连接”。问题在于 TCP 状态跳变不只有这两条路connectToHost 失败、收到 RST、本端 abort 都会让状态直接跳回 Unconnected。源码改造时最好加一个函数做统一转换QString stateText(QAbstractSocket::SocketState s) { switch (s) { case QAbstractSocket::ConnectedState: return QStringLiteral(已连接); case QAbstractSocket::ConnectingState: return QStringLiteral(连接中); case QAbstractSocket::HostLookupState: return QStringLiteral(解析地址); default: return QStringLiteral(未连接); } }把这个函数接到 socket stateChanged 信号里再配合 peerAddress 和 peerPort 一起显示诊断连接问题时才不用反复打断点。看到一个状态不是 Connected 但又不是 Unconnected先看 HostLookup、Connecting、Closing 这三个中间态能少走很多弯路。5.2 日志落盘用 qInstallMessageHandler别堆内存调试助手一跑就是一整天内存里 QTextEdit 的 append 太多会越来越卡。常见做法是把套接字错误、重连动作、收发帧摘要都通过 qDebug 输出再用 qInstallMessageHandler 写进磁盘文件void installLogRedirect() { qInstallMessageHandler([](QtMsgType type, const QMessageLogContext ctx, const QString msg) { QFile log(QCoreApplication::applicationDirPath() /tcp_helper.log); if (log.open(QIODevice::Append | QIODevice::Text)) { QTextStream out(log); out QDateTime::currentDateTime() .toString(yyyy-MM-dd hh:mm:ss.zzz) [ type ] msg \n; } Q_UNUSED(ctx) }); }日志路径要放在 applicationDirPath 或用户数据目录别写到安装目录。如果把这个函数放在 main 开头调用后面所有 qDebug 都会自动落盘配合前面 stateText 的状态字符串就能把每次“连上、断线、又连上”的顺序完整拼出来。收到异常数据时把帧长度、对端端口和原始字节同时打一行日志重放现场会容易很多。本文还有配套的精品资源点击获取