Django致力于API的稳定性和向前兼容性。简而言之,这意味着针对Django版本开发的代码将继续用于将来的版本。在升级项目使用的Django版本时,可能需要进行一些小的更改:请参阅 release note 对于要升级到的一个或多个版本。
在将API稳定性作为一个非常重要的优先事项的同时,Django还致力于持续改进,并在我们提供的API中实现“一种方法”(最终)。这意味着,当我们发现明显优越的做事方法时,我们会反对并最终消除旧的方法。我们的目标是提供一个现代的,可靠的最高质量的网络框架,鼓励所有使用它的项目中的最佳实践。通过使用渐进式的改进,我们试图避免停滞和大规模破坏性升级。
在这种情况下,稳定意味着:
如果不提供向后兼容的别名,则不会移动或重命名所有公共API(本文档中的所有内容)。
如果向这些API中添加新的特性(这是完全可能的),它们将不会破坏或改变现有方法的含义。换句话说,“稳定”并不(必然)意味着“完整”。
如果出于某种原因,必须删除或替换声明为稳定的API,则该API将被声明为不推荐使用,但将保留在API中至少两个功能版本。调用不推荐使用的方法时将发出警告。
见 正式发布 有关django的版本编号方案如何工作以及功能将如何被弃用的详细信息。
只有当一个bug或安全漏洞使其完全不可避免时,我们才会打破这些api的向后兼容性,而不必进行弃用过程。
一般来说,文档中包含的所有内容——除了 internals area 被认为是稳定的。
对于这种稳定性和向后兼容性承诺,有一些例外。
如果我们意识到一个安全问题——希望有人跟踪我们 security reporting policy --我们会尽一切必要的办法来修复它。这可能意味着破坏向后兼容性;安全性胜过兼容性保证。
某些API通过以下几种方式显式标记为“内部”:
一些文档提到了内部,并提到了它们。如果文档中说某个东西是内部的,我们保留更改它的权利。
以前导下划线作为前缀的函数、方法和其他对象 (_
)这是标准的python方法,用于指示某个对象是私有的;如果任何方法以一个 _
,这是一个内部API。
12月 18, 2023