企业官网建设流程全解析

• 嵌入式
• 物联网
• 硬件开发
• 驱动开发

本文是一份面向 FastLED 嵌入式 C++ 库的架构评审实战指南。它以仓库中的 架构评审 Agent 定义 为核心骨架，系统讲解 FastLED 的六层依赖架构、平台分发（dispatch）三后缀命名约定、_noop回退实现、Public Settings 模式、以及并行 IO 外设"一引擎双模式"的 ChannelEngine 统一规则，并配套可复用的评审流程与输出模板。读完本文，你将掌握一套完整的代码架构审查方法论，能够在 PR/diff、组件审计、依赖审计与 API 面审查四个场景中定位分层违规、循环依赖与 API 破坏。

一、为什么需要架构评审：维护大型嵌入式代码库的第一道防线

FastLED 是一个支持 Arduino、ESP32、STM32、RP2040、Teensy 等多种平台的 LED 动画库，代码横跨 examples、src/fl（核心库）、src/platforms（平台抽象）、src/fl/third_party（第三方依赖）与 tests（测试）五个大区。平台数量多、外设驱动杂（RMT、PARLIO、I2S、SPI、UART、FlexIO、ObjectFLED……），若没有强制的分层纪律，极易出现"平台代码反向包含核心逻辑""核心代码散布#ifdef ESP32""新增全局配置只提供自由函数却不暴露FastLED.setX()"之类的腐化点。

仓库通过 架构评审 Agent 定义 将架构审查标准固化为可执行的评审清单。它要求评审者在批准任何新抽象之前，先确认其真实的生产路径（仓库内或已命名的下游集成）以及用户可见结果的证据；对只有 fake/test 用户的接口或状态机、把声称的行为推迟到后续 issue 的"预留抽象"，尤其要标记出来。文中明确给出反例：不能把"准备工作型 PR"当作端到端验收测试的完成，FastLED #4534 即为此类被撤回的反例。

二、评审前的必读基础：cpp-standards 与核心模式

2.1 命名空间与头部约定

在动手评审前，Agent 定义要求先阅读 C++ 编码标准，其中约定的核心规范包括：

• 使用fl::命名空间而非std::，标准库头文件优先查找 fl/type_traits.h 等对应替代品；动态数组使用 fl::vector。
• fl::net两级命名空间约定：主用户类型（如fl::net::OTA）直接位于fl::net；支撑类型（枚举、传输类型、选项）放入fl::net::<module>子命名空间（如fl::net::ota::Service）；门面/集合型模块所有类型都在子命名空间（如fl::net::http::*）。移动类型进子命名空间时去掉模块前缀：OTAService→fl::net::ota::Service。
• API Object Pattern：公开包装头与其同名实现目录成对出现，用户只#includeAPI 头，包装头只做转发不做核心逻辑，目录内每个具体类型独立自洽。典范：src/fl/stl/fixed_point.h 包装 src/fl/stl/fixed_point/。
• Span 用法：优先用 fl::span 作为参数与返回值（零拷贝视图），容器可隐式转换，不必显式包裹。
• 宏命名：平台/特性检测宏遵循FL_IS_<PLATFORM><_OPTIONAL_VARIANT>模式（如FL_IS_STM32_F1、FL_IS_ESP_32S3），禁止FASTLED_*新宏——该规则由 Rust 版MacroPrefixChecker在bash lint --cpp中强制执行，存量名称集中在 legacy_macro_amnesty.txt 白名单管理。

2.2 三后缀分发约定（Three-suffix dispatch convention）

这是 FastLED 平台分发架构的核心词汇表，评审任何平台相关改动前必须默记：

router 的典型骨架（摘自 cpp-standards）：

// IWYU pragma: private // Platform detection #include "platforms/arm/is_arm.h" #include "platforms/esp/is_esp.h" #include "platforms/wasm/is_wasm.h" #if defined(FL_IS_WASM) #include "platforms/wasm/feature_wasm.impl.hpp" #elif defined(FASTLED_STUB_IMPL) #include "platforms/stub/feature_stub.impl.hpp" #elif defined(FL_IS_ESP32) #include "platforms/esp/32/feature_esp32.impl.hpp" #else // Fallback: null/no-op implementation #include "platforms/shared/feature_null.impl.hpp" #endif

