3. 第3例

循环依赖的三种典型形态与治理策略

头文件互相包含通常表现为三种形态：直接循环（A.h 包含 B.h，B.h 又包含 A.h）、间接循环（A→B→C→A）、接口与实现耦合（接口头文件暴露了实现细节，迫使调用方包含实现头文件）。治理手段按侵入性从低到高依次为：前置声明、接口分离、PIMPL。

前置声明消除直接循环

以下示例中，Order 与 Customer 互相引用。原始版本两个头文件互相包含，编译时产生循环。通过前置声明，Order.h 不再包含 Customer.h，仅声明 class Customer;，因为 Order 只持有 Customer 的指针和引用。

// ---- Customer.h ----
#pragma once
#include <string>
#include <vector>

class Order;  // 前置声明，替代 #include "Order.h"

class Customer {
public:
    explicit Customer(std::string name);
    void addOrder(Order* order);
    const std::string& name() const;
private:
    std::string name_;
    std::vector<Order*> orders_;  // 仅存指针，不需要完整类型
};

// ---- Order.h ----
#pragma once
#include <string>

class Customer;  // 前置声明，替代 #include "Customer.h"

class Order {
public:
    Order(int id, Customer* owner);
    int id() const;
    Customer* owner() const;
private:
    int id_;
    Customer* owner_;  // 仅存指针
};

// ---- Order.cpp（需要完整类型时在 .cpp 中包含）----
#include "Order.h"
#include "Customer.h"  // 此处才需要完整定义

Order::Order(int id, Customer* owner) : id_(id), owner_(owner) {}
int Order::id() const { return id_; }
Customer* Order::owner() const { return owner_; }

PIMPL 隐藏实现细节

当类需要持有值类型成员且不希望暴露其定义时，PIMPL 将实现细节移入 .cpp 中的嵌套结构体，头文件只保留一个不透明指针。

// ---- Widget.h ----
#pragma once
#include <memory>

class Widget {
public:
    Widget();
    ~Widget();                          // 析构必须在 .cpp 中定义
    Widget(Widget&&) noexcept;
    Widget& operator=(Widget&&) noexcept;
    Widget(const Widget&) = delete;
    Widget& operator=(const Widget&) = delete;

    void draw() const;
    int width() const;
private:
    struct Impl;                        // 仅声明
    std::unique_ptr<Impl> pImpl_;       // 不透明指针
};

// ---- Widget.cpp ----
#include "Widget.h"
#include "Renderer.h"   // 实现细节头文件，不暴露给调用方
#include <vector>

struct Widget::Impl {
    Renderer renderer;
    std::vector<int> layers;
    int cachedWidth = 0;
};

Widget::Widget() : pImpl_(std::make_unique<Impl>()) {}
Widget::~Widget() = default;            // 此处 Impl 完整，unique_ptr 可正确析构
Widget::Widget(Widget&&) noexcept = default;
Widget& Widget::operator=(Widget&&) noexcept = default;

void Widget::draw() const { pImpl_->renderer.render(pImpl_->layers); }
int Widget::width() const { return pImpl_->cachedWidth; }

接口分离切断间接循环

当 A→B→C→A 形成间接循环时，提取公共接口是有效手段。将 C 对 A 的依赖改为对抽象接口 IA 的依赖，C.h 只包含 IA.h，不再包含 A.h。

// ---- IShape.h（无依赖，稳定接口）----
#pragma once

class IShape {
public:
    virtual ~IShape() = default;
    virtual double area() const = 0;
    virtual void scale(double factor) = 0;
};

// ---- Circle.h ----
#pragma once
#include "IShape.h"

class Circle : public IShape {
public:
    explicit Circle(double r);
    double area() const override;
    void scale(double factor) override;
private:
    double radius_;
};

// ---- ShapeManager.h（依赖接口，不依赖具体实现）----
#pragma once
#include <vector>
#include <memory>

class IShape;  // 前置声明即可

class ShapeManager {
public:
    void add(std::unique_ptr<IShape> shape);
    double totalArea() const;
private:
    std::vector<std::unique_ptr<IShape>> shapes_;
};

验证头文件耦合度下降

治理后需要量化验证。两种常用手段：

• include-what-you-use（IWYU）：编译时分析每个源文件实际使用的符号，报告多余包含和缺失包含。运行 iwyu_tool.py -p build/ 后，若输出中不再出现循环包含建议，说明耦合已降低。
• CMake 依赖图：在 CMakeLists.txt 中启用 --graphviz=deps.dot，生成目标级依赖图。对比治理前后 deps.dot 中头文件节点的入度和出度，循环边消失即为验证通过。

# 生成依赖图
cmake -S . -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
cmake --graphviz=build/deps.dot build/
dot -Tpng build/deps.dot -o build/deps.png

# 使用 IWYU 检查
iwyu_tool.py -p build/ -- -Xiwyu --mapping_file=iwyu.imp