模块名必须与文件路径严格对齐，如export module data::user;需置于data/user.ixx中；CMake须显式标记模块接口/实现属性；旧头文件需封装为胶水模块；模块粒度应依变更频率与耦合度权衡。
模块接口文件（.ixx/.cppm）必须放在对应目录层级，且路径需与模块名严格对齐
模块名不是随意起的字符串，它直接参与编译器查找和 BMI（Binary Module Interface）生成路径。比如 export module data::user; 要求该声明必须出现在 data/user.ixx 或 data/user.cppm 中；若放在 src/data/user.ixx，而构建系统未将 src 加入模块搜索路径，Clang 就会报 error: module 'data::user' not found。
实操建议：
立即学习“C++免费学习笔记（深入）”；
组合式C++代码评审方案，融合静态分析、AI推理、多轮迭代评审和C++专项检查，适用于PR审查、增量代码审查、全项目评审和代码质量评分，触发词包括review cpp、cpp代码评审、C++review、代码审查。
- 模块名用双冒号分隔（如
core::math、net::http::client），对应目录结构必须是core/math.ixx、net/http/client.ixx - 不要用相对路径拼接模块名，比如在
utils/string.cppm里写export module string;—— 这会让模块失去层级语义，后续无法被import utils::string正确解析 - MSVC 默认识别
.ixx为模块接口文件，Clang 推荐用.cppm；混用会导致部分编译器跳过模块解析，当成普通源文件处理
CMake 中必须显式声明每个模块接口单元，并控制编译顺序
CMake 不会自动扫描 .ixx 文件并推导依赖。如果只把模块文件加进 add_executable()，MSVC 可能勉强通过，但 Clang/GCC 会因缺少 set_property(SOURCE ... PROPERTY CXX_MODULE_INTERFACE ON) 而静默失败——最终生成的是普通 OBJ，不是 BMI。
实操建议：
立即学习“C++免费学习笔记（深入）”；
- 对每个接口文件单独调用
set_property(SOURCE core/math.ixx PROPERTY CXX_MODULE_INTERFACE ON) - 模块实现文件（如
core/math_impl.cpp）要用set_property(SOURCE ... PROPERTY CXX_MODULE_IMPLEMENTATION ON) - 确保
import core::math;出现的翻译单元（如main.cpp）在 CMake 中后于core/math.ixx被处理，否则链接阶段找不到符号 - 使用
target_link_libraries(myapp PRIVATE core_math)配合模块库 target，而非仅靠target_sources()
跨模块依赖不能靠 #include 混用，必须用 import + 模块封装层隔离
超大型工程里总存在遗留头文件（如第三方库、自研但未模块化的几何内核）。若在某个 .ixx 里直接 #include "legacy/geometry.h"，会导致整个模块退化为传统翻译单元：宏污染、重复解析、ODR 冲突全回来，且 import legacy::geometry 根本不会生效。
实操建议：
立即学习“C++免费学习笔记（深入）”；
- 为每个旧头文件创建一个“胶水模块”，例如
legacy/geometry.ixx内容为：export module legacy::geometry;<br>export header "legacy/geometry.h";
- Clang 需配合
-fmodule-header=legacy/geometry.h预编译该头文件为 BMI；MSVC 用/headerUnit参数 - 禁止在任何
.ixx中出现#include；所有#include必须下沉到.cpp实现文件中，且该文件只能属于一个模块（即以module xxx;开头） - 标准库模块（如
import std;）目前仅 MSVC 提供完整支持；Clang/GCC 仍 fallback 到头文件，此时应统一用import <vector></vector>语法（C++23 扩展），避免混用#include <vector>
模块粒度太细或太粗都会拖慢增量编译，得按“变更频率+逻辑耦合”切分
有人把每个类拆成一个模块（ui::button.ixx、ui::label.ixx），结果编译一次改了三个按钮样式，要重建十几个 BMI 文件——比头文件还慢。也有人把整个“渲染引擎”塞进一个 render.ixx，改一行 shader 工具链就重编整个模块，失去增量优势。
实操建议：
立即学习“C++免费学习笔记（深入）”；
- 高频修改的部分（如 UI 控件、配置解析）适合细粒度模块，单个文件 ≤ 500 行接口声明
- 强内聚低耦合的子系统（如布线算法、DRC 检查器）可独立成模块，但内部用
module : private;隐藏辅助类型，避免导出爆炸 - 基础工具层（内存池、原子计数器、日志）应合并为
core::base，减少导入链长度 - 观察 BMI 缓存命中率：Clang 下看
clang -fmodules-cache-path=... -###输出；MSVC 看/d1reportAllClassLayout日志里是否频繁 recompile module interface
