Dagger TypeScript SDK 的 DirectoryStatOpts目录状态查询与符号链接处理详解【免费下载链接】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本篇指南聚焦 Dagger自动化构建/测试/交付引擎TypeScript SDK 中DirectoryStatOpts类型别名的定义、使用场景与底层实现。读者将掌握如何通过Directory.stat()查询目录内文件的状态信息大小、权限、类型理解doNotFollowSymlinks参数对符号链接symlink解析行为的精确控制并看到这一配置项在引擎源码与集成测试中的真实运行逻辑。什么是DirectoryStatOptsDirectoryStatOpts是 Dagger TypeScript SDK 为Directory.stat()方法定义的可选参数对象类型。在 client.gen.ts 中它的定义非常精简export type DirectoryStatOpts { /** * If specified, do not follow symlinks. */ doNotFollowSymlinks?: boolean }该类型仅包含一个可选布尔属性属性类型是否可选默认值说明doNotFollowSymlinksboolean可选false跟随符号链接指定后统计目录内路径时不再解析跟随符号链接而是直接返回符号链接自身的状态在Directory.stat()中的使用DirectoryStatOpts的唯一消费者是Directory对象的stat()方法其签名如下见 client.gen.ts/** * Return file status * param path Path to stat (e.g., /file.txt). * param opts.doNotFollowSymlinks If specified, do not follow symlinks. */ stat async ( path: string, opts?: DirectoryStatOpts, ): PromiseStat | null { const ctx this._ctx.select(stat, { path, ...opts }).select(id) const response: Awaitedstring | null await ctx.execute() if (response null) { return null } return new Stat(ctx.copy().selectNode(response, Stat)) }核心行为path为必填参数例如/file.txt或src/main.goopts可选直接以对象展开...opts的方式合并进 GraphQL 查询参数返回Stat | null路径不存在时返回null否则返回一个Stat对象Dagger 会按id重新实例化该对象调用是惰性的实际查询在ctx.execute()时才发送到 Dagger 引擎。典型调用示例import { connect } from dagger.io/dagger connect(async (client) { const dir client.directory().withNewFile(quotes/descartes, Cogito, ergo sum) // 默认行为跟随符号链接 const statDefault await dir.stat(quotes/descartes) console.log(await statDefault?.name()) // descartes // 不跟随符号链接 const statNoFollow await dir.stat(quotes/descartes, { doNotFollowSymlinks: true, }) })stat()返回的Stat对象stat()返回的Stat对象在 core/directory.go 中被构建包含以下字段Name文件/目录名fileInfo.Name()Size字节大小int(fileInfo.Size())Permissions权限位int(fileInfo.Mode().Perm())FileType文件类型取值为REGULAR_TYPE、DIRECTORY_TYPE、SYMLINK_TYPE等枚举便捷方法isDir()/IsDir()用于判断是否为目录。在 TypeScript SDK 中这些字段通过Stat对象的同名异步方法如name()、size()、permissions()、fileType()获取。doNotFollowSymlinks的引擎级实现原理doNotFollowSymlinks虽然只是 TS 层的一个布尔开关但它会一路传到 Dagger 引擎的 GraphQL 参数并最终影响底层文件系统调用。在 directory.go 的Directory.Stat实现中osStatFunc : os.Stat rootPathFunc : containerdfs.RootPath if doNotFollowSymlinks { // symlink testing requires the Lstat call, which does NOT follow symlinks osStatFunc os.Lstat // similarly, containerdfs.RootPath cant be used, since it follows symlinks rootPathFunc RootPathWithoutFinalSymlink }两个关键切换os.Stat→os.Lstatos.Stat会解析路径中的符号链接并返回目标对象的状态os.Lstat不解析符号链接返回符号链接自身的信息。这保证了查询的是链接本身而非其指向。containerdfs.RootPath→RootPathWithoutFinalSymlink容器根路径解析也做了对应的不跟随末尾符号链接处理避免在解析挂载根目录时意外展开链接。在 directory.go 的Directory.Exists中该参数被透传给Stat且当检查类型为ExistsTypeSymlink时也会强制开启stat, err : dir.Stat(ctx, self, srv, targetPath, doNotFollowSymlinks || targetType ExistsTypeSymlink)TypeScript SDK 的代码生成侧dagger.gen.go则负责把该参数序列化为 GraphQL 参数q.Arg(doNotFollowSymlinks, opts[i].DoNotFollowSymlinks)。与Directory.exists()的联动DirectoryStatOpts的姊妹类型DirectoryExistsOpts同样包含doNotFollowSymlinks并额外支持expectedTypeExistsType枚举REGULAR_TYPE、DIRECTORY_TYPE、SYMLINK_TYPE见 client.gen.tsexport type DirectoryExistsOpts { /** * If specified, also validate the type of file (e.g. REGULAR_TYPE, DIRECTORY_TYPE, or SYMLINK_TYPE). */ expectedType?: ExistsType /** * If specified, do not follow symlinks. */ doNotFollowSymlinks?: boolean }exists()与stat()共用同一套符号链接语义设置doNotFollowSymlinks: true后exists()判断的是符号链接本身是否存在/是否为指定类型而非其指向的目标。测试验证与预期行为引擎的集成测试用实际用例锁定了该参数的行为语义见 directory_test.go。测试构造了一个含文件、目录与符号链接的目录quotes/descartes # 普通文件内容 Cogito, ergo sum i-am # 指向 quotes/descartes 的符号链接 nothing # 指向不存在文件的符号链接关键断言默认跟随链接exists(i-am, { expectedType: REGULAR_TYPE })返回true—— 因为test命令语义中所有 FILE 相关测试都会解析符号链接doNotFollowSymlinks: trueexists(i-am, { expectedType: REGULAR_TYPE, doNotFollowSymlinks: true })返回false—— 此时看到的是链接自身不是普通文件悬空链接dangling symlink如nothing在doNotFollowSymlinks: true下可被正常识别为存在。Stat的测试directory_test.go则验证了name、size、permissions、fileType等字段的返回正确性例如对权限为0o444的文件permissions()返回0o444。相关类型与适用场景doNotFollowSymlinks参数并非Directory独有它同样存在于类型位置所属方法DirectoryStatOptsclient.gen.tsDirectory.stat()DirectoryExistsOptsclient.gen.tsDirectory.exists()ContainerStatOptsclient.gen.tsContainer.stat()ContainerExistsOptsclient.gen.tsContainer.exists()其底层实现与Directory.Stat一一对应container.go 的Container.Stat、container.go 的Container.Exists。典型适用场景包括审计与安全检查识别并区分真实的符号链接文件判断目录中是否存在指向敏感路径的链接精确的类型判断配合ExistsTypeSymlinkType使用只判断链接本身是否存在避免链接指向目标带来的干扰避免意外解析当目标可能为悬空链接或循环链接时开启该选项可防止底层os.Stat返回错误容器内文件系统检查在 CI 流水线中对构建产物目录做文件类型、权限、大小的精确校验。使用注意事项默认语义是跟随不传该选项时行为等价于 POSIX 的stat()符号链接会被解析到目标此时无法从返回值区分这是链接还是真实文件悬空链接处理默认跟随模式下对指向不存在目标的符号链接调用stat()会返回null或报错开启doNotFollowSymlinks: true后可以正常获取链接自身的状态与其他方法的配合若需要检测链接是否指向目录/文件可先以doNotFollowSymlinks: true确认链接存在再以默认模式stat()链接目标完整类型判断可参考 ExistsType 枚举定义惰性执行stat()返回的Stat对象与Directory一样是惰性句柄只有在调用其字段方法如size()时才真正向引擎发起查询。【免费下载链接】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），仅供参考
