客户端状态管理架构：单向数据流、状态机与「状态爆炸」的治理

做了多年 Web 前端，reducer 纯函数、单向数据流、Pinia 的 store 分层、Redux DevTools 的时间旅行，这些几乎是职业本能。但一转到 C++/Qt 桌面客户端，很多工程师会把这些经验整体丢掉：状态散落在几十个成员变量里，用 bool isConnecting / bool isConnected / bool isReconnecting 拼出一个"隐式状态机"，界面和数据偶尔分叉，最后谁都不敢碰那块代码。这不是水平问题，而是 Qt 世界观里缺少一个"被反复强调的状态管理范式"。

今天我们把状态管理当作客户端架构的一等公民来学。它的回报非常直接：状态边界一旦清晰，UI 刷新粒度、撤销重做、断线重连、向导流程、多线程回传这五件最痛的事会同时变简单；而且它是所有架构问题里少数"后期几乎无法补救"的一类——你可以在项目中期引入 CMake 或日志系统，却很难在产品上线后重新划分状态所有权。对正在从 Web 转桌面架构方向的你来说，这是最能直接复用的迁移资产。

状态是什么。严格定义上，状态是「一组变量在某一时刻的取值快照」。UI 程序与批处理程序最大的差别就在于：它永远在「等待事件 → 更新状态 → 重绘」这个循环里，永远没有终态。因此状态管理要回答的其实是两个问题：系统现在可能处于哪些状态，以及谁能、通过什么路径改变它。第一个问题决定可靠性（非法状态能不能出现），第二个问题决定可维护性（改动会不会失控）。

第一件事：把状态分成三层。绝大多数"状态混乱"的项目，根因都是三种性质完全不同的状态被混在一起，谁都能改。

第二件事：单向数据流。Redux 把它压缩成三句话：单一真相源（Single Source of Truth）、状态只读、只能由纯函数（reducer）产生新状态。落到工程上有两个关键收益：状态的变更路径可枚举，因此可以记录、回放、做时间旅行；副作用被隔离在 reducer 之外（middleware / effect / saga），纯逻辑与 I/O 不再纠缠。注意：reducer 是纯函数这件事，价值不在"函数式优雅"，而在于它让"变更"成为可测试的纯计算——同样的旧状态加同样的 action，永远得到同一个新状态。C++ 世界里这一点同样成立：把修改收敛成 bool Model::apply(const Command& cmd)，这个函数可以用单元测试完整覆盖，而点击按钮之后的 I/O 由外层负责。

第三件事：不可变性与结构共享。Redux 坚持返回新对象而不是原地修改，是为了能用 O(1) 的引用比较判断"到底变了没有"，这正是 React 的 memo / shouldComponentUpdate 能成立的前提。C++ 没有 GC，但有等价工具：值语义 + 隐式共享（QString/QList/QVariant 都是 copy-on-write），以及给状态类型实现 operator== 后做"变更时 diff、通知时精确到 item"——Qt 的 dataChanged(index, index) 就是这个机制的天然接口。换句话说，C++ 侧不需要不可变对象库，需要的只是"变更时产生快照或精确通知"，而不是"每次都全量重置视图"。

第四件事：状态爆炸，以及显式状态机。系统的状态不是变量的取值集合，而应该是显式的、有限的、有名字的集合。假设你用 6 个布尔位描述"加载中 / 已加载 / 出错 / 空态 / 连接中 / 已连接"，理论上就有 2⁶ = 64 种组合，而业务上合法的可能只有 4 种——剩下的 60 种都是不该出现、却随时可能因为一处赋值写错而出现的非法状态。状态机的核心价值不是"写起来优雅"，而是把合法状态变成枚举、把非法状态变成不可能表示，并让每一次转移都显式出现在代码里、可以加断言和日志。当状态数量增长时，还有两个标准武器：层次状态机（HSM）把公共转移提升到父状态（比如"任何子状态下收到断开事件都进入 Offline"），避免转移边数爆炸；正交区域（parallel regions）处理真正互不相关的维度（如"播放状态"×"网络质量"），Qt 里对应 QState::ParallelStates。此外 QHistoryState 能记住"上次离开时的那个子状态"，这正是"从详情页返回列表要恢复原选中项"这类需求的正解。

第五件事：转移、守卫与动作。状态机的最小完备定义是「状态 + 事件 + 转移（transition）」，转移上可以挂守卫（guard，条件）和动作（action，副作用）。工程上的纪律是：守卫只做判断，不产生业务副作用；动作只做必要的事，且尽量排在转移完成之后。否则你会得到"转移进行中又触发新转移"的重入类 bug，这类问题在 C++ 里比在 JS 里更难查，因为它可能只在高并发或特定事件顺序下出现。

