批量转表工具

在实际项目中,我们一般会同时涉及几十甚至上百张表。为了统一配置,我们提供了批量转表工具。 批量转表分为 命令行批量转表工具-xresconv-cliGUI批量转表工具-xresconv-gui 两个工具。

前者用于服务器和客户端发布流程的集成,后者主要提供给临时转表和策划验证数据时可以拿来转出部分数据。 这两个工具都以 批量转表配置模板仓库-xresconv-conf 中的配置为配置规范。

../_images/quick_start_cli_sample.png

以上为 命令行批量转表工具-xresconv-cli 的输出示例。

../_images/quick_start_gui_sample.png

以上为 GUI批量转表工具-xresconv-gui 的输出示例。

我们在 快速上手-配置批量转表配置文件 章节里也提供了一个简单的例子:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <global>
        <work_dir desc="工作目录,相对于当前xml的目录,我们的Excel文件放在这里">.</work_dir>
        <xresloader_path desc="指向前面下载的 转表工具-xresloader,相对于当前xml的目录">../xresloader/target/xresloader-1.4.3.jar</xresloader_path>

        <proto desc="协议类型,-p选项">protobuf</proto>
        <output_type desc="输出类型,对饮-t选项,输出二进制">bin</output_type>
        <proto_file desc="协议描述文件,-f选项">kind.pb</proto_file>

        <output_dir desc="输出目录,-o选项">../sample-data</output_dir>
        <data_src_dir desc="数据源目录,-d选项"></data_src_dir>

        <java_option desc="java选项-最大内存限制2GB">-Xmx2048m</java_option>
        <java_option desc="java选项-客户端模式">-client</java_option>

        <default_scheme name="KeyRow" desc="默认scheme模式参数-Key行号,对应上面Id、Level、CostType、CostValue那一行">2</default_scheme>
    </global>
    
    <groups desc="分组信息(可选)">
        <group id="client" name="客户端"></group>
        <group id="server" name="服务器"></group>
    </groups>

    <category desc="类信息(用于GUI工具的树形结构分类显示)">
        <tree id="all_cats" name="大分类">
            <tree id="kind" name="角色配置"></tree>
        </tree>
    </category>

    <list>
        <item name="升级表" cat="kind" class="client server">
            <scheme name="DataSource" desc="数据源(文件名|表名|数据起始行号,数据起始列号)">role_tables.xlsx|upgrade_10001|3,1</scheme>
            <scheme name="ProtoName" desc="协议名">role_upgrade_cfg</scheme>
            <scheme name="OutputFile" desc="输出文件名">role_upgrade_cfg.bin</scheme>
        </item>
    </list>
</root>

