个人笔记

外观

1 eboxcli 宣贯文档 ​

1.1 宣贯目标 ​

本次宣贯面向研发、测试、联调与运维协作团队，目标是统一对 eboxcli 的认知，并形成可复制的使用与扩展方式：

  • 统一命令入口，降低工具碎片化和沟通成本
  • 建立 plugin + verb 的能力组织心智模型
  • 让一线同学可以直接上手 topic 与 service 核心场景
  • 让研发能够按规范快速扩展新插件与新命令

1.2 一句话架构说明 ​

eboxcli 是一个基于 CLI11 与 Boost.DLL 的可扩展 CLI（命令行）框架，通过动态库（插件）加载能力，按 主命令 -> 插件 -> Verb（子命令） 进行组织与执行。

1.3 总体设计图 ​

mermaid
flowchart LR
    User["用户命令输入<br/>./eboxcli <plugin> <verb> ..."] --> Main["eboxcli 主程序"]
    Main --> PM["PluginManager（插件管理器）"]
    PM --> Scan["扫描 pluginlib 目录"]
    Scan --> DLL["动态库：libcli<plugin>.so"]
    DLL --> Factory["create_plugin 工厂函数"]
    Factory --> Plugin["IPlugin 实现类"]
    Plugin --> VerbReg["VerbRegistry（注册表）"]
    VerbReg --> Verb["Verb 实例（echo/hz/bw/...）"]
    Verb --> Exec["执行逻辑"]
    Exec --> Transport["ZMQ / Iceoryx"]
    Transport --> Output["终端输出（观测/诊断/调用结果）"]

1.4 扩展流程图 ​

mermaid
flowchart TD
    B["创建插件目录（include/src）"] --> C["实现 IPlugin 并导出工厂函数"]
    C --> D["新增 Verb 并注册到 VerbRegistry"]
    D --> E["更新 CMake 输出到 pluginlib"]
    E --> F["编译安装并验证 -h 与命令执行"]
    F --> G["补齐 usage 文档与示例"]

1.5 核心设计 ​

1.5.1 关键组件 ​

  • PluginManager：负责插件发现、加载、注册与执行路由
  • IPlugin：插件统一接口，约束插件接入方式
  • Verb：子命令抽象，承载实际执行逻辑
  • VerbRegistry：维护插件与 Verb 工厂函数的注册关系
  • ISerializable：消息对象与序列化处理接口

1.5.2 为什么这样设计 ​

  • 可扩展：新增插件/Verb 不需要侵入主程序
  • 可维护：统一注册与命名规则，降低多人协作成本
  • 可演进：动态加载天然支持能力按需交付

1.6 功能全景与典型场景 ​

1.6.1 功能全景 ​

  • 插件发现与命令注册
  • Topic 数据观测与诊断
  • Topic 数据发布
  • Service 请求-响应调用
  • ZMQ 与 Iceoryx 双传输支持

1.6.2 典型场景 ​

  1. 联调阶段看消息是否正确
    • 使用：./eboxcli topic echo <channel> <topic> <message_type>
  2. 性能排查看频率/带宽/延迟
    • 使用：topic hz、topic bw、topic delay
  3. 构造输入验证上下游逻辑
    • 使用：./eboxcli topic pub ...
  4. 服务链路健康性验证
    • 使用：./eboxcli service call ...

1.7 快速上手 ​

1.7.1 查看可用命令 ​

bash
./eboxcli -h

1.7.2 查看主题 ​

bash
./eboxcli topic list

1.7.3 订阅回显消息 ​

bash
./eboxcli topic echo pub_sub_server11 /aa/bb/ datacenter.proto.TestData

1.7.4 查看频率与带宽 ​

bash
./eboxcli topic hz pub_sub_server11 /aa/bb/ -w 100
./eboxcli topic bw pub_sub_server11 /aa/bb/

1.7.5 发送消息 ​

bash
./eboxcli topic pub data_channel position_data Position --r 10 --t 100

1.7.6 发起服务调用 ​

bash
./eboxcli service call --channel cmd_channel --req-type SetSpeed --rsp-type SetSpeedAck --req-data "{speed:100}"

1.8 端到端使用示例 ​

1.8.1 示例 A：3 分钟完成一次 Topic（主题）观测 ​

目标：确认某 channel/topic 是否有消息，并验证消息类型是否匹配。

bash
# 1) 看全量命令入口
./eboxcli -h

