Day 31：PIMPL 模式（Pointer to Implementation）

PIMPL（Pointer to IMPLementation，指向实现的指针），业界也叫 d-pointer（d 指针）或者更直白地叫 编译防火墙（Compilation Firewall）。它只做一件事：把一个类的全部私有数据成员和实现细节，整体搬进一个「在头文件里只有前置声明、在 .cpp 文件里才有完整定义」的私有实现类（通常命名为 XxxPrivate 或 Xxx::Impl）中；公开类自身只剩下两样东西——一个指向实现类的指针，以及那些不会随实现变化的公有函数签名。

如果你是从 Web 前端转过来的，可以这样理解：PIMPL 之于 C++ 头文件，相当于 TypeScript 的 .d.ts 声明文件之于实现。你发布给别人的只有声明，实现藏在另一个文件里；调用方永远看不到你内部用了什么库、什么数据结构，也就永远不需要因为你换了一个内部字段而重新编译。

先看一段几乎没有 C++ 程序员没写过的「无模式」坏代码：

// ❌ 反面教材：把实现细节全部摊在头文件里的 NetworkClient
// networkclient.h
#pragma once

#include <QTcpSocket>        // 重量级头文件：只为声明一个成员
#include <QTimer>
#include <QJsonDocument>
#include <queue>
#include <mutex>
#include <string>

class NetworkClient : public QObject {
    Q_OBJECT
public:
    explicit NetworkClient(QObject *parent = nullptr);
    void send(const QByteArray &data);
    bool isConnected() const;

private:
    QTcpSocket socket;                  // 实现细节完全暴露
    QTimer heartbeatTimer;              // 想换成 QNetworkAccessManager？所有客户重编译
    std::queue<QByteArray> pending;
    std::mutex mtx;
    int retryCount = 0;
    std::string lastError;              // 用 std::string 还是 QString？这是实现选择
};

这段代码能跑，但它在工程上埋了四颗雷：

1. 编译耦合（最致命）。networkclient.h 被 200 个 .cpp 文件 include。你只是把 std::string lastError 改成 QString lastError，或者在 private 里加一个 int m_failCount，这 200 个文件全部要重新编译——哪怕它们谁都没碰过 lastError。更糟的是 include 传染：QTcpSocket 会拖进 QAbstractSocket → QIODevice → QObject → 一大串平台相关头文件。一个「客户端类」的头文件，最终把半个 Qt 网络栈塞进了每一个用到它的编译单元。大型 Qt 项目里，全量重编译动辄几十分钟，绝大部分时间都花在这种无意义的传染上。

2. ABI 脆弱（二进制兼容）。C++ 的对象布局是「编译期烧死」在客户代码里的：客户编译时认为 sizeof(NetworkClient) == 64，就在栈上按 64 字节分配、按固定偏移取成员。哪天你加了一个成员，库里的对象变成 80 字节，而客户程序还在按 64 字节操作——内存越界、踩踏、随机崩溃，而且这种 bug 极难定位。这就是为什么 Linux 发行版和 Qt 都把「二进制兼容性」当红线：Qt 敢承诺「同一个大版本内升级小版本不用重新编译你的程序」，正是因为它所有公有类都是 PIMPL 的——公有类的 sizeof 永远等于「一个虚表指针 + 一个 d_ptr」，加多少私有成员，客户看到的尺寸都不变。

3. 信息泄露。private 只是编译器的访问控制，不是信息隐藏。任何人打开头文件，就能知道你内部用了 QTcpSocket、用了 std::mutex、用了 std::queue。对商业库来说，这等于把设计图纸贴在门口；对团队协作来说，别人会忍不住依赖你的内部细节（「反正 m_retryCount 是 public-ish 的，我 hack 一下」）。

4. 违背 SOLID。 ①单一职责：一个头文件同时承担了「对外接口契约」和「内部数据结构说明书」两种职责； ②依赖倒置：客户模块在编译期被迫依赖 QTcpSocket/QJsonDocument 这些低层实现细节（哪怕它一行都没调用），高层模块依赖了低层实现； ③开闭原则：把传输层从 TCP 换成 WebSocket 本应是一次「扩展」（新实现），结果却要改动头文件，导致所有使用者重新编译——这就是「对修改关闭」被打破； ④可测试性：单元测试想验证 send() 的重试逻辑，就必须链接真实网络栈，不能塞一个假的实现进去。

PIMPL 用一个指针、一次堆分配，把这四颗雷一次性拆掉。

