Dagger TypeScript SDK 函数缓存策略配置FunctionWithCachePolicyOpts 与 timeToLive 实战指南【免费下载链接】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 中的FunctionWithCachePolicyOpts类型别名展开讲解函数结果缓存策略Cache Policy的配置方式与底层校验逻辑。读者将掌握withCachePolicy的完整用法、timeToLive时长字符串的合法取值与边界规则并能理解缓存策略在 Dagger 引擎中的持久化语义从而在实际模块开发中正确为函数配置缓存。一、概述函数缓存策略配置的入口在 Dagger 中模块Module通过函数Function对外暴露能力而函数的结果缓存行为由缓存策略Cache Policy控制。TypeScript SDK 将这一能力封装在Function_类的withCachePolicy()方法中见 Function.mdwithCachePolicy(policy, opts?)返回一个应用了指定缓存策略的新Function_对象。policy参数的类型为FunctionCachePolicy枚举可取值Default、Never、PerSession。opts参数的类型正是本篇核心主题FunctionWithCachePolicyOpts用于携带可选的附加配置。二、FunctionWithCachePolicyOpts 类型定义与属性详解类型签名FunctionWithCachePolicyOpts是一个对象类型别名object其完整定义如下type FunctionWithCachePolicyOpts { /** * 缓存策略的 TTL存活时间如适用。 * 以时长字符串形式提供例如 5m、1h30s。 */ timeToLive?: string; };属性timeToLive可选属性类型必填说明timeToLive?string否缓存策略的 TTL以 Go duration 字符串格式提供例如5m、1h30s该属性的语义要点格式必须是 Gotime.ParseDuration可解析的时长字符串支持组合单位如5m5 分钟、1h30s1 分 30 秒、30s30 秒。可选性timeToLive为可选参数。不传时由缓存策略本身决定默认行为详见下文“持久化语义”一节。适用限制从源码实现看TTL 只能与Default缓存策略组合使用与PerSession组合会直接报错见下文第四节。三、实战用法在模块中为函数配置缓存FunctionWithCachePolicyOpts是withCachePolicy()的可选第二参数。典型调用方式如下TypeScriptimport { dag, FunctionCachePolicy } from dagger.io/dagger; // 构建一个函数对象并为其配置带 TTL 的默认缓存策略 const fn dag .module() .withObject(dag.typeDef().withObject(MyModule)) .withFunction( dag .function_(myTask, dag.typeDef().withObject(MyModule)) .withCachePolicy(FunctionCachePolicy.Default, { timeToLive: 5m, // 结果缓存 5 分钟 }) );在多语言 SDK 中该 API 由代码生成器统一产出。例如在 Go SDK 的生成代码中对应的客户端方法实现如下见 dagger.gen.gofunc (r *Function) WithCachePolicy(policy FunctionCachePolicy, opts ...FunctionWithCachePolicyOpts) *Function { q : r.query.Select(withCachePolicy) for i : len(opts) - 1; i 0; i-- { // timeToLive optional argument if !querybuilder.IsZeroValue(opts[i].TimeToLive) { q q.Arg(timeToLive, opts[i].TimeToLive) } } q q.Arg(policy, policy) return Function{query: q} }从这段生成代码可以确认两个实现细节timeToLive是GraphQL 可选参数仅当调用方显式传入非零值时才会附加到查询参数中policy是必选参数始终随查询发送。四、底层实现timeToLive 的解析与边界校验FunctionWithCachePolicyOpts对应的服务端实现在 core/schema/module.go 的functionWithCachePolicy方法中。GraphQL Schema 中该参数的定义与文档描述完全一致dagql.Arg(timeToLive).Doc(The TTL for the cache policy, if applicable. Provided as a duration string, e.g. 5m, 1h30s.)服务端对timeToLive的处理逻辑包含以下关键规则1. TTL 仅允许与 Default 策略组合if args.TimeToLive.Valid { // For now, restrict TTLs to the default policy. We could support it // for PerSession in the future if desired. if fn.CachePolicy ! core.FunctionCachePolicyDefault { return nil, errors.New(time to live can only be set with default cache policy) } ... }即一旦指定了timeToLive策略必须是Default否则返回错误time to live can only be set with default cache policy。2. 时长解析与特殊值处理ttlDuration, err : time.ParseDuration(string(args.TimeToLive.Value)) if err ! nil { return nil, fmt.Errorf(failed to parse time to live duration %q: %w, args.TimeToLive.Value, err) } switch { case ttlDuration 0: // a TTL of 0 sounds an awful lot like never cache, so we treat it that way. fn.CachePolicy core.FunctionCachePolicyNever ...字符串必须可被time.ParseDuration解析否则报错TTL 为 0 时被等价转换为Never策略源码注释明确说明“TTL 为 0 听起来很像永不缓存”。3. 上下限约束case ttlDuration core.MinFunctionCacheTTLSeconds*time.Second: return nil, fmt.Errorf(time to live duration must be at least %q, got %q, ...) case ttlDuration core.MaxFunctionCacheTTLSeconds*time.Second: return nil, fmt.Errorf(time to live duration must be at most %q, got %q, ...) default: fn.CacheTTLSeconds dagql.NonNull(dagql.Int(int(ttlDuration.Seconds())))边界常量定义在 core/modfunc.goMaxFunctionCacheTTLSeconds 7 * 24 * 60 * 60 // 1 week1 周 MinFunctionCacheTTLSeconds 1 // 1 秒由此得到 TTL 的合法取值范围规则取值行为下限 1s报错time to live duration must be at least 1s特殊值 0不报错但策略被改写为Never上限 604800s7 天报错time to live duration must be at most 168h0m0s合法区间1s ≤ TTL ≤ 7d写入fn.CacheTTLSeconds按秒取整存储五、FunctionCachePolicy 枚举与持久化语义timeToLive只有在理解了FunctionCachePolicy三种取值后才能正确使用见 FunctionCachePolicy.md枚举值含义Default默认策略结果是可持久化的TTL 生效Never结果永不缓存不可持久化PerSession结果仅在当前会话内有效不可持久化不同策略在引擎层的持久化判定实现在 core/typedef.gospec.IsPersistable true switch cachePolicy { case FunctionCachePolicyNever: spec.IsPersistable false case FunctionCachePolicyPerSession: spec.IsPersistable false case FunctionCachePolicyDefault: if fn.CacheTTLSeconds.Valid { spec.TTL fn.CacheTTLSeconds.Value.Int64() } else { // we still set a max TTL for now as a very primitive form of pruning spec.TTL MaxFunctionCacheTTLSeconds } }这揭示了两个容易被忽略的行为Never与PerSession都会把IsPersistable置为false即结果不会被持久化缓存Default策略下若未显式指定timeToLive引擎会以MaxFunctionCacheTTLSeconds7 天作为默认 TTL作为“非常原始的一种裁剪pruning手段”防止结果无限期滞留。六、使用注意事项与边界总结综合文档与源码使用FunctionWithCachePolicyOpts时需注意TTL 格式使用 Go duration 字符串如5m、1h30s这是由time.ParseDuration决定的硬性格式要求策略组合timeToLive只能与Default策略共用与PerSession组合会直接报错传入0s等效于改用Never策略取值范围合法区间为 1 秒至 7 天MaxFunctionCacheTTLSeconds越界会报错并拒绝写入可选语义timeToLive不传时Default策略默认按 7 天 TTL 处理Never/PerSession策略下结果不可持久化生成代码一致性所有语言 SDK 的withCachePolicy客户端方法均由代码生成器统一产出参考 dagger.gen.goTS 与 Go 的行为保持一致。对缓存策略感兴趣的读者还可以进一步阅读 Function.md 了解Function_类的其他方法如withArg、withDescription以及 core/schema/module.go 中withCachePolicy的 GraphQL Schema 定义深入理解模块函数从定义到缓存的完整链路。【免费下载链接】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 函数缓存策略配置：FunctionWithCachePolicyOpts 与 timeToLive 实战指南
Dagger TypeScript SDK 函数缓存策略配置FunctionWithCachePolicyOpts 与 timeToLive 实战指南【免费下载链接】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 中的FunctionWithCachePolicyOpts类型别名展开讲解函数结果缓存策略Cache Policy的配置方式与底层校验逻辑。读者将掌握withCachePolicy的完整用法、timeToLive时长字符串的合法取值与边界规则并能理解缓存策略在 Dagger 引擎中的持久化语义从而在实际模块开发中正确为函数配置缓存。一、概述函数缓存策略配置的入口在 Dagger 中模块Module通过函数Function对外暴露能力而函数的结果缓存行为由缓存策略Cache Policy控制。TypeScript SDK 将这一能力封装在Function_类的withCachePolicy()方法中见 Function.mdwithCachePolicy(policy, opts?)返回一个应用了指定缓存策略的新Function_对象。policy参数的类型为FunctionCachePolicy枚举可取值Default、Never、PerSession。opts参数的类型正是本篇核心主题FunctionWithCachePolicyOpts用于携带可选的附加配置。二、FunctionWithCachePolicyOpts 类型定义与属性详解类型签名FunctionWithCachePolicyOpts是一个对象类型别名object其完整定义如下type FunctionWithCachePolicyOpts { /** * 缓存策略的 TTL存活时间如适用。 * 以时长字符串形式提供例如 5m、1h30s。 */ timeToLive?: string; };属性timeToLive可选属性类型必填说明timeToLive?string否缓存策略的 TTL以 Go duration 字符串格式提供例如5m、1h30s该属性的语义要点格式必须是 Gotime.ParseDuration可解析的时长字符串支持组合单位如5m5 分钟、1h30s1 分 30 秒、30s30 秒。可选性timeToLive为可选参数。不传时由缓存策略本身决定默认行为详见下文“持久化语义”一节。适用限制从源码实现看TTL 只能与Default缓存策略组合使用与PerSession组合会直接报错见下文第四节。三、实战用法在模块中为函数配置缓存FunctionWithCachePolicyOpts是withCachePolicy()的可选第二参数。典型调用方式如下TypeScriptimport { dag, FunctionCachePolicy } from dagger.io/dagger; // 构建一个函数对象并为其配置带 TTL 的默认缓存策略 const fn dag .module() .withObject(dag.typeDef().withObject(MyModule)) .withFunction( dag .function_(myTask, dag.typeDef().withObject(MyModule)) .withCachePolicy(FunctionCachePolicy.Default, { timeToLive: 5m, // 结果缓存 5 分钟 }) );在多语言 SDK 中该 API 由代码生成器统一产出。例如在 Go SDK 的生成代码中对应的客户端方法实现如下见 dagger.gen.gofunc (r *Function) WithCachePolicy(policy FunctionCachePolicy, opts ...FunctionWithCachePolicyOpts) *Function { q : r.query.Select(withCachePolicy) for i : len(opts) - 1; i 0; i-- { // timeToLive optional argument if !querybuilder.IsZeroValue(opts[i].TimeToLive) { q q.Arg(timeToLive, opts[i].TimeToLive) } } q q.Arg(policy, policy) return Function{query: q} }从这段生成代码可以确认两个实现细节timeToLive是GraphQL 可选参数仅当调用方显式传入非零值时才会附加到查询参数中policy是必选参数始终随查询发送。四、底层实现timeToLive 的解析与边界校验FunctionWithCachePolicyOpts对应的服务端实现在 core/schema/module.go 的functionWithCachePolicy方法中。GraphQL Schema 中该参数的定义与文档描述完全一致dagql.Arg(timeToLive).Doc(The TTL for the cache policy, if applicable. Provided as a duration string, e.g. 5m, 1h30s.)服务端对timeToLive的处理逻辑包含以下关键规则1. TTL 仅允许与 Default 策略组合if args.TimeToLive.Valid { // For now, restrict TTLs to the default policy. We could support it // for PerSession in the future if desired. if fn.CachePolicy ! core.FunctionCachePolicyDefault { return nil, errors.New(time to live can only be set with default cache policy) } ... }即一旦指定了timeToLive策略必须是Default否则返回错误time to live can only be set with default cache policy。2. 时长解析与特殊值处理ttlDuration, err : time.ParseDuration(string(args.TimeToLive.Value)) if err ! nil { return nil, fmt.Errorf(failed to parse time to live duration %q: %w, args.TimeToLive.Value, err) } switch { case ttlDuration 0: // a TTL of 0 sounds an awful lot like never cache, so we treat it that way. fn.CachePolicy core.FunctionCachePolicyNever ...字符串必须可被time.ParseDuration解析否则报错TTL 为 0 时被等价转换为Never策略源码注释明确说明“TTL 为 0 听起来很像永不缓存”。3. 上下限约束case ttlDuration core.MinFunctionCacheTTLSeconds*time.Second: return nil, fmt.Errorf(time to live duration must be at least %q, got %q, ...) case ttlDuration core.MaxFunctionCacheTTLSeconds*time.Second: return nil, fmt.Errorf(time to live duration must be at most %q, got %q, ...) default: fn.CacheTTLSeconds dagql.NonNull(dagql.Int(int(ttlDuration.Seconds())))边界常量定义在 core/modfunc.goMaxFunctionCacheTTLSeconds 7 * 24 * 60 * 60 // 1 week1 周 MinFunctionCacheTTLSeconds 1 // 1 秒由此得到 TTL 的合法取值范围规则取值行为下限 1s报错time to live duration must be at least 1s特殊值 0不报错但策略被改写为Never上限 604800s7 天报错time to live duration must be at most 168h0m0s合法区间1s ≤ TTL ≤ 7d写入fn.CacheTTLSeconds按秒取整存储五、FunctionCachePolicy 枚举与持久化语义timeToLive只有在理解了FunctionCachePolicy三种取值后才能正确使用见 FunctionCachePolicy.md枚举值含义Default默认策略结果是可持久化的TTL 生效Never结果永不缓存不可持久化PerSession结果仅在当前会话内有效不可持久化不同策略在引擎层的持久化判定实现在 core/typedef.gospec.IsPersistable true switch cachePolicy { case FunctionCachePolicyNever: spec.IsPersistable false case FunctionCachePolicyPerSession: spec.IsPersistable false case FunctionCachePolicyDefault: if fn.CacheTTLSeconds.Valid { spec.TTL fn.CacheTTLSeconds.Value.Int64() } else { // we still set a max TTL for now as a very primitive form of pruning spec.TTL MaxFunctionCacheTTLSeconds } }这揭示了两个容易被忽略的行为Never与PerSession都会把IsPersistable置为false即结果不会被持久化缓存Default策略下若未显式指定timeToLive引擎会以MaxFunctionCacheTTLSeconds7 天作为默认 TTL作为“非常原始的一种裁剪pruning手段”防止结果无限期滞留。六、使用注意事项与边界总结综合文档与源码使用FunctionWithCachePolicyOpts时需注意TTL 格式使用 Go duration 字符串如5m、1h30s这是由time.ParseDuration决定的硬性格式要求策略组合timeToLive只能与Default策略共用与PerSession组合会直接报错传入0s等效于改用Never策略取值范围合法区间为 1 秒至 7 天MaxFunctionCacheTTLSeconds越界会报错并拒绝写入可选语义timeToLive不传时Default策略默认按 7 天 TTL 处理Never/PerSession策略下结果不可持久化生成代码一致性所有语言 SDK 的withCachePolicy客户端方法均由代码生成器统一产出参考 dagger.gen.goTS 与 Go 的行为保持一致。对缓存策略感兴趣的读者还可以进一步阅读 Function.md 了解Function_类的其他方法如withArg、withDescription以及 core/schema/module.go 中withCachePolicy的 GraphQL Schema 定义深入理解模块函数从定义到缓存的完整链路。【免费下载链接】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），仅供参考
