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

某些 API 以多种方式明确标记为“内部”:

  • 一些文档提到内部结构并如此提及它们。 如果文档说某些内容是内部的,我们保留更改它的权利。
  • 以下划线 (_) 为前缀的函数、方法和其他对象。 这是指示某些内容是私有的标准 Python 方式; 如果任何方法以单个 _ 开头,则它是内部 API。