C / C++ / 系统课时

规划项目模块和目录结构

规划项目模块和目录结构

这一节先不急着堆功能,而是把命令行工具拆成可维护的工程骨架:核心逻辑放进独立库,公共头文件形成稳定接口,应用入口只负责调用,测试代码单独组织,并用 CMake 验证依赖方向。

学习目标

  • 根据职责拆分核心模块、公共接口、应用入口和测试代码
  • 让目录结构与 CMake target 对应,避免依赖关系隐藏在文件路径里
  • 建立可以直接配置、构建和测试的最小工程骨架

先按职责划分四个区域

一个小型命令行工具也会同时包含业务逻辑、对外接口、程序入口和测试。如果全部堆在同一个目录,main.c 很容易逐渐混入计算、文件操作和测试辅助逻辑,后续既难复用,也难单独验证核心功能。

建议把工程划成四个区域:src 放核心实现,include/mytool 放允许其他 target 使用的公共头文件,app 放最终可执行程序入口,tests 放测试程序。顶层 CMakeLists.txt 负责把这些区域组织成真正的构建目标。

命令行工具模块与目录依赖关系

这种划分的关键不是文件夹名称本身,而是依赖方向:应用和测试都依赖核心库,核心库不应该知道命令行入口或测试程序的存在。

建立最小目录骨架

下面的命令在类 Unix 环境中创建本节需要的目录和空文件。它只建立工程骨架,不写入业务代码。

bash
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'

预期输出

text
project skeleton created

创建完成后,五个文件各自承担单一职责:公共声明进入头文件,核心实现进入 src,命令行入口只放在 app/main.c,测试入口只放在 tests/test_core.c。以后新增其他可执行程序时,可以继续复用同一个核心库。

用 target 表达模块边界

下面四个 C 文件都是片段示例,依赖本节后面的顶层 CMakeLists.txt 共同组成完整工程,不单独执行。先定义公共接口 include/mytool/core.h:

c
#ifndef MYTOOL_CORE_H
#define MYTOOL_CORE_H

int add_numbers(int left, int right);

#endif

src/core.c 实现核心逻辑,不处理命令行入口职责:

c
#include "mytool/core.h"

int add_numbers(int left, int right) {
    return left + right;
}

app/main.c 通过公共接口调用核心模块,而不是直接包含实现文件:

c
#include <stdio.h>
#include "mytool/core.h"

int main(void) {
    printf("%d\n", add_numbers(2, 3));
    return 0;
}

tests/test_core.c 同样只通过公共接口访问核心模块:

c
#include "mytool/core.h"

int main(void) {
    return add_numbers(2, 3) == 5 ? 0 : 1;
}

顶层 CMakeLists.txt 再把目录职责转换成真正的构建依赖:

cmake
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 的常规构建日志,只保留验收结果。

bash
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'

预期输出

text
5
tests passed

程序输出 5 说明应用已经正确链接 tool_core;ctest 返回成功后才会打印 tests passed,因此第二行同时证明测试 target 已建立并通过。

判断目录是否真的合理

目录规划完成后,可以用两个问题做检查。第一,核心逻辑能否在不启动命令行程序的情况下被测试;如果不能,说明 main.c 中仍混入了业务逻辑。第二,新增另一个程序入口时,是否只需链接 tool_core;如果还需要复制源文件或引用 app 目录,说明模块边界仍不清晰。

工程规模变大后可以继续拆分更多库,但原则不变:先让每个 target 有明确职责,再让目录服务于这些职责,而不是先创建大量文件夹再寻找用途。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

规划项目模块和目录结构

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通