核心概念

本页讲清使用 OnePath 前需要理解的几个核心模型：统一逻辑网络、层级化寻址与通配符、两种通信范式、会话与不透明句柄、节点角色。

统一逻辑网络

OnePath 的核心抽象是一张统一逻辑网络：无论节点身处数据中心、局域网、跨网段还是同一台机器的不同进程，对应用而言都被收敛成一张统一、扁平、可寻址的逻辑网络。节点之间无需感知彼此的物理位置、所在子网或底层传输方式——同一份应用代码到处都能正确工作。

同一网络内的节点自动相互发现并建立连接，无需手工维护地址列表。跨网段时，由转发网关在不同子网之间中继消息，对发布者与订阅者完全透明。

层级化寻址与通配符

OnePath 用类似文件路径的层级名称（key expression）标识资源，层与层之间用 / 分隔，例如：

robot/sensor/temperature
robot/sensor/humidity
building/floor3/room12/light

订阅与查询时可使用通配符进行批量匹配：

通配符	含义	示例	匹配
*	匹配单个层级	robot/sensor/*	robot/sensor/temperature、robot/sensor/humidity；不匹配 robot/sensor/cam/rgb
**	匹配任意多个层级（含零层）	robot/**	robot/sensor/temperature、robot/arm/joint/3 等所有 robot/ 下资源

这让「订阅某一类资源」成为一行代码的事，天然适合海量、动态的数据与服务空间。判断两个 key expression 是否有交集可用 onepath_keyexpr_intersects。

两种通信范式

OnePath 内置两类通信范式，覆盖绝大多数分布式场景。

• 发布 / 订阅（Pub/Sub）：面向数据分发，一对多广播。发布者不关心有多少订阅者；订阅者按 key expression（含通配符）声明兴趣，匹配的消息自动送达。接收方式有回调（push）与拉取（pull 通道）两种。
• 请求 / 响应（Query/Reply）：面向服务调用。请求者发起、响应者应答，内建请求关联与多应答聚合。一次性查询用 onepath_get，需要反复发起则声明持久请求者 onepath_declare_requester；服务侧用 onepath_declare_responder 注册应答回调。

此外还提供存活感知（Liveliness）：节点可声明存活令牌，其他节点订阅其上线 / 下线事件，用于服务注册与拓扑维护。

会话与不透明句柄模型

一切从会话（session）开始：onepath_open 打开会话后返回一个 onepath_session_t 句柄，之后所有发布者、订阅者、应答器、请求者、令牌都在这个会话上声明。

OnePath 的所有资源都以不透明句柄（opaque handle）形式暴露——你拿到的是一个类型化的句柄值，内部结构对用户不可见，只能通过 API 操作。这隐藏了底层实现细节，也保证了 API 的长期稳定。

每个 onepath_declare_* / onepath_open* / onepath_*_create 创建的句柄，都有对应的 onepath_*_destroy / onepath_close 负责销毁。销毁顺序与所有权规则详见 内存管理。

节点角色

会话可以三种角色之一打开，决定本节点在网络中的连接行为：

角色	打开方式	行为
peer（对等）	onepath_open / onepath_open_peer	默认角色。与同网段对等节点直接互联，启用多播自动发现，去中心化。
client（客户端）	onepath_open_client(&s, endpoint)	连接到一个指定端点（通常是 router），由其转发流量。
router（路由器 / 转发网关）	配置 mode = "router" 后打开	承担转发与跨网段中继，连接不同子网内的节点。

也可通过配置构建器（onepath_config_new → onepath_config_set_mode / onepath_config_add_endpoint → onepath_open_with_config）或 JSON5 配置文件（onepath_open_config_file）做更细的会话配置。完整接口见 API 手册。