C++自定义迭代器实战：适配器模式让STL算法识别列式存储

先说个真实场景。之前业务里有一个自研的列式日志存储，底层按列存时间戳、级别、消息文本，一行日志的数据分散在不同缓冲区里。业务代码想复用std::count_if、std::find_if这些标准库算法，结果发现算法根本不认识这个存储结构。标准库算法只认迭代器，不认任何“容器类型”。想要让算法跑起来，就得按迭代器协议补一层适配，这就是自定义迭代器配合适配器模式的核心价值。

这篇文章就围绕这条线展开：先拆解迭代器协议到底是什么，再讲适配器模式怎么落地到自定义迭代器上，最后给出一个完整的列式存储迭代器示例和一套避坑清单。适合正在跟 STL 算法较劲、或者想给自研容器接上标准库生态的 C++ 开发者，不管你是上手阶段还是已经踩过几个编译错误，应该都有参考价值。

1. 为什么标准库算法只认迭代器不认容器

1.1 算法与容器的解耦设计

先看一个最简单的例子：

template<class InputIt, class T> InputIt find(InputIt first, InputIt last, const T& value);

注意这个签名里没有出现任何容器类型，只有“迭代器区间”。也就是说，标准库算法在设计层面从不过问数据到底存在std::vector、std::list还是自研的列式存储里，它只要求你提供两个迭代器：一个指向开头，一个指向结尾，并且这两个迭代器能支持“解引用当前位置”“移动到下一个位置”“比较是否到达末尾”这几件事。

这个设计的妙处在于，算法的关注点从“数据形态”转移到了“访问方式”。你可以把算法当成一个只认路书的司机，路书只需要保证每隔一段能读到路标、能向前挪动，至于路是柏油路还是土路，司机不关心。

放到 C++ 的世界里，迭代器就是这份路书。标准库算法被设计成模板，编译期通过静态多态来匹配迭代器能力，而不是像 Java、C# 那样要求迭代器必须继承某个抽象接口。这种设计让自定义迭代器变得极其轻量：你不需要继承任何基类，只需要保证类型长相和行为符合算法期望即可，C++ 领域管这叫鸭子类型。

1.2 自定义容器什么时候必须写迭代器

很多人的第一反应是：既然标准库容器都有迭代器，那我直接用std::vector不就行了？确实，如果数据可以规规矩矩地装进标准容器，自己写迭代器属于没事找事。但有几类场景下，标准容器根本没法直接用：

• 列式存储：数据按列分开存放，一行数据需要从多个列缓冲区里组合出来，语义上是“行”，物理上却不是连续结构。
• 数据库游标：查询结果可能流式返回，底层可能是网络包或磁盘页，但业务希望用 STL 算法做过滤、统计。
• 加密或压缩数据：原始数据经过编码，解引用迭代器时需要实时解码出逻辑值。
• 内存映射的特定格式文件：文件里可能有头部、索引、记录区，直接按偏移量读取比拷贝到标准容器更高效。

这些场景的共同点是：底层数据形态与“标准容器 + 连续对象”的假设不一致，但业务代码又希望复用标准库那几十个已经打磨好的算法。这时候写一个自定义迭代器，相当于给算法递上一份它认识的路书。

需要说明的是，下面所有内容并不是要求你给每个自研容器都硬造迭代器，而是当你确实需要“让算法认识新数据结构”时，知道这条适配链路该怎么铺。

2. 迭代器协议拆解：给算法验明正身的那些类型

2.1 五个关键类型到底是什么

一个迭代器类型想要被标准库算法正常使用，历史上必须暴露五个类型别名，C++20 之后pointer变得可选，但理解它们仍然很重要：

很多人写自定义迭代器时最容易犯的错，就是把reference直接写成T&，然后发现*it返回临时对象时编译不过。实际上reference不一定是真正的左值引用，它可以是“代理类型”。最典型的例子是std::vector<bool>，它的reference是一个内部代理类，负责表示单个 bit，并不是真正的bool&。

理解这一点是适配器模式实现的关键：当你不能给出真正的引用时，就用一个轻量代理对象作为reference，只要这个代理能用、可比较、可转换，算法照样能工作。

