Qt 最佳实践

project/ ├── CMakeLists.txt # 或 .pro 文件 ├── src/ # 源文件 ├── include/ # 公共头文件（如果被其他模块使用） ├── ui/ # .ui 文件 ├── resources/ # .qrc 资源文件及图标 ├── tests/ # 单元测试 └── README.md

### 1.2 优先使用 CMake

虽然 `qmake` 仍然可用，但 Qt 官方已明确推荐 CMake 作为默认构建系统。CMake 提供更好的模块化支持，且更容易与持续集成（CI）系统集成。一个最小的 `CMakeLists.txt` 示例：

```cmake
cmake_minimum_required(VERSION 3.16)
project(MyApp VERSION 1.0 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_AUTOMOC ON)

find_package(Qt6 REQUIRED COMPONENTS Widgets)

add_executable(MyApp
    src/main.cpp
    src/mainwindow.cpp
)

target_include_directories(MyApp PRIVATE include)
target_link_libraries(MyApp PRIVATE Qt6::Widgets)

1.3 减少头文件依赖

在头文件中尽可能使用前向声明（forward declaration），避免包含其他头文件，可以有效缩短编译时间。

// mainwindow.h
#include <QMainWindow>

class QLabel;      // 前向声明
class QPushButton;

class MainWindow : public QMainWindow
{
    Q_OBJECT
public:
    explicit MainWindow(QWidget *parent = nullptr);

private:
    QLabel *m_statusLabel;
    QPushButton *m_button;
};

2. 内存管理与对象生命周期

2.1 充分利用 Qt 的对象树

Qt 的对象树机制使得父对象被销毁时，其所有子对象也会被自动回收。因此，只要为堆上分配的对象指定一个合适的父对象，就能避免手动 delete 带来的风险。

auto button = new QPushButton("Click Me", this);  // this 作为父对象
auto layout = new QVBoxLayout(this);

2.2 谨慎使用裸指针

对于非 Qt 对象或生命周期不明确的对象，应优先使用智能指针（std::unique_ptr、std::shared_ptr）。尤其是在容器中存储对象时，可以考虑 std::vector<std::unique_ptr<MyClass>>。

2.3 避免在构造函数中过度操作

对象的构造函数应尽量简短，不要做可能抛出异常或长时间阻塞的操作。Qt 对象的初始化通常放在 init() 方法中，由调用方显式调用。

3. 信号与槽的现代用法

3.1 使用新式语法

Qt5 引入的基于函数指针的信号槽语法具有编译期类型检查的优势，可及早发现拼写错误和参数不匹配。

// 旧式语法（不推荐）
connect(sender, SIGNAL(valueChanged(int)), receiver, SLOT(updateValue(int)));

// 新式语法（推荐）
connect(sender, &Sender::valueChanged, receiver, &Receiver::updateValue);

3.2 利用 Lambda 表达式

对于简单逻辑，可以直接连接 Lambda，减少额外的槽函数定义：

connect(button, &QPushButton::clicked, this, [this]() {
    m_statusLabel->setText("Button clicked");
});

如果需要断开连接，可以将 QMetaObject::Connection 保存起来。

3.3 明确连接类型

默认情况下，如果发送者和接收者在同一线程，Qt 会使用 Qt::DirectConnection；否则使用 Qt::QueuedConnection。在多线程环境下，显式指定连接类型可以提高代码可读性：

connect(worker, &Worker::finished, this, &MainWindow::onFinished,
        Qt::QueuedConnection);

3.4 避免信号槽循环

确保信号链不会形成闭环，否则可能导致无限递归或意外行为。可以使用 QSignalBlocker 临时阻止信号发送。

4. 用户界面设计

4.1 分离界面与业务逻辑

无论是使用 QWidget 还是 QML，都应该将业务逻辑封装在独立的类（如 Model、ViewModel）中，让 UI 层只负责展示和交互转发。对于小项目可使用“被动视图”模式，大型项目建议采用 Model-View-Delegate 或 MVVM 架构。

4.2 合理使用布局管理器

避免绝对定位，使用 QHBoxLayout、QVBoxLayout 和 QGridLayout 等布局类，以支持屏幕缩放与多语言文本长度变化。通过设置 sizePolicy 和拉伸因子来微调空间分配。

4.3 用样式表进行轻量级定制

对于简单的主题修改，Qt 样式表（QSS）比重载 paintEvent 更加便捷，但不宜过度使用，大量样式表会影响渲染性能。复杂的自定义外观应使用 Qt Quick 或自绘控件。

4.4 遵循平台设计规范

使用 QStyle 获得原生外观，除非有明确的定制需求。利用 Q_OS_MAC、Q_OS_WIN 等宏来定制平台特有行为，并尽量用 QStandardPaths 获取标准路径。

5. 多线程编程

5.1 使用 QThread 的正确姿势

不要子类化 QThread，而是为工作对象创建一个 QObject 子类，然后将其移动到新线程中：

auto worker = new Worker;
auto thread = new QThread(this);
worker->moveToThread(thread);

connect(thread, &QThread::started, worker, &Worker::doWork);
connect(worker, &Worker::finished, thread, &QThread::quit);
connect(thread, &QThread::finished, worker, &QObject::deleteLater);
thread->start();

5.2 优先使用 QtConcurrent 与线程池

对于并行计算任务，QtConcurrent::run() 和 QThreadPool 是更简洁的选择，能自动管理线程数量。

QFuture<int> future = QtConcurrent::run([]() {
    return heavyComputation();
});

然后用 QFutureWatcher 监测结果，并通过信号槽通知主线程。

5.3 GUI 线程规则

所有与窗口、控件相关的操作必须在主线程执行。跨线程更新 UI 时，使用信号槽（Qt::QueuedConnection）或 QMetaObject::invokeMethod。

6. 性能优化

6.1 延迟初始化与可视区域加载

使用 QStackedWidget 时，只在页面首次可见时才创建其内容；列表控件（如 QListView）配合 Model 会自动处理视图区域外的数据，无需一次性加载全部项。

6.2 减少不必要的重绘与事件处理

通过设置 setAttribute(Qt::WA_StaticContents) 或使用 QWidget::setUpdatesEnabled(false) 暂时冻结更新。在自定义 paintEvent 中，只重绘 event->region() 限定的区域。

6.3 使用隐式共享与高效容器

Qt 的许多类（如 QString、QByteArray、QImage、QMap）都使用隐式共享（copy-on-write），传递值时很高效。避免无谓的深拷贝，尽量采用 const 引用。

6.4 数据库操作

使用 QSqlQuery::prepare() 和绑定值，而不是拼接 SQL 字符串，既可防止注入攻击，又能提升执行计划缓存效率。对于大量数据插入，使用事务包围：

db.transaction();
for (auto &data : dataList) {
    query.addBindValue(data);
    query.exec();
}
db.commit();

7. 调试与测试

7.1 使用 Qt 的日志系统

用 qDebug()、qWarning()、qCritical() 代替 std::cout，可通过 qInstallMessageHandler 自定义输出格式并写入文件。

7.2 启用编译警告与静态分析

在 CMake 中开启高等级警告（-Wall -Wextra），并建议使用 Clang-Tidy 或 Clazy（针对 Qt 的静态分析器）检查常见错误。

7.3 编写单元测试

使用 Qt Test 框架编写测试用例，覆盖信号槽连接、模型逻辑、文件操作等关键路径。保持测试的独立性，每个测试函数应清理所有状态。

8. 部署与打包

8.1 使用 windeployqt / macdeployqt

Qt 提供了自动复制所需动态库和插件到可执行文件目录的工具。在构建后运行：

windeployqt release/MyApp.exe
macdeployqt MyApp.app