更多具体的配置说明如下:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <include desc="可以包含其他文件配置,然后本文件里的配置将会覆盖或合并配置,相对于当前xml的目录">sample.xml</include>
    <global>
        <work_dir desc="工作目录,相对于当前xml的目录">../xresloader/sample</work_dir>
        <xresloader_path desc="xresloader地址,相对于当前xml的目录">../target/xresloader-1.4.3.jar</xresloader_path>

        <proto desc="协议类型,对应xresloader的-p选项">protobuf</proto>
        <output_type desc="输出类型,对应xresloader的-t选项">json</output_type>
        <proto_file desc="协议描述文件,对应xresloader的-f选项">proto_v3/kind.pb</proto_file>

        <output_dir desc="输出目录,对应xresloader的-o选项"></output_dir>
        <data_src_dir desc="数据源(Excel查找)目录,对应xresloader的-d选项"></data_src_dir>
        <data_version desc="数据版本号,对应xresloader的--data-version选项,留空则自动生成">1.0.0.0</data_version>

        <rename desc="重命名规则,正则表达式:/搜索模式/替换内容/,对应xresloader的-n选项">/(?i)\.bin$/\.json/</rename>

        <!-- java_option标签是传递给java -jar的java选项 -->
        <java_option desc="java附加选项">这里的选项会在运行xresloader-*.jar时附加到java控制参数列表中</java_option>
        <java_option desc="java选项-最大内存限制2GB">-Xmx2048m</java_option>
        <java_option desc="java选项-客户端模式">-client</java_option>

        <!-- default_scheme 是下面直接填写scheme时的默认参数。如果后面的scheme标签设置两相同的name,则该条目会覆盖默认配置 -->
        <default_scheme name="KeyRow" desc="默认scheme模式参数-Key行号">2</default_scheme>
        <default_scheme name="MacroSource" desc="默认scheme模式参数-Key行号">资源转换示例.xlsx|macro|2,1</default_scheme>
    </global>

    <gui>
        <!-- 
            set_name标签用于GUI工具生成每个树形节点时执行的事件(nodejs)脚本,可以用于修改显示数据,便于策划核对具体的表名。
            传入的参数结构如下。修改里面的数据可以改变显示的内容。
            {
                item_data: {
                    id: id,
                    file: "数据源文件",
                    scheme: "数据源scheme表名",
                    name: "描述名称",
                    cat: "分类名称",
                    options: ["额外选项"],
                    desc: "描述信息",
                    scheme_data: {"元数据Key": "元数据Value"}
                }
            }
        -->
        <set_name desc="这个脚本用于GUI工具修改树形节点的显示数据,便于策划核对具体的表名">
            if (item_data.file) {
                // 这个示例是给显示名称附加不带后缀的文件名
                item_data.name += " (" + item_data.file.match(/([^.]+)\.\w+$/)[1] + ")"
            }
            return item_data;
        </set_name>

        <!-- 
            on_before_convert和on_after_convert标签用于GUI工具执行转表前和后执行一段(nodejs)脚本,方便用于一些自动化功能的集成。
            传入的参数结构如下:
            {
                work_dir: "执行xresloader的工作目录",
                xresloader_path: "xresloader目录",
                global_options: {"全局选项": "VALUE"},
                selected_nodes: ["选中要执行转表的节点集合"],
                run_seq: "执行序号",
                alert_warning: function(content, title, options) {}, // 警告弹框, options 结构是 {yes: 点击是按钮回调, no: 点击否按钮回调, on_close: 关闭后回调}
                alert_error: function(content, title) {}, // 错误弹框
                log_info: function (content) {}, // 打印info日志
                log_error: function (content) {}, // 打印info日志
                resolve: function (value) {}, // 通知上层执行结束,相当于Promise的resolve
                reject: function(reason) {}, // 通知上层执行失败,相当于Promise的reject
                require: function (name) {} // 相当于 nodejs的 require(name) 用于导入nodejs 模块
            }
        -->
        <on_before_convert type="text/javascript" timeout="15000" description="事件执行结束必须调用resolve(value)或reject(reason)函数,以触发进行下一步">
            // 这里可以执行nodejs代码,比如下面是Windows平台执行 echo work_dir
            var os = require("os");
            var spawn = require("child_process").spawn;
            if (os.type().substr(0, 7).toLowerCase() == "windows") {
                var exec = spawn("cmd.exe", ["/c", "echo " + work_dir], {
                    cwd: work_dir,
                    encoding: 'utf-8'
                });
                exec.stdout.on("data", function(data) {
                    log_info(data);
                });
                exec.stderr.on("data", function(data) {
                    log_error(data);
                });
                exec.on("error", function(data) {
                    log_error(data.toString());
                    reject("执行失败" + data.toString());
                });
                exec.on("exit", function(code) {
                    if (code === 0) {
                        resolve();
                    } else {
                        reject("执行失败");
                    }
                });
            } else {
                resolve();
            }
        </on_before_convert>
        <on_after_convert type="text/javascript" timeout="60000" description="事件执行结束必须调用resolve(value)或reject(reason)函数,以触发进行下一步">
            // 同上
        </on_after_convert>
    </gui>
    
    <groups desc="分组信息,保留,暂未被使用">
        <group id="client" name="客户端"></group>
        <group id="server" name="服务器"></group>
    </groups>

    <category desc="分类信息,这个用于GUI工具做树形结构的分类">
        <tree id="all_cats" name="大分类">
            <tree id="kind" name="角色配置"></tree>
        </tree>
        <tree id="test" name="测试"></tree>
    </category>

    <!-- 转换列表 -->
    <list>
        <item file="描述转换规则的Excel文件名" scheme="描述转换规则的表名" name="显示名称" cat="分类" class="分组">
            <option desc="附加选项" name="附加选项名称">这里的选项会在运行xresloader-*.jar时附加到参数列表中</option>
            <!-- 当这里使用scheme来设置转换规则时,不要设置item标签的file属性和scheme属性 -->
            <scheme name="描述转换规则的Key" desc="描述">描述转换规则的Value用|分割主配置、次配置和补充配置</scheme>
        </item>
        <item file="资源转换示例.xlsx" scheme="scheme_upgrade" name="升级表" cat="kind" class="client server">
            <option desc="自定义选项" name="移除空列表项">--disable-empty-list</option>
        </item>
        <item name="嵌套数组测试" cat="test" class="client server">
            <scheme name="DataSource" desc="数据源(文件名|表名|数据起始行号,数据起始列号)">资源转换示例.xlsx|arr_in_arr|3,1</scheme>
            <scheme name="ProtoName" desc="协议名">arr_in_arr_cfg</scheme>
            <scheme name="OutputFile" desc="输出文件名">arr_in_arr_cfg.bin</scheme>
        </item>
    </list>
