前段时间我接了一个 C 服务端仓库的维护工作。第一周我几乎没写业务代码全在等编译改动一行头文件下游能有几十个翻译单元跟着重新展开全量编译稳定在四十分钟上下增量也经常二十分钟起步。后来我用工具拉了一下 include 依赖图发现根因压根不是代码量大而是几乎所有 .cpp 都间接包含了一个两千多行的“公共头文件”这个公共头文件又拉进了 json、protobuf、日志库和一堆第三方头。模块化设计这四个字在这种仓库里不是锦上添花是救命的。这篇文章想认真聊聊 C 模块化设计原则。我不打算把它讲成那种面试八股因为关于模块化面试官想听的也不只是“高内聚低耦合”六个字。我会从编译期、接口、依赖方向、构建系统、可测试性这几个角度把我实际拆过项目后的理解和踩坑记录下来。适合正在接手老 C 项目的同学、准备 C 面试时被问到模块化设计一脸懵的同学也适合想在下个项目里提前把依赖管好的团队。1. 先弄清楚模块化在 C 里到底解决什么问题1.1 模块化的本质是约束依赖不是追求文件美观很多人对模块化的第一反应是“把一个大文件拆成多个小文件”。这是一个很容易误导人的直觉。把一个 5000 行的文件拆成 10 个 500 行的文件如果它们之间互相 include、互相调用全局变量项目并不会变得更好维护只是把一团乱麻理成了十个更小的一团乱麻。我理解中模块化的本质是给代码之间的依赖关系建立规则让整个项目的依赖图保持“有向无环、单向流动”。一个模块之所以能独立维护、独立测试、独立替换靠的不是它有多少行代码而是它对外暴露的依赖面有多小。判断一个模块设计得好不好可以看三个指标改动它内部实现时有多少外部代码需要重新编译替换它的实现时需要动多少调用方给它的某个功能写单测时要替身掉多少无关依赖。这三个指标对应的正是 C 里模块化的三个层面编译期依赖、接口依赖、运行期依赖。后面我会逐个展开。1.2 编译期、接口、运行期三层边界C 和脚本语言不一样模块化在它身上有三个完全不同的物理载体。第一层是编译期边界头文件、源文件、预处理、链接。这一层决定了当你改一个头文件编译系统要重建多少个翻译单元。第二层是接口边界类的 public 部分、抽象基类、函数签名它决定调用方能看到哪些信息、把哪些实现细节挡在视线之外。第三层是运行期边界虚函数表、动态多态、函数指针、依赖注入它决定程序运行时模块之间如何协作、如何替换。一个常见的误解是只要把接口设计好就算模块化了。其实编译期边界如果失控接口再干净也没用因为你每改一个私有成员变量所有 include 了这个类的调用方都会被迫重新编译。这正是很多大型项目改动效率低的元凶。反过来也一样如果只把文件拆干净接口却把内部实现细节全暴露出去那拆出来的也不是模块是“头文件收集册”。面试时如果被问到 C 模块化设计原则能说出这三层边界并且用自己经历过的重构案例来佐证比背十个原则定义要有说服力得多。1.3 模块化带来的收益是可以量化的我习惯在拆模块之前先量化一下现状。最简单的做法是用 clangd 或者 include-what-you-use 生成一份 include 关系图统计每个头文件被多少个翻译单元间接包含再统计全量编译耗时和增量编译耗时。拆完再测同一组数据收益数字清清楚楚。我自己拆过一个项目改造前全量编译 38 分钟左右改动一个底层头文件要连带构建 120 多个目标改造后全量编译 11 分钟底层的稳定头文件几乎不再引起下游连锁编译。这个对比比任何理念都更能说服团队投入重构。2. 物理模块化头文件与源文件的分工不是形式主义2.1 头文件只放“契约”源文件才放“实现”先说一条最基础但又最常见的红线头文件里尽量只放声明不要在头文件里随手定义函数体。我知道很多人觉得在类里直接写函数短小精悍看着舒服但代价是每个包含这个头文件的翻译单元都要重新解析并可能内联展开这段实现。哪怕是三行的 getter如果头文件被 200 个 .cpp 包含就是 200 次重复解析。我推荐的典型划分是头文件放类声明、必要的数据成员、公开函数的签名、需要给调用方看到的类型别名实现细节放 .cpp。举一个用户模块的例子// include/auth/user.hpp #pragma once #include string namespace auth { class User { public: User(std::string name, std::string email); const std::string name() const noexcept; bool isValid() const noexcept; void activate(); private: std::string name_; std::string email_; bool activated_ false; }; } // namespace auth对应的 .cpp 只负责实现还能把 isValid 里的校验逻辑写成文件内私有函数避免污染头文件同时不影响外部可见性// src/user.cpp #include auth/user.hpp #include algorithm #include cctype namespace auth { namespace { bool looksLikeEmail(const std::string email) { if (email.empty()) { return false; } return std::all_of(email.begin(), email.end(), [](char c) { unsigned char uc static_castunsigned char(c); return std::isalnum(uc) || c || c .; }); } } // namespace User::User(std::string name, std::string email) : name_(std::move(name)), email_(std::move(email)) {} bool User::isValid() const noexcept { return looksLikeEmail(email_); } void User::activate() { activated_ true; } } // namespace auth注意我放了一个匿名命名空间里的 looksLikeEmail这个函数只在本翻译单元可见外部完全碰不到。匿名命名空间是 C 里实现文件内部模块化最好的工具比 static 函数更现代也比把辅助函数塞进头文件干净得多。2.2 Include What You Use一条被低估的纪律“包含你直接用到的头”这个原则叫 Include What You UseIWYU它被违反的频率远超想象。最常见的写法是一个 .cpp 自己没直接 include 某个头但依赖了别人头文件里顺手 include 进来的类型代码能编过就没人管了。问题是哪一天那个“顺手 include”的中间头文件重构了你的编译就断了而且报错位置往往非常难定位。我给自己立的规矩很简单每个 .cpp 或 .hpp 文件只要在文件里用到了某个类型或函数就必须显式 include 对应的头哪怕这个头已经被其他头文件间接包含。这样做起初会让人觉得头文件列表变长、冗余但换来的是删除一个头文件时能精确知道有多少文件会受到牵连而不是全凭运气。include-what-you-use 工具现在 clang 系生态里也有类似检查可以在 CI 里跑自动扫描违反情况。include guard 的选择上我建议新代码统一用#pragma once。绝大多数主流编译器都支持而且不会像传统宏守卫那样有宏名冲突的风险。如果因为兼容老旧编译器必须用宏守卫记得把宏名写完整#ifndef _FILE_H这种太容易撞车了也占用了保留标识符。2.3 头文件是编译时间的头号敌人C 编译慢的物理原因就藏在预处理机制里include 的本质是文本复制。头文件越大、include 链越长每个翻译单元要展开的文本就越多展开完之后还要做模板实例化、重载决议这些高成本阶段。打个比方你把一份说明书复印给一百个人复印成本不高但这份说明书有 200 页每个人还要从头到尾读一遍成本就上去了。所以物理模块化的核心动作是缩小“有效头文件体积”。注意是有效不是行数。一个被 100 个翻译单元包含的稳定头文件就算 2000 行问题也不大真正致命的是一个大而全的头文件被到处包含或者把模板实现、第三方重头戏json、opencv、protobuf全部拉进公共头文件。前阵子很多人在折腾 VS Code 配置 C 环境和 visual c redistributable 相关的问题新手调试时最头疼的往往也是头文件解析链太长导致智能提示卡顿、跳到定义要绕一大圈。降低编译依赖的常用手段能用前置声明就不用完整定义能不放数据成员就考虑 pimpl模板实现如果必须放头文件考虑用extern template显式实例化来避免每个翻译单元重复实例化合理使用 ccache 缓存中间产物。这些措施独立看都是小事叠加起来对构建速度的影响是数量级的。3. 让模块的“门面”尽量小接口设计的取舍3.1 最小公开接口原则模块的公开接口就是它对外承诺的契约。契约越大将来被迫变更时受影响的面就越大。所以最简单也最有效的原则是能 private 就不要 public能文件内部可见就不要对外暴露。这不是鼓励把所有东西都藏起来装神秘而是让每个声明都有明确的“被使用范围”。一个我经常举的反面例子是那种给每个数据成员都配 getter/setter 的类。看起来很方便实际上把内部状态完全摊开了调用方可以随意修改内部字段模块想换存储结构或者加不变量检查都变得极其困难。更好的做法是只暴露业务需要的行为比如订单模块的 Order 类不应该暴露setStatus(int)而应该暴露confirm()、cancel()让状态流转规则活在模块内部。这样外部只知道“我能对订单做什么”不知道订单内部有几张状态表。3.2 Pimpl 惯用法把实现细节锁进 .cpppimplpointer to implementation是我在大型项目里非常依赖的一个手段。它的核心思想是头文件里只放一个指向 Impl 的指针真正的数据成员和实现逻辑全部移动到 .cpp 里用户看到的这个类只是“一扇门”。// include/ui/widget.hpp #pragma once #include memory namespace ui { class Widget { public: Widget(); ~Widget(); Widget(Widget) noexcept; Widget operator(Widget) noexcept; Widget(const Widget) delete; Widget operator(const Widget) delete; void resize(int w, int h); void draw() const; private: class Impl; std::unique_ptrImpl impl_; }; } // namespace ui对应的 .cpp 里完整定义 Impl这段实现对外部完全不可见只有 Widget 的成员函数能访问// src/widget.cpp #include ui/widget.hpp #include iostream namespace ui { class Widget::Impl { public: void resize(int w, int h) { width_ w; height_ h; } void draw() const { std::cout width_ x height_ \n; } private: int width_ 0; int height_ 0; }; Widget::Widget() : impl_(std::make_uniqueImpl()) {} Widget::~Widget() default; Widget::Widget(Widget) noexcept default; Widget Widget::operator(Widget) noexcept default; void Widget::resize(int w, int h) { impl_-resize(w, h); } void Widget::draw() const { impl_-draw(); } } // namespace ui这里有几个非常容易踩的坑我必须提醒。第一Widget::~Widget() default;必须写在 .cpp 里因为这里需要看到 Impl 的完整定义才能调用unique_ptr的析构如果写在头文件里编译器在实例化析构时看不到 Impl会直接编译报错。第二因为有了自定义析构移动构造和移动赋值不会隐式生成最好显式声明并放到 .cpp 里 default。第三pimpl 付出了每次构造都做一次堆分配、每次访问成员都多一层指针跳转的代价拷贝语义还要手动处理。所以它适合的是“接口稳定、实现频繁变动、或者对 ABI 稳定性有要求”的模块不适合所有类无