🐉 ShenYu 元数据同步操作文档

在权限中心数据库中填写接口数据

在 api_service_json_config 表中插入新接口记录：

INSERT INTO api_service_json_config (
    service,          -- 接口路径（不含 /rest/ 前缀）
    service_name,     -- HSF 接口全限定名
    method_name,      -- 方法名
    belong_center,    -- 所属业务中心
    message,          -- 接口描述
    is_open,          -- 是否开放（1 是 / 0 否）
    service_version,  -- HSF 版本号
    group_name,       -- HSF 分组名
    client_timeout,   -- 超时时间（毫秒）
    retry_num,        -- 重试次数
    operat_type,      -- 操作类型
    is_sensitive      -- 是否敏感（1 是 / 0 否）
) VALUES (
    'commodity/queryMaterialPage/v1',
    'com.tydic.newretail.busi.service.MaterialService',
    'queryMaterialPage',
    'commodity-service',
    '商品分页查询',
    '1',
    '1.0.0',
    'XLS_LOCAL',
    '3000',
    '0',
    'select',
    '0'
);

进入 ShenYu Admin 元数据管理页面

浏览器访问 ShenYu Admin：

登录后进入：系统管理 → 元数据管理（路径：/System/Metadata）

点击「从权限中心同步」按钮

在元数据表格上方工具栏，找到绿色「从权限中心同步」按钮并点击：

系统会弹出确认提示："确认从权限中心同步元数据？" → 点击「确认」

查看同步结果

同步完成后，弹出结果弹窗显示：

• 新增：权限中心有但 ShenYu 中没有的接口，已自动创建元数据
• 更新：两边都有的接口，HSF 配置（版本、超时等）已更新
• 失败：同步出错的记录及原因

补全 parameterTypes（参数类型）

权限中心的数据不包含 Java 方法参数类型，同步后的元数据 parameterTypes 默认为空。

为什么 api-gateway 不需要参数全限定名？

旧 api-gateway 在每个 Provider 工程中维护了 service/*.json 配置文件，启动时动态生成 proxy-remote-consumer.xml（Spring XML）。这种方式下：

• 每个 HSF 服务都创建了一个强类型代理 Bean（通过 Spring 容器管理）
• 调用时走的是 JDK 反射代理（HSFSpringConsumerBean），JVM 在运行时可从 Method 对象中自动获取参数类型
• 参数类型信息已隐含在编译后的 .class 文件中，不需要额外配置

为什么 ShenYu 必须手动填写 parameterTypes？

ShenYu 网关不依赖 Provider 工程的 JAR 包，而是使用 HSF 泛化调用（GenericService）。这是一种不依赖接口 Stub 的调用方式：

• 网关在运行时动态构造调用请求，不加载任何业务 JAR
• HSF 泛化调用通过 GenericService.$invoke(methodName, parameterTypes, args) 发起
• 参数在网络传输前需要序列化为字节流，HSF 框架必须知道参数的全限定类名才能找到正确的序列化器（如 Hessian/Java 原生序列化）
• 如果 parameterTypes 为空或错误，HSF 无法确定参数属于哪个类，序列化失败 → 调用报错

对比维度	旧 api-gateway	新 ShenYu
调用方式	Spring Bean 强类型代理	HSF 泛化调用（GenericService）
依赖业务 JAR	✅ 是（需引入 Provider 接口包）	❌ 否（纯运行时动态调用）
参数类型来源	编译期确定，JVM 自动获取	需手动填写全限定类名
扩容新接口	需更新 JAR + 重启网关	只需同步元数据 + 补全参数类型

需要研发人员手动补全：

方式一：在线编辑（推荐）

1. 在元数据列表中找到 parameterTypes 为空的记录
2. 点击右侧操作栏的 ✏️ 编辑按钮
3. 在弹出的编辑框中填写 参数类型 字段
4. 格式：参数的全限定类名，多个用逗号分隔
   例如：com.xxx.dto.MaterialPageRequest
5. 点击确认保存

方式二：上传 JAR/WAR 自动补全

1. 点击工具栏「补全参数类型」按钮
2. 上传包含对应服务接口的 JAR/WAR 文件
3. 系统通过反射自动识别方法参数类型并回填

验证同步数据

在元数据列表中搜索刚才同步的服务路径，确认字段值正确：

• path 路径格式为 /{service}
• rpcType 为 hsf
• rpcExt 包含 version、group、timeout 等 HSF 配置
• enabled 状态为「开启」