# 2) 看可用 topic
./eboxcli topic list

# 3) 订阅并回显消息
./eboxcli topic echo pub_sub_server11 /aa/bb/ datacenter.proto.TestData

预期结果：

  • -h 能看到目标插件（如 topic）
  • topic list 能看到目标 channel/topic
  • topic echo 有持续输出，且字段可被解析

失败时优先排查：

  1. channel/topic 是否拼写一致
  2. message_type 是否与实际消息类型一致
  3. 运行环境是否具备对应 proto 与依赖

1.8.2 示例 B：4 分钟完成一次性能初筛 ​

目标：用同一套命令快速判断“频率、带宽、时延”是否异常。

bash
# 频率
./eboxcli topic hz pub_sub_server11 /aa/bb/ -w 100

# 带宽
./eboxcli topic bw pub_sub_server11 /aa/bb/

# 延迟
./eboxcli topic delay pub_sub_server11 /aa/bb/ -w 100

预期结果：

  • hz 输出稳定且无大幅抖动
  • bw 平均大小与业务预期一致
  • delay 的平均值、最大值在可接受阈值内

1.8.3 示例 C：3 分钟完成一次链路注入与调用验证 ​

目标：模拟发布侧输入，并验证服务调用通路可用。

bash
# 注入测试消息
./eboxcli topic pub data_channel position_data Position --r 10 --t 100

# 发起服务调用（手动模式）
./eboxcli service call --channel cmd_channel --req-type SetSpeed --rsp-type SetSpeedAck --req-data "{speed:100}"

预期结果：

  • topic pub 执行期间下游可观察到输入流量
  • service call 返回响应且语义正确

1.9 Iceoryx（共享内存）模式示例 ​

bash
# echo：切换到 Iceoryx
./eboxcli topic echo pub_sub1 / TestData --iox

# hz：指定结构体类型
./eboxcli topic hz pub_sub1 / --iox TestData

# bw：指定结构体类型
./eboxcli topic bw pub_sub1 / --iox TestData

宣贯建议强调：

  • --iox 不是“性能开关”，而是“传输通路切换”
  • 切换后必须保证消息类型注册与运行依赖完整

1.10 扩展能力宣贯 ​

1.10.1 插件扩展流程 ​

  1. 新建插件目录（include/src）
  2. 实现插件类并继承 IPlugin
  3. 导出工厂函数（如 EXPORT_CLI_PLUGIN(...)）
  4. 新增 Verb 并注册到插件（REGISTER_VERB_FOR_PLUGIN(...)）
  5. 更新 CMake，输出到插件目录并安装

1.10.2 传输与消息扩展 ​

  • ZMQ 路径：支持通用消息回显与 proto 动态解析
  • Iceoryx 路径：需要按 message_type 注册对应 Subscriber（订阅者）工厂
  • 新类型接入时需同步消息序列化与注册项

1.11 规范要求 ​

1.11.1 命名规范 ​

  • 插件名称：全小写（例如 hello、topic）
  • Verb 类名：以 Verb 结尾（例如 EchoVerb）
  • 插件库名：libcli<pluginname>.so

1.11.2 目录与构建规范 ​

  • 插件以独立目录维护
  • 插件库输出到统一 pluginlib 目录
  • 扩展库输出到对应功能目录（如 ioxlib）

1.11.3 交付规范 ​

  • 新增能力必须附带：命令示例、参数说明、最小可运行案例
  • 文档同步更新 usage.md 与对应插件说明

1.12 常见问题（FAQ） ​

1.12.1 为什么 -h 看不到某插件？ ​

  • 插件动态库命名不符合规则
  • 插件未编译/未安装到扫描目录
  • 导出工厂函数缺失或符号名不匹配

1.12.2 --iox 模式失败常见原因 ​

  • 未注册对应消息类型的 Subscriber 工厂
  • 消息类型名与注册名不一致
  • 运行环境缺少对应依赖或配置

1.12.3 回显消息为空或无法解析 ​

  • message_type 未正确提供
  • proto 文件未按要求安装到指定配置目录

1.12.4 排障建议顺序 ​

  1. 先确认命令入口可见（./eboxcli -h）
  2. 再确认资源可见（topic list/info）
  3. 再确认数据可见（echo/pub）
  4. 最后看性能指标（hz/bw/delay）

基于 VitePress 构建

Copyright © 2026 ww1820