VS Code：命令是唯一扩展点，视图状态可序列化。VS Code 的核心设计原则是"所有能力都暴露为 Command"，插件通过 registerCommand 参与，而不是直接操纵 UI 组件。这带来天然的单向数据流：UI 只发出意图（命令），状态变更收拢在工作台服务里。更值得学的是它的"现场恢复"：编辑器布局、分屏、光标与滚动位置会被序列化（Monaco 的 createEditorMemento() 就是典型实现），重启后恢复到用户离开时的状态。为什么这么设计？因为桌面 IDE 的用户预期是"关掉再打开，我的工作现场还在"——而这要求 UI 状态必须是可导出、可导入的值，而不是藏在控件内部的临时变量。Qt 侧的对应物是 QMainWindow::saveState()/restoreState() 与 QSettings，很多团队只存了窗口大小，丢掉了最有价值的那部分。

Chrome：标签页生命周期就是一个显式状态机。Chrome 的 Page Lifecycle 把页面明确划分为 active / passive / hidden / frozen / discarded 等状态，并以此决定谁能冻结定时器、谁能回收内存（Tab Discarding、内存节省模式）。这件事用布尔标志是做不出来的：后台标签有"不可见"、"被冻结"、"被丢弃"三重含义，只有把它们建模成状态并允许显式转移，浏览器才能安全地释放 GPU 与重建页面。这正是"非法状态不可表示"在高性能客户端里的真实价值。

Qt Creator：插件阶段化与"一切皆可禁用"。Qt Creator 把启动过程划分成明确阶段，插件在特定阶段被装载并赋予能力，同时坚持"任何插件都必须能被禁用而不影响其他部分"。这背后是一种状态化的依赖管理：能力在某个状态之后才可用，越界调用就是编程错误。这种设计让它能在保证启动速度的同时支撑上百个插件——对比很多自研客户端"插件初始化顺序靠偶然的加载顺序"的写法，差距不在一行代码，而在是否显式建模了进程生命周期的状态。

微信/QQ 的长连接：状态机 + 指数退避 + 消息队列。移动端 IM 客户端最核心的一段逻辑就是"断线重连"：断开后不能立刻狂发连接请求（会被服务端限流、也耗电），而是按 500ms、1s、2s、4s、8s 的指数退避重拨，并叠加随机抖动避免全量客户端同时重连（惊群）；退避期间所有发送请求进队列，连接成功后按序补发。用布尔标志根本无法回答"现在能不能发消息"这个问题。有意思的是，Qt 自己的网络层就是状态机：QAbstractSocket::SocketState（UnconnectedState / HostLookupState / ConnectingState / ConnectedState / ClosingState）与独立的 SocketError 枚举，框架作者早就替我们证明了这个方向是对的。

错误一：布尔标志位堆叠。出现 isConnecting + isConnected + isReconnecting + isIdle 四个及以上标志位，就一定会出现"同时 connected 且 connecting"的非法组合，而且是概率出现、难以复现。原因很朴素：多布尔表达的是取值空间，而业务需要的是互斥状态。避免方法：合并成 enum class State { Idle, Dialing, Online, Backoff };，并在状态变化处加 Q_ASSERT 或日志，让非法转移在开发期就炸出来。

错误二：多来源真值（SSOT 被打破）。同一份数据既存在 Model 里，又在某个自定义控件的成员变量里缓存一份"方便访问"；改了一处忘了同步另一处，界面和数据就此分叉，随后所有 bug 都变得不可解释。避免方法：明确唯一 owner（通常是 Model），其他位置一律通过引用、指针或订阅获取；视图只读、只发意图。Qt 里更进一步：视图不应保存任何领域数据的副本，只能保存 UI 状态。

错误三：在信号槽链里改状态造成回环。典型形态是：代码里以编程方式更新控件（setCurrentIndex、setChecked、setText）触发了"像是用户操作"的信号，信号处理里又去改状态，状态变化再回写控件，形成循环或"用户改 A 变成 B"。避免方法有三层：优先连"用户专属信号"（textEdited 而不是 textChanged、clicked 而不是 toggled）；确需程序化更新时用 QSignalBlocker/blockSignals 明确屏蔽；架构上让状态更新只有一个入口，更新完由 Model 统一广播。

错误四：在绘制路径里更新状态。在 paintEvent()（或任何绘制/布局回调）里修改状态并触发 update()，会同时造成两件事：重绘死循环（表现为 CPU 100% 卡死）和状态撕裂。Web 世界的等价错误是在渲染阶段调用 setState。避免方法：状态更新只允许发生在事件处理、命令执行或定时回调中；绘制函数必须是纯读取的（必要时 const 修饰，让编译器帮你把关）。

