C++ 工程实践记录：性能、资源管理和长期维护

C++ 的价值不只是快#

很多人谈 C++ 时会直接落到性能。它确实有这个优势，尤其是需要控制内存布局、减少分配、靠近系统接口、处理大量数据或做低延迟任务时，C++ 有很强的表达力。但如果只把 C++ 当成“更快的语言”，很容易写出一种危险的代码：每个地方都想省一点，每个函数都想少一次拷贝，每个结构都想压到极致，结果整个系统变得很脆。

工程里的性能不是一句“用 C++ 就快”能解决的。快来自几个层面：数据结构选得合适，内存访问模式稳定，分配次数可控，接口边界不制造不必要的拷贝，关键路径能被测量，异常路径不会把主流程拖垮。语言只是给了你这些能力，真正把它们用起来还需要设计。

比如处理一批数据时，单纯把所有函数都写成引用传参，并不会自动变快。真正有影响的可能是数据是否连续、遍历顺序是否友好、对象是否频繁构造、缓存命中是否稳定。很多时候，性能问题不是出在语法层，而是出在数据流。

1
struct Sample {
2
    double x;
3
    double y;
4
    double weight;
5
};
6

7
double weighted_sum(std::span<const Sample> samples) {
8
    double total = 0.0;
9
    for (const auto& item : samples) {
10
        total += (item.x + item.y) * item.weight;
11
    }
12
    return total;
13
}

这段代码没有炫技，只是把输入表达成一段连续视图。调用者可以传 vector，也可以传数组，函数不用关心所有权。相比把容器复制进函数，或者让函数保存外部引用，这种写法的边界更清楚。它并不保证性能一定最好，但它让后面的优化有了稳定起点。

我更愿意把 C++ 的价值理解成“可控”。性能可控，资源可控，布局可控，依赖可控，生命周期可控。可控带来的不是随便优化，而是知道每一层的代价在哪里。写 C++ 时，如果一个抽象让代价变得完全看不见，就要谨慎；如果一个优化让边界变得完全看不懂，也要谨慎。

资源管理要靠结构，不靠记性#

C++ 项目最怕的一类问题，是资源生命周期靠人脑记。打开文件后记得关，申请内存后记得释放，加锁后记得解锁，注册回调后记得注销。单独看每个地方都不难，但项目变大之后，人总会漏。

RAII 是 C++ 里非常朴素但非常重要的思想。资源的生命周期跟对象绑定，让构造和析构承担获取与释放。这样代码不需要在每条分支上手动收尾，异常、提前返回和错误路径也更容易保持一致。

1
class FileHandle {
2
public:
3
    explicit FileHandle(std::FILE* fp) : fp_(fp) {}
4

5
    ~FileHandle() {
6
        if (fp_) {
7
            std::fclose(fp_);
8
        }
9
    }
10

11
    FileHandle(const FileHandle&) = delete;
12
    FileHandle& operator=(const FileHandle&) = delete;
13

14
    FileHandle(FileHandle&& other) noexcept : fp_(other.fp_) {
15
        other.fp_ = nullptr;
16
    }
17

18
    FileHandle& operator=(FileHandle&& other) noexcept {
19
        if (this != &other) {
20
            if (fp_) {
21
                std::fclose(fp_);
22
            }
23
            fp_ = other.fp_;
24
            other.fp_ = nullptr;
25
        }
26
        return *this;
27
    }
28

29
    std::FILE* get() const { return fp_; }
30

31
private:
32
    std::FILE* fp_{nullptr};
33
};

这个例子并不复杂，但它体现了 C++ 资源管理里几个关键点：资源要有明确所有者；不能随便复制所有权；可以移动，但移动后原对象要进入安全状态；析构函数负责收尾。现代 C++ 里很多时候可以直接用标准库类型，比如 unique_ptr、shared_ptr、lock_guard、jthread，不必自己写包装。但理解这个思路很重要。

智能指针也不是越多越好。unique_ptr 表达独占所有权，适合大部分明确归属的对象。shared_ptr 表达共享所有权，但共享也意味着生命周期变复杂。如果一个对象到处被 shared_ptr 持有，到头来谁也说不清它应该什么时候结束，那其实只是把问题从裸指针换成了引用计数。

