API稳定性

Django自1.0版以来承诺API稳定性和向前兼容性。 简而言之,这意味着您针对Django版本开发的代码将继续与未来版本一起工作。 升级项目使用的Django版本时,可能需要做一些细微的修改:请参阅release note的“向后不兼容的更改”一节,了解您要升级的版本。

什么“稳定”的意思是

在这方面,稳定意味着:

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

  • 如果新功能被添加到这些API中 - 这是很有可能的 - 它们不会中断或改变现有方法的含义。 换句话说,“稳定”并不一定意味着“完整”。

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

    请参阅Official releases了解有关Django版本编号方案如何工作的更多详细信息以及如何使用功能。

  • 如果bug或安全漏洞完全无法避免,我们只会破坏这些API的兼容性。

稳定的API

一般来说,文档中涵盖的所有内容(除了internals area中的任何内容)都被认为是稳定的。

例外¶ T0>

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

安全修复

如果我们意识到安全问题 - 希望遵守我们的security reporting policy - 我们会尽一切努力来解决这个问题。 这可能意味着打破向后兼容;安全胜过兼容性保证。

标记为内部的API

某些API被明确地标记为“内部”在几个方面:

  • 有些文档提到内部,并提到它们。 如果文件中提到有内部信息,我们保留修改的权利。
  • 以前导下划线(_)为前缀的函数,方法和其他对象。 这是标准的Python方式,表明某些东西是私有的;如果任何方法以单个_开头,那么这是一个内部API。