本文详解如何在 freeopcua（或 opcua-asyncio）中正确声明 opc-ua 自定义结构体（如 `st_namevalue`），注册为服务端数据类型，并创建其长度为 20 的 extensionobject 数组变量，解决因直接使用 python 类引发的 `keyerror: 'st_namevalue'` 和 `attributeerror: objectids has no attribute` 等核心错误。
在 OPC-UA 协议中，Python 原生类（如 class ST_NameValue:）无法被直接序列化为符合规范的 UA ExtensionObject。OPC-UA 要求所有结构体必须先在地址空间中明确定义为标准数据类型（即注册为 StructureDataTypeNode），客户端与服务端才能识别、序列化和反序列化该类型。FreeOpcUa（同步版）和 opcua-asyncio（异步版）均不支持“即用即定义”的 Python 对象映射，必须显式调用结构体注册 API。
✅ 正确步骤：定义 → 注册 → 实例化 → 使用
1. 定义并注册自定义结构体 ST_NameValue
使用 server.new_struct()（同步版）或 await new_struct()（异步版）在服务器地址空间中创建结构体类型节点。注意：idx 是命名空间索引（通常取 server.get_namespace_index("your_ns") 或默认 2），字段需明确指定名称与 UA 内置类型（如 ua.VariantType.String、ua.VariantType.Int32）：
# 在 server.start() 之前添加以下代码
idx = server.get_namespace_index("http://example.org/ST_NameValue") # 可选：自定义命名空间 URI
# 若未注册命名空间，可先添加：
# server.register_namespace("http://example.org/ST_NameValue")
# 创建结构体类型：ST_NameValue，含两个字段 Name (String) 和 Value (String)
snode, _ = server.new_struct(
idx,
"ST_NameValue",
[
server.new_struct_field("Name", ua.VariantType.String),
server.new_struct_field("Value", ua.VariantType.String),
]
)⚠️ 注意：new_struct() 返回的 snode 是结构体类型节点，其 NodeId 将自动注册到 ua.ObjectIds 中，后续可通过 ua.ST_NameValue 访问。
2. 创建结构体数组变量
注册完成后，即可使用 ua.ST_NameValue 构造实例，并作为 ExtensionObject 数组赋值：
# 构造 20 个 ST_NameValue 实例（注意：必须用 ua.ST_NameValue，而非自定义 Python 类）
initial_values = [ua.ST_NameValue(Name=f"param_{i}", Value=f"value_{i}") for i in range(20)]
# 添加变量：类型为 ExtensionObject，维度为 [20]
astParams_var = base.add_variable(
ua.NodeId("astParams", 10),
"astParams",
initial_values,
varianttype=ua.VariantType.ExtensionObject
)
astParams_var.set_array_dimensions([20])
astParams_var.set_attribute(ua.AttributeIds.ValueRank, ua.DataValue(ua.Variant(1))) # 1 表示一维数组3. 客户端读写时的关键操作：加载数据类型定义
若从外部 OPC-UA 客户端（如 UaExpert、Python 客户端）访问该变量，必须在连接后调用 client.load_data_type_definitions()，否则客户端无法解析 ST_NameValue：
立即学习“Python免费学习笔记（深入）”；
# Python 客户端示例（需使用 opcua-asyncio 或兼容版本）
import asyncio
from opcua import Client
async def main():
client = Client("opc.tcp://localhost:4840/freeopcua/server/")
async with client:
# ? 关键：加载服务端定义的所有自定义数据类型
await client.load_data_type_definitions()
node = client.get_node("ns=2;i=10") # 替换为实际 astParams NodeId
# 读取
values = await node.read_value()
print("Read:", values[0].Name, values[0].Value)
# 写入（需构造 ua.ST_NameValue 实例）
new_item = ua.ST_NameValue(Name="choixIndexeur", Value="1")
await node.write_value([new_item] + [ua.ST_NameValue("", "")] * 19)
if __name__ == "__main__":
asyncio.run(main())? 常见错误与规避清单
| 错误现象 | 根本原因 | 解决方案 |
|---|---|---|
| AttributeError: 'ObjectIds' has no attribute 'ST_NameValue' | 结构体未注册，ua.ST_NameValue 不存在 | 必须调用 server.new_struct() 注册 |
| KeyError: 'ST_NameValue'（客户端） | 客户端未加载服务端数据类型定义 | 客户端连接后执行 await client.load_data_type_definitions() |
| 数组维度异常或写入失败 | 未设置 array_dimensions 或 ValueRank | 显式调用 .set_array_dimensions([20]) 和 .set_attribute(ua.AttributeIds.ValueRank, ...) |
| 字段名大小写不匹配（如 name vs Name） | UA 结构体字段名严格区分大小写 | 构造 ua.ST_NameValue(Name=..., Value=...) 时参数名必须与注册时完全一致 |
✅ 总结
OPC-UA 结构体不是 Python 类的简单映射，而是协议层的数据类型契约。要成功使用结构体数组：
- 服务端：用 server.new_struct() 注册结构体 → 用 ua.ST_NameValue(...) 实例化 → 以 ExtensionObject 类型添加带维度的变量；
- 客户端：连接后务必 load_data_type_definitions() → 使用同名 UA 类构造对象 → 按数组规则读写。
完整可运行的服务端结构体注册示例请参考官方仓库：server-custom-structures-and-enums.py。遵循此范式，即可稳定支撑工业场景中参数表、配置块等复杂数据结构的 OPC-UA 交互。
