Skip to main content

API稳定性

Django承诺从1.0版开始的API稳定性和向前兼容性。简而言之,这意味着您针对Django版本开发的代码将继续在未来的版本中使用。您可能需要在升级项目使用的Django版本时进行小幅更改:有关您要升级的版本,请参阅 发行公告 的“向后不兼容的更改”部分。

什么“稳定”的意思

在这方面,稳定意味着:

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

  • 如果将新功能添加到这些API - 这是很有可能的,他们不会打破或改变现有方法的意义。换句话说,“稳定”不一定意味着“完全”。

  • 如果由于某些原因,必须移除或替换声明为稳定的API,那么它将被声明为已弃用,但会保留在API中至少有两个功能版本。当调用已弃用的方法时将发出警告。

    有关Django的版本编号方案如何工作以及如何弃用功能的更多详细信息,请参阅 官方发布

  • 如果一个错误或安全漏洞使得这些API完全不可避免,我们只会破坏这些API的向后兼容性。

稳定的API

一般来说,文档中涵盖的一切 - 除了 内部区域 中的任何内容都被认为是稳定的。

例外

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

安全修复

如果我们意识到一个安全问题 - 希望有人按照我们的 安全报告策略,我们将做一切必要的修复它。这可能意味着破坏向后兼容性;安全胜过兼容性保证。

标记为内部的API

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

  • 一些文档提到内部并提到它们。如果文档说内容是内部的,我们保留更改它的权利。

  • 函数,方法和其他以前导下划线(_)为前缀的对象。这是标准的Python方式,表明某事是私有的;如果任何方法以单个 _ 开始,则它是一个内部API。