评审检查点（来自 Agent 定义）：

1. 每组件一个 dispatcher：<component>.impl.cpp.hpp只能位于src/platforms/根目录（不能进平台族子目录），且只能被一个 TU 包含。
2. 平台实现一律以.impl.hpp结尾——不是.cpp.hpp（那是 dispatcher 专用），也不是裸.hpp（那暗示是普通头文件）。
3. dispatcher 的#else分支必须回退到src/platforms/shared/的_noop.hpp——没有回退就无法在不受支持平台上编译。
4. no-op 必须用字面_noop后缀：_null.hpp、_stub.hpp、_dummy.hpp、_empty.hpp都是对既定关键字约定的违反。
5. no-op 函数体必须真无事可做：返回0/false/nullptr/空 span，禁止断言、禁止日志、禁止任何副作用。
6. no-op 函数必须位于fl::platforms::命名空间，保持公开的fl::表面干净。
7. 能力宏归属组件而非平台：若 PR 新增FL_<PLATFORM>_<COMPONENT>_HAS_<FEATURE>（平台前缀），这是一个坏味道——标志应是组件作用域形式，用户代码不需要知道哪个平台提供该特性；同理，用组件名缩写（如FL_WDT_*而非FL_WATCHDOG_*）也是违规。

仓库中的可引用典范：

• Dispatcher：src/platforms/coroutine.impl.cpp.hpp
• No-op 回退：memory_noop.hpp、pin_noop.hpp、simd_noop.hpp，以及 watchdog_noop.hpp、embedded_fs_noop.hpp

以 memory_noop.hpp 为实例，其函数体完全符合第 5/6 条规则：

