Optique 选项间依赖关系：动态校验与上下文感知补全的完整解决方案

【免费下载链接】optiqueType-safe combinatorial CLI parser for TypeScript项目地址https://gitcode.com/gh_mirrors/op/optique点击查看免费下载Optique 是一个为 TypeScript 打造的类型安全组合式 CLI 解析器Type-safe combinatorial CLI parser它的**选项间依赖Inter-option dependencies**机制能让一个选项的合法取值范围随另一个选项的值动态变化——实现真正的动态校验与上下文感知的 Shell 补全。本文将完整拆解这套依赖系统的用法与原理帮你把prod 模式不允许 debug 日志这类业务规则直接编码进 CLI 参数中。为什么你的 CLI 需要选项间依赖写命令行工具时这类需求你一定见过场景规则日志级别--log-level--mode dev时可选debug/info/warn/error--mode prod时只允许warn/error目标服务器--server合法值由--env和--region两个选项共同决定分支名--branch取决于选定的--remote甚至需要联网查询传统做法是在业务代码里手动 if-else 校验但此时 CLI 的帮助文本、错误提示和 Shell 补全都失聪了。Optique 的依赖系统自0.10.0起提供把这类关系声明为一等公民校验规则、帮助文档和补全建议都从同一份解析器定义推导出来。先区分两种依赖这是理解本功能的关键可用性依赖如 dependent-options.ts某个 flag 是否开启决定另一个选项是否可用靠 TypeScript 判别联合类型在编译期约束。取值依赖本文主角选项 A 的值决定选项 B 哪些取值合法靠dependency()系统在运行期动态校验。三步建立依赖关系dependency、derive、自动重放第 1 步用dependency()创建依赖源把任意值解析器包一层就得到可被引用的依赖源DependencySourceimport { dependency } from optique/core/dependency; import { choice } from optique/core/valueparser; const modeParser dependency(choice([dev, prod] as const));第 2 步用derive()创建派生解析器依赖源上的derive()方法接收四个参数参数作用metavar帮助文本中显示的占位名如LEVELmode工厂函数返回同步还是异步解析器sync/asyncfactory核心逻辑接收依赖值返回该值下应使用的值解析器defaultValue依赖选项未提供时用来推导取值范围的默认值const logLevelParser modeParser.derive({ metavar: LEVEL, mode: sync, factory: (mode) choice(mode dev ? [debug, info, warn, error] : [warn, error]), defaultValue: () dev as const, });第 3 步像普通解析器一样使用重放全自动import { object } from optique/core/constructs; import { option } from optique/core/primitives; const parser object({ mode: option(--mode, -m, modeParser), logLevel: option(--log-level, -l, logLevelParser), });背后发生了什么依赖系统采用延迟重放deferred replay策略解析阶段依赖选项只记录原始输入全部选项解析完成后Optique 构建共享的依赖运行时先解析出依赖源的真实值再带着这个值重新执行派生解析器。因此——✅顺序无关--log-level error --mode prod与反过来的顺序结果一致✅跨组合子有效依赖源和派生项分处不同的object()、再经merge()拼接依赖依然成立✅异步友好factory返回异步解析器如联网查分支列表时派生项自动变为异步模式。完整示例见 inter-option-dependencies.ts它同时演示了单依赖与多依赖两种写法。进阶用法多依赖与链式派生一个选项依赖多个选项deriveFrom()当合法值由多个选项共同决定时改用deriveFrom()const serverParser deriveFrom({ metavar: SERVER, mode: sync, dependencies: [envParser, regionParser] as const, factory: (env, region) choice([${env}-${region}-1, ${env}-${region}-2, ${env}-${region}-3]), defaultValues: () [local, us-east] as const, });factory会按dependencies数组顺序收到所有依赖值参考 examples/patterns/inter-option-dependencies.ts 的部署服务器场景。三级及以上链条1.3.0中间层的派生解析器再包一层dependency()即可成为下一级的依赖源--framework ──▶ --package-manager ──▶ --storage (hono) (npm) (redis)链式解析按依赖图顺序而非字段声明顺序执行中间层只向下游发布重放后的真实值。更妙的是与交互式提示的结合——依赖源可被prompt()包裹用户未输入时先弹选择框选中的答案会注册为依赖值直接决定下游选项的合法取值见 docs/concepts/dependencies.md 的 Interactive sources 一节。上下文感知 Shell 补全补全建议看得见当前命令依赖系统与 Shell 补全深度集成支持 Bash、zsh、fish、PowerShell、Nushell补全结果是动态的命令行已出现--mode prod→ 补全--port时只建议80、443命令行尚未出现--mode→ 用defaultValue如dev推导建议3000、8080。用户敲Tab时看到的候选项始终与当前命令状态一致而不是一个静态的全集。这是同类 CLI 库中很少见的体验底层实现位于 packages/core/src/internal/dependency.ts。动态校验的边界行为与常见陷阱依赖系统的错误语义非常明确理解这几点能少走弯路情况行为依赖选项未提供派生项按defaultValue推导取值范围不报错依赖源本身非法绝不回退默认值失败沿依赖链传播诊断信息包含整条 metavar 链依赖图成环直接拒绝并给出涉及的依赖路径分支互斥的假环conditional()中不可能同时选中的分支不构成环可正常通过⚠️ 新手最常踩的一个坑来自 docs/pitfalls.md中间层的派生解析器若要被下一层依赖必须写成dependency(source.deriveSync(...))——先包dependency()才能当依赖源漏掉这层包装是链式依赖最常见的失败原因。另一个易混淆点依赖系统决定的是哪些值合法如果你要的是某分支才有某组选项应使用 conditional-options.ts 演示的conditional()判别式或withDefault判别联合见 examples/patterns/dependent-options.ts。两者可以组合使用。相关资源速查 概念文档docs/concepts/dependencies.md官方 API 参考 单依赖 / 多依赖示例examples/patterns/inter-option-dependencies.ts 可用性依赖与取值依赖对比docs/cookbook.mdInter-option value dependencies 小节⚠️ 避坑指南docs/pitfalls.md API 导出入口packages/core/src/dependency.ts一句话总结声明一个dependency()源写一个derive()工厂Optique 会自动替你完成动态校验、错误传播与上下文补全——把非法的 CLI 状态在入口处就变成不可能表达的东西。赞分享【免费下载链接】optiqueType-safe combinatorial CLI parser for TypeScript项目地址https://gitcode.com/gh_mirrors/op/optique点击查看免费下载相关推荐NoneBot2插件依赖管理解决复杂依赖关系的完整方案NoneBot2插件依赖管理解决复杂依赖关系的完整方案 NoneBot2作为跨平台Python异步聊天机器人框架其插件依赖管理机制为开发者提供了一套完整的解后端即时通讯Clink核心功能解析从自动补全到历史记录的10个实用技巧Clink核心功能解析从自动补全到历史记录的10个实用技巧 Clink是一款为Windows命令提示符cmd.exe带来Bash式强大命令行编辑能力的工具开发工具终极指南AJV依赖验证如何高效处理属性间关联关系 终极指南AJV依赖验证如何高效处理属性间关联关系 AJVAnother JSON Validator是目前最快的JSON Schema验证器它能够后端API设计上一篇johnny-five 接入 HMC6352 I2C 数字罗盘获取 heading 与 bearing 的完整实践下一篇Pelican 草稿Draft机制全解析从 draft_page.rst 看 status 元数据与草稿生成管线创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考