Effect CLI 使用 Command.withExamples 为命令附加使用示例并渲染到帮助文档【免费下载链接】effectBuild production-ready applications in TypeScript项目地址: https://gitcode.com/GitHub_Trending/ef/effect导读本篇基于 Effect 仓库的变更记录.changeset/pre/few-foxes-grin.md深入讲解 Effect 的 CLI 模块effect/unstable/cli在 v4.0.0 引入的Command.withExamplesAPI如何为命令行命令附加具体的使用示例、示例数据如何通过HelpDoc.examples结构化暴露以及默认帮助格式化器如何将其渲染为终端中的EXAMPLES区块。读完本文你将掌握在 Effect CLI 应用中为每条命令配置可复制、可运行的示例并随--help输出的完整方案同时理解其底层数据结构与渲染规则。一、变更概览一次让 CLI 帮助文档更实用的功能新增.changeset/pre/few-foxes-grin.md记录了一项effect包的patch级变更AddCommand.withExamplesto attach concrete usage examples to CLI commands, expose them throughHelpDoc.examples, and render them in the default help formatter.该变更描述了三层内容API 层新增组合子combinatorCommand.withExamples为命令附加具体的使用示例数据层示例通过HelpDoc.examples以结构化形式暴露与描述、用法、参数、标志等帮助信息并列渲染层默认帮助格式化器新增EXAMPLES区块的渲染。在 Effect 的 CLI 模块中帮助系统遵循数据模型与渲染分离的设计HelpDoc只定义描述帮助的数据形状HelpDoc.ts 顶部注释明确说明 This module only defines the data shapes used to describe help. Rendering that data as terminal text is handled byCliOutput而终端文本渲染由CliOutput负责。withExamples正是接入这一架构的新增入口。二、核心 APICommand.withExamples 与 Command.ExampleCommand.withExamples定义在 Command.ts类型签名如下源码为>export const withExamples: { (examples: ReadonlyArrayCommand.Example): const Name extends string, Input, E, R, ContextInput( self: CommandName, Input, ContextInput, E, R ) CommandName, Input, ContextInput, E, R const Name extends string, Input, E, R, ContextInput( self: CommandName, Input, ContextInput, E, R, examples: ReadonlyArrayCommand.Example ): CommandName, Input, ContextInput, E, R }其实现非常简洁将examples写入命令实现toImpl(self)并返回新命令不改变命令的输入、错误与服务需求类型} dual(2, const Name extends string, Input, E, R, ContextInput( self: CommandName, Input, ContextInput, E, R, examples: ReadonlyArrayCommand.Example ) makeCommand({ ...toImpl(self), examples }))Command.Example 的结构每个示例是一个只有两个字段的对象Command.tsexport interface Example { readonly command: string readonly description?: string | undefined }command一条具体的命令行调用示例必填例如myapp login --token sbp_abc123description该示例的说明文字可选渲染时以注释形式出现在命令上方。Command模型本身新增了readonly examples: ReadonlyArrayCommand.Example字段Command.ts并且在Command.make的默认构造中初始化为空数组、在复制命令时随其它字段一并保留Command.ts 与 Command.ts确保withExamples与withSubcommands、withDescription、withHandler等其它组合子可以自由组合而不会丢失示例。三、数据层HelpDoc.examples 的结构化暴露帮助文档模型在 HelpDoc.ts 中新增了可选字段/** * Optional concrete usage examples for the command */ readonly examples?: ReadonlyArrayExampleDoc对应新增的ExampleDoc模型HelpDoc.tsexport interface ExampleDoc { /** * Command line invocation example */ readonly command: string readonly description?: string | undefined }ExampleDoc与Command.Example形状一致command为命令行调用示例字符串description为可选的说明。由于HelpDoc是独立于格式化方式的纯数据源码注释指出它支持 text、markdown、JSON 等不同输出格式这意味着同一份示例数据未来可被多种输出端复用——默认终端格式化器只是其中一种消费者。HelpDoc的完整模型还包含description、usage、flags、globalFlags、annotations、args、subcommands等字段HelpDoc.tsexamples与它们并列共同构成命令的完整用户可见帮助信息。四、渲染层默认格式化器的 EXAMPLES 区块默认帮助格式化器位于 CliOutput.ts渲染逻辑如下// Examples section if (doc.examples doc.examples.length 0) { sections.push(colors.bold(EXAMPLES)) let first true let previousHadDescription false for (const example of doc.examples) { if (example.description) { if (!first) sections.push() sections.push( ${colors.dim(# ${example.description})}) } else if (previousHadDescription) { sections.push() } sections.push( ${colors.cyan(example.command)}) first false previousHadDescription !!example.description } sections.push() }渲染规则可以归纳为以下几点仅当示例列表非空时输出EXAMPLES区块标题加粗有description的示例说明以#前缀的暗色注释行显示在命令上方连续两个无说明的示例之间不加空行无说明示例紧跟前一个有说明示例时也会插入一个空行分隔最终输出结构为说明注释 命令成组排列每条命令以青色colors.cyan渲染与USAGE、GLOBAL FLAGS等区块的视觉风格保持一致。真实输出示例Help.test.ts 中的测试用例验证了渲染结果。对于如下命令const command Command.make(login).pipe( Command.withDescription(Authenticate with Supabase), Command.withExamples([ { command: myapp login, description: Log in with browser OAuth }, { command: myapp login --token sbp_abc123, description: Log in with a token }, { command: myapp login --logout } ]) )运行myapp login --help测试中使用Command.runWith(command, { version: 1.0.0 })并注入TestConsole得到的终端输出为DESCRIPTION Authenticate with Supabase USAGE login [flags] GLOBAL FLAGS --help, -h Show help information --version, -v Show version information --wizard Start wizard mode for a command --completions bash|zsh|fish|sh Print shell completion script (choices: bash, zsh, fish, sh) --log-level all|trace|debug|info|warn|warning|error|fatal|none Sets the minimum log level (choices: all, trace, debug, info, warn, warning, error, fatal, none) EXAMPLES # Log in with browser OAuth myapp login # Log in with a token myapp login --token sbp_abc123 myapp login --logout注意示例中的命令字符串是完整可执行的调用如myapp login --token sbp_abc123而USAGE中的login [flags]只描述语法骨架——这正是withExamples的价值向用户展示这条命令实际上长什么样。五、权威用法示例源码内置文档Command.withExamples的 JSDoc 自带可运行的示例Command.ts演示了>import { Command } from effect/unstable/cli const login Command.make(login).pipe( Command.withExamples([ { command: myapp login, description: Log in with browser OAuth }, { command: myapp login --token sbp_abc123, description: Log in with a token } ]) ) login.examples.map((example) example.command) // [myapp login, myapp login --token sbp_abc123]要点示例可直接从命令对象读取Command暴露examples字段可供程序化消费如生成文档、补全提示或测试断言withExamples返回新命令与 Effect 一贯的不可变、管道化组合风格一致该 API 归类为category combinators自since 4.0.0起可用属于effect/unstable/cli模块。六、测试验证帮助输出被快照锁定除了渲染示例的用例Help.test.ts 围绕帮助文档还有多个相关测试例如仅包含 unlisted 子命令的分组整个消失L301-L314它们共同确保帮助系统各区块DESCRIPTION、USAGE、GLOBAL FLAGS、SUBCOMMANDS、EXAMPLES的行为稳定。渲染示例的测试使用toMatchInlineSnapshot将完整输出锁定为快照意味着EXAMPLES区块的排版空行、缩进、注释前缀若有任何回归都会被测试捕获——这为将该功能应用于生产 CLI 提供了可靠保障。七、实践建议与注意事项示例应写完整可执行命令command字段建议包含程序名与全部必要参数如myapp login --token sbp_abc123而不是只写子命令名与USAGE的语法骨架形成互补。描述保持简短description渲染为#注释行适合一句话说明这条示例演示了什么场景而非长篇解释。与其它组合子自由组合withExamples不改变命令类型参数可与withDescription、withSubcommands、withHandler、annotate等按任意顺序管道组合。输出格式可扩展由于示例存储于纯数据结构的HelpDoc.examples除默认终端格式化器外未来可在 markdown、JSON 等其它输出端复用同一份示例数据。版本与模块说明本功能位于effect/unstable/cli模块Command、HelpDoc、CliOutput均在 packages/effect/src/unstable/cli 目录下API 标注since 4.0.0unstable前缀表示该模块 API 仍可能演进升级时请留意 CHANGELOG.md 中的相关变更记录。结语Command.withExamples虽然是一次patch级别的变更却补齐了 CLI 帮助系统的关键一环让用户不仅看到语法还能看到真实可运行的调用示例。从 API 定义Command.withExamplesCommand.Example、数据结构HelpDoc.examples到终端渲染EXAMPLES区块再到快照测试Effect 仓库给出了完整闭环的实现可作为在自身 CLI 工具中完善帮助文档的直接参照。【免费下载链接】effectBuild production-ready applications in TypeScript项目地址: https://gitcode.com/GitHub_Trending/ef/effect创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
