2026/9/17 21:46:11
FEATURED · 精选文章 
Dagger TypeScript SDK 深度解析DirectoryWithNewDirectoryOpts 与 withNewDirectory 目录创建实战【免费下载链接】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导读DirectoryWithNewDirectoryOpts是 Dagger TypeScript SDK 中Directory.withNewDirectory()方法的可选参数类型用于控制新建目录的文件权限。本文以该类型别名为核心结合 Dagger 仓库的 GraphQL Schema 定义、Go 核心实现与集成测试系统讲解其字段语义、默认值、底层调用链、边界行为与最佳实践帮助你理解在不可变目录树中创建新目录这一基础操作背后的完整机制。一、类型定义一个参数、一个职责在 Dagger TypeScript SDKv0.21中DirectoryWithNewDirectoryOpts定义于 sdk/typescript/src/api/client.gen.ts是一个极简的object类型别名export type DirectoryWithNewDirectoryOpts { /** * Permission granted to the created directory (e.g., 0777). */ permissions?: number }类型别名仅包含一个可选属性属性类型是否必填说明permissionsnumber可选赋予新建目录的权限位如0777其官方语义为Permission granted to the created directory赋予所创建目录的权限。参考文档见 docs/versioned_docs/version-0.21/reference/typescript/api/client.gen/type-aliases/DirectoryWithNewDirectoryOpts.md。从 SDK 生成的相邻类型可以更好地理解它的定位DirectoryWithFilesOpts的permissions注释是 Permission given to the copied files复制文件的权限DirectoryWithNewFileOpts是 Permissions of the new file新文件的权限。三者的permissions字段语义一致都采用 Unix 八进制权限表示法只是作用对象分别为新创建的目录、复制进来的文件和新建的文件。二、调用方withNewDirectory 方法签名与用途DirectoryWithNewDirectoryOpts唯一的使用场景是Directory类上的withNewDirectory方法其 SDK 实现同样位于 sdk/typescript/src/api/client.gen.ts/** * Retrieves this directory plus a new directory created at the given path. * param path Location of the directory created (e.g., /logs). * param opts.permissions Permission granted to the created directory (e.g., 0777). */ withNewDirectory ( path: string, opts?: DirectoryWithNewDirectoryOpts, ): Directory { const ctx this._ctx.select(withNewDirectory, { path, ...opts }) return new Directory(ctx) }关键信息参数path新建目录的位置例如/logs。参数opts可选即本文主题DirectoryWithNewDirectoryOpts目前只承载permissions。返回值Directory——一个新目录对象。这与 Dagger 的不可变immutable执行模型一致withNewDirectory不会原地修改原目录而是返回原目录内容 新增目录的新快照。底层机制this._ctx.select(withNewDirectory, { path, ...opts })表明该方法实际是对 GraphQL API 的withNewDirectory查询的一次延迟求值调用opts中的属性会被展开合并进查询参数。在 Dagger TypeScript SDK 参考文档中该方法的完整签名记录于 docs/versioned_docs/version-0.21/reference/typescript/api/client.gen/classes/Directory.md。与 withDirectory、withFile 的区别withNewDirectory创建的是全新的空目录。与之相对Directory.withDirectory(path, source)把已有目录source的内容合并到目标路径已有路径下原内容保留source 携带的文件优先Directory.withNewFile(path, contents, opts?)在指定路径创建新文件并写入内容。一条典型的使用链const dir dag.directory() .withNewDirectory(/logs, { permissions: 0o700 }) .withNewFile(/app/main.js, console.log(hi))三、GraphQL Schema 层参数的默认值Dagger 的核心 API 以 GraphQL Schema 暴露withNewDirectory的 Schema 参数定义在 core/schema/directory.gotype withNewDirectoryArgs struct { Path string Permissions int default:0644 }这里有一个容易踩坑的细节GraphQL 层声明的默认权限是0644一个文件型权限位但在 TypeScript SDK 的DirectoryWithNewDirectoryOpts中permissions是可选参数且 SDK 层注释示例为0777。真正生效的默认值要到 Go 核心实现中确认见下文未指定时实际回退为0755。这种 Schema 默认值与运行时回退值之间的差异正是阅读源码才能发现的深层信息。Schema 处理器core/schema/directory.go接收参数后会构造一个core.DirectoryWithNewDirectoryLazy惰性求值节点把Path与fs.FileMode(args.Permissions)一并暂存等待引擎实际求值。四、Go 核心实现路径校验、默认权限与幂等优化withNewDirectory的引擎端核心逻辑位于 core/directory.go整个过程可分为三步。1. 路径清理与越界校验dest path.Clean(dest) if strings.HasPrefix(dest, ../) { return fmt.Errorf(cannot create directory outside parent: %s, dest) }目标路径先经path.Clean规范化合并./、../、连续斜杠等若清理后的路径以../开头直接报错cannot create directory outside parent防止目录逃逸出父目录。2. 默认权限回退if permissions 0 { permissions 0755 }当未显式指定permissions即DirectoryWithNewDirectoryOpts缺省、GraphQL 传值落到零值时运行时会回退为0755rwxr-xr-x属主可读写执行组与其他用户可读执行这是绝大多数场景下合理的目录默认权限。3. 已存在路径的幂等优化no-op 等价这是实现中最值得注意的工程细节。MkdirAll对已存在的目录不会修改其权限因此每次调用都分配新的可变快照会导致 overlay 层链无意义地增长。核心实现专门在分配快照前做了存在性检查core/directory.go// MkdirAll leaves existing directories (including their permissions) alone. // Check before allocating a mutable snapshot so repeated calls cannot grow // the overlay layer chain without changing any files.如果目标路径已存在且是目录直接复用父目录的快照必要时通过SnapshotManager重新打开句柄并通过cache.TeachCallEquivalentToResult把本次调用教给引擎缓存使后续相同的withNewDirectory调用直接等价于父目录结果不产生新的缓存条目见 core/directory.go。也就是说对已存在目录重复执行withNewDirectory是一个零开销的幂等操作不会覆盖原有目录的权限也不会破坏其中的既有文件。五、集成测试验证边界行为一览仓库的集成测试 core/integration/directory_mkdir_test.go 对withNewDirectory的边界行为做了系统覆盖可以直接作为参数行为说明书阅读。1. 幂等与权限保持TestWithNewDirectoryNoopparent : c.Directory(). WithNewDirectory(scope/existing, dagger.DirectoryWithNewDirectoryOpts{Permissions: 0o750}). WithNewFile(scope/existing/keep.txt, keep). Directory(scope) // 对已存在目录连续调用 600 次 withNewDirectory result : parent for range 600 { result result.WithNewDirectory(existing, dagger.DirectoryWithNewDirectoryOpts{Permissions: 0o700}) }测试断言已存在的keep.txt内容保持不变keepexisting目录权限仍为最初创建的0o750后续传入的0o700不生效——证明 no-op 优化不会覆盖既有权限复用同一快照后两条分支parent与result都还能继续写入文件快照句柄互不干扰。2. 各种路径形态TestWithNewDirectoryPaths对.、/、existing、/existing、link指向已存在目录的符号链接调用withNewDirectory变更集为空——即均为 no-op穿符号链接创建link/new会在真实目标existing/new下创建目录权限0o700生效对悬空符号链接dangling的目标missing也能正常创建文件冲突报错目标路径指向已存在的文件如existing/keep.txt或文件下的子路径existing/keep.txt/child时Sync返回错误根目录形态c.Directory().WithNewDirectory(.)在空目录scratch root上创建根目录是合法 no-op条目列表为空。3. 缓存等价性TestWithNewDirectoryNoopCacheresult : parent.WithNewDirectory(existing) _, err : result.Sync(ctx) // 下游容器的随机输出与直接使用 parent 时完全一致 require.Equal(t, want, run(result))该测试证明no-op 的withNewDirectory调用在求值阶段被识别为与父目录等价下游容器执行时命中父目录的既有缓存不会因看似多了一层目录操作而破坏缓存命中。六、实战建议与注意事项综合 SDK、Schema 与核心实现使用DirectoryWithNewDirectoryOpts时有以下几点值得牢记权限用八进制字面量书写TypeScript 中推荐直接写{ permissions: 0o750 }与注释中的0777语义一致避免字符串转义歧义。默认权限是0755不传permissions时引擎回退到0755。如果目录要承载敏感数据务必显式收紧例如0o700。创建已存在目录是安全的幂等操作不会覆盖既有目录的权限也不会删除其中的文件但若路径上是文件会报错。路径以目标目录为锚点withNewDirectory的path是相对目录树的绝对位置如/logs支持多层路径自动创建中间目录等价mkdir -p语义且路径清理与越界校验由引擎端保证../逃逸会被拒绝。注意 Schema 默认值与运行时默认值的差异GraphQL Schema 声明0644而运行时实际回退0755core/directory.go。依赖默认权限时建议以实际运行时行为为准并显式传参。配合其他目录操作方法使用需要合并已有目录内容时用withDirectory需要新建文件时用withNewFilewithNewDirectory只负责创建空的目录骨架。七、更多参考资料类型别名参考DirectoryWithNewDirectoryOptsDirectory类参考DirectoryTypeScript SDK 生成源码sdk/typescript/src/api/client.gen.tsGraphQL Schema 参数定义core/schema/directory.goGo 核心实现core/directory.go集成测试core/integration/directory_mkdir_test.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），仅供参考
Dagger TypeScript SDK 深度解析：DirectoryWithNewDirectoryOpts 与 withNewDirectory 目录创建实战
Dagger TypeScript SDK 深度解析DirectoryWithNewDirectoryOpts 与 withNewDirectory 目录创建实战【免费下载链接】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导读DirectoryWithNewDirectoryOpts是 Dagger TypeScript SDK 中Directory.withNewDirectory()方法的可选参数类型用于控制新建目录的文件权限。本文以该类型别名为核心结合 Dagger 仓库的 GraphQL Schema 定义、Go 核心实现与集成测试系统讲解其字段语义、默认值、底层调用链、边界行为与最佳实践帮助你理解在不可变目录树中创建新目录这一基础操作背后的完整机制。一、类型定义一个参数、一个职责在 Dagger TypeScript SDKv0.21中DirectoryWithNewDirectoryOpts定义于 sdk/typescript/src/api/client.gen.ts是一个极简的object类型别名export type DirectoryWithNewDirectoryOpts { /** * Permission granted to the created directory (e.g., 0777). */ permissions?: number }类型别名仅包含一个可选属性属性类型是否必填说明permissionsnumber可选赋予新建目录的权限位如0777其官方语义为Permission granted to the created directory赋予所创建目录的权限。参考文档见 docs/versioned_docs/version-0.21/reference/typescript/api/client.gen/type-aliases/DirectoryWithNewDirectoryOpts.md。从 SDK 生成的相邻类型可以更好地理解它的定位DirectoryWithFilesOpts的permissions注释是 Permission given to the copied files复制文件的权限DirectoryWithNewFileOpts是 Permissions of the new file新文件的权限。三者的permissions字段语义一致都采用 Unix 八进制权限表示法只是作用对象分别为新创建的目录、复制进来的文件和新建的文件。二、调用方withNewDirectory 方法签名与用途DirectoryWithNewDirectoryOpts唯一的使用场景是Directory类上的withNewDirectory方法其 SDK 实现同样位于 sdk/typescript/src/api/client.gen.ts/** * Retrieves this directory plus a new directory created at the given path. * param path Location of the directory created (e.g., /logs). * param opts.permissions Permission granted to the created directory (e.g., 0777). */ withNewDirectory ( path: string, opts?: DirectoryWithNewDirectoryOpts, ): Directory { const ctx this._ctx.select(withNewDirectory, { path, ...opts }) return new Directory(ctx) }关键信息参数path新建目录的位置例如/logs。参数opts可选即本文主题DirectoryWithNewDirectoryOpts目前只承载permissions。返回值Directory——一个新目录对象。这与 Dagger 的不可变immutable执行模型一致withNewDirectory不会原地修改原目录而是返回原目录内容 新增目录的新快照。底层机制this._ctx.select(withNewDirectory, { path, ...opts })表明该方法实际是对 GraphQL API 的withNewDirectory查询的一次延迟求值调用opts中的属性会被展开合并进查询参数。在 Dagger TypeScript SDK 参考文档中该方法的完整签名记录于 docs/versioned_docs/version-0.21/reference/typescript/api/client.gen/classes/Directory.md。与 withDirectory、withFile 的区别withNewDirectory创建的是全新的空目录。与之相对Directory.withDirectory(path, source)把已有目录source的内容合并到目标路径已有路径下原内容保留source 携带的文件优先Directory.withNewFile(path, contents, opts?)在指定路径创建新文件并写入内容。一条典型的使用链const dir dag.directory() .withNewDirectory(/logs, { permissions: 0o700 }) .withNewFile(/app/main.js, console.log(hi))三、GraphQL Schema 层参数的默认值Dagger 的核心 API 以 GraphQL Schema 暴露withNewDirectory的 Schema 参数定义在 core/schema/directory.gotype withNewDirectoryArgs struct { Path string Permissions int default:0644 }这里有一个容易踩坑的细节GraphQL 层声明的默认权限是0644一个文件型权限位但在 TypeScript SDK 的DirectoryWithNewDirectoryOpts中permissions是可选参数且 SDK 层注释示例为0777。真正生效的默认值要到 Go 核心实现中确认见下文未指定时实际回退为0755。这种 Schema 默认值与运行时回退值之间的差异正是阅读源码才能发现的深层信息。Schema 处理器core/schema/directory.go接收参数后会构造一个core.DirectoryWithNewDirectoryLazy惰性求值节点把Path与fs.FileMode(args.Permissions)一并暂存等待引擎实际求值。四、Go 核心实现路径校验、默认权限与幂等优化withNewDirectory的引擎端核心逻辑位于 core/directory.go整个过程可分为三步。1. 路径清理与越界校验dest path.Clean(dest) if strings.HasPrefix(dest, ../) { return fmt.Errorf(cannot create directory outside parent: %s, dest) }目标路径先经path.Clean规范化合并./、../、连续斜杠等若清理后的路径以../开头直接报错cannot create directory outside parent防止目录逃逸出父目录。2. 默认权限回退if permissions 0 { permissions 0755 }当未显式指定permissions即DirectoryWithNewDirectoryOpts缺省、GraphQL 传值落到零值时运行时会回退为0755rwxr-xr-x属主可读写执行组与其他用户可读执行这是绝大多数场景下合理的目录默认权限。3. 已存在路径的幂等优化no-op 等价这是实现中最值得注意的工程细节。MkdirAll对已存在的目录不会修改其权限因此每次调用都分配新的可变快照会导致 overlay 层链无意义地增长。核心实现专门在分配快照前做了存在性检查core/directory.go// MkdirAll leaves existing directories (including their permissions) alone. // Check before allocating a mutable snapshot so repeated calls cannot grow // the overlay layer chain without changing any files.如果目标路径已存在且是目录直接复用父目录的快照必要时通过SnapshotManager重新打开句柄并通过cache.TeachCallEquivalentToResult把本次调用教给引擎缓存使后续相同的withNewDirectory调用直接等价于父目录结果不产生新的缓存条目见 core/directory.go。也就是说对已存在目录重复执行withNewDirectory是一个零开销的幂等操作不会覆盖原有目录的权限也不会破坏其中的既有文件。五、集成测试验证边界行为一览仓库的集成测试 core/integration/directory_mkdir_test.go 对withNewDirectory的边界行为做了系统覆盖可以直接作为参数行为说明书阅读。1. 幂等与权限保持TestWithNewDirectoryNoopparent : c.Directory(). WithNewDirectory(scope/existing, dagger.DirectoryWithNewDirectoryOpts{Permissions: 0o750}). WithNewFile(scope/existing/keep.txt, keep). Directory(scope) // 对已存在目录连续调用 600 次 withNewDirectory result : parent for range 600 { result result.WithNewDirectory(existing, dagger.DirectoryWithNewDirectoryOpts{Permissions: 0o700}) }测试断言已存在的keep.txt内容保持不变keepexisting目录权限仍为最初创建的0o750后续传入的0o700不生效——证明 no-op 优化不会覆盖既有权限复用同一快照后两条分支parent与result都还能继续写入文件快照句柄互不干扰。2. 各种路径形态TestWithNewDirectoryPaths对.、/、existing、/existing、link指向已存在目录的符号链接调用withNewDirectory变更集为空——即均为 no-op穿符号链接创建link/new会在真实目标existing/new下创建目录权限0o700生效对悬空符号链接dangling的目标missing也能正常创建文件冲突报错目标路径指向已存在的文件如existing/keep.txt或文件下的子路径existing/keep.txt/child时Sync返回错误根目录形态c.Directory().WithNewDirectory(.)在空目录scratch root上创建根目录是合法 no-op条目列表为空。3. 缓存等价性TestWithNewDirectoryNoopCacheresult : parent.WithNewDirectory(existing) _, err : result.Sync(ctx) // 下游容器的随机输出与直接使用 parent 时完全一致 require.Equal(t, want, run(result))该测试证明no-op 的withNewDirectory调用在求值阶段被识别为与父目录等价下游容器执行时命中父目录的既有缓存不会因看似多了一层目录操作而破坏缓存命中。六、实战建议与注意事项综合 SDK、Schema 与核心实现使用DirectoryWithNewDirectoryOpts时有以下几点值得牢记权限用八进制字面量书写TypeScript 中推荐直接写{ permissions: 0o750 }与注释中的0777语义一致避免字符串转义歧义。默认权限是0755不传permissions时引擎回退到0755。如果目录要承载敏感数据务必显式收紧例如0o700。创建已存在目录是安全的幂等操作不会覆盖既有目录的权限也不会删除其中的文件但若路径上是文件会报错。路径以目标目录为锚点withNewDirectory的path是相对目录树的绝对位置如/logs支持多层路径自动创建中间目录等价mkdir -p语义且路径清理与越界校验由引擎端保证../逃逸会被拒绝。注意 Schema 默认值与运行时默认值的差异GraphQL Schema 声明0644而运行时实际回退0755core/directory.go。依赖默认权限时建议以实际运行时行为为准并显式传参。配合其他目录操作方法使用需要合并已有目录内容时用withDirectory需要新建文件时用withNewFilewithNewDirectory只负责创建空的目录骨架。七、更多参考资料类型别名参考DirectoryWithNewDirectoryOptsDirectory类参考DirectoryTypeScript SDK 生成源码sdk/typescript/src/api/client.gen.tsGraphQL Schema 参数定义core/schema/directory.goGo 核心实现core/directory.go集成测试core/integration/directory_mkdir_test.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），仅供参考 
