Dagger TypeScript SDK 中的 Stat 类文件/目录状态查询 API 完全指南【免费下载链接】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导读Stat是 Dagger TypeScript SDKdagger.io/dagger中用于描述文件或目录状态的核心数据对象。通过Container、Directory、File对象的stat入口你可以在不把文件拉取到本机的情况下直接查询容器或目录中任意路径的文件类型、文件名、权限位permission bits与字节大小常用于构建前的结构校验、变更集类型断言、挂载点内容检查等场景。读完本文你将掌握Stat类的全部公开 APIfileType()、id()、name()、permissions()、size()、配套的FileType枚举取值以及这些接口在 Dagger 引擎中的底层实现原理与可复现的集成测试用例。本文对应的原始 API 文档为 Stat 类参考配套类型请参阅 FileType 枚举 与 StatID 类型别名。Stat 是什么一个文件或目录状态对象按照官方 API 文档的定义Stat是“A file or directory status object”文件或目录状态对象。它并不携带文件内容只携带描述文件元信息的四个字段。这一设计在 Dagger 的 GraphQL 核心 Schema 中有完整对应——core/schema/testdata/base_schema.graphqls中的type Stat implements Node定义了以下字段schema 定义A file or directory status object. type Stat implements Node { file type fileType: FileType A unique identifier for this Stat. id: ID! file name name: String! permission bits permissions: Int! file size size: Int! }TypeScript SDK 中Stat类继承自BaseClient所有 Dagger API 对象的公共基类并在构造时持有_id、_fileType、_name、_permissions、_size五个内部字段类定义export class Stat extends BaseClient { private readonly _id?: ID undefined private readonly _fileType?: FileType undefined private readonly _name?: string undefined private readonly _permissions?: number undefined private readonly _size?: number undefined constructor( ctx?: Context, _id?: ID, _fileType?: FileType, _name?: string, _permissions?: number, _size?: number, ) { ... } }需要特别注意Stat的构造函数是仅供 SDK 内部使用的文档原话 “Constructor is used for internal usage only, do not create object from it”。你永远不应该、也不需要new Stat()来手动创建实例——Stat对象只能通过引擎在执行查询后返回给你。获取 Stat 的三种入口Stat对象不会凭空出现它由以下三个 GraphQL 查询入口返回1.Container.stat(path)—— 查询容器内任意路径在 TypeScript SDK 中Container对象暴露了stat(path)方法返回PromiseStat | null。它在客户端实现上先选择stat字段再选择id拿到 ID 后用selectNode重建一个可继续查询的Stat实例实现代码stat async (): PromiseStat | null { const ctx this._ctx.select(stat).select(id) const response: Awaitedstring | null await ctx.execute() if (response null) { return null } return new Stat(ctx.copy().selectNode(response, Stat)) }2.Directory.stat(path, opts?)—— 查询目录中的路径Directory的stat接受路径参数并可通过DirectoryStatOpts传入doNotFollowSymlinks布尔选项类型定义export type DirectoryStatOpts { /** * If specified, do not follow symlinks. */ doNotFollowSymlinks?: boolean }3.File.stat()—— 查询单个文件File对象上的stat无参数用于获取该文件自身的状态。路径不存在时的行为当目标路径不存在时查询会失败并返回路径错误。在 Go 核心实现中Directory.Stat对空路径、快照为空、或文件系统返回fs.ErrNotExist的情况统一返回os.PathError{Op: stat, Path: targetPath, Err: syscall.ENOENT}core/directory.go即标准的“文件不存在”ENOENT语义。Stat 类的五个公开方法详解以下五个方法构成Stat类的完整公开 API。它们的共同点是都返回Promise即每次调用都会向 Dagger 引擎发起一次求值除非字段已在构造时被注入。fileType()—— 文件类型签名fileType(): PromiseFileType返回该路径条目的文件类型取值来自FileType枚举见下一节。底层 GraphQL 字段fileType: FileType在 Schema 中声明为可空未加!因此某些特殊环境下可能返回null但引擎在正常情况下会返回上述四种取值之一。客户端拿到引擎返回的字符串如REGULAR后会调用工具函数FileTypeNameToValue将其转换为枚举值实现代码fileType async (): PromiseFileType { if (this._fileType) { return this._fileType } const ctx this._ctx.select(fileType) const response: AwaitedFileType await ctx.execute() return FileTypeNameToValue(response) }name()—— 文件名签名name(): Promisestring返回os.FileInfo.Name()语义下的文件名——即路径的最后一段basename而不是完整路径。例如对路径/sub/subdir/data调用statname()返回data。permissions()—— 权限位签名permissions(): Promisenumber返回 POSIX 风格的权限位permission bits对应 Go 中fileInfo.Mode().Perm()的结果即传统 Unix 的rwxr-xr-x之类的 9 位权限数值八进制 0–0o777。它不包含setuid、setgid、sticky 等特殊位。size()—— 文件大小签名size(): Promisenumber返回文件大小单位是字节。对于目录此值通常是文件系统报告的逻辑大小在 Go 实现中同样取自os.FileInfo.Size()。id()—— Stat 的唯一标识符签名id(): PromiseStatID返回该Stat实例的全局唯一标识。其类型为StatID定义是string object带__StatID品牌标记的字符串字面量类型见 StatID 文档。Stat实现了 GraphQL 的Node接口因此id可用于在后续查询中直接引用该对象例如通过loadStatFromID加载。FileType 枚举四种文件类型fileType()的返回值类型FileType是 Dagger 公开枚举包含 4 个逻辑取值其中每个取值都提供了一对等价成员Xxx与XxxType指向同一字符串值方便不同风格的代码引用枚举定义枚举成员底层字符串值含义FileType.Directory/FileType.DirectoryTypeDIRECTORY目录FileType.Regular/FileType.RegularTypeREGULAR普通文件FileType.Symlink/FileType.SymlinkTypeSYMLINK符号链接FileType.UnknownUNKNOWN未知类型如设备文件、FIFO、socket在 TypeScript SDK 源码 中枚举按字符串值注册并提供了双向转换工具函数FileTypeValueToName与FileTypeNameToValue转换函数前者用于把枚举值转回字符串以便传给引擎暴露的函数后者用于把引擎返回的字符串解析为枚举。在 Go 核心实现中这四种取值由 dagql 枚举视图注册描述文本与 SDK 一一对应注册代码FileTypeRegular FileTypes.RegisterView(REGULAR, enumView, regular file type) FileTypeDirectory FileTypes.RegisterView(DIRECTORY, enumView, directory file type) FileTypeSymlink FileTypes.RegisterView(SYMLINK, enumView, symlink file type) FileTypeUnknown FileTypes.RegisterView(UNKNOWN, enumView, unknown file type)底层原理Stat 在引擎中如何被计算出来Stat不是凭空捏造的元数据——它由 Dagger 引擎对容器快照container snapshot执行真实的文件系统stat系统调用获得。核心数据结构Go 侧的Stat结构体定义在 core/directory.gotype Stat struct { Size int field:true doc:file size Name string field:true doc:file name FileType FileType field:true doc:file type Permissions int field:true doc:permission bits }它实现了dagql.PersistedObject与dagql.PersistedObjectDecoder接口支持将Stat序列化/反序列化从而可以被缓存并在多轮查询间复用编解码实现。目录 Stat 的实现Directory.Stat的核心逻辑core/directory.go依次是求值目录快照若快照为空则返回 ENOENT在doNotFollowSymlinks为 true 时把os.Stat换成os.Lstat不跟随符号链接并把路径解析函数换成RootPathWithoutFinalSymlink这是“symlink testing 必须用 Lstat”的关键所在在挂载的快照根目录下解析目标路径并执行stat从os.FileInfo提取Size、Name、Mode().Perm()通过模式位判断文件类型目录 →FileTypeDirectory普通文件 →FileTypeRegular符号链接 →FileTypeSymlink其余如设备、FIFO→FileTypeUnknownm : fileInfo.Mode() stat : Stat{ Size: int(fileInfo.Size()), Name: fileInfo.Name(), Permissions: int(fileInfo.Mode().Perm()), } if m.IsDir() { stat.FileType FileTypeDirectory } else if m.IsRegular() { stat.FileType FileTypeRegular } else if mfs.ModeSymlink ! 0 { stat.FileType FileTypeSymlink } else { stat.FileType FileTypeUnknown }容器 Stat 的实现Container.Statcore/container.go会先通过locatePath判断目标路径位于容器 rootfs、目录挂载点还是文件挂载点然后分别委派给对应的Directory.stat或File.stat查询rootfs 内路径先选择容器的rootfs一个Directory再对其调用stat目录挂载点mnt.DirectorySource选择挂载目录对应的directory对象后调用stat文件挂载点mnt.FileSource若子路径不为空则直接返回 ENOENT否则对挂载的File调用stat。复用 Stat 的辅助判断Stat结构体还提供了IsDir()便捷方法core/directory.go并被引擎内部的Exists检查、git 主机目录检测git_hostdir.go中对.git目录类型与普通文件类型的区分、以及文件内容提取core/file.go中判断“Stat 为目录时拒绝读取内容”等逻辑复用可见Stat是 Dagger 内部大量路径判断的基础设施。实战示例用 Stat 校验构建产物下面是一段完整的 TypeScript SDK 用法演示如何查询容器内文件状态并逐项断言import { connect, FileType } from dagger.io/dagger connect(async (client) { const ctr client .container() .from(alpine:latest) .withWorkdir(/sub) .withNewFile(subdir/data, contents) // 1. 查询容器内路径的状态 const stat await ctr.stat(subdir/data) if (!stat) { throw new Error(stat 返回 null) } // 2. 断言文件类型为普通文件 const fileType await stat.fileType() console.log(file type:, fileType) // FileType.Regular // 3. 断言文件大小字节 const size await stat.size() console.log(size:, size) // 8 // 4. 读取文件名basename与权限位 const name await stat.name() // data const perms await stat.permissions() // 例如 0o644 console.log(${name} perms${perms.toString(8)}) // 5. 目录的状态fileType 返回 FileType.Directory const dirStat await ctr.stat(/sub) console.log(await dirStat?.fileType()) })上面示例中size()返回8的事实在仓库集成测试中有精确对应core/integration/container_test.go的TestStat用例中withNewFile(subdir/data, contents)写入 8 字节内容随后断言FileType为FileTypeRegularType、Size为8测试用例。同文件中的TestStatWithMountedDir与TestStatWithMountedFile则分别验证了目录挂载与文件挂载场景下stat的查询结果。注意符号链接与 doNotFollowSymlinksStat的一个关键语义是它默认报告的是被解析后的路径状态还是符号链接自身的状态默认情况下doNotFollowSymlinks: false引擎使用os.Stat跟随符号链接——对一个指向普通文件的 symlink 调用statfileType()会返回REGULAR而非SYMLINK传入doNotFollowSymlinks: true时仅Directory.stat支持此选项引擎改用os.LstatfileType()返回SYMLINK从而能识别出“链接指向的类型”。这一点在core/integration/changeset_test.go的符号链接变更测试中被反复验证retarget、new-link、dangling-link等路径在DoNotFollowSymlinks: true下全部断言为FileTypeSymlinkType而把链接替换成普通文件后的link-to-file则断言为FileTypeRegularType测试用例。如果你需要精确区分“目录被文件替换”“链接被重定向”这类结构变更务必开启此选项。小结Stat是 Dagger 中描述文件/目录状态的统一对象四个字段类型、名称、权限位、大小分别对应fileType()、name()、permissions()、size()四个方法另有id()提供唯一标识它只能通过Container.stat(path)、Directory.stat(path, opts)、File.stat()获取不可手动构造FileType枚举覆盖DIRECTORY、REGULAR、SYMLINK、UNKNOWN四种取值并通过doNotFollowSymlinks选项控制是否跟随符号链接其底层实现基于容器快照的真实文件系统stat/lstat系统调用相关逻辑与测试分别位于 core/directory.go、core/container.go 与 core/integration/container_test.go可以作为你实现 Dagger 模块或 CI 流水线时校验文件状态的可靠依据。【免费下载链接】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），仅供参考