</root>

如上时所有支持的标签的说明及示例配置。

除了前面章节提及过的字段外,还有一些特别的配置。

  • //root/include : 包含其他配置文件。相当于把其他配置文件离得配置复制过来。然后这个文件里有重复得配置则覆盖之。

  • //root/global/work_dir : 运行 xresloader 的目录。如果是相对目录的话相对于xml配置文件。

  • //root/global/xresloader_path : xresloader 的jar包的路径。如果是相对目录的话相对于xml配置文件。

  • //root/global/java_option : 用于传给java命令。所有的条目都会附加到java选项种。比如示例种的 -Xmx2048m 用于设置最大堆为2GB,用于对于比较大的Excel导表的时候可能会临时占用较高内存。

  • //root/global/default_scheme : 默认的导表映射关系的配置(详见 可用的配置项 )。对所有转换条目都会附加这里面的配置项。可多个。

  • //root/list/item/scheme : 导表映射关系的配置(详见 可用的配置项 )。如果和上面 default_scheme 冲突则会覆盖默认配置,仅对这个条目生效。可多个。

  • //root/list/item/option : 运行 xresloader 的额外附加参数(详见 转表引擎-xresloader )。比如使用 --enable-empty-list 可以不移除Excel里的空数据,仅对这个条目生效。可多个。

GUI批量转表工具的特殊事件

其他得配置看内容应该比较容易理解,但是 GUI工具 还有一些额外的配置,遍域用来做工具集成,需要特别说明一下

第一个是 //root/gui/set_name 这是里面必须是一个有效的nodejs代码,传入的参数是:

{
    item_data: {
        id: "条目ID",
        file: "数据源文件",
        scheme: "数据源scheme表名",
        name: "描述名称",
        cat: "分类名称",
        options: ["额外选项"],
        desc: "描述信息",
        scheme_data: {"元数据Key": "元数据Value"}
    }
}

这个结构。在 GUI工具 显示每个条目的时候会运行这个函数并传入上述结构,在函数里我们可以通过改变 namedesc 来改变 GUI工具 工具的显示内容。

比如 批量转表配置模板仓库-xresconv-conf 中的 sample.xml 文件,我们给所有条目的名字附加上了不带后缀的文件名。

另外还有 //root/gui/on_before_convert//root/gui/on_after_convert ,用于在开始转表流程的前和后执行自定义脚本,便于流程集成。 在这是里面必须是一个有效的nodejs代码,其中 //root/gui/on_before_convert[timeout]//root/gui/on_after_convert[timeout] 可以用于控制超时时间,单位是毫秒。 传入的参数是:

{
    work_dir: "执行xresloader的工作目录",
    xresloader_path: "xresloader目录",
    global_options: {"全局选项": "VALUE"},
    selected_nodes: ["选中要执行转表的节点集合"],
    run_seq: "执行序号",
    alert_warning: function(content, title, options) {}, // 警告弹框, options 结构是 {yes: 点击是按钮回调, no: 点击否按钮回调, on_close: 关闭后回调}
    alert_error: function(content, title) {}, // 错误弹框
    log_info: function (content) {}, // 打印info日志
    log_error: function (content) {}, // 打印info日志
    resolve: function (value) {}, // 通知上层执行结束,相当于Promise的resolve
    reject: function(reason) {}, // 通知上层执行失败,相当于Promise的reject
    require: function (name) {} // 相当于 nodejs的 require(name) 用于导入nodejs 模块
}

批量转表配置模板仓库-xresconv-conf 中的 sample.xml 文件中也有示例。