115 lines
2.9 KiB
Markdown
115 lines
2.9 KiB
Markdown
|
# 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 结构定义
|
|||
|
|
|
|||
|
|
```cpp
|
|||
|
|
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()` 检查：
|
|||
|
|
|
|||
|
|
1. `traceId` 非空
|
|||
|
|
2. `objectRef` 非空且为合法五层路径
|
|||
|
|
3. `command` 非空
|
|||
|
|
4. `params` 为 JSON 对象（非 null、非数组）
|
|||
|
|
|
|||
|
|
### 3.4 示例
|
|||
|
|
|
|||
|
|
**写值命令：**
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"type": "executeCommand",
|
|||
|
|
"traceId": "trace-cmd-001",
|
|||
|
|
"objectRef": "DemoSite/DemoSystem/DemoAsset/SimModbusDevice/Temperature",
|
|||
|
|
"command": "write",
|
|||
|
|
"params": {"value": 42.5}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**校验失败响应（OPC UA Method 出参）：**
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{"success": false, "error": "objectRef is invalid"}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**成功响应：**
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{"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`
|