生活类比：餐厅菜单与后厨。菜单（头文件）上只写「宫保鸡丁 38 元」——这是你承诺给顾客的稳定契约。后厨用什么牌子的灶、几口锅、厨师是不是换了人、今天是不是改用电磁炉（实现细节），顾客完全不需要知道，也不需要因此重新印一份菜单。菜单上如果印上「本菜使用 XX 牌 30cm 铸铁炒锅、灶台功率 5kW」，那后厨一换设备就得全国门店重印菜单——这就是把实现细节写进头文件的代价。PIMPL 做的事，就是把菜单上的锅具参数全部删掉，只在菜单背面钉一个写着「详见后厨手册第 N 页」的便签（d_ptr）。

补充类比：遥控器与电视。遥控器上按键位置固定（稳定的公有接口），电视机内部从 CR 管换成 LCD 再换成 OLED（实现演进），你手里的遥控器一直能用。PIMPL 让「接口的稳定性」和「实现的可变性」彻底解耦——这是它的全部价值，没有别的玄机。

用一句话概括实现手法：把「数据」从「对象」里拆出去，对象只剩「身份（identity）+ 行为入口（函数签名）+ 一个指向数据的指针」。C++ 里对象的 sizeof 和内存布局由数据成员决定，所以只要数据成员不在公有类里，公有类的尺寸和布局就永远不会因为实现变化而变。

       客户代码 (Client)
            │  只 include 头文件，看不到任何实现细节
            ▼
   ┌───────────────────────────────┐
   │      SettingsManager          │  ← 角色1：稳定接口（Owner / Facade）
   │───────────────────────────────│
   │ + value()   + setValue()      │     公有函数签名 = 对外契约
   │ + keys()    + sync()          │
   │───────────────────────────────│
   │ - d_ptr ─────────────────┐    │  ← 角色3：d-pointer（唯一私有成员）
   └──────────────────────────┼────┘
                              │  独占持有（unique_ptr / 裸指针 + delete）
                              ▼
   ┌───────────────────────────────┐
   │   SettingsManagerPrivate      │  ← 角色2：真实实现（定义在 .cpp 中）
   │───────────────────────────────│
   │ - q_ptr  ─────────────────────┼──→ 反向指回 Owner（可选，Q_Q 模式）
   │ - settings : QSettings        │     实现细节：客户永远看不到
   │ - dirty    : bool             │
   └───────────────────────────────┘

一个小而完整的 Logger：接口三行，实现全套。

// ================= logger.h —— 对外发布的稳定接口 =================
#pragma once

#include <cstddef>      // std::size_t
#include <memory>       // std::unique_ptr
#include <string>

class Logger {
public:
    Logger();
    ~Logger();                              // ★ 必须在 .cpp 中定义（原因见下）
    Logger(Logger &&) noexcept;             // ★ 移动语义也放到 .cpp
    Logger &operator=(Logger &&) noexcept;

    Logger(const Logger &) = delete;         // PIMPL 类通常禁用拷贝（深拷贝需手写）
    Logger &operator=(const Logger &) = delete;

    void log(const std::string &msg);
    void setPrefix(const std::string &prefix);
    const std::string &prefix() const;
    std::size_t count() const;

private:
    struct Impl;                            // ★ 前置声明：不完整类型
    std::unique_ptr<Impl> d;                // ★ d-pointer：唯一的私有成员
};
// 注意：头文件里没有 <vector>、没有 <iostream>、没有 <QString>
// 客户代码的编译时间与「实现用了什么容器」完全无关。

// ================= logger.cpp —— 只有这里能看到 Impl =================
#include "logger.h"

#include <iostream>
#include <vector>    // 这个头只在 .cpp 里出现，绝不传染给客户

// 私有实现的完整定义：客户代码永远看不到这一块
struct Logger::Impl {
    std::string prefix{"<默认>"};
    std::vector<std::string> history;   // 内部表示随时可换（例如换成 QVector）
    std::size_t totalChars = 0;         // 新增成员不会改变 sizeof(Logger)
};

// 此处 Impl 已是完整类型，unique_ptr 的析构器才能正常实例化
Logger::Logger() : d(std::make_unique<Impl>()) {}

Logger::~Logger() = default;                        // ★ 定义在 .cpp 是硬性要求
Logger::Logger(Logger &&) noexcept = default;        // 移动 = 搬走那个指针，零拷贝
Logger &Logger::operator=(Logger &&) noexcept = default;

