AI封装总结

1980882096

封装完毕之后，让AI总结一下封装经验，有懂封装的大佬帮忙看一眼，AI总结的对不对：

8. **嵌入行中火山对象与 C++ 的交互只用官方已验证模式，三个未验证模式实测会运行期失败**（TA-Lib 案例：指标输入数据错乱/结果全零，随后空数组 `取成员(-1)` 触发 vol_array.h 的 IsIndexValid 校验崩溃）：
    - ✅ 类对象数组参数填充：**非静态**方法 + `@<参数>.data ().Add/SetAt/InitCount(...)`（SQLite 取表内容模式）；
    - ✅ C++ 结果传回火山对象：`@dt<目标类> ((INT_P)&局部C++对象)`，在被构造类 `<include>` 区定义 `INT_P` 参数构造并**深拷贝**
    - ❌ 静态方法接收火山类对象参数并在嵌入行调 `.data()`（官方先例全部是非静态方法）；
    - ❌ C++ 类**按值返回**穿越火山边界（`return @dt<类> (C++函数(...))` 传临时对象）；
    - ❌ 嵌入行中声明火山类局部变量（`@ @dt<类> x;`，无任何官方先例）。需要向调用方返回数组时改为"参数填充"式方法。

### 封装架构

9. **`.lib` 是导入库还是静态库要先判别**：体积与 DLL 同量级→静态库；体积仅零头、内部含大量对应 DLL 名字符串、归档成员平均几百字节（跳转桩）→导入库，**运行时必须携带 DLL**。此时 `@视窗.外部库`（编译期链接）+ `@视窗.附属文件`（编译后复制 DLL）缺一不可。


10. **三层封装结构**：官方 C 头文件（原样使用、可直接升级替换）→ `vol_xxx.h` 包装类（RAII 释放/所有权转移/复合操作）→ `.wsv` 火山类（中文名）。`vol_xxx.h` 的必要性：火山类不能直接持有 C 指针成员；纯 C 头无 RAII；**按值返回的结构体句柄（如 duckdb_result）不能像指针句柄（sqlite3_stmt）那样存裸指针**，需 TakeResult 式所有权转移。


11. `DECLARE_REF_OBJECT_CLASS_WITH_DATA(X)` 要求 X 为默认可构造 C++ 类，析构调 Close() 按正确顺序释放；跨类构造火山对象在被构造类 `<include>` 区定义 `inline_ @sn<current_class> (参数) : @sn<current_class> () {...}`，调用侧 `return @dt<目标类名> (参数);`。`@视窗.外部头文件` 只声明在模块主类上，其余类用 `@强制依赖` 带出。库路径用 `$(p)` 适配平台。


12. **文本/内存模式**：火山文本→UTF-8 用 `CU8String (@<参数>.GetText ()).GetText ()`；UTF-8 `const char*` 可直接 return（CVolString 按 UTF-8 解释）；**需库函数 free 的返回值**（如 `*_value_varchar`）先构造 `@an<CVolString>` 拷贝、再 free、再返回；字节集用 `@an<CVolMem> (ptr, size)` 后 free。