错误五：工具错配。两种相反的错误都常见：一是用 QStateMachine 去表达表格排序规则、字段校验这类高频、细粒度的数据流状态，结果是维护成本远高于收益；二是反过来，把"按钮 hover / 当前展开的树节点"这类纯局部状态塞进全局 store 或全进程会话对象，导致无关模块互相耦合。判断标准只有一条：这个状态的所有者范围与合法组合数量——范围小、组合少，就地用成员变量；范围跨模块、组合呈现爆炸倾向，才升级成显式状态机。

1. 分层声明状态所有权，并写进类注释。每个类在文件头写清楚：我持有哪些状态（领域 / UI / 会话）、只能由谁修改、对外通过什么信号广播变化。这看起来像文档工作，但它是唯一能让新成员在五分钟内搞懂"这个状态该改哪儿"的手段。Code Review 时第一个问题就是"这份状态属于谁"。

2. 关键流程一律显式状态机，并画出状态图。连接、认证、任务向导、下载、播放器、编辑器生命周期，这些流程的共同点是"非法转移会造成实际损失"（重复提交、状态错乱、数据丢失）。把它们写成枚举状态 + 显式转移，并把状态图放进设计文档。Qt 侧可以用 QStateMachine（Qt6 为独立模块 Qt StateMachine），需要非 C++ 人员参与维护时还可以用 SCXML（Qt SCXML 模块）让状态图变成可被产品/测试阅读和评审的资产。

3. 用类型消灭非法状态。C++17 起你有一整套工具：enum class 替代布尔位；std::variant + std::visit 表达"互斥且各自携带不同数据的几种状态"（等价于 TypeScript 的可辨识联合 Discriminated Union，编译器会强制你处理所有分支）；std::optional 表达"可能没有值"，而不是用 nullptr 或空字符串硬凑。当非法状态在类型层面无法构造时，运行期断言就只是第二道防线。

4. 状态变更走唯一入口（Command 风格）。UI 只发"意图"，所有修改收敛到一个入口函数（Model 的 setData、领域层的 apply(Command)）。收益是连锁的：命令栈（QUndoStack）天然可实现撤销重做；日志与埋点可以在入口处统一注入；单元测试只需覆盖入口函数而不必模拟 UI 交互；后续做协作/同步（OT、CRDT）时也有明确的变更事件流可用。

5. 派生数据现算，关键状态可序列化。凡是能由其他状态算出来的（可见行数、过滤后的列表、汇总金额），都不要单独存储——那是在给自己制造一致性维护任务（Web 侧对应 Vue 的 computed、React 的 useMemo；Qt 侧就是在 data() 里现算或缓存并在依赖变更时失效）。同时，把"值得跨会话保留"的状态实现成显式的值：窗口布局用 saveState()，用户偏好与工作现场用 QSettings 或 JSON 落盘。

Trade-off 与"何时不用"：引入状态机或全局 store 不是免费的。它增加一层间接、增加调试跳转距离、也让"小改动"需要更多仪式感。判断标准是：如果这个状态的合法组合数量少、生命周期与某个控件绑定、出错的后果只是界面轻微不一致，就用成员变量；如果状态会被多个模块读写、转移有业务意义、错误后果是数据错误或不可恢复，就上状态机。团队规模小、产品是单窗口小工具时，一个层级清晰的对象 + 少量枚举往往比完整的 store 骨架更划算。

这可能是本篇最有迁移价值的一节——你在 Web 侧形成的直觉几乎全部可以平移，只是 Qt 把很多"自动化"的部分交回了你手上。

再补两个思维层面的连接。第一，Node.js 的事件循环与 Qt 事件循环同构：都是"取事件 → 分发 → 执行回调"，因此"不要在回调里做长任务"这条纪律完全通用，区别只是 Qt 里还可以用 QThread/QtConcurrent 真正并行，而 Node 只能靠 worker_threads 或进程。第二，状态更新的时机语义一致：浏览器里在事件处理函数中连续 setState 会被合并；Qt 里同一线程内的信号槽是同步直连（DirectConnection），状态变更会立即生效，所以"连续改三次状态"在 Qt 里就是三次真实变更，这也是为什么"唯一入口 + 批量提交"的纪律在 Qt 侧更重要。

作为 Team Leader，你要意识到状态边界几乎决定了团队的协作成本。新人上手慢的典型原因不是不懂语法，而是"看不懂这个界面现在处于什么状态"；需求评审时最常吵的也不是功能，而是"加载中"和"已完成"哪个先出现。把状态图当作沟通材料，产品、测试、新人能同时看懂，这比写十页设计文档都有效。

Code Review 上建议固定追问四件事：①这个新类有没有明确的状态所有权声明？②是否新出现了第三个以上的布尔标志位？③状态转移是否都出现在显式位置、且附有断言或日志？④同一份数据是否在两个地方被写入（SSOT 是否被破坏）？把这四条写进团队的 Review Checklist，比事后联调救火便宜得多。最后一条原则值得反复强调：状态治理属于"现在做很便宜、以后做极贵"的那类工作，值得在立项阶段就投入，而不是等出事故再重构。