void Logger::log(const std::string &msg) {
    d->history.push_back(msg);      // 所有动作都委托给实现
    d->totalChars += msg.size();
    std::cout << d->prefix << ' ' << msg << '\n';
}

void Logger::setPrefix(const std::string &prefix) { d->prefix = prefix; }
const std::string &Logger::prefix() const { return d->prefix; }
std::size_t Logger::count() const { return d->history.size(); }

// ================= main.cpp =================
#include "logger.h"
#include <iostream>

int main() {
    Logger a;
    a.setPrefix("[APP]");
    a.log("启动完成");
    a.log("加载配置");
    std::cout << "a.count = " << a.count() << '\n';

    Logger b = std::move(a);            // 只搬一个指针，没有字符串拷贝
    b.log("来自 b 的日志");
    std::cout << "b.count = " << b.count() << '\n';
    // ⚠️ 此后不要再使用 a：它的 d 已被置空，再调用成员会解引用 nullptr

    Logger c;                           // 独立实例，各有一份 Impl
    c.log("独立实例");
    std::cout << "c.prefix = " << c.prefix()
              << ", c.count = " << c.count() << '\n';
    return 0;
}

编译与运行：

$ g++ -std=c++17 -Wall -Wextra -O2 logger.cpp main.cpp -o pimpl_demo
$ ./pimpl_demo
[APP] 启动完成
[APP] 加载配置
a.count = 2
[APP] 来自 b 的日志
b.count = 3
<默认> 独立实例
c.prefix = <默认>, c.count = 1

场景：一个跨模块复用的 SettingsManager 配置服务。头文件必须干净——绝不能暴露 QSettings，同时要能发射 valueChanged 信号。这正好用上 Qt 双向指针（d_ptr + q_ptr）的完整套路。

// ==================== settingsmanager.h ====================
#pragma once

#include <QObject>
#include <QString>
#include <QStringList>
#include <memory>

class SettingsManagerPrivate;      // ★ 前置声明：不 include <QSettings>

class SettingsManager : public QObject
{
    Q_OBJECT
public:
    explicit SettingsManager(const QString &organization,
                             const QString &application,
                             QObject *parent = nullptr);
    ~SettingsManager() override;   // ★ 必须在 .cpp 中定义

    SettingsManager(const SettingsManager &) = delete;
    SettingsManager &operator=(const SettingsManager &) = delete;

    QString  value(const QString &key, const QString &defaultValue = QString()) const;
    void     setValue(const QString &key, const QString &value);
    QStringList keys() const;
    void     sync();               // 落盘

signals:
    void valueChanged(const QString &key, const QString &value);

private:
    SettingsManagerPrivate *d_func() const noexcept { return d_ptr.get(); }
    friend class SettingsManagerPrivate;      // Impl 需要反向访问 q_ptr

    std::unique_ptr<SettingsManagerPrivate> d_ptr;   // ★ d-pointer（RAII 版）
};

// ==================== settingsmanager.cpp ====================
#include "settingsmanager.h"

#include <QSettings>          // 实现细节：只在 .cpp 里出现

// ---------- 私有实现类：外部 TU 完全不可见 ----------
class SettingsManagerPrivate
{
public:
    SettingsManagerPrivate(SettingsManager *q, const QString &org, const QString &app)
        : q_ptr(q), settings(org, app) {}

    // 让实现类自己拥有「通知」逻辑：q_ptr 的唯一用途
    void notifyChanged(const QString &key, const QString &value) {
        emit q_ptr->valueChanged(key, value);   // 反向调用 Owner 的信号
    }

    SettingsManager *q_ptr = nullptr;   // ★ q-pointer（Q_Q 模式）
    QSettings settings;                 // 重量级实现细节，藏在 .cpp 里
    bool dirty = false;
};

SettingsManager::SettingsManager(const QString &organization,
                                 const QString &application,
                                 QObject *parent)
    : QObject(parent)
    , d_ptr(std::make_unique<SettingsManagerPrivate>(this, organization, application))
{
    // 此处 Impl 已是完整类型，make_unique 合法
}

SettingsManager::~SettingsManager()
{
    if (d_ptr)                      // 防御：析构时把未落盘的设置刷出去
        d_ptr->settings.sync();
}

QString SettingsManager::value(const QString &key, const QString &defaultValue) const
{
    SettingsManagerPrivate *d = d_func();       // const 方法里改私有状态是允许的
    return d->settings.value(key, defaultValue).toString();
}

