softbus_api

路径： src/softbus_api
构建目标： softbus_api（STATIC 库）
层级： L1 契约层

1. 概述

softbus_api 定义跨模块共享的控制面契约。当前仅暴露 ExecuteCommand 结构体，作为 OPC UA Method、TCP 下行与边缘回调的统一载荷格式。

2. CONSTRAINTS

softbus_api 仅定义跨边界命令语义，不包含传输或协议实现。
新增命令类型须通过扩展 command 字段值实现，保持 ExecuteCommand 结构稳定。
JSON 序列化/反序列化与校验逻辑集中在本模块，调用方不得绕过 validate()。
本模块不得依赖 transport、opcua、daemon 或 edge。

3. ExecuteCommand

3.1 结构定义

namespace softbus::api {

struct ExecuteCommand {
    std::string traceId;
    std::string objectRef;
    std::string command;
    nlohmann::json params;

    static ExecuteCommand fromJson(const nlohmann::json& j);
    nlohmann::json toJson() const;
    bool validate(std::string* error) const;
};

}

3.2 JSON 字段

字段	类型	必填	说明
`type`	string	是（线协议）	固定 `"executeCommand"`，仅线编码时包含
`traceId`	string	是	追踪 ID
`objectRef`	string	是	五层对象路径
`command`	string	是	命令名称
`params`	object	是	命令参数

3.3 校验规则

validate() 检查：

traceId 非空
objectRef 非空且为合法五层路径
command 非空
params 为 JSON 对象（非 null、非数组）

3.4 示例

写值命令：

{
  "type": "executeCommand",
  "traceId": "trace-cmd-001",
  "objectRef": "DemoSite/DemoSystem/DemoAsset/SimModbusDevice/Temperature",
  "command": "write",
  "params": {"value": 42.5}
}

校验失败响应（OPC UA Method 出参）：

{"success": false, "error": "objectRef is invalid"}

成功响应：

{"success": true}

4. 使用场景

调用方	场景
`UaMethodBinder`	OPC UA 客户端调用 `ExecuteCommand` Method
`CommandDispatcher`	校验并转发至 `TcpUplinkServer`
`UplinkWire`	编码/解码 TCP 线消息
`softbus_edge`	接收下行命令并执行（Phase 1 仅日志）

5. 数据流位置

OPC UA Client
  → UaMethodBinder (JSON 入参)
  → ExecuteCommand::fromJson() + validate()
  → CommandDispatcher::dispatch()
  → UplinkWire::encodeWireMessage()
  → TCP → Edge commandHandler

6. 依赖

softbus_core（ObjectRef 校验）
nlohmann_json
被依赖： softbus_transport, softbus_opcua, softbus_edge, softbus_daemon

7. Phase 2 规划

扩展命令类型：read、subscribe、discover
增加命令响应结构 ExecuteResult（含 statusCode、result 字段）
支持批量命令 ExecuteCommandBatch

2.9 KiB Raw Blame History Unescape Escape