Version range dependencies for functions（函数的版本范围依赖）¶
In addition to depending on a pinned version of a Function, some applications like Workshop and Actions allow you to depend on a Function at a version range. Doing so enables automatic upgrades at runtime, which can save you time in your development cycle and provide a downtime-less upgrade experience for deployed functions.
While version range dependencies are a powerful feature, they also carry certain risks (for example, there are permissioning consequences specific to Actions). This documentation explains the mechanics behind version range resolution so that you can better understand these risks and make an informed decision on whether version range dependencies are suitable for your application.
:::callout{theme="neutral"} This documentation page assumes prior knowledge on topics like backward compatibility and the Semantic Versioning system. If you are not familiar with these topics, review our documentation on functions versioning.
You should also be familiar with the rules around version precedence as defined in the Semantic Versioning specification ↗. In other words, you should be able to determine, given two distinct versions, which one has lower precedence. For example, 1.0.0-rc.1 < 1.0.0 < 1.0.1 < 1.1.0 < 2.0.0.
:::
Version ranges¶
In its simplest form, a version range is a collection of version inequalities, and a version is said to "satisfy" a range if it satisfies all of its inequalities. For example, version 1.2.0 satisfies the range >=1.0.0 <2.0.0.
:::callout{theme="neutral"} Internally, the semantics of Function version ranges are adopted from NPM, a popular package manager for the JavaScript ecosystem. Review the NPM documentation on version ranges ↗ for a rigorous definition. :::
Applications like Workshop and Actions currently only allow version ranges that comprise backward compatible versions (that is, minor or patch upgrades).
:::callout{theme="neutral"} The NPM equivalent of this backward compatible range used by Workshop and Actions is the caret range ↗. :::
Version range resolution¶
With the exception of deployed functions, when you depend on a Function at a version range, a concrete version that satisfies the range will be chosen at runtime during execution. In particular, the maximum satisfying version will be chosen on an eventual basis (it can take a few minutes to pick up new releases).
Deployed functions¶
For deployed functions, a concrete version is instead resolved to the currently deployed version, if it satisfies the range. If the deployed version does not satisfy the range, an error will be returned.
Risks¶
While functions developers are guided towards the Semantic Versioning specification and general best practices, it is always possible for breaks to be accidentally introduced in non-major version releases.
If your application picks up a breaking change, it can manifest in any number of problems, like runtime failures or unexpected behavior.
Upon noticing a breaking change, you should immediately contact the developer of the Function so that they can release a fix, and in the meantime, you should pin your Function dependency to the last working version.
:::callout{theme="warning"} With the caveat of deployed Function dependencies, if your application has strict uptime requirements and cannot tolerate any breaks, you should use pinned version dependencies. :::
Permissions and provenance in Actions¶
When using Function version ranges in Function-backed Actions, there are important considerations around permissions and provenance that can affect Action behavior. For more information about these implications, refer to the Actions documentation on auto upgrades.
中文翻译¶
函数的版本范围依赖¶
除了依赖函数的固定版本外，Workshop 和 Actions 等应用程序允许您依赖某个版本范围内的函数。这样做可以在运行时实现自动升级，从而节省开发周期的时间，并为已部署函数提供无停机升级体验。
虽然版本范围依赖是一项强大的功能，但也存在一定风险（例如，Actions 中存在特定的权限影响）。本文档将解释版本范围解析的机制，帮助您更好地理解这些风险，并就版本范围依赖是否适合您的应用做出明智决策。
:::callout{theme="neutral"} 本文档假设您已了解向后兼容性和语义化版本控制系统的相关知识。如果您不熟悉这些主题，请先查阅函数版本控制文档。
您还应熟悉语义化版本规范 ↗中定义的版本优先级规则。换句话说，您应能判断两个不同版本中哪个优先级更低。例如：1.0.0-rc.1 < 1.0.0 < 1.0.1 < 1.1.0 < 2.0.0。
:::
版本范围¶
简单来说，版本范围是一组版本不等式的集合，如果一个版本满足所有不等式，则称该版本"满足"该范围。例如，版本 1.2.0 满足范围 >=1.0.0 <2.0.0。
:::callout{theme="neutral"} 在内部，函数版本范围的语义借鉴自 NPM（JavaScript 生态系统中流行的包管理器）。请查阅 NPM 版本范围文档 ↗ 获取严格定义。 :::
Workshop 和 Actions 等应用程序目前仅允许包含向后兼容版本的版本范围（即次要版本或补丁版本升级）。
:::callout{theme="neutral"} Workshop 和 Actions 使用的这种向后兼容范围在 NPM 中对应的是脱字符范围 ↗。 :::
版本范围解析¶
除已部署函数外，当您依赖某个版本范围内的函数时，系统会在运行时选择一个满足该范围的具体版本。具体来说，系统会基于最终一致性原则选择最大满足版本（新版本的生效可能需要几分钟时间）。
已部署函数¶
对于已部署函数，如果当前部署的版本满足范围要求，则会解析为该版本。如果部署的版本不满足范围要求，则会返回错误。
风险¶
虽然函数开发者会遵循语义化版本规范和通用最佳实践，但非主要版本发布中仍有可能意外引入破坏性变更。
如果您的应用程序引入了破坏性变更，可能会导致各种问题，如运行时故障或意外行为。
发现破坏性变更后，您应立即联系函数开发者，以便他们发布修复版本，同时应将函数依赖固定到最后一个可正常工作的版本。
:::callout{theme="warning"} 需要注意的是，对于已部署函数依赖，如果您的应用程序有严格的正常运行时间要求且无法容忍任何中断，则应使用固定版本依赖。 :::
Actions 中的权限与来源¶
在基于函数的 Actions 中使用函数版本范围时，需要考虑权限和来源方面的重要影响，这些因素可能影响 Action 的行为。有关这些影响的更多信息，请参阅 Actions 文档中的自动升级部分。