void SettingsManager::setValue(const QString &key, const QString &value)
{
    SettingsManagerPrivate *d = d_func();
    if (d->settings.value(key).toString() == value)
        return;                                  // 值没变：不写盘、不发信号
    d->settings.setValue(key, value);
    d->dirty = true;
    d->notifyChanged(key, value);                 // 交由 Impl 发信号
}

QStringList SettingsManager::keys() const
{
    SettingsManagerPrivate *d = d_func();
    return d->settings.allKeys();
}

void SettingsManager::sync()
{
    d_func()->settings.sync();
}

// ==================== main.cpp ====================
#include "settingsmanager.h"

#include <QCoreApplication>
#include <QDebug>

int main(int argc, char *argv[])
{
    QCoreApplication app(argc, argv);

    SettingsManager sm(QStringLiteral("JankerLi"), QStringLiteral("PimplDemo"));

    QObject::connect(&sm, &SettingsManager::valueChanged,
                     [](const QString &key, const QString &value) {
                         qInfo() << "[信号] 配置变更:" << key << "=" << value;
                     });

    sm.setValue(QStringLiteral("ui/theme"), QStringLiteral("dark"));
    sm.setValue(QStringLiteral("ui/theme"), QStringLiteral("dark"));  // 未变化 → 不发信号
    sm.setValue(QStringLiteral("editor/fontSize"), QStringLiteral("13"));
    sm.sync();

    qInfo() << "全部键:" << sm.keys();
    qInfo() << "theme =" << sm.value(QStringLiteral("ui/theme"));
    return 0;
}
// 首次运行输出（QSettings 会持久化，第二次运行 ui/theme 已存在，故首条信号不再出现）：
// [信号] 配置变更: "ui/theme" = "dark"
// [信号] 配置变更: "editor/fontSize" = "13"
// 全部键: QList("editor/fontSize", "ui/theme")
// theme = "dark"

# ==================== CMakeLists.txt ====================
cmake_minimum_required(VERSION 3.16)
project(PimplDemo LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_AUTOMOC ON)          # Q_OBJECT 需要 moc
set(CMAKE_AUTORCC ON)

find_package(Qt6 REQUIRED COMPONENTS Core)

add_executable(pimpl_demo
    main.cpp
    settingsmanager.cpp
    settingsmanager.h
)
target_link_libraries(pimpl_demo PRIVATE Qt6::Core)

# 构建：
#   cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build -j
#   ./build/pimpl_demo

以 SettingsManager 为例，一次 setValue() 调用经历的完整链路：

① 构造阶段（客户调用构造函数）。客户写 SettingsManager sm("JankerLi", "PimplDemo");。控制权进入 .cpp 里的构造函数，先初始化基类 QObject(parent)（把对象挂进 Qt 对象树），再初始化成员 d_ptr——std::make_unique<SettingsManagerPrivate> 在堆上分配一份 Impl，把 this 作为 q_ptr 存进去，并构造内部的 QSettings（登记组织名/应用名）。此刻客户代码里对 SettingsManager 的全部认知，仍然只是一个指针的大小。

② 调用阶段（客户调用公有方法）。客户写 sm.setValue("ui/theme", "dark")。此时执行的是 .cpp 里那个函数体：进入函数后第一件事是 SettingsManagerPrivate *d = d_func(); 取回 Impl 指针，随后所有逻辑（读取旧值、比较、写入、置 dirty）都在 Impl 的字段上完成。

③ 反向通知（Impl → Owner 信号）。值确实变了，d->notifyChanged(key, value) 被调用；Impl 内部通过 q_ptr 找到外层对象，执行 emit q_ptr->valueChanged(key, value)。Qt 的 moc 生成的信号函数把这次发射交给元对象系统，同步分发给所有 connect 到它的槽/λ（这里是一条 qInfo() 打印）。这就是 q_ptr 存在的唯一理由：Impl 不是 QObject，没资格 emit，必须借 Owner 的身份。

④ 销毁阶段（对象离开作用域）。main 结束时 sm 析构：先执行 .cpp 里手写的析构函数体（settings.sync() 兜底落盘），然后成员逆序销毁，~unique_ptr 调用 delete Impl——因为是 .cpp 里生成的析构代码，编译器此时完全清楚 SettingsManagerPrivate 的大小和析构行为，不会出现「删除不完整类型」的警告。最后基类 ~QObject 运行，把对象从父对象的 children 列表里摘掉。