2.2 迭代器分类标签选错了会怎样

iterator_category是迭代器协议里信息量最大的一个类型，它直接对应迭代器的五种能力级别：输入迭代器、输出迭代器、前向迭代器、双向迭代器、随机访问迭代器。标准库算法的很多实现会根据这个标签做“标签派发”，选择不同的内部策略。

选错标签最直接的后果是算法复杂度退化。举个例子，std::distance在随机访问迭代器上可以直接return last - first;，复杂度 O(1)；在前向迭代器上只能while (first != last) ++first, ++n;，复杂度 O(N)。如果你的迭代器明明支持随机跳转，却把标签写成forward_iterator_tag，std::distance就会老老实实地一格一格往后数。

反过来更糟糕：如果你的迭代器实际上做不到随机访问，却把标签写成random_access_iterator_tag，后果不是编译错误，而是各种诡异行为。比如std::sort内部会使用it + n、it - n这种运算，你的迭代器如果没有真正实现这些运算，编译直接失败；就算硬凑出来，性能也会和承诺完全不符。

所以我给的建议是：标签不是荣誉勋章，而是能力承诺。承诺了双向能力，就必须支持--it；承诺了随机访问，就必须支持it + n。图一时省事承诺过头，早晚会在某个算法里付出代价。

2.3 类型别名在算法内部如何被使用

以std::remove_if为例，它的内部会通过std::iterator_traits<It>::value_type拿到元素类型，并对区间里的元素做移动赋值。如果你的value_type给错了，算法可能无法编译；如果你的reference是临时代理类型但value_type又是另一个类型，算法里某些类型推导也会出幺蛾子。

这也是为什么标准库算法都是模板：类型别名的正确性是在编译期被校验的。与其记住一堆规则，不如直接掌握校验工具。C++20 里可以用概念（concept）在编译期断言：

static_assert(std::forward_iterator<MyIterator>);

这一行比任何文档都有说服力。写了好几个.h文件之后，先别急着跑算法，把这句话贴上，概念没过就说明你的迭代器还缺东西，编译器会把具体缺口报出来。

3. 适配器模式的落地：把列式日志行包装成标准迭代器

3.1 需求场景：一个按列存储的日志系统

假设我们有这样一个日志存储：

class LogStore { public: void add(std::int64_t ts, int level, std::string msg) { ts_.push_back(ts); level_.push_back(level); msg_.push_back(std::move(msg)); } std::size_t rows() const { return ts_.size(); } std::int64_t tsAt(std::size_t i) const { return ts_[i]; } int levelAt(std::size_t i) const { return level_[i]; } const std::string& msgAt(std::size_t i) const { return msg_[i]; } private: std::vector<std::int64_t> ts_; std::vector<int> level_; std::vector<std::string> msg_; };

这里三个字段分别存在三个std::vector里。从物理布局看，它是标准的列式存储，写入时对缓存友好，批量压缩也方便。但从算法角度看，它不提供“一行日志”的连续对象，标准库算法没法直接用。

需求是：不需要把数据完整拷贝成std::vector<LogRow>，而是让算法能像遍历普通容器一样遍历这个列式存储。

3.2 核心设计：LogRowIterator 的骨架

适配器模式在这个场景里的做法是：设计一个迭代器对象，内部持有底层存储的指针和当前行号，每次解引用时“即时组装”出一个代表当前行的轻量视图对象。

先定义行视图：

class LogRow { public: LogRow(const LogStore* store, std::size_t row) : store_(store), row_(row) {} std::int64_t timestamp() const { return store_->tsAt(row_); } int level() const { return store_->levelAt(row_); } const std::string& message() const { return store_->msgAt(row_); } private: const LogStore* store_; std::size_t row_; };

注意LogRow本身不是一个“独立数据”，它是底层存储的视图。它很轻量，只存了一个指针和一个行号，所有访问都是转发到底层存储。

再写迭代器：