1
class Decoder {
2
public:
3
    std::vector<std::byte> decode(std::span<const std::byte> input);
4
};
5

6
class Pipeline {
7
public:
8
    explicit Pipeline(std::unique_ptr<Decoder> decoder)
9
        : decoder_(std::move(decoder)) {}
10

11
    std::vector<std::byte> run(std::span<const std::byte> input) {
12
        return decoder_->decode(input);
13
    }
14

15
private:
16
    std::unique_ptr<Decoder> decoder_;
17
};

这里 Pipeline 拥有 Decoder，关系很直接。如果未来需要共享，可以再改；但一开始就用共享所有权，反而会让设计变模糊。C++ 写久了会发现，很多 bug 不是因为指针这个工具本身，而是因为所有权没有被设计清楚。

资源管理的另一个细节是异常安全。并不是所有项目都使用异常，但无论是否使用异常，函数都可能在中途失败。RAII 的好处是让失败路径不需要额外记忆。如果每个资源都有对象托管，那么错误返回时自然会释放资源。相比在每个 if 分支里手动清理，这种结构更稳。

接口边界比技巧更重要#

C++ 的表达能力很强，也很容易把接口写得过于自由。一个函数既接收裸指针，又接收引用，又通过输出参数返回结果，还可能把内部缓存暴露出去。短期看很灵活，长期看会很难维护。

我现在更倾向于让接口表达几件事：谁拥有资源，谁只是观察，函数是否会修改输入，失败如何返回，结果是否需要拷贝。只要这些边界说清楚，内部实现就算后面换掉，也不会影响调用者太多。

1
struct ParseError {
2
    std::string message;
3
    std::size_t offset{};
4
};
5

6
struct Config {
7
    std::string name;
8
    int workers{};
9
};
10

11
std::expected<Config, ParseError> parse_config(std::string_view text);

这类接口比“传一个字符串，返回 bool，再通过引用填结果”的写法更明确。调用者知道成功时拿到 Config，失败时拿到 ParseError。错误信息不需要靠全局状态，也不需要靠额外输出参数。expected 不是唯一选择，项目也可以自己定义结果类型，但方向是一样的：让成功和失败都成为接口的一部分。

模板和泛型也要克制。C++ 的模板非常强，但模板一多，编译错误和构建时间都会变重。通用代码确实能减少重复，但如果只是为了少写几行而把接口搞得难懂，就不值得。尤其是业务边界或模块边界，我更愿意使用普通类型和清晰函数，而不是到处塞泛型。

1
template <class Clock>
2
class RateLimiter {
3
public:
4
    explicit RateLimiter(std::chrono::milliseconds interval)
5
        : interval_(interval), next_(Clock::now()) {}
6

7
    bool allow() {
8
        const auto now = Clock::now();
9
        if (now < next_) {
10
            return false;
11
        }
12
        next_ = now + interval_;
13
        return true;
14
    }
15

16
private:
17
    std::chrono::milliseconds interval_;
18
    typename Clock::time_point next_;
19
};

这个模板的价值是测试时可以注入假时钟，生产时用真实时钟。它解决了具体问题。相比之下，如果只是为了让任何类型都能传进来，却没有清晰约束，那就很容易把复杂度推给调用方。

接口边界还包括头文件组织。C++ 的头文件会影响编译速度，也会影响模块耦合。能前向声明的地方不要随便包含大头文件；能隐藏实现细节的地方不要把内部类型放进公共头。头文件不是简单的声明集合，它实际决定了依赖图。

构建系统要尽早整理#

小项目里，C++ 构建经常被随手处理。几个源文件，一个命令，能编译就行。项目一大，问题就来了：不同平台编译选项不一致，第三方库版本不清楚，测试目标和主程序混在一起，Debug 与 Release 行为差别很大。

CMake 不是完美工具，但它现在仍然是 C++ 工程里绕不开的组织方式。我的习惯是让 CMake 目标尽量清楚：库是库，可执行文件是可执行文件，测试是测试；公共 include 和私有 include 分开；编译特性通过 target 设置，不在全局随便加。

