第二章:工程目录结构设计

聊到大型C++项目,我第一个想说的就是目录结构。

你可能觉得这玩意儿有啥好讲的?不就是建几个文件夹嘛。嗯,我以前也这么想。直到有一次,我接手一个遗留项目,光找一个头文件就花了半小时——那个项目的目录结构,怎么说呢,就像把一堆衣服全塞进一个衣柜,连分类都没有。

从那以后,我深刻意识到:目录结构不是摆设,它是工程的骨架。骨架歪了,后面再怎么填肉都别扭。

2.1 模块化设计原则

先说说模块化。说白了,就是把大系统拆成小零件。但怎么拆?我总结了几条原则:

  • 高内聚、低耦合:一个模块只干一件事,模块之间少说话。你想想看,如果A模块改了,B、C、D都得跟着改,那还叫模块化吗?
  • 接口清晰:模块对外暴露什么,内部藏什么,要分清楚。我习惯用抽象基类或者纯虚接口来定义模块边界。
  • 可替换性:理论上,任何一个模块都可以被另一个实现替换,而不影响其他模块。比如日志模块,今天用spdlog,明天想换成自己写的,应该只改一个地方。

核心观点:模块化不是把代码拆散,而是让每个部分都有明确的职责和边界。拆得不好,比不拆还痛苦。

我在项目中遇到过一种情况:团队把模块拆得太细,一个功能拆成七八个小模块,结果接口调用链长得像蜘蛛网。后来我们重新合并了一些模块,反而更清晰了。所以,模块化要适度,别为了拆而拆。

2.2 常见目录结构模式

实际项目中,我见过三种主流模式。每种都有它的适用场景,没有绝对的好坏。

2.2.1 Flat模式(扁平结构)

所有源文件放在同一个目录下。简单粗暴,适合小项目或者原型验证。

project/
├── main.cpp
├── utils.cpp
├── utils.h
├── network.cpp
├── network.h
├── config.cpp
├── config.h
└── Makefile

优点:一眼能看到所有文件,找东西快。
缺点:项目一超过20个文件,就开始乱了。我见过一个项目,Flat模式堆了200多个.cpp文件,那感觉就像在垃圾堆里找针。

避坑指南:我曾经在一个小工具项目里用了Flat模式,后来功能越加越多,文件数直奔50+。每次打开目录都要滚动半天。最后花了半天重构成分层结构。所以,如果你预计项目会增长,一开始就别偷懒。

2.2.2 分层模式(Layered)

这是我最推荐的一种模式,尤其适合中大型项目。按逻辑层次划分目录,比如:

project/
├── interface/       # 接口层
│   ├── api.h
│   └── service.h
├── core/            # 核心逻辑层
│   ├── engine.cpp
│   ├── engine.h
│   └── processor.cpp
├── utils/           # 工具层
│   ├── logger.cpp
│   └── config.cpp
├── platform/        # 平台适配层
│   ├── linux/
│   └── windows/
└── tests/           # 测试层
    ├── unit/
    └── integration/

分层的好处是:依赖关系是单向的。上层可以调用下层,但下层不能反过来调用上层。这样改上层代码时,不用担心影响到底层。

我个人习惯把接口层单独拎出来。为什么呢?因为接口是模块之间的契约,它应该最稳定。我在项目中遇到过,接口和实现混在一起,结果改个实现细节,接口也跟着变,搞得所有调用方都得改。后来我把接口独立出来,这个问题就解决了。

2.2.3 功能分组模式(Feature-based)

按业务功能划分目录。每个功能模块自成一体,包含自己的头文件、源文件、测试等。

project/
├── user/            # 用户模块
│   ├── user.cpp
│   ├── user.h
│   ├── user_test.cpp
│   └── user_config.h
├── order/           # 订单模块
│   ├── order.cpp
│   ├── order.h
│   ├── order_test.cpp
│   └── order_types.h
├── payment/         # 支付模块
│   ├── payment.cpp
│   ├── payment.h
│   └── payment_test.cpp
└── common/          # 公共模块
    ├── utils.cpp
    └── types.h

这种模式适合业务逻辑清晰、功能边界分明的项目。比如电商系统、游戏服务器等。

优点:每个功能独立,团队可以并行开发。缺点:如果功能之间有大量共享代码,容易产生重复。

我的建议:实际项目中,我经常把分层模式和功能分组模式混用。比如,在每个功能模块内部,再按接口、实现、测试分层。这样既有业务上的清晰度,又有技术上的规范性。

2.3 命名规范

命名这事儿,看似简单,其实坑很多。我总结了几条铁律:

2.3.1 目录命名

  • 全小写:避免大小写混用带来的跨平台问题(Windows不区分大小写,Linux区分)。
  • 用短横线或下划线:我个人偏好短横线(kebab-case),比如 user-service/,因为看起来更清爽。但团队统一就行。
  • 不要用数字前缀:比如 01_core/、02_utils/。这会让目录排序看起来有顺序,但实际维护时,新加的模块该排第几?很尴尬。

2.3.2 文件命名

类型 命名规则 示例
头文件 小写+下划线 user_manager.h
源文件 与头文件对应 user_manager.cpp
测试文件 文件名+_test user_manager_test.cpp
配置文件 全小写 app_config.json

2.3.3 命名空间

C++的命名空间一定要用。我见过一些项目,全局命名空间里塞了几百个函数,那叫一个酸爽。

// 推荐
namespace myproject::core {
    class Engine { ... };
}

// 不推荐
class Engine { ... };  // 全局命名空间

命名空间的层级一般和目录结构对应。比如 core/engine.h 对应 myproject::core。这样找代码时,看命名空间就知道文件在哪。

重要提醒:命名规范不是用来束缚你的,而是用来减少沟通成本的。团队里只要统一,用什么风格都行。但如果不统一,每个人写代码都按自己的喜好来,那项目后期维护起来,你会想骂人。

2.4 实战建议

说了这么多,最后给几个落地建议:

  1. 项目初期就定好目录结构。别想着「先写着,后面再重构」。重构的成本远比你想象的高。
  2. 用工具保证一致性。比如用CMake的 add_subdirectory 来组织模块,用clang-format来统一代码风格。
  3. 定期审视目录结构。项目在演进,目录结构也要跟着调整。我每半年会做一次「目录结构健康检查」,看看有没有模块膨胀、依赖混乱的问题。
  4. 写一份README。在项目根目录放一个 README.md,说明目录结构的设计思路。新同事来了,一看就懂。

嗯,目录结构这事儿,说大不大,说小不小。但一个好的目录结构,能让你的项目活得更久、更健康。就像盖房子,地基打好了,后面怎么装修都顺手。

下一章,我们来聊聊构建系统的选择。CMake、Bazel、Meson……到底哪个适合你?到时候见。