class LogRowIterator { public: using iterator_category = std::forward_iterator_tag; using value_type = LogRow; using difference_type = std::ptrdiff_t; using pointer = const LogRow*; using reference = LogRow; LogRowIterator() = default; LogRowIterator(const LogStore* store, std::size_t row) : store_(store), row_(row) {} reference operator*() const { return LogRow(store_, row_); } LogRowIterator& operator++() { ++row_; return *this; } LogRowIterator operator++(int) { auto tmp = *this; ++row_; return tmp; } friend bool operator==(const LogRowIterator& a, const LogRowIterator& b) { return a.store_ == b.store_ && a.row_ == b.row_; } friend bool operator!=(const LogRowIterator& a, const LogRowIterator& b) { return !(a == b); } private: const LogStore* store_ = nullptr; std::size_t row_ = 0; };

这里有几个设计决策值得展开讲。

第一，reference是LogRow而非LogRow&，因为operator*每次返回的都是新建的临时对象。这正好呼应了第一节讲的代理迭代器模式：reference不一定是真引用。

第二，iterator_category我选了forward_iterator_tag。因为LogStore是不可变的，迭代器可以反复遍历同一段数据，多遍扫描没问题，满足前向迭代器的核心要求。我没有选random_access_iterator_tag，因为LogRowIterator并没有实现it + n这样的运算，而且底层是三个独立vector，逻辑上也不存在“稳定地址”的随机访问语义。

第三，我没有写operator->。这是代理迭代器常见的取舍：因为operator*返回临时对象，没有办法安全地返回指向它的指针。标准库算法在实际实现中更依赖*it和std::addressof(*it)，而不是it->，所以实际影响很小。如果你在自定义迭代器里遇到“箭头运算符无法实现”的困惑，记住这不是缺陷，而是代理迭代器的正常特征。

3.3 自由函数与命名空间安排

有了迭代器，还需要提供begin和end自由函数，让范围for和后续的 ranges 算法能找到它们：

inline LogRowIterator begin(const LogStore& store) { return LogRowIterator(&store, 0); } inline LogRowIterator end(const LogStore& store) { return LogRowIterator(&store, store.rows()); }

这两个函数最好放在LogStore所在的命名空间里，这样 ADL（实参相关查找）在查找begin(store)和end(store)时能自动发现它们。for (const auto& row : store)才能正常工作。

3.4 从 input_iterator 到 forward_iterator 的取舍

这里展开一个不少初学者会纠结的问题：既然例子里的LogStore是不可变的，那我直接声明input_iterator_tag不行吗？从编译角度看，很多算法确实能跑起来，但问题出在语义上。

输入迭代器是“单遍”的，它承诺的是：你只能从头到尾走一遍，迭代器拷贝之后，两个拷贝的解引用结果不能保证独立。这让你在遍历过程中不能保存一个旧迭代器、继续用新迭代器推进，然后回头比较两者指向的元素。

前向迭代器则要求“多遍”安全：同一个范围内的多次遍历应该得到相同的结果，迭代器的拷贝在解引用时是独立且有效的。

LogStore是不可变的列式存储，天然满足前向迭代器的多遍要求，所以声明forward_iterator_tag是在告诉算法：你可以在这个区间上做多遍扫描，哪怕代价是某些优化路径走不了。选择标签的本质，是把“底层数据特性”翻译成“算法能利用的能力承诺”。

4. 完整可运行示例与逐步解释

4.1 最小实现跑起来

把上面的代码拼到一起，配上一点测试数据，就能立刻看到效果：

#include <algorithm> #include <iostream> #include <string> #include <vector> // ... LogStore、LogRow、LogRowIterator、begin/end 定义见前文 ... int main() { LogStore logs; logs.add(1001, 0, "session started"); logs.add(1002, 2, "database timeout"); logs.add(1003, 0, "session ended"); logs.add(1004, 1, "retry in progress"); auto warnCount = std::count_if(begin(logs), end(logs), [](const LogRow& r) { return r.level() == 2; }); std::cout << "warning count: " << warnCount << '\n'; auto it = std::find_if(begin(logs), end(logs), [](const LogRow& r) { return r.message().find("timeout") != std::string::npos; }); if (it != end(logs)) { std::cout << "found timeout at ts=" << it->timestamp() << '\n'; } return 0; }