1
cmake_minimum_required(VERSION 3.24)
2
project(engine_core LANGUAGES CXX)
3

4
add_library(engine_core
5
    src/parser.cpp
6
    src/pipeline.cpp
7
)
8

9
target_compile_features(engine_core PUBLIC cxx_std_23)
10
target_include_directories(engine_core
11
    PUBLIC include
12
    PRIVATE src
13
)
14

15
add_executable(engine_cli src/main.cpp)
16
target_link_libraries(engine_cli PRIVATE engine_core)

这段配置没有多少内容，但比把所有文件塞进一个目标要清楚。engine_core 是核心库，engine_cli 是命令行入口。以后加测试，可以链接核心库；以后换入口，也不用动核心逻辑。

构建配置还应该尽早把警告、格式和静态检查纳入习惯。C++ 很多错误编译器能提前提醒，但前提是你愿意听。开启合理警告，定期跑静态分析，不是为了追求形式，而是为了把一部分低级问题挡在提交前。

1
target_compile_options(engine_core PRIVATE
2
    $<$<CXX_COMPILER_ID:Clang,GNU>:-Wall -Wextra -Wpedantic>
3
    $<$<CXX_COMPILER_ID:MSVC>:/W4>
4
)

当然，警告也不能盲目堆。项目里如果有第三方头文件，或者需要兼容不同编译器，就要区分自己的代码和外部代码。目标很简单：自己能控制的部分尽量保持干净，外部依赖不要让它们的警告淹没真正的问题。

依赖管理也是长期维护的一部分。C++ 生态不像 Python 或 Rust 那样有统一包管理体验，项目会遇到系统包、源码引入、vcpkg、Conan、FetchContent 等不同方案。我的倾向是尽量少引入依赖，引入后固定版本，构建方式写清楚。依赖越多，迁移和排查就越难。

跨平台也要尽早放进考虑里。C++ 项目很容易在一台机器上跑得很好，换到另一套编译器、标准库或操作系统后开始暴露问题。换行、路径、字符编码、动态库加载、线程调度、文件权限、浮点细节，这些东西单独看都不大，但叠在一起就会消耗很多排查时间。写工程时，平台差异不能等到发布前才想起来。

我比较喜欢把平台相关代码压到少数边界里。核心逻辑尽量用标准库和项目自己的抽象，真正需要系统能力时再集中封装。这样做不是为了把所有差异抹平，而是为了让差异有固定位置。比如文件系统、时间、网络、动态库这些能力，如果散落在业务逻辑里，后面迁移平台会非常难受。

1
class Clock {
2
public:
3
    virtual ~Clock() = default;
4
    virtual std::chrono::steady_clock::time_point now() const = 0;
5
};
6

7
class SystemClock final : public Clock {
8
public:
9
    std::chrono::steady_clock::time_point now() const override {
10
        return std::chrono::steady_clock::now();
11
    }
12
};

这类抽象不用到处写，但在需要测试时间逻辑、控制超时行为或适配不同运行环境时很有用。它的价值不是“面向对象”，而是把不可控的外部因素收在一个接口后面。C++ 项目长期维护时，很多麻烦都来自外部环境变化，给这些变化留出边界，会比临时补丁稳得多。

性能要测，不要靠感觉#

C++ 很容易让人产生一种错觉：因为语言本身性能强，所以自己的代码也应该快。实际不是这样。错误的数据结构、不必要的分配、糟糕的缓存访问、锁竞争、过度抽象，都能让 C++ 写出很慢的程序。

性能优化应该从测量开始。没有测量时，很多判断只是猜。猜测当然可以作为排查线索，但不能作为结论。哪怕只是简单的基准测试，也比凭感觉改代码要靠谱。

1
auto begin = std::chrono::steady_clock::now();
2

3
for (int i = 0; i < rounds; ++i) {
4
    benchmark_target(input);
5
}
6

7
auto end = std::chrono::steady_clock::now();
8
auto cost = std::chrono::duration_cast<std::chrono::microseconds>(end - begin);
9

10
std::cout << "cost: " << cost.count() << "us\n";

