orm_frpc_client远程orm访问

orm_frpc_client.lua

用于远程同步和调用其他节点的orm数据，基于watch_client实现增量同步，支持新增、修改、删除回调。

创建与获取

• M:new(svr_name, svr_id, orm_entity_instance_name)
  描述: 创建远程orm访问对象
  参数:
  - svr_name (string): 远程结点名称
  - svr_id (number): 远程结点ID
  - orm_entity_instance_name (string): 远程orm entity的instance_name
  返回值:

  1. orm_client(table): 远程orm访问对象

• M:instance(svr_name, svr_id, orm_entity_instance_name)
  描述: 获取单例远程orm访问对象（同参数只创建一次）
  参数:
  - svr_name (string): 远程结点名称
  - svr_id (number): 远程结点ID
  - orm_entity_instance_name (string): 远程orm entity的instance_name
  返回值:

  1. orm_client(table): 远程orm访问对象

监听同步

• obj:watch(main_key, add_cb, change_cb, del_cb)
  描述: 监听orm第一个key下的所有数据变更
  参数:
  - main_key (string|number): orm的第一个key值
  - add_cb (function): 新增回调 function(one_data)
  - change_cb (function): 修改回调 function(one_data, change_value)
  - del_cb (function): 删除回调 function(one_data)
  返回值:

  1. ret(bool): true成功，false失败
     说明:
     • 首次watch时会拉取全量数据
     • 之后通过watch_client接收增量推送
     • 支持单key和多key的orm表
     • 对端断连重连时会自动重新全量同步

• obj:unwatch(main_key)
  描述: 取消监听
  参数:
  - main_key (string|number): orm的第一个key值
  返回值:
  无

数据获取

• obj:get_data(main_key)
  描述: 获取已监听同步到本地的数据
  参数:
  - main_key (string|number): orm的第一个key值
  返回值:
  1. data(table|nil): 同步到的数据
     说明:
     • 单key的orm表返回单条数据table
     • 多key的orm表返回嵌套的map结构（按第2、第3…key层级索引）

远程调用

• obj:call_orm(cmd, …)
  描述: 远程调用orm的方法
  参数:
  - cmd (string): orm方法名
  - … (any): 方法参数
  返回值:
  1. … 远程方法的返回值（自动unpack）
     说明:
     • 底层使用frpc byid模式调用对端的._ormagent_服务

使用示例

local orm_frpc_client = require "skynet-fly.client.orm_frpc_client"

-- 创建远程orm访问对象（单例模式）
local cli = orm_frpc_client:instance("game_svr", 1, "player_entity")

-- 监听玩家ID=1001的所有数据变更
local ok = cli:watch(1001, 
    function(one_data)  -- 新增
        log.info("player data added:", one_data.player_id, one_data.name)
    end,
    function(one_data, change_value)  -- 修改
        log.info("player data changed:", one_data.player_id, change_value)
    end,
    function(one_data)  -- 删除
        log.info("player data deleted:", one_data.player_id)
    end
)

-- 获取已同步的数据
local data = cli:get_data(1001)

-- 远程调用orm方法
local result = cli:call_orm("get_entry", 1001, "item_1")

-- 取消监听
cli:unwatch(1001)

多key的orm数据结构

对于多key的orm（如主key为player_id，副key为item_id）：

-- 监听player_id=1001的所有道具
cli:watch(1001, add_cb, change_cb, del_cb)

-- get_data返回的结构：
-- data[item_id1] = {player_id=1001, item_id=item_id1, count=5, ...}
-- data[item_id2] = {player_id=1001, item_id=item_id2, count=3, ...}
local data = cli:get_data(1001)
for item_id, item_data in pairs(data) do
    log.info(item_id, item_data.count)
end

注意事项

1. GC时会自动取消所有监听，但建议手动调用unwatch，避免因回调upvalue引用自身造成循环引用
2. 对端断连重连时会自动全量重新同步，保证数据一致性
3. instance方法返回单例对象，同一参数在整个进程生命周期只创建一次