Serial Studio 组合根改造Spec 0001用显式构造顺序与依赖捕获终结 59 个 Meyers 单例的启动竞态【免费下载链接】Serial-StudioOpen-source telemetry dashboard. Supports UART, BLE, MQTT, Modbus, CAN Bus and more.项目地址: https://gitcode.com/GitHub_Trending/se/Serial-Studio本篇技术指南以doc/claude/specs/0001-composition-root/spec.md为骨架结合同目录下的 plan.md、tasks.md 以及仓库当前源码完整讲解 Serial Studio 将约 59 个 Meyers 单例服务收敛为组合根 依赖捕获架构的动机、目标、设计、验收标准与七阶段落地路径。读者将理解为什么惰性单例的构造顺序会让启动图依赖用户保存的设置、如何用instantiateCoreModules()固定拓扑顺序并消灭AppState-ProjectModel重入隐患以及如何在不回归 256 kHz 热路径的前提下把 1,852 处散落的X::instance()调用点收缩到受监管的许可面内。背景与问题59 个 Meyers 单例的隐式构造顺序Serial Studio 的约 59 个核心服务全部是 Meyers 单例——在第一次调用X::instance()时才惰性构造。问题在于这个构造顺序不是由代码定义的而是由哪个instance()调用恰好最先触发涌现出来的而第一次触发取决于用户机器上保存的设置。spec 文档给出了一个具体而典型的例子在一台保存了operation_mode为 ProjectFile 的机器上AppState的构造函数会执行deriveFrameConfig()其 ProjectFile 分支调用ProjectModel::instance()——于是ProjectModel在AppState构造函数内部被构造而在 QuickPlot 机器上该分支从不执行ProjectModel被推迟到更晚才构造。开发者在某台机器上验证过的启动图只是众多顺序中的一种任何重构若只在一种顺序下验证过都是不完整的验证。这个设置条件性边界settings-conditional edge不只是不整洁而是一个活的重入风险ProjectModel的构造函数调用newJsonFile()后者会发出groupsChanged信号而此时AppState仍处于构造中途如果在newJsonFile()之前就连接了触碰 AppState 的 lambda就会在 AppState 自己的 Meyers 初始化过程中重入AppState::instance()——这是未定义行为维护者此前靠调整一次connect调用的顺序躲过了这个问题源码注释spec 中引用的ProjectModel.cpp:446newJsonFile() emits groupsChanged while AppState is still mid-init正是这一险情的记录。换言之惰性依赖图今天之所以还像一个 DAG只是靠一条注释和一个精心放置的 connect 碰巧维持的任何一次 connect 重排都可能触发 UB而没有任何机制把它钉在原地。与此同时ModuleManager事实上已经是组合根composition root——它强制实例化各模块、按顺序执行 17 次setupExternalConnections()调用、随后restoreLastProject()、再注册约 60 个Cpp_*QML 上下文属性、最后加载 QML。缺少的只是代码钉死的构造顺序以及显式、被强制执行的构造-接线两阶段生命周期。Spec 0001 正是要把这一点形式化让启动图不再依赖保存的设置移除AppState-ProjectModel隐患并把松散散落的::instance()调用面59 个单例头文件、1,852 个调用点在回归守卫的监督下逐步收缩——同时不回归 256 kHz 热路径。目标与非目标目标Goals核心模块的构造顺序由代码定义在 QuickPlot、ProjectFile、Console-only 三种启动模式下完全一致绝不随持久化的operation_mode变化。消除AppState-ProjectModel重入隐患ProjectModel永远先于AppState构造使设置条件性边界无法形成。ModuleManager成为唯一、显式的组合根具备两阶段生命周期先构造全部模块再接线三条既有顺序不变式INV-1..INV-3见下文由构造保证而非偶然成立。非热路径消费者把依赖作为捕获成员持有而非到处散布X::instance()调用松散调用点数量逐波严格下降。回归守卫使任何新增::instance()调用点在 code-verify 报告中可见调用面只减不增。256 kHz 热路径门禁保持或改善成员加载比 Meyers 守卫的原子加载加分支更廉价。非目标Non-Goals不是容器/框架式依赖注入DI约 60 个Cpp_*QML 上下文属性需要稳定、长寿命的QObject地址容器会引发约 60 参数的接线爆炸和 1,852 个调用点的 flag-day 式重写QML 从中得不到任何好处且最终形态与普通构造函数注入在结构上完全相同——捕获成员将来可以机械地提升为构造参数。容器在这里买不到任何东西却要付出一场重写的代价。不是服务定位器service locator它把同样的全局状态藏在更慢、更难 grep 的查找后面在 256 kHz 不允许间接成本的热路径上增加开销且对真正的病灶——未钉死的惰性构造顺序——毫无作用。不删除单例也不改变 QML 上下文属性模型。instance()访问器和约 60 个上下文属性都保留改变的只是依赖的获取方式。不把FrameParser转换为捕获或强制实例化依赖见附录特例其构造闭包依赖项目内容保持惰性/延迟。目标架构组合根 依赖捕获Spec 0001 主张的是形式化的组合根 依赖捕获而非引入新机制。组合根ModuleManager拥有启动ModuleManager拥有启动过程。新的私有方法instantiateCoreModules()最先执行在一个由代码钉死的拓扑顺序中强制每个核心模块进入存在使依赖图不再取决于哪个instance()先触发。该顺序的承载性质load-bearing property是ProjectModel先于AppState这直接消灭设置条件性边界。两阶段生命周期先构造再接线阶段一构造instantiateCoreModules()依次构造模块。每个构造函数只做自初始化、读取QSettings、连接到模块自身强制的对象。阶段二接线按顺序对每个模块执行setupExternalConnections()连接跨模块的信号/槽。随后restoreLastProject()INV-1、注册上下文属性INV-2、安装 Qt 消息处理器INV-3、加载 QML。这正是 DI 会强加的 construct/wire 拆分只不过表达在我们已有的根里。依赖捕获Dependency Capture取代每个使用点的即席X::instance()消费者一次性捕获依赖并持有真叶类与近叶类作为构造函数初始化列表中的引用成员-Wreorder 零警告在构建期抓住初始化顺序错误五边形pentagon核心模块AppState、ProjectModel、FrameBuilder、ConnectionManager、Dashboard这些类在接线前就可能被触达因此在它们各自的setupExternalConnections()顶部以指针形式捕获接线前的表面继续保持直接instance()调用热路径最后转换并受基准门禁约束。Ratchet棘轮收缩一条建议性advisorylint 规则标记新增的松散::instance()调用点许可面逐阶段收缩直至只剩组合根、main入口、类自身的instance()定义和setupExternalConnections函数体。三条不变式组合根必须保住的顺序INV-1接线先于项目恢复每个模块的setupExternalConnections()必须运行在restoreLastProject()之前。恢复项目会驱动接线逻辑其前提是所有模块都已连接完毕。源码印证ModuleManager.cpp 中appState-restoreLastProject()位于全部setupExternalConnections()调用之后。INV-2上下文属性注册时序约 60 个Cpp_*QML 上下文属性必须在所有接线完成之后、QML 引擎加载之前注册保证 QML 永远不会绑定到半接线的模块。INV-3Qt 消息处理器的安装时机qInstallMessageHandler(MessageHandler)只能在Console::Handler和NotificationCenter存在之后安装。原因很细消息处理器在第一次警告时会从任意线程构造这两个类而Console::Handler的构造函数会拉取CommonFonts后者触碰字体数据库必须运行在 GUI 线程。过早安装消息处理器可能在第一条零散警告出现时导致非 GUI 线程访问字体数据库。附加约束不得回归 256 kHz 的--benchmark-hotpath门禁全部七档。必须在 QuickPlot、ProjectFile、Console-only 三种模式下行为一致。不得给FrameReader/CircularBuffer添加互斥锁热路径信号跳转保持Qt::DirectConnection依赖捕获不得改变热路径上的连接类型。行为保持固定顺序中的每个强制实例化模块必须是组合根今天已经传递构造的模块仅自初始化 QSettings 自强制连接不引入任何新构造只是把构造提前钉住。作用域纪律在上下文属性注册时才首次构建的模块ProjectEditor、ProtoImporter、Examples、HelpCenter等保持在原处不拉入固定核心顺序。需求与验收标准编号需求验收标准均已勾选完成R1核心模块构造顺序由代码定义QuickPlot/ProjectFile/Console-only 一致不随operation_mode变化AC1三种模式均正常启动运行组合根在每种模式下都先构造 ProjectModel 再构造 AppStateR2ProjectModel 永远先于 AppState 构造deriveFrameConfig() - ProjectModel::instance() - newJsonFile() - groupsChanged重入边无法再形成AC1同上R3所有模块接线经 ModuleManager 两阶段完成INV-1..INV-3 成立AC2restoreLastProject()在所有setupExternalConnections()之后上下文属性在接线后、QML 加载前注册消息处理器在Console::Handler/NotificationCenter存在后安装R4非热路径消费者以捕获成员持有依赖松散::instance()调用点逐波严格下降、永不增加AC3每波转换后grep -c X::instance()在构造函数初始化列表叶类或接线前表面五边形之外为零头文件每个依赖恰好新增一个成员advisory 计数严格下降R5新建议性 lint 规则报告许可面外的新增::instance()调用点不改变阻塞错误数AC4规则落地前后python3 scripts/code-verify.py app/src的阻塞错误数完全一致advisory 报告只新增该种类合成Foo::instance()片段触发规则各许可模式不触发R6热路径捕获阶段后--benchmark-hotpath七档全部通过无回归逐帧依赖访问是成员加载而非 Meyers 守卫AC5七档全部通过与阶段前基线相比无回归实现路径七个门控阶段plan.md 把改造拆成七个门控阶段S1-S7对应 tasks.md 中的任务 T1-T9全部标记完成。构建门控贯穿所有实现阶段一次构建一个阶段每个构建-启动周期只落地一个阶段或一个 S4 波次/一个五边形类绝不把两个顺序敏感变更混进同一次构建。三种操作模式全部启动任何改变构造顺序S3或模块接线S5的阶段之后都要在 QuickPlot、ProjectFile、Console-only 三种模式下启动验证。S6 之后跑--benchmark-hotpath全部七档与 S6 前基线对比S3/S4/S5 在逐帧路径之外不强制跑基准但仍需启动冒烟测试。S1依赖普查 初始化顺序契约文档— 已完成编写 spec/plan/tasks 包与 architecture.md 新增小节Composition Root Construction Order -- ModuleManager包含验证过的构造器边图spec 附录表、S3 固定实例化顺序、三条不变式 INV-1..INV-3以及逐文件::instance()清点1,852 个调用点、59 个单例头文件作为晨间波次的预划定。验证命令python3 scripts/documentation-verify.py。S2回归守卫arch-singleton-instance建议性规则Python— 已完成在 scripts/code_verify_rules.py 中新增建议性规则并把它注册进 scripts/code-verify.py 的_ADVISORY_KINDS。当前源码中的实现要点见 code_verify_rules.py 的 Composition-root rule (spec 0001) 注释段触发正则\b[A-Za-z_][\w:]*::instance\(\)_SINGLETON_INSTANCE_REQt 自身的静态访问器QCoreApplication::instance()等先被_QT_INSTANCE_RE从行内剥除因为它们不是 Serial Studio 单例、没有未钉死的构造顺序许可面不产生 finding组合根文件、访问器自身instance()函数体、setupExternalConnections()接线函数体、过渡期static auto x X::instance()热路径缓存惯用法、构造初始化列表捕获、以及单行Q_ASSERT(...)表达式_SINGLETON_SANCTIONED_FUNCS frozenset({instance, setupExternalConnections})定义了许可函数集合。验证规则落地前后code-verify.py app/src阻塞错误数一致、advisory 报告只新增该种类合成片段触发、各许可模式不触发。S3钉死构造顺序形式化组合根— 已完成新增私有void instantiateCoreModules();作为setupCrossModuleConnections()的第一行调用。当前源码实现在 ModuleManager.cpp其固定构造顺序与 spec 设计一致ProjectModel在AppState之前是承载性质为TranslatorTimerEventsCommonFontsWorkspaceManagerNotificationCenterThemeManagerExtensionManagerControlScriptProjectModel先于AppState——消灭设置条件性边AppStateLemonSqueezy/MachineID商业版FrameBuilderIO::ConnectionManagerConsole::HandlerAPI::ServerCSV::PlayerMDF4::PlayerSessions::Player商业版/可选四个导出器FrameParserUI::Dashboard最后——其构造函数触碰五个核心模块 两个播放器 TimerEvents注意当前源码已演进instantiateCoreModules()同时做了消息总线挂接attachMessageBus、通过SessionContext收养模块adoptProjectModel/adoptAppState等与许可状态发布商业版但ProjectModel先于AppState的顺序被严格保留。作用域规则只列出setupCrossModuleConnections今天已传递构造的模块上下文属性注册时才构建的模块ProjectEditor、ProtoImporter、Examples、HelpCenter等留在原处。验证grep 对称性instantiateCoreModules中的每个类也出现在后面的setupCrossModuleConnections中或已被传递构造顺序与 spec 表完全一致restoreLastProject()仍在所有setupExternalConnections()之后INV-1。S4叶类构造器引用捕获宽泛、按波次— 已完成对每个消费者类添加引用成员如Misc::TimerEvents m_timerEvents;在构造初始化列表初始化m_timerEvents(Misc::TimerEvents::instance())并把文件内非热路径调用替换为成员。已验证零单例出边的叶类Translator、TimerEvents、CommonFonts、NotificationCenter、WorkspaceManager、CSV::Player、MDF4::Player、CommandHandler外加近叶ThemeManager。-Wreorder 零警告在构建期抓住初始化顺序错误——初始化顺序错误是编译期错误而非运行时错误。三个波次(1)Misc/*UI/Widgets/*中消费 CommonFonts/TimerEvents/ThemeManager 的类(2)Console/、CSV/、MDF4/(3)DataModel/编辑器。逐文件验证(a).cpp中grep -c X::instance()在构造初始化列表之外为 0(b) 头文件每个依赖恰好新增一个成员(c) 初始化列表位置与成员声明顺序一致(d) advisory 计数严格下降。S5五边形延迟指针捕获 — 已完成AppState、ProjectModel、FrameBuilder、ConnectionManager、Dashboard各添加X* m_x构造初始化列表置 nullptr在各自setupExternalConnections()顶部赋值使用点Q_ASSERT(m_x)方法体调用点转为m_x-。构造器体与接线前可达的方法保持直接instance()——这些接线前表面包括AppState::deriveFrameConfig()、ProjectModel::newJsonFile()/setModified()/watchProjectFile()及其可达路径、Dashboard构造函数连接的一切、ConnectionManager的m_uiDriverSaveTimerlambda。顺序每次晨间构建一个类AppState-ConnectionManager-FrameBuilder-ProjectModel-Dashboard。S3 之后AppState可以构造器捕获ProjectModel因为 S3 保证 ProjectModel 先构造但绝不允许从 ProjectModel 构造器捕获 AppState活体 A-B 隐患。当前源码印证AppState.cpp 中m_projectModel(DataModel::ProjectModel::instance())已出现在构造初始化列表setupExternalConnections()同文件第 122 行捕获m_frameBuilder DataModel::FrameBuilder::instance()并连接jsonFileChanged等信号——五边形捕获已落地。验证每类头文件恰好新增指针成员每个被转换的调用点位于已被证明在接线后运行的方法中接线前表面仍用直接instance()advisory 计数下降三种模式启动。S6热路径捕获基准门控最后— 已完成把ConnectionManager::{onFrameReady,onRawDataReceived,processPayload,processMultiSourcePayload}与Dashboard::updateStreamAvailable中的static auto缓存静态量转换为 S5 指针成员把onFrameReady中逐帧的AppState::instance().operationMode()轮询替换为缓存的m_operationMode由operationModeChanged信号刷新复用 FrameBuilder 的缓存标志模式。所有连接保持Qt::DirectConnection。风险点若m_operationMode未接入operationModeChangedonFrameReady中的操作模式分支会静默变陈旧。验证转换后的调用点是成员而非静态量m_operationMode刷新已接到operationModeChanged--benchmark-hotpath全部七档无回归。S7棘轮收缩 — 已完成把arch-singleton-instance的许可面收缩到{ModuleManager.cpp, main.cpp, 类自身 instance() 定义, setupExternalConnections 函数体}去掉 S6 已移除的static auto缓存惯用法豁免可选地把五边形提升为按类阻塞。此后新服务一律从构造参数获取依赖。源码印证组合根当前的实际形态仓库当前代码完整反映了 spec 的落地方案ModuleManager.cpp 的setupCrossModuleConnections()第一行即调用instantiateCoreModules()随后执行bindInterfaces()、registerApiHandlers()、各模块setupExternalConnections()最后appState-restoreLastProject()INV-1instantiateCoreModules()中ProjectModelctx.adoptProjectModel(...)严格先于AppStatectx.adoptAppState(...)构造ModuleManager.h中instantiateCoreModules/bindInterfaces/registerApiHandlers/setupHeadlessSessionConnections均为公开静态方法并被 CLI.cpp 的无界面路径基准、会话校验、schema 导出复用——固定顺序成为所有启动形态的公共底座AppState.cpp 展示了叶式引用成员 接线期指针捕获的混合形态scripts/code_verify_rules.py 中的arch-singleton-instance规则与 spec/plan 描述的触发正则以树-sitter 作用域实现对 Qt 静态访问器做了显式剥离。落地后的回归事故tasks.md 事后记录tasks.md 记录了一次值得警惕的回归落地次日凌晨发现某个在newJsonFile()内加入 AppState/Dashboard 同步的修复在 ProjectModel 构造函数内执行在 ProjectFile 机器上递归了 Meyers 守卫__cxa_guard_acquire在启动时 abort。T3 的构造器边证明在书写时是正确的但后续修复波次使其失效。修复方式用m_initialized标志门控该同步。由此确立一条常驻规则任何修改 ProjectModel 构造闭包newJsonFile、watchProjectFile、scheduleAutoSave、setCode 链的编辑在合并前必须重新触发构造器边检查。权衡与备选方案plan.md 的权衡表可概括为决策点选项选择及理由整体形态容器 DI / 服务定位器 / 组合根捕获组合根捕获——ModuleManager 本就是根两阶段 construct/wire 是 DI 的拆分却免去约 60 参数爆炸和 1,852 点 flag-day热路径严格改善ProjectModel vs AppState 顺序保持设置条件性 / 钉 PM 优先 / 钉 AppState 优先钉 ProjectModel 优先——正是生产环境 ProjectFile 机器每天运行的顺序且消灭重入边叶类捕获机制构造初始化列表引用 / 延迟指针 / 惰性访问器构造初始化列表引用——-Wreorder使初始化顺序错误成为编译期错误仅在接线前可达的类用延迟指针热路径时机随 S5 一起 / 延迟到门控的最后阶段延迟到 S6 基准门控——把唯一逐帧可见的变化隔离在--benchmark-hotpath之后守卫强度立即阻塞 / 建议后棘轮建议后棘轮——1,852 个既有调用点使阻塞式 flag-day 不可行建议制让调用面逐波收缩风险与缓解构造期重入核心隐患S3 钉住 ProjectModel 先于 AppState设置条件性边无法形成ProjectModel.cpp:446的围栏表面与所有接线前表面保持直接instance()绝不捕获。叶引用成员初始化顺序错误-Wreorder 零警告使其成为构建失败。接线前使用未赋值的五边形指针使用点Q_ASSERT(m_x)S5 明确接线前表面清单一次构建一个类。陈旧缓存标志导致热路径静默故障S6 把m_operationMode接入operationModeChanged--benchmark-hotpath门禁兜底。强制实例化导致行为变化作用域规则只钉住根已传递构造的模块S3 grep 对称性检查。1,852 个调用点上的范围蔓延严格波次边界advisory 计数逐波严格下降、永不增加。测试与验证计划单元无直接单元测试无tests/scripts/JS 面S2 lint 规则用合成Foo::instance()片段自测并对比code-verify.py前后阻塞计数。静态python3 scripts/documentation-verify.py校验 S1 文档每波对变更的 C 文件跑python3 scripts/code-verify.py --check各阶段 grep 对称性配方每个 C diff 经qt-cpp-review。集成维护者执行S3 与每个 S5 五边形类之后在 QuickPlot、ProjectFile、Console-only 三种模式启动确认正常启动、项目恢复与控制台输出。热路径维护者执行S6 后跑--benchmark-hotpath全部七档与 S6 前基线对比deploy.yml对发布的 PGO 二进制做最终兜底门禁。提交每次提交前运行python3 scripts/sanitize-commit.py工作树无 lint 债务。附录构造器捕获安全表前 15 大单例下表来自 spec 附录Capture BY others 其他类捕获该类是安全的Own deps capture mode 该类应如何获取自己的依赖#单例调用点数已验证构造器出边可被他人捕获自身依赖捕获模式1ProjectModel (343)ControlScript经 newJsonFilePM.cpp:2116可以但 ControlScript/worker 除外setupExternalConnections中的延迟指针ctor/newJsonFile 表面保持直接调用。绝不可 ctor 捕获 AppState活体 A-B 隐患2ConnectionManager (301)无可以延迟指针AppState、ProjectModel、FrameBuilder、Console::Handler、API::Server可 ctor 捕获 Translator3Dashboard (152)CSV::Player、MDF4::Player、ConnectionManager、AppState、FrameBuilder、Sessions::Player、TimerEventsDashboard.cpp:172-229不可以——无人 ctor 捕获 Dashboard延迟指针ctor 连接保持4AppState (146)ProjectModel条件性deriveFrameConfig可以但 ProjectModel 与 ControlScript 除外S3 后可 ctor 捕获 ProjectModel其余不可5ThemeManager (58)WorkspaceManagerloadUserThemes、Translator可以但这两者除外两者均可 ctor 引用捕获6FrameBuilder (56)LemonSqueezy - MachineID商业版可以延迟指针热路径成员仅在 S67Console::Handler (33)CommonFonts可以必须早于qInstallMessageHandler存在可 ctor 捕获 CommonFonts8CommonFonts (31)无GUI 线程字体库可以真叶类9Translator (29)无可以真叶类10TimerEvents (28)无可以真叶类11API::Server (27)CommandHandler平凡可以可 ctor 捕获 CommandHandler12CSV::Player (26)无可以近叶qApp 过滤器13WorkspaceManager (25)无mkdir 遗留迁移可以真叶类14MDF4::Player (25)无可以近叶15NotificationCenter (25)无可以必须早于消息处理器存在真叶类附录FrameParser 特例FrameParser23 个调用点只能保持惰性/延迟其构造函数调用engineForSource(0)而 Lua 引擎构造会触达FrameBuilder::instance()spec 附录引用的 LuaScriptEngine.cpp:167构造闭包依赖项目内容因此FrameParser不能被 ctor 捕获。它仍可出现在固定顺序中被强制实例化因为根已传递构造它但任何类都不得把它作为成员捕获。延伸阅读完整规范见 spec.md技术设计见 plan.md任务清单与落地记录见 tasks.md架构总览见 architecture.mdlint 规则实现见 code_verify_rules.py 与 code-verify.py组合根实现在 ModuleManager.cpp。【免费下载链接】Serial-StudioOpen-source telemetry dashboard. Supports UART, BLE, MQTT, Modbus, CAN Bus and more.项目地址: https://gitcode.com/GitHub_Trending/se/Serial-Studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考