pimpl全称是pointer to implementation，核心思路是把类中容易变动的私有部分抽离到一个实现类，对外只保留一个前向声明和指针成员。这样头文件不再依赖实现类的完整定义，修改实现时无需重新编译调用方代码，同时也让动态库的ABI更稳定。
一、基础实现方式
最常见的写法是在公开类里定义一个前向声明的实现结构体，并用unique_ptr持有它。头文件只包含最小信息，cpp文件里给出结构体的完整定义。下面示例展示了一个简单的Widget类。
// widget.h
#pragma once
#include <memory>
class Widget {
public:
Widget();
~Widget();
void do_something();
private:
struct Impl; // 前向声明
std::unique_ptr<Impl> pImpl; // 不透明指针
};
// widget.cpp
#include "widget.h"
#include <string>
#include <vector>
struct Widget::Impl {
std::string name;
std::vector<int> data;
void helper() { /* 具体逻辑 */ }
};
Widget::Widget() : pImpl(std::make_unique<Impl>()) {}
Widget::~Widget() = default;
void Widget::do_something() {
pImpl->helper();
}
注意析构函数必须在cpp中显式定义，而不能在头文件用=default。因为头文件里Impl是不完整类型，unique_ptr的默认删除器需要看到完整定义才能正确释放内存，否则会导致编译错误。
如果需要在头文件提供内联函数访问Impl成员，就必须把Impl定义挪到头文件，这就破坏了编译防火墙，所以通常只把接口函数放在cpp中实现。对于不需要转移所有权的场景，也可以用裸指针配合手动new和delete，但现代C++更推荐智能指针。
二、降低编译依赖的原理
普通写法下，类的私有成员写在头文件，一旦成员变量类型发生变化，比如增加一个std::string字段，所有包含该头文件的源文件都必须重新编译，大型项目里可能触发成千上万个编译单元重建。pimpl把这种变动封死在cpp内部，公开头文件内容几乎不变。
// 没有pimpl时，增加成员导致重编译
class Widget {
std::string a;
int b;
// 新增下面一行，所有用到Widget的文件都要重编
std::vector<double> c;
};
使用pimpl后，新增的vector字段只存在于Impl结构里，头文件的Widget大小永远是sizeof指针，调用方完全感知不到。这对减少增量构建时间效果明显，尤其适合作为库接口的基础类。
从编译器角度看，前置声明切断了类型依赖图。头文件不再需要包含<string>或<vector>，也就不会把这些模板定义扩散到调用方，进一步缩短预处理和模板实例化开销。
三、二进制兼容方案
在发布动态库时，如果直接把成员写在类里，后续版本给类加字段会改变对象内存布局，老程序加载新库就会读错偏移量而崩溃。pimpl让类的公开布局固定为单个指针，实现类的改动只影响库内部。
| 改动类型 | 普通类 | pimpl类 |
|---|---|---|
| 新增私有成员 | 破坏ABI | 兼容 |
| 修改私有成员类型 | 破坏ABI | 兼容 |
| 修改公开函数签名 | 破坏ABI | 同样破坏 |
需要强调的是，pimpl只能保护私有实现部分的二进制兼容，如果修改了公开方法的参数或虚函数表，仍然会破坏兼容。因此库的版本管理还要配合语义化版本规范。
在跨编译器交付时，不同编译器的unique_ptr实现可能略有差异，有些团队会改用shared_ptr或者裸指针并自定义销毁函数，确保导出的符号稳定。无论哪种方式，核心原则都是让公开头文件描述的结构体尺寸和顺序永不改变。
四、注意事项与取舍
pimpl并非没有代价。每次访问实现都要通过指针间接跳转，对极致性能热点可能有微小影响；同时对象被分到堆上，增加了内存分配次数。在嵌入式或高频调用场景要权衡是否采用。
// 手动管理版本，避免unique_ptr跨库边界问题
class Widget {
public:
Widget();
~Widget();
void run();
private:
struct Impl;
Impl* p;
};
Widget::Widget() { p = new Impl(); }
Widget::~Widget() { delete p; }
如果库和使用者使用不同的运行库，unique_ptr的删除器可能在边界上不匹配，此时手动new和delete反而更可控。另外，友元关系和内部嵌套类型也要重新设计，因为Impl默认无法访问公开类的私有区域，必要时可将Impl声明为friend。
总体来看，pimpl是C++里用少量运行时开销换取编译速度和ABI稳定的经典手段。只要控制好指针生命周期、避开跨库智能指针陷阱，就能在大型项目和长期维护的库中显著降低耦合成本。