这个测量很粗，但能帮助你发现数量级问题。更严肃的性能分析应该使用专门工具，控制输入规模，避免编译器把代码优化掉，区分冷启动和热路径。这里的重点不是某个具体工具，而是建立习惯：性能结论要有数据。

内存分配是 C++ 性能里很常见的成本来源。很多时候，少一次分配比少一次普通函数调用更有意义。比如循环里反复创建临时字符串，或者每个元素都单独分配对象，都会让性能变差。

1
std::vector<std::string> normalize(std::span<const std::string_view> names) {
2
    std::vector<std::string> output;
3
    output.reserve(names.size());
4

5
    for (auto name : names) {
6
        std::string item{name};
7
        trim_in_place(item);
8
        to_lower_in_place(item);
9
        output.push_back(std::move(item));
10
    }
11

12
    return output;
13
}

reserve 很朴素，但它经常有效。移动语义也不是为了写得高级，而是为了让所有权转移表达清楚。性能优化里很多有效手段都不神秘，只是需要你知道成本在哪。

内存布局也值得关注。对象数组和指针数组在访问模式上差别很大。连续数据对缓存更友好，但如果对象很大，或者只访问少数字段，也可能需要拆结构。这里没有一条固定规则，关键是结合访问模式。

1
struct ParticleBlock {
2
    std::vector<float> x;
3
    std::vector<float> y;
4
    std::vector<float> vx;
5
    std::vector<float> vy;
6
};
7

8
void step(ParticleBlock& block, float dt) {
9
    for (std::size_t i = 0; i < block.x.size(); ++i) {
10
        block.x[i] += block.vx[i] * dt;
11
        block.y[i] += block.vy[i] * dt;
12
    }
13
}

这种布局并不适合所有场景，但在只处理少数字段的大量数据时，它可能比对象数组更友好。C++ 的优势在于你能做这种选择，但选择之前要理解访问路径。

并发边界要小#

C++ 并发很强，也很危险。线程、锁、原子、条件变量，每个工具都能解决问题，也都能制造问题。我的经验是，并发边界越小越好。能把并发限制在少数模块里，就不要让整个系统都知道线程存在。

一种常见做法是让任务通过队列进入工作线程，外部只看到提交和结果，不直接接触锁。这样并发复杂度集中在队列和 worker 内部，其他模块保持普通同步代码。

1
class Counter {
2
public:
3
    void add(int value) {
4
        std::lock_guard lock(mutex_);
5
        value_ += value;
6
    }
7

8
    int value() const {
9
        std::lock_guard lock(mutex_);
10
        return value_;
11
    }
12

13
private:
14
    mutable std::mutex mutex_;
15
    int value_{0};
16
};

这个例子很简单，但它体现了一个原则：状态和保护它的锁放在一起。不要让调用者自己记得先锁哪个 mutex，再访问哪个对象。锁如果散在外面，长期一定会出错。

C++20 之后的 jthread 也让线程生命周期更好处理。线程对象析构时能自动 join，并且支持停止请求，比手动管理线程更安全。

1
class Worker {
2
public:
3
    Worker() : thread_([this](std::stop_token token) { run(token); }) {}
4

5
private:
6
    void run(std::stop_token token) {
7
        while (!token.stop_requested()) {
8
            do_one_round();
9
        }
10
    }
11

12
    std::jthread thread_;
13
};

并发设计里，取消、退出和资源释放经常比启动更难。线程能跑起来只是开始，能稳定停下来才是工程。服务关闭、测试清理、异常退出，都需要考虑线程生命周期。

原子操作也不是越多越好。atomic 能避免某些锁成本，但它不会让复杂状态自动安全。如果多个字段之间有一致性关系，单独把它们都变成原子并不能解决问题。遇到复杂状态，清晰的锁有时比聪明的无锁写法更可靠。

错误处理和日志要服务排查#

C++ 项目里错误处理风格差异很大。有的项目使用异常，有的项目禁用异常，有的项目使用错误码，有的项目使用结果类型。具体选哪种要看团队和场景，但无论选择什么，都要让错误能被定位。

我不太喜欢只返回 false 的接口。失败时没有上下文，排查只能靠猜。更好的方式是把错误原因、位置和必要上下文带出来，同时不要让错误处理把主流程写得很乱。