注意上面it->timestamp()能工作吗？我前面说过LogRowIterator没有实现operator->，那it->timestamp()怎么编译？实际上这里有个隐藏细节：如果迭代器没有提供operator->，编译器不会自动帮你调用(*it).timestamp()。但在我给的代码里我没有写operator->，所以上面代码里写it->timestamp()会怎样？答案是：LogRowIterator没有operator->，这段代码不能编译。

那为什么很多示例里it->可以正常使用？因为标准容器的迭代器都实现了operator->。对于代理迭代器，你需要在文中明确：如果要使用it->语法，就必须提供一个“箭头代理对象”，或者干脆用(*it).timestamp()。

为了不让示例误导，这里把访问方式改成(*it).timestamp()：

if (it != end(logs)) { std::cout << "found timeout at ts=" << (*it).timestamp() << '\n'; }

这样就和前面“不提供operator->”的取舍保持一致了。

4.2 复用几十种算法的收益

上面的代码跑起来之后，你会发现一个很有成就感的事实：一旦LogStore有了合法的迭代器，标准库所有基于前向迭代器的算法都能直接套用。比如：

auto maxTs = std::max_element(begin(logs), end(logs), [](const LogRow& a, const LogRow& b) { return a.timestamp() < b.timestamp(); }); auto allInfo = std::all_of(begin(logs), end(logs), [](const LogRow& r) { return r.level() == 0; }); auto countInfo = std::count_if(begin(logs), end(logs), [](const LogRow& r) { return r.level() == 0; });

不用为每个算法单独写循环，不用把数据倒腾到临时vector，性能上也不会因为“先拷贝再遍历”产生额外开销。这就是适配器模式给的杠杆：一次适配，处处复用。

4.3 性能与正确性层面的细节

operator*每次返回一个LogRow临时对象，表面上看似乎有构造开销，但LogRow内部只有两个字段，构造成本几乎可以忽略。真正要避免的是在operator*里拷贝std::string或其他重对象。LogRow::message()返回的是const std::string&，所以“组装一行”并不复制消息文本，只是复制指针和索引。

如果你的value_type本身是个重量级对象，解引用时每次都要深拷贝，那性能就会很糟糕。这时候有两种优化思路：一是把真正重的数据放到底层存储里，value_type只做视图；二是用移动语义配合iter_move定制点，把“按需生成”的对象移交给算法。前面例子已经走了第一种思路，这也是代理迭代器的常见形态。

5. 复杂玩法：C++20 概念约束与 ranges

5.1 把列式存储塞进 ranges 算法

C++20 的 ranges 算法让使用体验更顺滑，因为你可以直接传整个范围对象：

#include <ranges> auto errorRows = std::ranges::filter_view(logs, [](const LogRow& r) { return r.level() == 2; }); for (const auto& row : errorRows) { std::cout << "error: " << row.message() << '\n'; }

logs之所以能被filter_view接收，前提是LogStore被视为一个 range。这要求它对ranges::begin(logs)和ranges::end(logs)可用，而这两个函数会经由 ADL 找到我们定义的begin和end。

可以用静态断言确认它确实满足概念：

static_assert(std::forward_iterator<LogRowIterator>); static_assert(std::ranges::forward_range<LogStore>);

如果断言失败，编译器会告诉你缺了哪个表达式，这比在算法内部报一堆模板错误直观得多。

5.2 迭代器定制点：iter_move 与 iter_swap

C++20 ranges 引入了iter_move和iter_swap两个定制点，专门处理“怎么把迭代器指向的值搬走”和“怎么交换两个迭代器指向的值”。

对于普通迭代器，iter_move(it)默认等价于std::move(*it)，iter_swap(a, b)默认等价于swap(*a, *b)。但代理迭代器的*it是临时对象，默认行为不一定高效。比如你的value_type里有一个大字符串，默认iter_move可能先拷贝一次。

解决办法是为迭代器所在命名空间提供自定义iter_move重载。但这个话题比较深，我建议先把基础迭代器跑通，再考虑定制点优化。方向上记住一句话：代理迭代器写得好不好，最后往往要看iter_move和iter_swap这两个定制点有没有被好好对待。

