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`
|