API 的稳定性

从 1.0 版本开始,Django 保证 API 的稳定性和向前兼容。简而言之,这意味着你现在写的代码在将来的版本中依旧可以使用。如果你给你的项目升级了 Django 版本,你可能需要更改项目中的小细节,这些可以在每个版本或者你所升级的版本发行说明中的 “向后不兼容改动” 小节中查看 发布说明

什么是“稳定性”?

在此处,稳定意味着:

  • 所有发布的 API (在文档中的一切 API )在不提供向后兼容的别名的情况下,都不会被移除或者重命名。

  • 如果文档中的 API 添加了新特性(这是极有可能的),新特性不会导致现有方法罢工或者修改方法的含义。也就是说,“稳定性”并不意味着“不变性”。

  • 假如因为某些原因,一个“稳定的” API 必须被移除或者被代替,它将会被弃用但仍然会被保留直到至少有两个新特性发布。当调用即将被弃用的方法时,会产生警告。

有关 Django 是如何编写版本号以及一些功能是如何被弃用的详细信息,请看: Official releases

  • 我们只有在某些 API 中的一个 bug 或者 安全问题导致问题完全不能避免的时候,我们才会移除对这些 API 的向后兼容。

稳定的 API

一般来说,文档中的一切都确定是稳定的,除开 internals area

例外

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

安全修复

如果我们发现了安全问题 —希望报告者遵照我们的 安全报告政策—我们会尽一切努力解决它。 这可能意味着打破向后兼容性; 安全性优先于兼容性保证。

标记为内部的 API

某些API在几种方式中被明确标记为 "内部" :

  • 一些文档提及了这些 API 并标为“内部”,如果确实如此,我们保留修改它的权利。
  • 一些函数,方法以及其他对象以下划线“”开头,这是 Python 声明其为“私有”的标准方式,如果一个方法以单下划线“”开头,那么这意味着它是 Django 内部的一个 API。