1. David Harel,《Statecharts: A Visual Formalism for Complex Systems》(1987) —— 层次状态机的原始论文。QStateMachine、SCXML、XState 的理论源头都在这里，读它才能理解 parallel regions 与 history state 为什么被设计出来（而不是当成 API 特性去背）。

2. Redux 官方文档《Three Principles》 —— 英文短文档，单向数据流的最小公理集。迁移到 C++ 时只需要保留"单一真相源 + 只读 + 纯更新"三条，不必照搬 JS 的实现方式。

3. Qt 官方 State Machine Framework 与 Qt SCXML 文档 —— QState/QHistoryState/QSignalTransition/QEventTransition 的完整 API。SCXML 的价值在于把状态图变成 XML 资产，可以让非 C++ 成员参与维护与评审。

4. David Khourshid 的 XState 系列文章与演讲《Robust UI state machines》 —— 用状态机替代布尔组合的实战论证，从 Web 视角出发，是你现有经验最省力的延伸读物（推荐先看他讲"state explosion"的那一篇）。

5. 《设计数据密集型应用》(DDIA) 第 11 章「流处理」 —— 把状态变更视为事件日志（event sourcing）的思想来源。做会话恢复、审计、崩溃后重建现场时，这套心智模型比"存快照"更有扩展性。

// main.cpp —— 状态机版「指数退避重连」（Qt 6）
#include <QCoreApplication>
#include <QStateMachine>
#include <QState>
#include <QTimer>
#include <QRandomGenerator>
#include <QObject>
#include <QDebug>
#include <algorithm>

class Network : public QObject {                  // 真实项目里换成 QTcpSocket
    Q_OBJECT
public:
    Q_SLOT void dial() {
        qInfo() << "[net] dialing ...";
        emit connecting();
        if (QRandomGenerator::global()->bounded(100) < 45)  // 45% 失败率，观察退避
            emit failed();
        else
            emit up();
    }
    void drop() { qInfo() << "[net] link lost"; emit down(); }
signals:
    void connecting();   // 开始拨号
    void up();           // 连接成功
    void down();         // 已建连接断开
    void failed();       // 拨号失败
};

int main(int argc, char *argv[]) {
    QCoreApplication app(argc, argv);
    Network net;
    QStateMachine sm;

    auto *idle    = new QState(&sm);
    auto *dialing = new QState(&sm);
    auto *online  = new QState(&sm);
    auto *backoff = new QState(&sm);
    int   attempt = 0;

    idle->addTransition(&net, &Network::connecting, dialing);
    dialing->addTransition(&net, &Network::up,     online);   // 成功
    dialing->addTransition(&net, &Network::failed, backoff);  // 失败 → 退避
    online->addTransition(&net, &Network::down,    backoff);  // 掉线 → 退避
    backoff->addTransition(&net, &Network::connecting, dialing);

    QObject::connect(dialing, &QState::entered,
                     [&] { ++attempt; qInfo() << "-> dialing (attempt" << attempt << ")"; });
    QObject::connect(online, &QState::entered,
                     [&] { attempt = 0; qInfo() << "-> ONLINE, ready to send"; });
    QObject::connect(backoff, &QState::entered, [&] {
        const int ms = std::min(8000, 500 * (1 << std::min(attempt, 4)));  // 500/1k/2k/4k/8k
        qInfo() << "-> backoff" << ms << "ms, queue the requests";
        QTimer::singleShot(ms, &net, &Network::dial);   // 到点自动重拨
    });

    sm.setInitialState(idle);
    sm.start();
    QTimer::singleShot(0,    &net, &Network::dial);          // 开机即拨
    QTimer::singleShot(4000, &net, [&net] { net.drop(); });  // 4s 后模拟掉线
    return app.exec();
}
#include "main.moc"     // 单文件含 Q_OBJECT：需 CMAKE_AUTOMOC，并包含生成的 moc

# CMakeLists.txt
cmake_minimum_required(VERSION 3.16)
project(qsm-reconnect LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_AUTOMOC ON)
find_package(Qt6 REQUIRED COMPONENTS Core StateMachine)
qt_add_executable(qsm-reconnect main.cpp)
target_link_libraries(qsm-reconnect PRIVATE Qt6::Core Qt6::StateMachine)
# 注：Qt5 里 QStateMachine 位于 QtCore，无需单独组件

进阶挑战（选做）：①给 Dialing 加一个 QHistoryState，让"用户主动断开"后重连能回到上次的子状态；②把退避上限与失败率抽到 QSettings，实现运行期可调；③在入口处拦截：只有 Online 状态才允许发送消息，否则入队——这就是"用状态机回答'现在能不能发'这个问题"的最小实现。