Codelab 概览
本 Codelab 通过 33 个可独立编译运行的示例程序，带你从零上手 OnePath™ 统一逻辑网络。每个示例都是一个完整的 C 程序，聚焦一个能力点：自动发现、发布订阅、查询存储、可靠性纠错、零拷贝、安全、可观测性、便捷协同 API、多模冗余。
按主题分组阅读：
- 基础 — 自动发现 / 编码与键表达式 / 拉取订阅 / 一次性读写
- 查询与存储 — Get 查询 / 分布式存储 / 持久请求器
- 可靠性 — 断线重连 / 存活快照 / 连接监控 / 数据完整性 / 三模冗余 TMR
- 性能与零拷贝 — Ping/Pong / 延迟自适应 / 共享内存系列
- 安全 — TLS 加密 / 用户认证
- 可观测性 — 端到端链路追踪 / 网络拓扑地图
- 便捷 API 与协同 — 三模存储 / 三模计算 / JSON / 状态同步 / 自组网 Mesh / 会话信息
- 多模冗余 XMR — XMR 计算 / XMR 存储
全量示例索引
| # | 用例 | 演示能力 | 变体 | 运行命令（节选） |
|---|---|---|---|---|
| 1 | 自动发现 | 组播自动发现 + Peer 模式 Pub/Sub | 双后端 | onepath_discovery pub / sub |
| 2 | 用户认证 | 用户名密码鉴权入网 | 仅 full | onepath_auth_sub / onepath_auth_pub |
| 3 | TLS 加密 | TLS 加密通信 | 双后端 | onepath_tls_sub / onepath_tls_pub |
| 4 | 断线重连 | 自动重连 + 存活监控 | 双后端 | onepath_reconnect_sub / onepath_reconnect_pub |
| 5 | 分布式存储 | 内存存储 + 应答查询 | 双后端 | onepath_storage_demo |
| 6 | 查询演示 | 客户端主动查询 | 双后端 | onepath_get_demo -k "demo/example/**" |
| 7 | 一次性读写 | One-shot Put/Delete | 双后端 | onepath_put_delete put -k ... -v ... |
| 8 | 序列化 | 类型化序列化/反序列化 | 双后端 | onepath_bytes_demo |
| 9 | 共享内存 | SHM 零拷贝传输 | 仅 full | onepath_shm_sub / onepath_shm_pub |
| 10 | 高级 Pub/Sub | 缓存 + 丢包恢复 + 历史回放 | 仅 full | onepath_advanced_pub / onepath_advanced_sub |
| 11 | 会话信息 | 本节点 ID + 邻居列表 | 双后端 | onepath_info |
| 12 | 延迟测试 | Ping/Pong RTT 测量 | 双后端 | onepath_ping_pong pong / ping |
| 13 | 数据完整性 | CRC32 校验 + 位翻转检测 | 双后端 | onepath_integrity_sub / onepath_integrity_pub |
| 14 | 三模冗余 TMR | 2-of-3 多数投票纠错 | 双后端 | onepath_tmr_node voter/node1/2/3 |
| 15 | 延迟自适应 | RTT 探测 + QoS 动态调整 | 双后端 | onepath_latency_adapt monitor/sender |
| 16 | 状态同步 | HLC + LWW + 断线恢复 | 双后端 | onepath_state_sync --name A/B/C |
| 17 | 自组网 Mesh | 服务注册发现 + 拓扑表 | 双后端 | onepath_mesh_node --name ... --service ... |
| 18 | 拉取式订阅 | 环形缓冲非阻塞拉取 | 双后端 | onepath_pull_sub --size 3 --interval 2 |
| 19 | 存活快照查询 | 一次性查询存活节点 | 双后端 | onepath_liveliness_query -k "mesh/service/**" |
| 20 | 持久请求器 | 持久请求器 + 非阻塞查询 | 双后端 | onepath_requester_demo requester |
| 21 | SHM 请求/应答 | SHM 应答 + SHM 查询 | 仅 full | onepath_shm_request responder/get |
| 22 | SHM 延迟测试 | SHM Ping/Pong + 条件变量同步 | 仅 full | onepath_shm_ping pong/ping |
| 23 | 吞吐量测试 | 普通/SHM 吞吐对比 | 仅 full | onepath_throughput sub/pub/pub-shm |
| 24 | SHM 传输基准 | SHM vs socket 延迟（含 iperf3 加压） | 仅 full | onepath_shm_bench |
| 25 | 编码类型 | 编码类型 + 预声明键表达式 | 双后端 | onepath_encoding_demo local/pub/sub |
| 26 | 连接监控 | 会话信息轮询 + 存活监控 | 双后端 | onepath_link_monitor |
| 27 | 链路追踪 | 三进程端到端 tracing | 双后端 | onepath_tracing_demo sensor/router/storage |
| 28 | 网络拓扑地图 | 拓扑自省 + 全局图聚合 | 双后端 | onepath_topology_map nodeA/B/C |
| 29 | JSON 数据处理 | JSON/JSON5 解析、查询、修改、序列化 | 双后端 | onepath_json_demo |
| 30 | 三模存储 | 便捷 API：订阅摄入 + 应答查询 | 仅 full | onepath_store_node store/put/get/del |
| 31 | 三模计算 | 便捷 API：流式变换 + 按需 RPC | 仅 full | onepath_compute_node compute/feed/call |
| 32 | 多模冗余计算 | N worker 冗余计算 + 投票选举 | 双后端 | onepath_xmr_compute_demo consume/worker/submit |
| 33 | 多模冗余存储 | N 副本冗余存储 + 读端投票 | 双后端 | onepath_xmr_store_demo replica/put/get |
变体列说明：「双后端」表示完整版与精简版（tiny）均提供该示例；「仅 full」表示该能力（共享内存 SHM、高级 Pub/Sub、用户认证、三模存储/计算便捷 API）只在完整版提供，精简版不构建对应程序。完整版与精简版的差异是能力边界，全部能力在各自预编译库中开箱可用，无需任何额外配置。
如何编译与运行示例
每个示例都是一个独立、可单独编译的 C 程序，只依赖 OnePath 的公共头文件 onepath.h 与一个 OnePath 动态库。本 Codelab 假设你已拥有预编译好的 OnePath 库与头文件。
编译契约
用户代码编译时需要满足两点：
- 定义变体宏：完整版用
-DCONFIG_ONEPATH_VARIANT_FULL=1，精简版用-DCONFIG_ONEPATH_VARIANT_TINY=1（二选一）。 - 链接对应变体的 OnePath 动态库（完整版与精简版各一个
.so）。
运行时没有任何外部依赖——网络栈已静态嵌入到 OnePath 库内部，部署时只需带上这一个 .so。
一个最小编译示例：
bash
# 完整版
cc my_app.c -DCONFIG_ONEPATH_VARIANT_FULL=1 -lonepath-full -o my_app
# 精简版
cc my_app.c -DCONFIG_ONEPATH_VARIANT_TINY=1 -lonepath-tiny -o my_app运行约定
本 Codelab 给出的运行命令统一使用仓库内已构建好的可执行路径，例如：
bash
./examples/build/release/<变体>/onepath_discovery pub其中 <变体> 为 full（完整版）或 tiny（精简版）。可执行文件已内置运行时库搜索路径，直接运行即可。
角色与多终端
许多示例是多角色程序：同一个二进制通过子命令（如 pub / sub、voter / node1、consume / worker）扮演不同角色。这类示例通常需要多个终端分别启动各角色。Codelab 的「运行命令」小节给出了完整的多终端编排。
是否需要预启动路由器
- 无需路由器：多数示例默认走 Peer 模式 + 组播自动发现，直接在同一网络内多终端启动即可互相发现通信。
- 需要路由器：用户认证、TLS 加密、断线重连 等示例需要一个预先启动并正确配置（凭据 / 证书链）的路由节点；缺少时会在会话打开阶段返回连接失败并退出，这是预期行为。