1
enum class LoadErrorKind {
2
    NotFound,
3
    InvalidFormat,
4
    UnsupportedVersion,
5
};
6

7
struct LoadError {
8
    LoadErrorKind kind;
9
    std::string detail;
10
};
11

12
std::expected<Document, LoadError> load_document(std::string_view path);

错误类型不一定要复杂，但要足够表达问题。日志也是同样。日志不是越多越好，而是关键位置要有信息：输入规模、配置摘要、任务标识、耗时、失败原因。只写“failed”基本没什么用。

性能日志也要注意成本。热路径上不能随便拼接大字符串，也不能每次循环都输出。C++ 里日志库的异步能力、格式化成本和级别过滤都需要留意。很多项目不是没有日志，而是日志要么太少无法排查，要么太多影响运行。

错误处理还有一个容易被忽略的地方：错误边界要和模块边界一致。底层模块可以知道文件、网络、解析细节，但上层不一定需要知道所有底层枚举。反过来，上层的业务语义也不应该硬塞到底层。错误如果一路原样透传，调用方会被迫理解太多实现细节；错误如果被过度包装，又会丢掉排查信息。比较舒服的做法是在模块边界补充上下文，同时保留足够的原始原因。

1
std::expected<Project, ProjectError> load_project(std::string_view path) {
2
    auto config = load_project_config(path);
3
    if (!config) {
4
        return std::unexpected(ProjectError{
5
            .message = "project config cannot be loaded",
6
            .detail = config.error().detail,
7
        });
8
    }
9

10
    return build_project(*config);
11
}

这段代码没有把底层错误完全吃掉，而是在项目边界补了一层语义。真正排查时，既能看到“项目配置加载失败”，也能继续追到底层细节。C++ 里的错误处理方式很多，异常、错误码、结果类型都能用，关键是不要让失败变成没有上下文的黑洞。

测试要覆盖边界，不只覆盖顺路#

C++ 测试经常被低估。有人觉得 C++ 项目难测，或者测试搭起来麻烦，于是只靠手动运行。短期看省事，长期看风险很大。C++ 的很多问题在边界条件才出现，比如空输入、极大输入、重复释放、并发退出、异常路径、平台差异。

测试不一定一开始就很完整，但核心逻辑应该能离开主程序单独跑。前面提到把核心库和入口拆开，就是为了这个。

1
TEST(ParserTest, RejectsEmptyInput) {
2
    auto result = parse_config("");
3

4
    ASSERT_FALSE(result.has_value());
5
    EXPECT_EQ(result.error().offset, 0u);
6
}

测试要尽量靠近行为，而不是靠近实现。比如解析器应该测输入和输出，不要测内部用了几个临时对象。这样后面重构时测试还能保留。

对性能敏感的模块，也可以保留基准测试。基准测试不是每次提交都要卡得很死，但它能记录性能趋势。某次改动之后耗时突然翻倍，能尽早发现。

并发模块的测试更麻烦。它们需要避免依赖偶然时序，尽量使用可控的同步点、假时钟或小范围压力测试。不要指望一次跑通就说明并发没有问题，但有测试总比完全靠线上观察好。

测试还可以帮助约束接口。C++ 里重构时很容易不小心改变对象生命周期或错误语义，编译器只能检查类型层面的正确性，行为层面的变化仍然需要测试兜住。尤其是解析、序列化、缓存、状态机、任务调度这类模块，测试最好覆盖输入边界和状态变化，而不是只测一条顺路。

1
TEST(CacheTest, EvictsOldestEntryWhenCapacityIsReached) {
2
    Cache cache{2};
3

4
    cache.put("a", "1");
5
    cache.put("b", "2");
6
    cache.put("c", "3");
7

8
    EXPECT_FALSE(cache.find("a").has_value());
9
    EXPECT_EQ(cache.find("b").value(), "2");
10
    EXPECT_EQ(cache.find("c").value(), "3");
11
}

