Dagger TypeScript SDK 的 ModuleChecksOpts 类型别名模块检查筛选参数全面解析【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/daggerModuleChecksOpts是 Dagger TypeScript SDK 中用于调用Module.checks()方法时的参数对象类型别名它决定从模块树中收集哪些 check 目标、以何种方式过滤。本文以 version-0.20 参考文档 为主体结合当前仓库中 TypeScript SDK 生成源码、GraphQL Schema 定义与核心引擎实现深入讲解该类型别名的每个属性、匹配机制的底层原理并给出可运行的实战示例帮助你精准控制 Dagger 模块检查的执行范围。ModuleChecksOpts 在 Dagger 检查体系中的位置在 Dagger 中模块Module可以声明一系列“检查”check目标包括通过check注解标记的函数以及通过generate注解标记的“生成即检查”generate-as-checks目标。Module.checks()方法用于一次性获取模块定义的所有检查并返回一个CheckGroup对象对应 GraphQL 的CheckGroup类型随后可以对这个检查组执行list()、run()或生成report()。ModuleChecksOpts就是Module.checks()方法的可选参数对象。它本质上是一个object类型的 TypeScript 类型别名定义位置为 sdk/typescript/src/api/client.gen.ts 中Module类的checks方法签名处export type ModuleChecksOpts { /** * Only include checks matching the specified patterns */ include?: string[] /** * When true, only return annotated check functions; exclude generate-as-checks */ noGenerate?: boolean }注意version-0.20 参考文档中记录的属性仅包含includeoptional include?: string[]语义为 Only include checks matching the specified patterns当前仓库源码中该类型还包含noGenerate属性它对应 GraphQL 字段中标注为View(AfterVersion(v0.21.0))的noGenerate参数属于较新版本引入的能力详见下文“底层实现”小节。include 属性按模式筛选检查ModuleChecksOpts的核心属性是include类型为可选字符串数组string[]语义为“仅包含与指定模式匹配的检查”Only include checks matching the specified patterns。匹配语义从核心引擎实现看include的匹配并非简单的字符串相等而是支持两种形式的路径匹配对应 core/modtree.go 中ModTreeNode.Match方法的实现逻辑Glob 模式匹配将模式作为 glob 模式与节点的完整路径进行匹配命中即包含路径前缀匹配将模式解析为一个模块树路径ModTreePath若该路径是目标节点路径的前缀祖先关系同样视为命中。匹配发生在模块树遍历阶段core/modtree.go 的RollupNodes会深度遍历整棵模块树仅当节点满足include模式时才将其加入结果集RollupChecks则在此基础上进一步限定为检查节点func (node *ModTreeNode) RollupChecks(ctx context.Context, include []string, exclude []string) ([]*ModTreeNode, error) { return node.RollupNodes(ctx, func(n *ModTreeNode) bool { return n.IsCheck }, include, exclude) }最终结果会按路径稳定排序并去重保证返回顺序可预测core/modtree.go。常见用法不传include或传空数组返回模块定义的全部检查等价于 CLI 中不带过滤参数的dagger checks传入单个模式如{ include: [test] }只收集路径匹配test的检查传入多个模式只要命中任意一个模式即被包含OR 语义例如{ include: [lint, test:*] }。底层实现从 GraphQL Schema 到 CheckGroup 的完整链路ModuleChecksOpts不是孤立存在的类型它直接映射到 GraphQL 层Module.checks字段的参数。在 core/schema/module.go 中定义如下dagql.NodeFunc(checks, s.moduleChecks). Experimental(This API is highly experimental and may be removed or replaced entirely.). Doc(Return all checks defined by the module). Args( dagql.Arg(include).Doc(Only include checks matching the specified patterns), dagql.Arg(noGenerate).Doc(When true, only return annotated check functions; exclude generate-as-checks). View(AfterVersion(v0.21.0)), ),需要注意两点该 API 被标记为Experimental“highly experimental and may be removed or replaced entirely”这意味着其行为在未来的 Dagger 版本中可能发生变化noGenerate参数带有AfterVersion(v0.21.0)的版本门控说明在 v0.20 及其之前版本中该参数尚不存在这解释了为什么 version-0.20 参考文档中只记录了include一个属性。TypeScript SDK 侧由代码生成器自动生成对应的调用封装sdk/typescript/src/api/client.gen.ts/** * Return all checks defined by the module * param opts.include Only include checks matching the specified patterns * param opts.noGenerate When true, only return annotated check functions; exclude generate-as-checks * experimental */ checks (opts?: ModuleChecksOpts): CheckGroup { const ctx this._ctx.select(checks, { ...opts }) return new CheckGroup(ctx) }调用checks()后返回的CheckGroup提供三个主要操作对应 GraphQL 字段定义见 core/schema/checks.goTypeScript 侧见 sdk/typescript/src/api/client.gen.ts方法说明参数list()返回单个检查及其详细信息的列表无run(opts?)执行全部选中的检查CheckGroupRunOpts含failFast?: boolean为 true 时任一检查失败即停止report()生成 Markdown 格式的检查报告返回File无run()的参数类型是另一个类型别名CheckGroupRunOpts见 sdk/typescript/src/api/client.gen.ts它只有一个可选属性failFast。在核心引擎中CheckGroup.Run通过并行任务池执行所有检查failFast会直接传给该并行执行器core/checks.gofunc (r *CheckGroup) Run(ctx context.Context, failFast bool) (*CheckGroup, error) { ... jobs : parallel.New().WithContextualTracer(true).WithFailFast(failFast) for _, check : range r.Checks { jobs jobs.WithJob(check.Name(), func(ctx context.Context) error { if check.IsGenerate { err check.Node.RunGeneratorAsCheck(ctx, nil, nil) } else { err check.Node.RunCheck(ctx, nil, nil) } ... }) } ... }这里也体现了 generate-as-checks 的语义IsGenerate为 true 的检查由RunGeneratorAsCheck执行——当生成器产生空 changeset 时视为通过而普通注解检查由RunCheck执行。与 WorkspaceChecksOpts 的对比在 TypeScript SDK 中与ModuleChecksOpts类似的还有WorkspaceChecksOpts它用于Workspace.checks()方法返回工作区中加载的所有模块的检查。两者的对比有助于理解ModuleChecksOpts的能力边界定义见 sdk/typescript/src/api/client.gen.tsexport type WorkspaceChecksOpts { include?: string[] // Only include checks matching the specified patterns skip?: string[] // Skip checks matching the specified patterns noGenerate?: boolean // Only return annotated check functions; exclude generate-as-checks onlyGenerate?: boolean // Only return generate-as-checks; exclude annotated check functions }差异要点ModuleChecksOpts面向单个模块Module.checks()只提供正向筛选include当前版本另有noGenerateWorkspaceChecksOpts面向整个工作区Workspace.checks()额外提供反向排除skip与onlyGenerate筛选能力更完整。从核心引擎看两者共用同一套收集逻辑NewCheckGroup接受include, noGenerate, onlyGenerate三个布尔/数组参数core/checks.goonlyGenerate为 true 时跳过注解检查的收集noGenerate为 true 时跳过生成器检查的收集若一个函数同时被check与generate注解则按路径去重后仅保留一份。实战示例在 TypeScript SDK 中使用 ModuleChecksOpts以下示例展示如何将ModuleChecksOpts与CheckGroup结合实现模块检查的收集、筛选、执行与报告生成import { connect, Client } from dagger.io/dagger connect(async (client: Client) { // 加载模块 const mod client.module().withSource( client.host().directory(./my-module), ) // 仅收集路径匹配 lint 或 test 前缀的检查 const group mod.checks({ include: [lint, test:*], }) // 查看收集到的检查列表 const checks await group.list() // 执行全部选中的检查任一失败即停止 await group.run({ failFast: true }) // 生成 Markdown 报告并导出 await group.report().export(./check-report.md) })如果只想运行注解检查、跳过 generate-as-checks在支持noGenerate的版本中可改为const group mod.checks({ include: [test], noGenerate: true, })对应 CLIdagger checksModuleChecksOpts的筛选能力在 CLI 中有直接对应物。dagger checks命令internal/cmd/dagger/checks.go提供了同名的--skip、--no-generate、--generate等标志# 列出模块可用的检查 dagger checks --list # 运行所有检查任一失败即取消剩余检查 dagger checks --failfast # 仅运行注解检查函数跳过 generate-as-checks dagger checks --no-generate # 仅运行 generate-as-checks dagger checks --generate # 跳过匹配指定模式的检查 dagger checks --skip toolchain:*其中--no-generate与--generate互斥源码中使用MarkFlagsMutuallyExclusive保证。CLI 的--skip语义与WorkspaceChecksOpts.skip一致而ModuleChecksOpts当前仅提供正向的include筛选。小结ModuleChecksOpts是Module.checks()的参数对象类型别名核心属性为include?: string[]用于按 glob 模式或路径前缀筛选需要收集的检查Only include checks matching the specified patterns当前仓库源码中该类型还包含noGenerate?: boolean对应 GraphQL 层AfterVersion(v0.21.0)版本门控的参数用于排除 generate-as-checks返回的CheckGroup支持list()、run({ failFast })与report()三种操作分别对应 GraphQL 的list、run、report字段底层由NewCheckGroupcore/checks.go驱动的模块树遍历与路径匹配core/modtree.go实现include支持 glob 与祖先路径两种命中方式结果按路径稳定排序并去重该 API 在源码中被标记为 Experimentalcore/schema/module.go使用时应注意未来版本可能调整其行为。【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/dagger创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考