远程功能

远程功能模块提供三种服务端能力：远程变量、远程数据和远程函数。

远程变量

获取远程变量

获取服务端配置的远程变量值。

GET /api/client/v1/remote/variables/:key

路径参数

参数名	类型	必填	说明
key	string	是	变量名

请求参数

参数名	类型	必填	说明
app_key	string	是	应用标识
kami	string	否	卡密编号；变量开启卡密鉴权时必填
timestamp	int	是	当前时间戳（秒）
nonce	string	是	随机字符串
sign	string	是	请求签名

成功响应

{
  "code": 0,
  "message": "ok",
  "result": {
    "value": "变量值",
    "check": "5d41402abc4b2a76b9719d911017c592",
    "time": 1712123456
  }
}

check 字段说明

• 当变量未配置校验规则时，check 字段不返回
• 规则为 md5 时，返回 value 的 MD5 hex 字符串
• 规则为 crc32 时，返回 value 的 CRC32 校验值（uint32）
• 规则为其他值时，直接返回该固定值

相关错误码

错误码	说明
10501	远程变量不存在
10502	该变量需要卡密身份验证

---

远程数据

远程数据提供按应用维度、卡密维度的 KV 存储能力。当前 scope=user 预留，暂未实现。

获取远程数据

获取指定 key 的远程数据。

GET /api/client/v1/remote/data/:key

路径参数

参数名	类型	必填	说明
key	string	是	数据 key

请求参数

参数名	类型	必填	说明
app_key	string	是	应用标识
scope	string	否	数据作用域，默认 app，可选 app / card / user
kami	string	否	scope=card 时必填，对应卡密编号
timestamp	int	是	当前时间戳（秒）
nonce	string	是	随机字符串
sign	string	是	请求签名

成功响应

{
  "code": 0,
  "message": "ok",
  "result": {
    "value": "数据值"
  }
}

相关错误码

错误码	说明
10521	远程数据不存在

---

写入远程数据

创建或更新远程数据。

POST /api/client/v1/remote/data/:key

路径参数

参数名	类型	必填	说明
key	string	是	数据 key

请求参数

参数名	类型	必填	说明
app_key	string	是	应用标识
action	string	是	操作类型：create / update
value	string	否	数据值
scope	string	否	数据作用域，默认 app，可选 app / card / user
kami	string	否	scope=card 时必填，对应卡密编号
timestamp	int	是	当前时间戳（秒）
nonce	string	是	随机字符串
sign	string	是	请求签名

相关错误码

错误码	说明
10521	远程数据不存在（update 时）
10522	远程数据 key 已存在（create 时）

---

删除远程数据

删除指定 key 的远程数据。

DELETE /api/client/v1/remote/data/:key

路径参数

参数名	类型	必填	说明
key	string	是	数据 key

请求参数

参数名	类型	必填	说明
app_key	string	是	应用标识
scope	string	否	数据作用域，默认 app，可选 app / card / user
kami	string	否	scope=card 时必填，对应卡密编号
timestamp	int	是	当前时间戳（秒）
nonce	string	是	随机字符串
sign	string	是	请求签名

相关错误码

错误码	说明
10521	远程数据不存在

---

远程函数

远程函数基于 Goja (ES5+) 运行时，支持在服务端执行 JavaScript 脚本。

调用远程函数

调用服务端注册的远程函数。

POST /api/client/v1/remote/functions/:name/call

路径参数

参数名	类型	必填	说明
name	string	是	函数名

请求参数

参数名	类型	必填	说明
app_key	string	是	应用标识
params	string	否	函数参数，JSON 数组序列化后的字符串
timestamp	int	是	当前时间戳（秒）
nonce	string	是	随机字符串
sign	string	是	请求签名

params 示例

["arg1", 123, true]

成功响应

{
  "code": 0,
  "message": "ok",
  "result": {
    "return": "函数返回值"
  }
}

相关错误码

错误码	说明
10541	远程函数不存在
10542	参数必须为 JSON 列表格式
10543	远程函数调用错误，详见 message

注意

远程函数有超时和内存限制，请避免执行耗时或占用大量内存的操作。

---

对应实现

• Handler: internal/module/remote/handler_client.go
• DTO: internal/module/remote/dto_client.go