API稳定性

Django致力于API的稳定性和向前兼容性。简而言之,这意味着针对Django版本开发的代码将继续用于将来的版本。在升级项目使用的Django版本时,可能需要进行一些小的更改:请参阅 release note 对于要升级到的一个或多个版本。

在将API稳定性作为一个非常重要的优先事项的同时,Django还致力于持续改进,并在我们提供的API中实现“一种方法”(最终)。这意味着,当我们发现明显优越的做事方法时,我们会反对并最终消除旧的方法。我们的目标是提供一个现代的,可靠的最高质量的网络框架,鼓励所有使用它的项目中的最佳实践。通过使用渐进式的改进,我们试图避免停滞和大规模破坏性升级。

“稳定”是什么意思

在这种情况下,稳定意味着:

  • 如果不提供向后兼容的别名,则不会移动或重命名所有公共API(本文档中的所有内容)。

  • 如果向这些API中添加新的特性(这是完全可能的),它们将不会破坏或改变现有方法的含义。换句话说,“稳定”并不(必然)意味着“完整”。

  • 如果出于某种原因,必须删除或替换声明为稳定的API,则该API将被声明为不推荐使用,但将保留在API中至少两个功能版本。调用不推荐使用的方法时将发出警告。

    正式发布 有关django的版本编号方案如何工作以及功能将如何被弃用的详细信息。

  • 只有当一个bug或安全漏洞使其完全不可避免时,我们才会打破这些api的向后兼容性,而不必进行弃用过程。

稳定API

一般来说,文档中包含的所有内容——除了 internals area 被认为是稳定的。

例外情况

对于这种稳定性和向后兼容性承诺,有一些例外。

安全修补程序

如果我们意识到一个安全问题——希望有人跟踪我们 security reporting policy --我们会尽一切必要的办法来修复它。这可能意味着破坏向后兼容性;安全性胜过兼容性保证。

标记为内部的API

某些API通过以下几种方式显式标记为“内部”:

  • 一些文档提到了内部,并提到了它们。如果文档中说某个东西是内部的,我们保留更改它的权利。

  • 以前导下划线作为前缀的函数、方法和其他对象 (_ )这是标准的python方法,用于指示某个对象是私有的;如果任何方法以一个 _ ,这是一个内部API。