API 稳定性 — Django 文档

API稳定性

Django 致力于 API 稳定性和向前兼容性。 简而言之，这意味着您针对某个 Django 版本开发的代码将继续适用于未来的版本。 在升级您的项目使用的 Django 版本时，您可能需要进行一些小的更改：请参阅 发行说明 的“向后不兼容的更改”部分，了解您要升级到的一个或多个版本。

在将 API 稳定性放在非常高的优先级的同时，Django 还致力于持续改进，同时在我们提供的 API 中力求“一种方法来做到这一点”（最终）。 这意味着，当我们发现明显更好的做事方式时，我们将弃用并最终删除旧的方式。 我们的目标是提供一个现代、可靠的最高质量的网络框架，鼓励所有使用它的项目的最佳实践。 通过使用增量改进，我们尽量避免停滞和大的突破性升级。

“稳定”是什么意思

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

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

• 如果将新功能添加到这些 API 中——这是很有可能的——它们不会破坏或改变现有方法的含义。 换句话说，“稳定”并不（必然）意味着“完整”。

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

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

• 如果错误或安全漏洞使其完全不可避免，我们只会在没有弃用过程的情况下破坏这些 API 的向后兼容性。

稳定的 API

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

例外

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

安全修复

如果我们发现安全问题——希望有人遵循我们的 安全报告政策 ——我们将尽一切努力修复它。 这可能意味着破坏向后兼容性； 安全胜过兼容性保证。

标记为内部的 API

某些 API 以多种方式明确标记为“内部”：

• 一些文档提到内部结构并如此提及它们。 如果文档说某些内容是内部的，我们保留更改它的权利。
• 以下划线 (_) 为前缀的函数、方法和其他对象。 这是指示某些内容是私有的标准 Python 方式； 如果任何方法以单个 _ 开头，则它是内部 API。