5.3 半开区间与哨兵模式

C++20 还推出了哨兵（sentinel）概念，允许end返回一个与迭代器不同类型的“终止标记”。示例里end(logs)返回的是LogRowIterator，已经足够。但如果你的终止条件不是“行号到达某个值”，而是“某字段满足某个条件”，哨兵模式就能派上用场。

哨兵的核心在于：只需要定义operator==让迭代器和哨兵可比，算法就能在到达终点时停下来。这给自定义迭代器提供了很大的灵活性，也让“无限数据源 + 条件终止”的写法成为可能。不过这是另一个话题了，这里先提一个方向。

6. 常见问题与避坑手册

6.1 编译错误清单

写自定义迭代器时，错误信息往往很长，核心问题躲在一堆模板展开的后面。这里列几个高频错误和排查思路：

这里特别提醒：auto& x = *it;这种写法对普通迭代器没问题，但对代理迭代器是编译错误，因为*it返回临时对象。初学者第一次遇到时很容易怀疑是自己的迭代器写错了，实际上这是代理迭代器的正常限制。

6.2 性能陷阱

迭代器的性能问题往往不来自迭代器本身，而来自标签选错导致的算法策略变化。

一个典型例子是std::distance。如果迭代器标签是random_access_iterator_tag，std::distance就是 O(1) 减法；如果是forward_iterator_tag，就只能 O(N) 递增。如果数据规模是百万级，这个差距会非常明显。

反过来，你的迭代器明明只能前向移动，却硬标成随机访问，std::sort这类算法会把随机访问运算用在你的迭代器上，编译期或许能过，但每次it + n都得从当前位置一格一格走，复杂度还不如老老实实承认自己是前向迭代器。

还有一个容易被忽视的点：operator++()的前缀版本应该返回LogRowIterator&，operator++(int)后缀版本返回旧值拷贝。如果两者搞混，或者后缀版本返回引用，通常会因为返回悬空引用导致 undefined behavior，而且是那种很难排查的运行时崩溃。

6.3 经验速查表

6.4 如果项目还在 C++17 怎么办

不是所有人都在用 C++20，但核心技巧在 C++17 下完全可用。区别主要是两点：

第一，不能用概念做静态断言，但可以用std::iterator_traits<It>搭配 SFINAE 做检测，或者干脆跑几个算法作为“编译期冒烟测试”。实测下来，先写一个小的static_assert(std::is_same_v<std::iterator_traits<It>::iterator_category, std::forward_iterator_tag>)，能提早发现一半的问题。

第二，C++20 ranges 的某些便捷写法（比如管道表达式）不可用，但手写迭代器配合begin/end自由函数，依然能让std::find_if等算法正常使用，也依然支持范围for。核心收益并没有少太多。

还有一个 C++17 时代的习惯问题：不少人会用std::iterator作为基类来省事，但这个类模板从 C++17 起就被标记为不建议使用，不要在新代码里依赖它。直接手写类型别名，也就多几行而已。

7. 写在最后的实操体会

自定义迭代器这东西，第一次写会觉得很玄，编译错误能淹没整个屏幕；但写过一两个之后就会发现，它的规律性其实非常强。我的个人经验是：不要急着写算法调用，先把迭代器类型扔到概念断言或者一个最简单的std::distance里跑一下，确认“身份正确”再往复杂算法上靠。

还有一个非常实用的小技巧：如果你不确定iterator_category该怎么选，可以先按“底层数据最保守的遍历能力”来声明，前向就是前向，双向就是双向，千万不要为了跑某个算法而虚报能力。虚报换来的只是短期编译通过，付出的是长期调试成本。

最后再分享一个调试习惯：在写LogRowIterator这类代理迭代器时，多写几个“本来不该用”的测试，比如拷贝迭代器、保存旧迭代器、连续几次*it解引用，确认结果是稳定的。前向迭代器的多遍保证不是嘴上说说，是要经得起这些基础操作考验的。项目上线半年后再回头改迭代器，那才是真的痛苦。