diff --git "a/oedp/doc/oedp \346\211\247\350\241\214\345\217\202\346\225\260\350\256\276\350\256\241\346\226\271\346\241\210.md" "b/oedp/doc/oedp \346\211\247\350\241\214\345\217\202\346\225\260\350\256\276\350\256\241\346\226\271\346\241\210.md" new file mode 100644 index 0000000000000000000000000000000000000000..9f5ef88c4669e95e43682864cce3bcb496f727b1 --- /dev/null +++ "b/oedp/doc/oedp \346\211\247\350\241\214\345\217\202\346\225\260\350\256\276\350\256\241\346\226\271\346\241\210.md" @@ -0,0 +1,120 @@ +### oedp 执行参数设计方案 + +#### 1. 功能概述 +oedp 执行参数用来控制某些功能是否启用或参数设定,提高用户使用 oedp 工具的自由度,提升用户使用体验。 + +用户可以手动修改配置文件来修改执行参数。同时,oedp 工具提供修改执行参数的功能。 + +##### 1.1. 执行参数类型 + +oedp 的执行参数分为三类,解释说明如下: + ++ 全局执行参数:对于全部 oedp 命令都生效的执行参数; ++ 插件执行参数:对于单个插件执行 oedp 命令时生效的执行参数; ++ 命令行执行参数:仅对于执行单一 oedp 命令生效的执行参数。 + +##### 1.2. 通过 oedp 修改执行参数 + +执行参数的修改主要分为持久修改和临时修改两类: + ++ 持久修改:使用`oedp args set` 子命令设置全局执行参数和插件执行参数。 ++ 临时修改:使用`oedp run -a `设置命令行执行参数。 + +##### 1.3. 执行参数冲突合并规则 + +对于重复出现的执行参数,采用覆盖方式进行合并,具体规则如下: + ++ 根据执行参数类型进行优先级排序,顺序为:命令行执行参数 > 插件执行参数 > 全局执行参数,优先级高的覆盖优先级低的; ++ 对于同一类型的执行参数中重复出现的,以最后一次为准。 + +#### 2. 功能设计 + +##### 2.1. 新增配置文件 + ++ 在`/etc/oedp/oedp.conf`中配置全局执行参数,此文件在 oedp 安装时生成,默认带有所有执行参数,值为默认值; ++ 在`{plugin_name}/args.conf`中配置插件执行参数,此文件默认不存在,在设定插件执行参数时自动生成; ++ 在`src/config/default.conf`中记录执行参数默认值,供恢复默认值时使用。 + +##### 2.2. 新增 oedp args 子命令 + +命令格式: + ++ 修改全局执行参数:`oedp args set -g`; + + `-g` 全称为 `--global`; + + 恢复默认值:`oedp args set -g`,下同; + + 允许一次修改多个执行参数,用逗号分隔,不允许带空格,下同。 ++ 修改插件执行参数:`oedp args set [-p ]`; + + `-p` 规则参考子命令 `run`,不含 `-p` 表示以当前目录作为插件路径; + + 修改插件执行参数之前先检查当前目录是不是一个合法的 oedp 插件目录(检查`main.yaml`); + + 如果执行时插件目录内不存在 `args.conf`,则创建该文件。 + +##### 2.3. 修改 oedp run 子命令,增加 -a 选项 + +命令格式: + ++ 添加命令行执行参数:`oedp run [-p ] [-a ]`; + + `-a` 全称为 `--args`; + + 当前仅考虑对`oedp run`子命令增加执行参数选项,后续可根据实际需要扩展至其他子命令。 + +##### 2.4. 增加执行参数合并模块 + +新增`src/utils/merge_args.py`文件,实现执行参数的合并功能: + ++ 输入:插件路径,命令行执行参数; ++ 输出:合并后的执行参数表(dict); ++ 执行过程:初始化一个执行参数表为默认值,依次根据全局执行参数、插件执行参数、命令行执行参数覆盖原有值,然后返回结果。 + +##### 2.5. 附加说明 + ++ oedp 工具不对执行参数合法性进行校验,具体效果如下: + + 尝试设置无效执行参数将会正常执行,但没有任何实际效果; + + 尝试将无效执行参数设置为默认值时,会将该项设置为空字符串。 + +#### 3. 测试用例 +1. **设置全局执行参数**: + + ```bash + oedp args set -g ARG_1=1 + ``` +预期结果:`/etc/oedp/oedp.conf` 中 `ARG_1` 被设置为 `1`。 + +2. **设置局部执行参数**: + + ```bash + oedp args set -p /path/to/project ARG_2=2 + ``` +预期结果:`/path/to/project/args.conf` 中 `ARG_2` 被设置为 `2`。 + +3. **设置局部执行参数(默认当前目录)**: + + ```bash + oedp args set ARG_3=3 + ``` + 预期结果:`./args.conf` 中 `ARG_3` 被设置为 `3`。 + +4. **设置多个执行参数**: + + ```bash + oedp args set -g ARG_1=1,ARG_2=2,ARG_1=3 + ``` + + 预期结果:`/etc/oedp/oedp.conf` 中 `ARG_1` 被设置为 `3`, `ARG_2` 被设置为 `2`。 + +5. **重置执行参数为默认值**: + + ```bash + oedp args set -g ARG_1 + ``` + + 预期结果:`/etc/oedp/oedp.conf` 中 `ARG_1` 被设置为默认值。 + +6. **设置命令行执行参数**: + + ```bash + oedp run install -a ARG_1=1,ARG_2 + ``` + + 预期结果:执行当前 `oedp run install` 命令时,`ARG_1` 被设置为 `1`,`ARG_2` 被设置为默认值。 + +#### 4. 后续扩展 +1. **配置项查看**:可以新增 `oedp args show` 子命令,用于查看执行参数的值(全局值或当前插件与全局合并后的值)。