数据 API 生成器的策略

项目
04/13/2024

一组策略控制与重大更改、通知、版本和版本控制相关的数据 API 生成器。

版本控制与发布

数据 API 生成器上下文中的发布是指软件的每个已发布版本，由 Major.Minor.Patch 格式标识。这些版本分为三类：稳定、 中断性变更和 预览版。

稳定版本

数据 API 生成器的 稳定版本 向后兼容。向后兼容意味着你编写的任何依赖于一个数据 API 生成器版本的代码都可以采用较新的稳定版本，而无需进行任何代码更改即可保持正确性或现有功能。

中断性变更版本

数据 API 生成器的 中断性变更版本 不向后兼容。在现有客户端代码中采用中断性变更版本可能需要更改代码，以确保客户端的行为与面向以前版本时的行为完全一样。

中断性变更版本通过中断性变更列表一文和 GitHub 版本的更改说明公布。预览版/候选版本的发布先于中断性变更版本，除非这些更改修复了关键的安全、隐私或法律问题。虽然 GitHub 发布页上可能仍提供以前版本的数据 API 生成器，但我们建议升级到最新版本，其中可能包括 bug 修复。

预览版本

数据 API 生成器预览版使用 X.Y.Z-rc 版本控制方案进行标识。后 -rc 缀指示生成是“候选发布”。预览版用于收集有关新功能和其他更改的反馈。

除非我们计划对上一个稳定版本进行重大更改，否则我们将发布下一个预览版本，其中包含最新稳定版本和新的预览版功能的所有内容。下一个数据 API 生成器更新可能会中断我们在预览版本之间添加的一些新预览功能。这种中断行为意味着可能需要更改代码才能使操作再次正常工作。

预览版不适用于长期或生产用途。当新的稳定版或预览版可用时，可能无法再访问较旧的预览版本。最好仅在你积极开发新功能并且准备在发布后不久切换到非预览版本时才使用预览版。如果预览版中的某些功能包含在新的稳定版本中，剩余的预览功能将添加到新的预览版中供你试用。

版本更改表

重要

当更改解决了关键的产品 bug、法律、安全或隐私问题时，我们可能会对次要版本或修补程序版本引入中断性变更。

版本类型	以前的版本	新版本	备注
是否重大更改	`1.Y.Z`	`2.Y.Z`	新功能和 bug 修复以及任何中断性变更。
Stable	`1.1.Z`	`1.2.Z`	新功能和 bug 修复，无需中断性变更，除非这些更改解决了关键的产品 bug、法律、安全或隐私问题。
Stable	`1.1.1`	`1.1.2`	Bug 修复，没有新功能或中断性变更，除非这些更改解决了关键的产品 bug、法律、安全或隐私问题。
预览	`X.Y.1-rc`	`X.Y.2-rc`	新的预览功能和 bug 修复。如果主版本颠簸，则包含 (中断性变更。)

重大更改

为了确定安全性的优先级、增强功能和维护代码质量，新版本的软件可能包含中断性变更。虽然我们努力通过谨慎的体系结构选择来最大程度地减少这些更改，但它们仍然可以发生。在这种情况下，我们优先宣布它们并提供可能的解决方案。

重要

如果更改被视为非中断性变更，或者为了解决关键的产品 bug 或法律、安全或隐私问题而进行的中断性变更，我们可能会在不事先通知的情况下进行更改。

什么是中断性变更？

中断性变更是需要更新应用程序以防止中断的修改。在数据 API 生成器中，中断性变更可能包括对 REST API 协定的更改、GraphQL架构生成以及影响兼容性和功能的其他元素。

中断性变更示例

以下示例是数据 API 生成器的中断性变更 的非完全 列表：

REST API 协定修改
GraphQL架构生成中的更改
影响向后兼容性的更改
删除或重命名 API 或参数
错误代码更改
权限定义功能的调整
删除允许的参数、请求字段或响应字段
添加不带默认值的必需参数或请求字段
对预期 API 终结点功能的修改

非中断性变更的定义

非中断性变更是指可以在不造成中断的情况下集成到应用程序中的更改。非中断性变更通常在实现后传达。应用程序应设计为处理这些更改，而无需事先通知。

非中断性变更示例

以下示例是对数据 API 生成器 进行非重大 更改的非执行列表：

引入新终结点
向现有终结点添加方法
将新字段合并到响应和请求中
响应中的字段顺序调整
引入可选请求标头
对数据长度和响应大小的更改
更改错误消息和代码
HTTP 响应代码的修复
生成的 OpenAPI 文档中的额外元数据

我们如何传达中断性变更？

我们优先考虑及时通知你有关重大更改的信息。可以在 GitHub 上数据 API 生成器版本的发行说明和专用的中断性变更列表一文中找到中断性变更通知。

当前中断性变更列表

本文中宣布了中断性变更和功能停用。

截至目前，没有中断性变更

通过