这种测试不是为了证明缓存内部用了什么结构，而是把外部行为固定下来。后面想把 list 换成别的数据结构，或者想调整内存布局，只要行为不变，测试就不应该跟着改。长期维护时，测试保护的应该是契约，不是实现细节。

长期维护靠约束#

C++ 项目能不能长期维护，很大程度上取决于约束有没有建立起来。编码风格、所有权规则、错误处理方式、构建目标、依赖引入标准、性能测量方式，这些东西不一定要写成很厚的规范，但要有共同习惯。

我比较在意几条约束。公共接口尽量稳定，内部实现可以换；资源所有权要能从类型上看出来；热路径优化要有数据；第三方依赖要谨慎；构建和测试要能在干净环境里跑；复杂模板和宏要有明确理由；并发状态要收在小范围里。

这些约束听起来普通，但它们能阻止项目慢慢变成一团难拆的代码。C++ 的自由度很高，如果没有约束，每个人都能写出自己喜欢的一套风格。项目小的时候还能看，项目大了就会很累。

后续维护还包括升级编译器和标准版本。C++ 标准演进很快，新特性确实能改善代码表达，比如 span、expected、jthread、ranges、modules 等。但升级不是看到新东西就用。要看工具链支持、平台兼容、团队熟悉程度和构建成本。新特性应该解决实际问题，而不是只为了显得现代。

文档也很重要。C++ 代码里很多边界靠约定，约定如果不写下来，新人很难知道。哪些模块拥有资源，哪些接口不能跨线程调用，哪些对象只能在特定生命周期内使用，哪些性能假设不能破坏，都应该留痕。

还有一类维护工作比较不起眼，但时间长了很关键：把“为什么这样写”留下来。C++ 项目里经常会有一些看起来奇怪的选择，比如某个结构故意不用虚函数，某段代码故意保留一次拷贝，某个锁故意放在更外层，某个容器没有换成看起来更快的实现。如果没有说明，后面的人很可能按直觉改掉，结果把原来规避的问题带回来。

我不太喜欢在代码里写太多解释语法的注释，但会给重要取舍留短说明。尤其是性能路径、线程边界、资源所有权、跨平台兼容这几类地方，注释不是给当前作者看的，而是给未来维护时的自己看的。C++ 很多问题不是当场炸，而是改动叠几轮之后才出现。把关键假设写下来，能减少这种“慢慢偏掉”的风险。

1
// Keep the buffer owned by Session. Worker threads only borrow immutable views.
2
// Moving ownership into workers makes shutdown ordering harder to reason about.
3
class Session {
4
public:
5
    std::span<const std::byte> payload() const { return payload_; }
6

7
private:
8
    std::vector<std::byte> payload_;
9
};

这种注释很短，但它说明了所有权为什么这样放。以后有人想把 payload_ 移到 worker 里，就会先看到这里的约束。长期项目里，代码表达事实，注释表达取舍。两者都克制，维护起来会舒服很多。

发布和回滚也属于 C++ 工程维护。编译产物、动态库版本、运行参数、配置文件格式、数据文件兼容性，都可能影响上线。C++ 程序经常贴近系统环境，发布时不能只看二进制能不能启动，还要看依赖是否齐全、CPU 指令集是否匹配、旧配置是否还能读、日志是否能看懂。很多线上问题和语言语法无关，都是发布链路里的假设没有被验证。

继续维护这把工具#

C++ 很适合写对性能、资源和系统边界有要求的东西，但它不会自动给你一个好工程。它给的是能力，不是秩序。秩序要靠项目自己建立：清楚的所有权、稳定的接口、可重复的构建、可验证的性能、能覆盖边界的测试，以及愿意长期维护的习惯。

我现在写 C++，不会只盯着某个语法是否漂亮。更关心的是半年之后还能不能安全改，性能问题能不能复现，资源问题能不能从结构上避免，构建出错时能不能定位，接口变化会不会牵一大片。真正的工程质量往往藏在这些地方。

这篇记录也会继续更新。后面如果在实际项目里遇到更具体的构建组织、性能分析、并发退出、跨平台兼容或工具链升级问题，还会再补。C++ 的维护不是一次写完代码就结束，而是持续把代价看清楚，把边界守住，让这把工具在长期使用里保持锋利。