3. QTcpServer基础：启动监听，拥抱连接

好，咱们今天来聊聊QTcpServer。这东西说白了，就是Qt网络编程里的“迎宾员”。你的程序想当服务器，就得靠它来接待客户端的连接请求。

我个人习惯把QTcpServer看作一个“连接工厂”。它不负责具体的数据收发，它的唯一使命就是：监听端口，然后当有客户端敲门时，给你创建一个全新的QTcpSocket，让你去跟这个客户端单独聊天。

3.1 QTcpServer类介绍

QTcpServer是Qt网络模块里的核心类。它封装了操作系统底层的socket监听机制。你不需要去碰那些复杂的select、poll、epoll，Qt全帮你搞定了。

它的主要职责就三件事：

• 监听：绑定一个IP地址和端口号，开始等待客户端连接。
• 接收：当有客户端连上来时，发出信号，并创建一个新的QTcpSocket。
• 管理：你可以通过它获取当前监听的地址和端口信息。

嗯，这里要注意，QTcpServer本身不是线程安全的。如果你要在多线程环境里用，得小心处理。我在项目中遇到过，有人直接在子线程里创建QTcpServer，结果信号死活连不上，就是因为没做线程上下文切换。

3.2 启动监听：listen()函数

启动监听是服务器端的第一步。你只需要调用一个函数：listen()。

它的签名很简单：

bool QTcpServer::listen(const QHostAddress &address = QHostAddress::Any, quint16 port = 0);

参数说明：

参数	说明
address	监听的IP地址。默认是QHostAddress::Any，表示监听所有网卡。
port	监听的端口号。如果传0，系统会自动分配一个可用端口。

返回值是bool类型。如果监听成功返回true，失败返回false。失败的原因通常是端口被占用，或者你没有权限。

来看个最简单的例子：

QTcpServer *server = new QTcpServer(this);
if (!server->listen(QHostAddress::Any, 8888)) {
    qDebug() << "监听失败:" << server->errorString();
    return;
}
qDebug() << "监听成功，端口:" << server->serverPort();

我曾经在项目里犯过一个低级错误：端口号写成了字符串"8888"，结果listen一直返回false。找了半天才发现，端口号是整数，不是字符串。你想想看，这种小坑是不是很气人？

3.3 处理新连接：newConnection信号

监听成功后，当有客户端连接进来时，QTcpServer会发射newConnection()信号。你需要把这个信号连接到一个槽函数，在槽函数里处理新来的客户端。

槽函数里，你需要调用nextPendingConnection()来获取这个新连接的QTcpSocket对象。

connect(server, &QTcpServer::newConnection, this, [=]() {
    QTcpSocket *clientSocket = server->nextPendingConnection();
    if (!clientSocket) return;
    
    qDebug() << "新客户端连接:" << clientSocket->peerAddress().toString();
    
    // 连接客户端的信号
    connect(clientSocket, &QTcpSocket::readyRead, this, [=]() {
        QByteArray data = clientSocket->readAll();
        qDebug() << "收到数据:" << data;
    });
    
    connect(clientSocket, &QTcpSocket::disconnected, this, [=]() {
        qDebug() << "客户端断开连接";
        clientSocket->deleteLater();
    });
});

这里有个细节：nextPendingConnection()返回的QTcpSocket对象，所有权归你。你需要负责管理它的生命周期。我一般会在disconnected信号里调用deleteLater()来安全地释放它。

为什么不用delete？因为deleteLater会等到事件循环返回后再删除，避免了在信号处理过程中直接释放对象可能引发的崩溃。说白了，就是更安全。

3.4 多客户端管理：别让客户端跑丢了

一个服务器通常要同时处理多个客户端。你不能只用一个QTcpSocket变量，因为新连接会覆盖旧连接。你需要一个容器来管理它们。

我个人习惯用QList或QHash来存储所有客户端socket。QHash的好处是你可以用客户端的IP或ID作为键，方便查找。

// 在类定义里
QList<QTcpSocket*> m_clients;

// 在newConnection槽函数里
QTcpSocket *clientSocket = server->nextPendingConnection();
m_clients.append(clientSocket);

// 在disconnected槽函数里
m_clients.removeOne(clientSocket);
clientSocket->deleteLater();

你想想看，如果不做管理，当客户端断开时，你都不知道该释放哪个socket。内存泄漏就是这么来的。

这里我画了一张图，帮你理清整个流程：

从这张图你能看到，QTcpServer就像个分发器。它不直接跟客户端通信，而是把每个客户端封装成一个QTcpSocket，然后交给你去管理。你用一个QList把它们存起来，就可以统一处理了。

3.5 广播消息：给所有客户端发数据

很多时候，你需要给所有连接的客户端发送同一条消息。比如聊天室里的广播功能。实现起来很简单：

void broadcastMessage(const QByteArray &message) {
    for (QTcpSocket *client : m_clients) {
        if (client->state() == QAbstractSocket::ConnectedState) {
            client->write(message);
            client->flush();
        }
    }
}

这里有个坑：write()只是把数据写入发送缓冲区，并不保证立即发送。如果你需要确保数据立刻发出去，可以调用flush()。但频繁调用flush会影响性能，我一般只在需要实时性的时候才用。

3.6 停止监听：close()函数

当服务器要关闭时，调用close()即可。它会停止监听，但不会关闭已有的客户端连接。

server->close();  // 停止接受新连接
qDebug() << "服务器停止监听";

如果你想彻底关闭服务器，包括断开所有客户端，你需要遍历客户端列表，逐个调用disconnectFromHost()或abort()。

// 优雅关闭所有客户端
for (QTcpSocket *client : m_clients) {
    client->disconnectFromHost();
    if (client->state() != QAbstractSocket::UnconnectedState) {
        client->waitForDisconnected(1000);  // 最多等1秒
    }
}

嗯，这里要注意，waitForDisconnected()会阻塞当前线程。如果你在UI线程里调用，界面可能会卡住。我一般会在关闭服务器时，先断开所有客户端，然后让它们自己慢慢断开，不阻塞主线程。

好了，QTcpServer的基础用法就这些。说白了，就是三步：listen监听、newConnection接客、容器管理。掌握了这三步，你就能搭建一个基本的TCP服务器了。

可可精品资料库