API的稳定性

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

什么是“稳定性”？

在此处，稳定意味着：

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

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

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

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

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

稳定的API

一般来说，文档中的一切都确定是稳定的，除开 internals area </internals/index> 。

例外

There are a few exceptions to this stability and backwards-compatibility promise.

安全修复

If we become aware of a security problem -- hopefully by someone following our security reporting policy -- we'll do everything necessary to fix it. This might mean breaking backwards compatibility; security trumps the compatibility guarantee.

API标记为内部

某些API由几个方式被明确标记为 "内部" :

  • Some documentation refers to internals and mentions them as such. If the documentation says that something is internal, we reserve the right to change it.
  • Functions, methods, and other objects prefixed by a leading underscore (_). This is the standard Python way of indicating that something is private; if any method starts with a single _, it's an internal API.
« previous | up | next »