API稳定性

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

“稳定”意味着什么

在这种情况下，稳定意味着：

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

  • 如果向这些API添加新功能（这是很有可能的），它们不会破坏或更改现有方法的含义。 换句话说，“稳定”不一定意味着“完全”。

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

    有关Django的版本编号方案如何工作以及如何弃用功能的详细信息，请参见Official releases。

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

稳定的API

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

异常

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

安全修复

如果我们发现有安全问题（希望有人按照我们的安全报告政策），我们会尽一切必要措施予以解决。 这可能意味着破坏向后兼容性；安全胜过兼容性保证。

标记为内部的API

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

  • 一些文档提到内部并提到它们。 如果文档说明内容是内部的，我们保留更改它的权利。
  • 函数，方法和其他以前导下划线（_）为前缀的对象。 这是标准的Python方式，表明某事是私有的；如果任何方法从单个_开始，它是一个内部API。