大型C++项目应按功能模块分层，每个模块自包含接口、实现、测试和资源，头文件与实现路径一致，构建系统自然映射目录；严格隔离构建产物，配套落地头文件保护、禁止跨模块include实现细节、显式声明依赖等规范。
大型 C++ 项目要长期可维护、易协作、好扩展，目录结构不是随便建几个文件夹就行——它本质是团队对模块边界、依赖关系和构建逻辑的共识体现。核心原则就三条：按功能/模块分层，而非按技术类型（比如不全堆一个 src/ 下）；头文件与实现分离但路径一致；构建系统能自然映射目录，避免硬编码路径。
按领域或组件划分顶层目录
避免传统“src/、include/、lib/”扁平结构。推荐以业务/技术模块为一级目录，每个模块自包含接口、实现、测试和内部资源：
-
core/—— 基础工具（日志、配置、内存池）、跨模块抽象（如IEventBus） -
network/—— 协议解析、连接管理、RPC 框架封装 -
storage/—— 数据库访问层、本地缓存、序列化策略 -
app/—— 主程序入口、服务生命周期、命令行参数解析 -
tests/—— 每个模块对应子目录（如tests/core/），用gtest或catch2，测试源码与被测模块路径对齐
每个模块内统一采用“接口先行 + 实现分离”布局
每个模块（如 network/）内部结构清晰，便于 IDE 导航和头文件管理：
-
network/include/network/—— 公共头文件，路径与安装目标一致（如#include <network></network>） -
network/src/—— 对应实现（tcp_client.cpp），可再按子功能分detail/存放内部头文件（不对外暴露） -
network/CMakeLists.txt—— 该模块专属构建脚本，只声明自身源码、依赖和导出接口
好处是：头文件路径即模块名，不依赖全局 include_directories()；第三方使用者只需 find_package(MyProject) 就能拿到干净的 INTERFACE_INCLUDE_DIRECTORIES。
立即学习“C++免费学习笔记（深入）”；
明确区分“构建产物”与“源码”，禁止混放
根目录下严格隔离生成物，让 Git 忽略更精准、CI 更稳定：
-
build/—— 所有构建输出（CMakeCache.txt、对象文件、可执行文件、静态库等） -
out/或dist/—— 打包后的发布产物（带依赖的 tar.gz、Windows installer） -
third_party/—— 外部依赖源码（如abseil、fmt），用 git submodule 或 vcpkg 集成，不放二进制 -
docs/—— Doxygen 配置和生成文档的输出目录单独设为docs/build/，源码在docs/src/
配套规范比结构更重要
再好的目录也救不了混乱的约定。必须同步落地几条铁律：
- 所有公开头文件必须用模块前缀保护：
#pragma once或#ifndef NETWORK_TCP_CLIENT_H_ - 禁止跨模块直接 include 实现细节头文件（如
network/src/detail/connection_pool.h），只能通过include/下的稳定接口 - CMake 中每个模块用
add_library(module_name INTERFACE)或add_library(module_name STATIC)显式声明，用target_link_libraries()表达依赖，不用全局link_directories() - 新增模块必须同步添加单元测试目录和最小 smoke test，CI 流水线失败时能快速定位到具体模块
基本上就这些。不复杂但容易忽略——目录结构不是一劳永逸的设计，而是随着模块演进持续重构的活文档。每次拆分新模块、合并旧功能时，顺手整理对应目录，团队就能一直走在清晰的路上。