namespace fl { namespace platforms { // @return Always returns 0 (heap tracking not available) inline size_t getFreeHeap() FL_NO_EXCEPT { return 0; } ... } // namespace platforms } // namespace fl

该文件同时标注// IWYU pragma: private（只能经 dispatcher 间接包含）、函数inline保证多 TU 包含时 ODR 安全。值得注意的例外：no-op 并非"一律返回 0"——当 API 契约要求文档化哨兵值时也允许（如 pin_noop.hpp 的needsPwmIsrFallback返回true，因为 no-op 平台确实需要 ISR 回退路径；setPwmFrequencyNative返回-4作为文档化的"不支持"错误码）。no-op 的意义是让用户代码在不受支持平台上继续运行。

还有一类 stub-only 变体：当 no-op 只对 host/stub 构建有意义（伪装成真实 MCU 上不存在的 OS 原语）时，放在src/platforms/stub/并使用_stub_noop.h后缀，例如mutex_stub_noop.h、thread_stub_noop.h、semaphore_stub_noop.h。

三、平台分发架构检查（Platform Dispatch Architectural Checks）

Agent 定义专门列出平台分发新增/变更时逐条核验的清单（上文 2.2 的 7 条即为其核心），并给出引用范例便于向开发者解释模式。除命名与回退规则外，还需确认：

• .cpp.hpp文件必须带IWYU pragma: private；
• 平台专属.cpp实现文件带平台守卫，头文件不带（干净的接口给 IDE/IntelliSense 提供更好的代码辅助）——正确形态是"header.h无守卫，header.cpp有守卫"，避免头尾都加#ifdef ESP32；
• 核心src/fl/中禁止#ifdef ESP32/#ifdef __AVR__等散布的平台判断，平台检测一律流经src/platforms/的分发头；
• 能力检测而非环境检测：ESP32 上判断"是 Arduino 还是 ESP-IDF"要问"driver/gpio.h是否可用"（FL_HAS_INCLUDE能力探测），而不是#ifdef ARDUINO——因为 Arduino-ESP32 同样打包了 ESP-IDF 驱动，能力探测能在两种框架下都选中 IDF 原生实现。详见 src/platforms/esp/32/ARCHITECTURE.md。

四、Channel 驱动架构检查：并行 IO 外设的"一引擎双模式"统一规则

当评审对象涉及 bus.h（Bus枚举）或src/platforms/**/drivers/**/channel_engine_*.{h,cpp.hpp}时，必须执行并行 IO 外设的 unified clockless+SPI 引擎规则。这条规则是 2026-06-27 在 #3428 FlexIO-SPI / ObjectFLED-SPI 实现中确立的：最初的设计草案把Bus::FLEX_IO_SPI与Bus::OBJECT_FLED_SPI拆成独立枚举槽位，并各自派生出ChannelEngineFlexIOSPI/ChannelEngineObjectFLEDSPI引擎；用户最终回退到统一模式，因为分叉让维护面扩大 4 倍而没有任何行为收益——外设是分发边界，不是模式。

4.1 六条强制规则

1. 每个外设一个 ChannelEngine，而不是每个模式一个。如果外设能原生同时跑 clockless WS281x 和 clocked SPI 芯片组（FlexIO2、ObjectFLED 的 DMA-to-GPIO 组、ESP32 PARLIO、LCD_CAM、I2S 等），引擎必须在同一个类中处理两种模式。标记任何为同一外设引入ChannelEngineXxxSPI作为ChannelEngineXxx兄弟类的 PR。
2. 每个外设一个Bus枚举项。标记任何为已有 clocklessBus::X的外设新增Bus::X_SPI枚举值（Bus::FLEX_IO_SPI、Bus::OBJECT_FLED_SPI、Bus::PARLIO_SPI、Bus::LCD_CAM_SPI等）的 PR。
3. getCapabilities()返回Capabilities(true, true)——统一引擎同时声明 clockless 与 SPI 能力。
4. BusSupports<Bus::X, ClocklessChipset>与BusSupports<Bus::X, SpiChipsetConfig>都特化为fl::true_type。
5. canHandle()同时接受两类芯片组，按各自的 pin/时序路由可行性分别把关。
6. show()按通道路由：依据data->isClockless()与data->isSpi()分流；相邻通道间发生模式切换时，必须先重配外设（shifter/定时器/DMA TCD）再发送，绝不静默丢弃"错误模式"的通道。

对应到 Channels API 文档 的推荐实现形态：

class ChannelEngineMyPeripheral : public fl::IChannelDriver { // Both modes -> one engine returns BOTH caps. Capabilities getCapabilities() const FL_NO_EXCEPT override { return Capabilities(/*clockless=*/true, /*spi=*/true); } bool canHandle(const ChannelDataPtr& data) const FL_NO_EXCEPT override { if (!data) return false; if (data->isClockless()) return pin_routes_for_clockless(data->getPin()); if (data->isSpi()) { const auto* spi =>inline void setPowerModel(const PowerModelRGB& model) { set_power_model(model); }

即用户调用FastLED.setPowerModel(PowerModelRGB(40, 40, 40, 2, 0.87f))，薄薄的inline委托把控制权交给自由函数fl::set_power_model。仅自由函数而无CFastLED包装的全局 setter 即构成架构违规。

6.2 适用范围与过渡名单

规则不适用于：辅助函数、构造函数、工厂、per-object 配置、匿名命名空间 /fl::detail::内部、只修改调用方自有对象的函数（如fl::fill_solid(span, color)）。

祖父化过渡名单（Grandfathering）：少量遗留裸 setter 被列入PUBLIC_SETTINGS_GRANDFATHERED名单（位于 public_settings.rs 的PublicSettingsPatternChecker），豁免直到其包装落地：fl::set_input_gamut（#2710）、fl::enable_rgbw_colorimetric_lut、fl::set_rgbww_colorimetric_profile。名单随每个名称被包装而逐项移除；新增名称不会获得祖父化豁免。这意味对新代码是严格模式：写过即审、审过即改。

七、评审流程：从 Scope 到输出

7.1 四个评审范围

7.2 分步检查清单

1. Scope the Review：确定评审范围（上述四选一）。
2. Check Layer Violations：搜寻向上依赖、循环依赖、实现细节泄漏。
3. Check API Surface：
   • 公开头卫生：最小化 include（尽量前置声明）、公开头无实现细节、命名一致（fl::命名空间）、正确使用 API Object Pattern。
   • 破坏性变更检测：删除公开函数/类、改变函数签名、改变枚举值、重命名类型而无别名。
   • Public Settings Pattern 强制（HIGH 级，见第六节）。
4. Check Dependency Direction：对照第五节允许/禁止矩阵，双向核验。
5. Check Platform Dispatch：.cpp.hpp必须IWYU pragma: private；平台.cpp有守卫而头文件无；核心src/fl/无#ifdef ESP32/#ifdef __AVR__；平台检测流经分发头。
6. Check Code Organization：单一职责、内聚分组、超过 500 行的文件标记为建议拆分、新公开 API 应有对应测试文件。

7.3 输出格式模板

## Architecture Review ### Summary - **Scope**: [files/component reviewed] - **Critical Issues**: N - **Warnings**: N - **Suggestions**: N ### Critical Issues (must fix) #### [Issue Title] - **Type**: Layer violation / Circular dependency / API break / etc. - **Location**: path/to/file.h:42 - **Details**: [explanation] - **Fix**: [recommended change] ### Warnings (should fix) #### [Issue Title] - **Type**: [category] - **Location**: path/to/file.h:42 - **Details**: [explanation] - **Suggestion**: [recommended change] ### Suggestions (nice to have) - [improvement opportunity] ### Dependency Map (if requested) [ASCII diagram of actual dependencies found]

7.4 评审工作纪律（Key Rules）

• 先读 cpp-standards.md 再动手，命名空间与模式约定优先于一切；
• 双向检查——向上与向下的依赖违规都要查；
• 量化影响——写"影响 12 个文件"而不是"影响很多文件"；
• 区分稳定与不稳定——对稳定 API 的改动严重级更高；
• 留在项目根目录——评审过程不cd到子目录；
• Python 命令一律用uv run；
• 多组件审计使用 TodoWrite跟踪进度。

八、配套机制：Rust 静态检查器与 CodeRabbit

架构规则不仅存在于文档，还通过自动化工具落地：

• ci/lint_cpp_rs/src/checkers/ 目录下集中了 20 余个 Rust 检查器，与架构评审直接相关的包括：public_settings.rs（Public Settings Pattern 强制）、macro_prefix.rs（FL_前缀强制）、container_ptr.rs（禁止对fl::容器取裸指针，ContainerNonContiguousPtrChecker对fl::deque/fl::circular_buffer硬失败，ContainerElementAddressChecker对fl::vector/fl::string等警告）、platform_policy.rs、platform_trampoline.rs（平台分发相关）、singleton_elision.rs等。它们通过 run_all_checkers.py 统一驱动。
• .coderabbit.yaml 为src/fl/channels/bus.h与 channel 驱动路径配置 CodeRabbit 路径指令，自动拦截并行 IO 模式分叉类的新增枚举。

因此架构评审 Agent 的定位是文档化标准 + 人工复核 + 自动化检查三层体系的中间层：把编码标准翻译成可执行的评审清单，同时在 PR 合并前兜住静态检查器无法判断的"架构意图"类问题（如新抽象是否有真实生产路径、维护成本是否被低估）。

九、快速自检表（评审交付前）

• 新抽象有真实生产路径或已命名的下游集成，且能说明用户可见结果；
• 无仅 fake/test 用户的接口/状态机，无把行为推迟到后续 issue 的"预留抽象"；
• 未把"准备工作型 PR"当作端到端验收测试的完成（#4534 为反例）；
• 平台分发三后缀命名正确，_noop回退存在且位于src/platforms/shared/；
• 并行 IO 外设未分叉成 clockless/SPI 双引擎或双Bus枚举；
• 新全局 setter 均有CFastLED::setX()委托，未新增祖父化名单之外的自由函数；
• 层规则双向核验通过，量化了影响文件数；
• 输出遵循 Summary / Critical / Warnings / Suggestions 模板。

• 嵌入式
• 物联网
• 硬件开发
• 驱动开发