refactor(array-tracer): 移除 preset 指令并简化类型参数
- 将 preset 功能合并到 create 指令中,简化 API 设计 - 移除 ArrayTracerPresetCommand 类型及相关处理逻辑 - 调整 createArrayTracer 泛型参数以直接接受数组类型 - 更新相关文档以反映新的初始化模式
This commit is contained in:
@@ -4,6 +4,8 @@
|
||||
|
||||
Structrail 平台的核心目标是提供一套**语言无关**的数据结构可视化协议。这意味着我们的 SDK 需要在不同特性的编程语言中(从高动态的 Python/JS 到静态底层的 C/C++)提供一致的功能体验。
|
||||
|
||||
**注意,我们不再需要 `preset` 指令了,但是即便 `preset` 的参数被合并到 `create` 指令中,这篇文档对于如何在不同语言中实现 `preset` 功能的说明仍然是有价值的。**
|
||||
|
||||
其中,`preset` 指令(一次性同步数组/容器状态)在静态类型语言(特别是 C 语言)中的实现是最大的挑战。本文档旨在论证其可行性,并为未来各语言 SDK 的实现提供参考规范。
|
||||
|
||||
## 核心挑战:数组的异构性
|
||||
@@ -17,20 +19,17 @@ Structrail 平台的核心目标是提供一套**语言无关**的数据结构
|
||||
为了抹平差异,我们建议 SDK 接口设计遵循\*\*“渐进式暴露”\*\*原则:
|
||||
|
||||
1. **Level 1: 智能推断接口**(针对 TS, Python, Java 等)
|
||||
- 用户直接传数组对象。
|
||||
- SDK 内部自动获取长度、遍历序列化。
|
||||
|
||||
* 用户直接传数组对象。
|
||||
|
||||
* SDK 内部自动获取长度、遍历序列化。
|
||||
2. **Level 2: 显式元数据接口**(针对 C++, Go, Rust 等)
|
||||
- 用户传递数据指针 + 长度。
|
||||
- 利用泛型/模板自动推导元素序列化逻辑。
|
||||
|
||||
* 用户传递数据指针 + 长度。
|
||||
|
||||
* 利用泛型/模板自动推导元素序列化逻辑。
|
||||
3. **Level 3: 手动序列化接口**(针对 C 语言)
|
||||
- 用户传递数据指针 + 长度 + 元素大小 + 序列化策略。
|
||||
|
||||
* 用户传递数据指针 + 长度 + 元素大小 + 序列化策略。
|
||||
|
||||
***
|
||||
---
|
||||
|
||||
## 各语言实现参考
|
||||
|
||||
@@ -156,7 +155,7 @@ tracer_preset_cb(t, nums, 3, sizeof(int), my_int_serializer);
|
||||
"tracer": "uuid-...",
|
||||
"action": "preset",
|
||||
"params": {
|
||||
"data": [1, 2, 3, 4] // 或者是 [{"x":1,"y":2}, ...]
|
||||
"data": [1, 2, 3, 4] // 或者是 [{"x":1,"y":2}, ...]
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -167,4 +166,3 @@ tracer_preset_cb(t, nums, 3, sizeof(int), my_int_serializer);
|
||||
|
||||
1. **`preset`** **指令是可移植的**:即使在最底层的 C 语言中,通过适当的 API 封装(宏或格式化串),也能实现与高级语言近似的开发体验。
|
||||
2. **不要为了 C 语言阉割协议**:不需要因为 C 语言处理数组麻烦,就放弃 `preset` 而强迫所有语言都用 `patch` 循环。SDK 应该把复杂性封装在内部,留给用户简洁的接口。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user