Dagger TypeScript SDK Address 类深度解析：用一条字符串加载任意 Dagger 资源

Dagger TypeScript SDK Address 类深度解析用一条字符串加载任意 Dagger 资源【免费下载链接】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本篇围绕 Daggerversion-0.19TypeScript API 文档中的Address类展开。Address 是 Dagger 客户端 API 中一个“多态资源加载器”你只需传入一个字符串地址再按目标类型调用container()、directory()、secret()等方法就能把容器镜像、本地/远程目录、文件、Git 仓库、网络服务、Unix Socket 和密钥统一转化为 Dagger 对象。读完本文你将掌握 Address 每个方法的可用地址格式、可选参数含义并能结合引擎侧源码core/schema/address.go理解每种地址在底层是如何被解析和校验的。Address 类概述官方 API 文档对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. 一个标准化地址用于加载容器、目录、密钥及其他对象类型。地址格式取决于目标类型并在选择类型时进行校验。对应到引擎侧core/address.go 中的实现极其简洁type Address struct { Value string }它实现了dagql.PersistedObject与dagql.PersistedObjectDecoder接口说明 Address 对象可以被持久化为缓存/ID 系统的一部分并跨调用还原。其TypeDescription()返回的正是 API 文档中那句描述印证了 TS 文档是由同一 GraphQL Schema 生成的。关键设计点在于Address 本身只保存字符串不做任何类型推断格式合法性检查发生在调用container()、service()等具体加载方法的那一刻。这也是文档中“validated at type selection”的含义。类的继承结构与生成来源TS 文档Address.md标注Address继承自BaseClient其源码位于 sdk/typescript/src/api/client.gen.tsexport class Address extends BaseClient { private readonly _id?: ID undefined private readonly _value?: string undefined /** * Constructor is used for internal usage only, do not create object from it. */ constructor(ctx?: Context, _id?: ID, _value?: string) { super(ctx) this._id _id this._value _value } ... }注意文档明确提示构造函数仅供内部使用不要直接 new Address(...)。用户应通过client.address(value)这一 Query 根字段创建实例。引擎侧对应入口在 core/schema/address.gofunc (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 }从源码可以看到两条硬约束地址不能为空字符串构造阶段不做其他格式校验把解析延迟到各加载方法。各方法对应的地址格式与底层实现下面逐个方法说明文档中列出的 10 个方法container、directory、file、gitRef、gitRepository、id、secret、service、socket、value并结合引擎实现给出每种地址的合法格式。value()读取原始字符串文档签名value(): Promisestring返回“the address value”。引擎实现core/schema/address.go直接返回parent.Value。集成测试 core/integration/address_test.go 的TestValue验证了一批可以无损回读的地址for _, input : range []string{ foo, bar, 123, env://DEBUG, cmd://echo hello world, https://github.com/dagger/dagger, tcp://localhost:4242, unix:///var/run/docker.sock, } { value, err : c.Address(input).Value(ctx) require.NoError(t, err) require.Equal(t, input, value) }这说明 Address 对任意非空字符串都是“透明容器”真正的语义解释交给具体加载方法。container()从镜像引用加载容器文档签名container(): Container无参数。引擎实现core/schema/address.go等价于执行container.from(address)地址通常是容器镜像引用如alpine:3.19。测试TestContainercore/integration/address_test.go用alpine镜像验证了ImageRef包含 alpine并读取/etc/alpine-release文件确认内容。源码中还有一层细节解析失败且地址形如module:function恰好一个冒号、无://和/时错误信息会附加提示“检查 dagger.toml 中的 [modules.X] 键”即你可能把已安装模块的函数引用误当成了镜像名见isBareRefShaped与moduleRefHintcore/schema/address.go。directory()加载本地或远程目录文档签名directory(opts?: AddressDirectoryOpts): Directory。AddressDirectoryOpts定义见 AddressDirectoryOpts.md包含 4 个可选字段字段类型含义exclude?string[]排除的文件/目录 glob 模式include?string[]仅包含的文件/目录 glob 模式gitignore?boolean是否按 .gitignore 规则过滤noCache?boolean是否跳过该调用的缓存地址格式由directory实现core/schema/address.go分两支处理远程 Git 目录地址可被解析为 Git URL如https://github.com/dagger/dagger可选带#subdir片段定位仓库子目录。实现走queryRemoteGitRoot(gitURL)即git(url).head.tree再按片段选directory(path)。本地目录走host.directory(path, include?, exclude?, gitignore?)。测试TestLocalDirectorycore/integration/address_test.go验证了绝对路径与相对路径.两种写法。注意noCache参数在 Schema 注册处被声明为请求级缓存输入dagql.RequestedCacheInput(noCache)与WithInput注册逻辑对应用于精细控制该节点的缓存键。file()加载本地或远程文件文档签名file(opts?: AddressFileOpts): File选项结构与AddressDirectoryOpts相同见 AddressFileOpts.md。引擎实现core/schema/address.go远程文件Git URL 必须带#subdir片段指定文件路径否则报错 “no file path specified within git repository”本地文件等价host.file(path)其中file://前缀会被自动剥除getLocalPath。测试TestLocalFile验证了绝对路径与./hello.txt相对路径均可加载core/integration/address_test.go。gitRepository() 与 gitRef()Git 资源加载文档签名gitRepository(): GitRepository与gitRef(): GitRef。gitRepositorycore/schema/address.go远程git(url)URL 不允许携带 ref 或子目录会分别报错 “git repository address cannot contain ref/subdir”本地host.directory(path).asGit()。gitRefcore/schema/address.go远程git(url).ref(name)若 URL 不带 ref 片段则默认取仓库head本地地址格式为path#ref以#切分路径与分支/标签/commitref缺省时同样回落到head。集成测试TestGit对远程仓库、远程分支等场景做了覆盖core/integration/address_test.go。secret()加载密钥支持多种来源与环境变量简写文档签名secret(): Secret。secret实现core/schema/address.go中最值得注意的是地址归一化逻辑// MY_SECRET - env://MY_SECRET if !strings.Contains(addr, :) { addr env:// addr } // legacy format: env:MY_SECRET - env://MY_SECRET secretSource, val, _ : strings.Cut(addr, :) if !strings.HasPrefix(val, //) { addr secretSource :// val }即裸名称MY_SECRET会被自动视为环境变量来源env://MY_SECRET旧式写法env:MY_SECRET会被自动升级为env://MY_SECRET地址支持查询参数其中?cacheKey...会被单独提取并作为cacheKey参数传入底层的secret(uri)构造selectSecret其余参数原样保留。引擎侧的 secret 支持env://、file://、cmd://等多种 URI 来源测试中的env://DEBUG、cmd://echo hello world均被TestValue列为合法地址字符串。service()把主机上的 TCP/UDP 端点包装为服务文档签名service(): Service。service实现core/schema/address.go要求地址是tcp://host:port或udp://host:port形式的 URL并据此校验 scheme其余 scheme如http://、foo://直接报 “unsupported service address”将端口解析为数字并构造PortForward{frontend: port, backend: port, protocol}通过host.service(host, ports)生成 Service 对象。测试TestServicecore/integration/address_test.go既验证了tcp://localhost:port可实际发起 HTTP 请求并返回 hello world也断言了、localhost:80、tcp://、http://localhost、foo://bar等非法地址必然报错——与文档“格式在类型选择时校验”的语义完全吻合。socket()加载本机 Unix Socket文档签名socket(): Socket。实现core/schema/address.go会把unix://前缀剥掉然后调用host.unixSocket(path)。因此地址应形如unix:///var/run/docker.sockTestValue中的示例值。id()获取对象唯一标识文档签名id(): PromiseAddressID。AddressID是一个标量类型别名见 AddressID.md表示 Address 类型对象的标识符。TS 侧实现sdk/typescript/src/api/client.gen.ts优先返回构造时缓存的_id否则执行 GraphQL 字段选择id。由于 Address 实现了PersistedObject编码core/address.go该 ID 可用于引擎缓存与对象持久化。使用示例从字符串到资源对象综合文档与测试一个典型用法TypeScript SDK形如import { dag } from dagger.io/dagger // 镜像引用 - Container const alpine dag.address(alpine:3.19).container() // 本地路径 - Directory可带 include/exclude/gitignore 过滤 const src dag.address(./src).directory({ include: [**/*.ts], exclude: [**/*.test.ts], gitignore: true, noCache: false, }) // 环境变量简写 - Secret const token dag.address(MY_TOKEN).secret() // 等价 env://MY_TOKEN // 主机端点 - Service const db dag.address(tcp://localhost:5432).service() // 本机 Unix Socket const dockerSock dag.address(unix:///var/run/docker.sock).socket()这些写法分别对应 core/integration/address_test.go 中TestContainer、TestLocalDirectory、TestService、TestLocalFile等已验证通过的用例可以放心作为可运行参考。版本提示与延伸阅读两点适用前提需要注意本文以 version-0.19 版 TS API 文档为准其Address方法集为上述 10 个方法。当前仓库源码中volume()engine-volume:///sshfs://与workspace()模块引用两个字段已经注册在 core/schema/address.go但带有View(AfterVersion(v1.0.0-0))版本门控因此不出现在 0.19 文档中引擎侧地址解析还支持把module:function形式的字符串解析为已安装模块的函数输出resolveModuleRefcore/schema/address.go这属于工作区模块体系的新特性同样不在 0.19 文档范围内。如需继续深入建议按以下路径阅读API 文档Address 类、client.gen 模块总览核心实现core/address.go对象定义与持久化、core/schema/address.go各加载方法解析逻辑行为验证core/integration/address_test.goSDK 源码sdk/typescript/src/api/client.gen.ts【免费下载链接】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），仅供参考