C / C++ / 系统课时
规划项目模块和目录结构
规划项目模块和目录结构
这一节先不急着堆功能,而是把命令行工具拆成可维护的工程骨架:核心逻辑放进独立库,公共头文件形成稳定接口,应用入口只负责调用,测试代码单独组织,并用 CMake 验证依赖方向。
学习目标
- 根据职责拆分核心模块、公共接口、应用入口和测试代码
- 让目录结构与 CMake target 对应,避免依赖关系隐藏在文件路径里
- 建立可以直接配置、构建和测试的最小工程骨架
先按职责划分四个区域
一个小型命令行工具也会同时包含业务逻辑、对外接口、程序入口和测试。如果全部堆在同一个目录,main.c 很容易逐渐混入计算、文件操作和测试辅助逻辑,后续既难复用,也难单独验证核心功能。
建议把工程划成四个区域:src 放核心实现,include/mytool 放允许其他 target 使用的公共头文件,app 放最终可执行程序入口,tests 放测试程序。顶层 CMakeLists.txt 负责把这些区域组织成真正的构建目标。

这种划分的关键不是文件夹名称本身,而是依赖方向:应用和测试都依赖核心库,核心库不应该知道命令行入口或测试程序的存在。
建立最小目录骨架
下面的命令在类 Unix 环境中创建本节需要的目录和空文件。它只建立工程骨架,不写入业务代码。
set -e
cmake -E make_directory src include/mytool app tests
cmake -E touch CMakeLists.txt
cmake -E touch src/core.c include/mytool/core.h app/main.c tests/test_core.c
printf 'project skeleton created\n'预期输出
project skeleton created创建完成后,五个文件各自承担单一职责:公共声明进入头文件,核心实现进入 src,命令行入口只放在 app/main.c,测试入口只放在 tests/test_core.c。以后新增其他可执行程序时,可以继续复用同一个核心库。
用 target 表达模块边界
下面四个 C 文件都是片段示例,依赖本节后面的顶层 CMakeLists.txt 共同组成完整工程,不单独执行。先定义公共接口 include/mytool/core.h:
#ifndef MYTOOL_CORE_H
#define MYTOOL_CORE_H
int add_numbers(int left, int right);
#endifsrc/core.c 实现核心逻辑,不处理命令行入口职责:
#include "mytool/core.h"
int add_numbers(int left, int right) {
return left + right;
}app/main.c 通过公共接口调用核心模块,而不是直接包含实现文件:
#include <stdio.h>
#include "mytool/core.h"
int main(void) {
printf("%d\n", add_numbers(2, 3));
return 0;
}tests/test_core.c 同样只通过公共接口访问核心模块:
#include "mytool/core.h"
int main(void) {
return add_numbers(2, 3) == 5 ? 0 : 1;
}顶层 CMakeLists.txt 再把目录职责转换成真正的构建依赖:
cmake_minimum_required(VERSION 3.24)
project(mytool LANGUAGES C)
add_library(tool_core src/core.c)
target_include_directories(tool_core
PUBLIC
${CMAKE_CURRENT_SOURCE_DIR}/include
)
add_executable(mytool app/main.c)
target_link_libraries(mytool PRIVATE tool_core)
include(CTest)
if(BUILD_TESTING)
add_executable(tool_tests tests/test_core.c)
target_link_libraries(tool_tests PRIVATE tool_core)
add_test(NAME tool_tests COMMAND tool_tests)
endif()这里最重要的是 tool_core。它把核心实现从“几个源文件”提升为可复用模块;PUBLIC 头文件路径会传递给依赖它的 mytool 和 tool_tests,但应用入口与测试代码之间不存在直接依赖。
构建并验证依赖关系
完成文件内容后,执行一次配置、构建、程序运行和测试。下面示例假设使用类 Unix 环境中的单配置生成器,并隐藏 CMake 的常规构建日志,只保留验收结果。
set -e
cmake -S . -B build -DBUILD_TESTING=ON >/dev/null
cmake --build build >/dev/null
./build/mytool
ctest --test-dir build --output-on-failure >/dev/null
printf 'tests passed\n'预期输出
5
tests passed程序输出 5 说明应用已经正确链接 tool_core;ctest 返回成功后才会打印 tests passed,因此第二行同时证明测试 target 已建立并通过。
判断目录是否真的合理
目录规划完成后,可以用两个问题做检查。第一,核心逻辑能否在不启动命令行程序的情况下被测试;如果不能,说明 main.c 中仍混入了业务逻辑。第二,新增另一个程序入口时,是否只需链接 tool_core;如果还需要复制源文件或引用 app 目录,说明模块边界仍不清晰。
工程规模变大后可以继续拆分更多库,但原则不变:先让每个 target 有明确职责,再让目录服务于这些职责,而不是先创建大量文件夹再寻找用途。