Dagger TypeScript SDK 中 Address 类详解统一地址加载容器、目录、密钥与 Git 对象【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/daggerAddress是 Dagger TypeScript SDK 提供的一个标准化地址抽象用于按统一字符串格式加载容器Container、目录Directory、文件File、Git 引用GitRef、Git 仓库GitRepository、密钥Secret、服务Service与本地 Socket 等各类对象。本指南以version-0.21的 Address API 参考文档 为核心骨架结合仓库源码剖析其构造方式、全部方法及每种地址的格式约定与底层实现帮助你写出可复制、可运行、可排查的 Dagger TypeScript 管道代码。Address 是什么一次字符串多种对象在 Dagger 的 GraphQL API 与 dagql 引擎中Address被定义为A standardized address to load containers, directories, secrets, and other object types. Address format depends on the type, and is validated at type selection.加载容器、目录、密钥及其他对象类型的标准化地址。地址格式取决于目标类型并在类型选择时进行校验。从源码看Address的核心数据结构极其精简——只是一个包着字符串的薄壳。见 core/address.gotype Address struct { Value string }它实现了dagql.PersistedObject与dagql.PersistedObjectDecoder见 core/address.go因此可以像其他 Dagger 核心对象一样被持久化编码/解码在多次查询与缓存之间传递。而在 core/schema/address.go 中address字段的解析逻辑同样简单——除空字符串会被拒绝外其余字符串原样保存func (s *addressSchema) address(ctx context.Context, root *core.Query, args struct { Value dagql.String },) (*core.Address, error) { addr : args.Value.String() if addr { return nil, fmt.Errorf(resource cannot have empty address) } return core.Address{Value: addr}, nil }理解要点Address本身不理解字符串内容它只负责保管。真正的解析与校验发生在调用.container()、.directory()等选择器方法的那一刻——这就是文档中validated at type selection在类型选择时校验的准确含义。获取与构造从字符串到 Address在 TypeScript SDK 中Address类继承自BaseClient见 sdk/typescript/src/api/client.gen.ts其构造函数签名与文档一致constructor(ctx?: Context, _id?: ID, _value?: string)构造函数仅供内部使用不要直接new Address()。正确做法是通过 Dagger 客户端的address()方法构造例如import { connect } from dagger.io/dagger connect(async (client) { const addr client.address(ghcr.io/owner/app:latest) // addr 是一个 Address 实例接下来可按目标类型调用选择器方法 })从源码结构看sdk/typescript/src/api/client.gen.ts 中Address内部维护了_id与_value两个私有字段作为缓存调用id()/value()时若字段已存在则直接返回否则才真正发起 GraphQL 查询。方法全景七种加载方式 两个元数据方法下表汇总了文档列出的全部方法及其返回类型方法签名返回类型用途container()container(): ContainerContainer从地址加载容器directory(opts?)directory(opts?: AddressDirectoryOpts): DirectoryDirectory从地址加载目录file(opts?)file(opts?: AddressFileOpts): FileFile从地址加载文件gitRef()gitRef(): GitRefGitRef从地址加载 Git 引用分支/标签/提交gitRepository()gitRepository(): GitRepositoryGitRepository从地址加载 Git 仓库secret()secret(): SecretSecret从地址加载密钥service()service(): ServiceService从地址加载服务socket()socket(): SocketSocket从地址加载本地 Socketid()id(): PromiseIDID返回该 Address 的唯一标识符value()value(): Promisestringstring返回地址字符串本身在 TypeScript 生成的代码中除了文档中列出的 10 个方法外sdk/typescript/src/api/client.gen.ts 还包含两个带版本门槛AfterVersion(v1.0.0-0)的扩展方法volume()与workspace()对应 core/schema/address.go 中注册的volume与workspace字段分别用于从地址加载卷与从模块引用加载工作区。0.21 版本文档未收录它们使用前请确认当前 SDK 版本。地址格式约定每种类型各成体系文档明确指出Address format depends on the type下面是基于 core/schema/address.go 实现的逐类型格式说明container()镜像引用或模块引用container()的实现路径core/schema/address.go非常直观先尝试把地址解析为已安装模块引用见下文模块引用解析若匹配失败则回退为镜像地址等价于执行container.from(address)q : []dagql.Selector{ {Field: container}, {Field: from, Args: []dagql.NamedInput{ {Name: address, Value: dagql.NewString(addr)}, }}, }因此client.address(node:22-alpine).container()等价于client.container().from(node:22-alpine)。注意解析会经由 canonical server 的container.from构造函数以避免外层 Query root 上的入口代理遮蔽核心容器构造逻辑见 core/schema/address.go 注释。directory() 与 file()本地路径、file:// 或 Git 远程directory()core/schema/address.go与file()core/schema/address.go共享同一套分发逻辑接受三种形式的地址本地路径如./src或/tmp/data内部会先经host.directory(path)/host.file(path)选择其中getLocalPath会剥离可选的file://前缀core/schema/address.goGit 远程地址能被gitutil.ParseURL解析的地址含#ref与#subdir片段会走git(url).ref(...).tree()链路对file()而言若地址未指明仓库内的子路径会直接报错 no file path specified within git repositorycore/schema/address.go模块引用以module:function形式指向已安装模块的输出同样优先解析。directory()与file()均接受可选参数opts类型为 AddressDirectoryOpts / AddressFileOpts在 sdk/typescript/src/api/client.gen.ts 中定义export type AddressDirectoryOpts { exclude?: string[] // 从加载中排除的路径 include?: string[] // 仅加载这些路径 gitignore?: boolean // 是否遵守 .gitignore noCache?: boolean // 跳过缓存强制重新加载 } export type AddressFileOpts { exclude?: string[] include?: string[] gitignore?: boolean noCache?: boolean }这四个选项与CopyFilter及HostDirCacheConfig一一对应见 core/schema/address.go 与 core/schema/address.go 中queryLocalDirectory组装参数的过程exclude/include决定哪些文件进入目录快照gitignore控制是否按.gitignore规则过滤noCache直接映射到 dagql 的RequestedCacheInput(noCache)core/schema/address.go。gitRef() 与 gitRepository()远程与本地 GitgitRef()core/schema/address.go支持https://github.com/org/repo#main形式的远程地址片段#后为分支/标签名缺省时取仓库 HEAD也支持本地仓库路径加#ref后缀的写法若地址中包含子目录片段会报错gitRepository()core/schema/address.go只接受仓库级地址若地址携带#ref或#subdir片段会分别报错 git repository address cannot contain ref/subdir因为仓库对象本身不含版本概念——版本选择交给gitRef()。secret()环境变量与 URIsecret()的解析core/schema/address.go非常灵活支持三种写法的自动归一化裸变量名MY_SECRET会被自动补全为env://MY_SECRET旧式env:前缀env:MY_SECRET被归一化为env://MY_SECRET完整 URI直接按secret(uri)传入还可携带?cacheKeyxxx查询参数来控制密钥在缓存中的标识解析时会剥离cacheKey参数并将其单独传给secret字段见 core/schema/address.go。这一归一化逻辑与 core/schema/secret.go 中secret字段对 URI 的处理保持一致目的是兼容历史写法、减少用户迁移成本。service()tcp:// 或 udp:// URLservice()core/schema/address.go要求地址是一个标准 URL且 scheme 只能是tcp或udp先尝试解析为模块引用见下节否则用net.SplitHostPort拆出主机与端口tcp→ TCP 协议、udp→ UDP 协议其余 scheme 直接报错unsupported service address: %q. Must be a valid tcp:// or udp:// URL最终将主机、端口frontend 与 backend 相同与协议组装成PortForward经host.service(host, ports)加载。例如tcp://127.0.0.1:5432会解析为一个指向本地 5432 端口的 TCP 服务。socket()Unix Socket 路径socket()core/schema/address.go接受本地 Unix Socket 路径可选的unix://前缀会被剥离然后经host.unixSocket(path)加载path : strings.TrimPrefix(addr, unix://)模块引用解析Address 的特殊超集能力Address的一个独特设计是几乎所有加载方法在走常规解析之前都会先尝试将地址解释为模块引用。这在 core/schema/address.go 的resolveModuleRef中实现其判定规则可总结为含://的 URL 风格字符串绝不视为模块引用长形式module:function如backend:serve第一段必须是 Query root 上真实存在且带模块来源Module provenance的字段核心字段git、secret、container等不在此列短形式function如serve只有当前工作区的入口模块entrypoint确实存在该函数时才视为模块引用否则维持普通地址语义一旦判定为模块引用任何解析失败都是硬错误不再回退到镜像/URL 解析若地址形如裸模块引用恰有一个冒号、无://、无/但未匹配任何已安装模块container()与service()会在报错时附加指向dagger.toml的提示见moduleRefHintcore/schema/address.go模块引用还带有循环检测通过 context 中的引用链记录一旦发现A:B - A:B式的循环会立即报 module reference cycle detected避免引擎无界增长core/schema/address.go。此外若引用的模块已在dagger.toml中安装但当前命令未加载例如dagger check mod:item这类选择器命令会收窄模块加载范围demandLoadInstalledModulecore/schema/address.go会按需加载模块并刷新客户端 schema 后重试。该加载只允许工作区所有者客户端触发防止一个裸字符串变成能力授予见 core/schema/address.go 注释。典型使用场景场景一用一条地址管道串联构建、测试与部署import { connect } from dagger.io/dagger connect(async (client) { // 1. 从镜像地址加载容器 const ctr client.address(node:22-alpine).container() const out await ctr .withExec([node, -e, console.log(hello address)]) .stdout() // 2. 从 Git 远程地址加载仓库与指定 ref const repo client.address(https://github.com/octo-org/example#main).gitRepository() const ref client.address(https://github.com/octo-org/example#v1.0.0).gitRef() // 3. 从本地目录地址加载源码遵守 .gitignore const src client.address(./).directory({ gitignore: true }) // 4. 从环境变量名加载密钥自动归一化为 env:// const token client.address(GITHUB_TOKEN).secret() })场景二模块引用作为地址在已安装模块的工作区中可以直接用模块引用地址获取其他模块函数的输出对象// 假设 dagger.toml 安装了名为 backend 的模块且其 server 函数返回 Service const svc client.address(backend:server).service()这也解释了为什么service()与container()的实现要先过一遍模块引用解析让地址字符串成为模块间输出对接的统一入口对应 core/schema/address.go 中对该机制的说明。验证与测试仓库在 core/schema/address_test.go 中为各地址类型提供了覆盖测试含模块引用、镜像地址、Git 地址与各类错误分支的断言TypeScript SDK 侧对应的类型定义与生成代码位于 sdk/typescript/src/api/client.gen.ts该文件顶部注明由client-gen自动生成、禁止手改sdk/typescript/src/api/client.gen.ts。若你发现文档与生成代码不一致应以生成代码为最终事实并反馈给上游生成器而非直接修改该文件。小结Address是 Dagger TypeScript SDK 中用一个字符串统一表达多种对象来源的关键抽象container()承接镜像与模块引用directory()/file()兼容本地路径、file://与 Git 远程gitRef()/gitRepository()管理仓库与版本secret()兼容多种密钥书写方式service()只认tcp:///udp://socket()面向本地 Unix Socket。地址本身的校验遵循类型选择时校验原则——Address只保存字符串加载方法才执行格式解析与类型匹配。掌握各方法的地址格式约定就能把 Dagger 管道中绝大多数从某处取对象的诉求统一收敛到client.address(...)这一入口上。【免费下载链接】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），仅供参考