Roam API
Roam 是节点间传递数据的核心容器。线程安全，支持多级 key 和引用语法。
实现基础
| 语言 | 底层实现 | 线程安全机制 |
|---|---|---|
| Java | ConcurrentHashMap<String, Object> | CAS + 分段锁 |
| Go | sync.RWMutex + map[string]any | 读写锁 |
| Python | threading.RLock + dict | 可重入锁 |
基础读写
多级 key
使用 . 分隔的 key 自动构建嵌套数据结构：
列表遍历
多级 key 中的数字片段可以读取已有 list/array 的元素。注意：putDeep 使用数字片段时会创建嵌套 map（以数字字符串为 key），而不会创建 list。
引用语法
@ 前缀表示从 Roam 中间接取值。非 @ 前缀返回参数自身：
引用语法的用途
在 Server 配置界面中，叶子节点的字段值可以设为 @key 形式，实现从 Roam 动态取值，而非硬编码。
Meta（执行元数据）
Roam 通过独立的 Meta 结构体/对象存储执行元数据（不在 data map 中）。
包含以下字段：id、scene、nid、ts、trace、debug、process。
各语言通过 Roam 便捷方法直接访问：
Go Value 流式 API
Value()/ValueDeep() 返回 RoamValue，提供链式类型转换方法：
roam.Value("score").Int() // int
roam.Value("score").IntOr(0) // int，不存在时返回默认值
roam.Value("score").Int64() // int64
roam.Value("score").Int64Or(0) // int64，不存在时返回默认值
roam.Value("name").String() // string
roam.Value("name").StringOr("N/A") // string，带默认值
roam.Value("rate").Float64() // float64
roam.Value("rate").Float64Or(0.0) // float64，不存在时返回默认值
roam.Value("active").Bool() // bool
roam.Value("active").BoolOr(false) // bool，不存在时返回默认值
roam.Value("key").Exists() // 是否存在
roam.Value("key").Raw() // 原始 any 值
// 深层访问
roam.ValueDeep("user.profile.level").Int()
roam.ValueDeep("user.profile.level").IntOr(1)
// 绑定到指针
var level int
roam.Value("level").To(&level)cloneRoam
浅拷贝 Roam：复制业务数据并克隆 Meta（重建 process 缓冲区）。主要用于并行 handler 执行时的数据隔离。
完整方法列表
Java (IceRoam)
| 方法 | 说明 |
|---|---|
put(key, value) | 写入值。value 为 null 时移除 key |
get(key) | 读取值，返回 Object |
putValue(key, value) | 写入值（泛型免强转） |
getValue(key) | 读取值（泛型免强转） |
putDeep(multiKey, value) | 按 . 分隔写入嵌套结构 |
getDeep(multiKey) | 按 . 分隔读取嵌套值 |
resolve(union) | 引用语法：@ 前缀从 roam 取值 |
getId() | 获取执行 ID |
getScene() | 获取场景 |
getTs() | 获取时间戳 |
cloneRoam() | 浅拷贝 Roam（并行执行时使用） |
Go (Roam)
| 方法 | 说明 |
|---|---|
Put(key, value) | 写入值 |
Get(key) | 读取值，返回 any |
PutDeep(multiKey, value) | 嵌套写入 |
GetDeep(multiKey) | 嵌套读取 |
Resolve(union) | 引用语法 |
Data() | 返回数据副本（不含元数据） |
String() | JSON 格式输出 |
Value(key) | 返回 RoamValue，支持链式类型转换 |
ValueDeep(multiKey) | 深层访问，返回 RoamValue |
GetMeta() | 获取 Meta |
Clone() | 浅拷贝 Roam（并行执行时使用） |
Python (Roam)
| 方法 | 说明 |
|---|---|
put(key, value) | 写入值 |
get(key, default=None) | 读取值 |
put_deep(key, value) | 嵌套写入 |
get_deep(key, default=None) | 嵌套读取 |
resolve(union) | 引用语法 |
contains(key) | 是否包含 key |
remove(key) | 移除 key |
keys() | 所有 key |
to_dict() | 转为 dict |
get_meta() | 获取 Meta |
clone() | 浅拷贝 Roam（并行执行时使用） |