API 稳定性 — Django 文档
来自菜鸟教程
Django/docs/2.2.x/misc/api-stability
API 的稳定性
Django 致力于 API 稳定性和向前兼容性。 简而言之,这意味着您针对某个 Django 版本开发的代码将继续适用于未来的版本。 在升级您的项目使用的 Django 版本时,您可能需要进行一些小的更改:请参阅 发行说明 的“向后不兼容的更改”部分,了解您要升级到的一个或多个版本。
在将 API 稳定性放在非常高的优先级的同时,Django 还致力于持续改进,同时在我们提供的 API 中力求“一种方法来做到这一点”(最终)。 这意味着,当我们发现明显更好的做事方式时,我们将弃用并最终删除旧的方式。 我们的目标是提供一个现代、可靠的最高质量的网络框架,鼓励所有使用它的项目的最佳实践。 通过使用增量改进,我们尽量避免停滞和大的突破性升级。
“稳定”是什么意思
在此处,稳定意味着:
所有发布的 API (在文档中的一切 API )在不提供向后兼容的别名的情况下,都不会被移除或者重命名。
如果将新功能添加到这些 API 中——这是很有可能的——它们不会破坏或改变现有方法的含义。 换句话说,“稳定”并不(必然)意味着“完整”。
如果出于某种原因,必须删除或替换声明为稳定的 API,它将被声明为已弃用,但将保留在 API 中至少两个功能版本。 调用已弃用的方法时将发出警告。
有关 Django 版本编号方案如何工作以及功能将如何被弃用的更多详细信息,请参阅 官方发布 。
如果错误或安全漏洞使其完全不可避免,我们只会在没有弃用过程的情况下破坏这些 API 的向后兼容性。
例外
这种稳定性和向后兼容性承诺有一些例外。
标记为内部的 API
某些 API 以多种方式明确标记为“内部”:
- 一些文档提到内部结构并如此提及它们。 如果文档说某些内容是内部的,我们保留更改它的权利。
- 以下划线 (
_
) 为前缀的函数、方法和其他对象。 这是指示某些内容是私有的标准 Python 方式; 如果任何方法以单个_
开头,则它是内部 API。