模块是可独立编译测试、有明确定义接口的单元，需通过头文件隔离、C++20 modules、CMake依赖控制及clang-tidy静态检查实现物理边界，链接错误才是真实边界。
大型C++项目一旦模块边界模糊，include 乱引、头文件爆炸、编译时间飙升、改动一处牵动全链路——这不是设计问题，是架构失控的明确信号。Core Guidelines 不是教条清单，而是对这类失控的系统性响应：它把“模块”定义为可独立编译、可独立测试、有明确定义接口的单元，而非逻辑分组或目录命名。
用 interface 和 implementation 分离强制约束头文件暴露面
Core Guidelines 明确要求：所有对外接口必须收口在 *.h 或 *.hxx（非 *.hpp）中，且该头文件不得包含任何实现细节（如私有成员定义、内联函数体、模板具体化）。真实工程中，90% 的隐式依赖都源于头文件里悄悄 #include 了不该暴露的内部头。
- 每个模块只允许一个公共头文件，命名与模块名一致，例如
network_client.h - 该头中仅声明
class、struct、enum及其公有成员函数签名；私有成员全部移入network_client_impl.h（不对外安装） - 禁止在公共头中使用
std::vector等模板实例化类型——改用std::vector、* std::unique_ptr<:vector>>或 PIMPL - 若必须导出模板，将其置于
network_client.tpp（非 .inl），并在公共头末尾#include "network_client.tpp"，确保使用者显式触发实例化
用 module interface unit（C++20）替代传统头文件依赖树
C++20 modules 不是“更快的头文件”，它是打破文本包含模型的根本手段。在已启用 /experimental:module（MSVC）或 -fmodules-ts（Clang）的项目中，模块接口单元能彻底切断宏污染、ODR 违规和隐式重编译链。
- 每个模块必须有且仅有一个
module interface unit，后缀为.ixx（MSVC）或.cppm（Clang/GCC），例如core_logging.ixx - 该文件以
export module core_logging;开头，所有需导出的声明前加export，未标记者默认不可见 - 禁止在
.ixx中#include
任何传统头文件——改用
import std.memory;等标准模块（若可用）或封装为module std_headers { #include} - 模块实现单元（
.cpp）通过import core_logging;使用，不再需要#include "core_logging.h"，也不再受其宏定义影响
用 target_link_libraries + INTERFACE_INCLUDE_DIRECTORIES 控制依赖可见性
CMake 是模块物理边界的守门人。仅靠目录结构无法阻止开发者 #include "src/infra/cache/lru_cache.h"。必须用 CMake target 层级策略让非法引用在编译期报错。
- 每个模块定义为独立
add_library(或INTERFACE) STATIC，例如add_library(network_client STATIC network_client.cpp) - 用
target_include_directories(network_client INTERFACE $限定对外暴露路径) - 下游模块通过
target_link_libraries(app PRIVATE network_client)建立依赖，此时只有network_client的INTERFACE包含路径对app可见 - 禁用全局
include_directories()；禁用target_include_directories(... PUBLIC ...)（除非是真正跨模块共享的基类头）
用 clang-tidy 的 google-build-explicit-make-pair 类规则做静态边界检查
人工审查无法覆盖每日数百次提交。必须将模块契约编码为机器可验证规则。Clang-Tidy 的 misc-definitions-in-headers、cppcoreguidelines-special-member-functions 等规则只是起点；关键是要自定义规则拦截越界访问。
- 启用
-Wundefined-internal（Clang）或/diagnostics:caret（MSVC）捕获因头文件缺失导致的符号未定义，这往往是模块拆分不彻底的征兆 - 编写自定义 Clang-Tidy 检查器：当源文件
#include路径匹配"^src/(?!core|utils)/"但当前 target 名为core_.*时，报错“core 模块不得依赖业务层头文件” - CI 流程中强制运行
clang-tidy --checks="*,cppcoreguidelines-*" --header-filter="^include/.*\.h$" *.cpp，失败即阻断合并 - 注意：不要依赖
IWYU（Include What You Use）自动修复——它可能把std::string的依赖从
// core_logging.ixx（C++20 module interface unit）
export module core_logging;
import std.core;
import std.memory;
export namespace core {
enum class log_level { debug, info, warning, error };
export class logger {
public:
explicit logger(std::string_view name);
void log(log_level level, std::string_view msg);
private:
struct impl;
std::unique_ptr pimpl_;
};
}
模块不是画在白板上的方框，是编译器拒绝链接时你看到的那行错误——undefined reference to 'core::logger::log(core::log_level, std::string_view)'。真正的边界，永远由链接器裁定，而不是架构图。
