{"title":"API 的稳定性","version":"2.0","locale":"zh-hans","docname":"misc/api-stability","url":"/zh-hans/2.0/misc/api-stability/","canonical":"https://djangodocs.dev/zh-hans/2.0/misc/api-stability/","summary":"从 1.0 版本开始，Django 保证 API 的稳定性和向前兼容。简而言之，这意味着你现在写的代码在将来的版本中依旧可以使用。如果你给你的项目升级了 Django 版本，你可能需要更改项目中的小细节，这些可以在每个版本或者你所升级的版本发行说明中的 “向后不兼容改动” 小节进行查看</releases/index>。…","html":"<h1>API 的稳定性<a class=\"heading-anchor\" href=\"#api-stability\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h1>\n<p>从 1.0 版本开始，Django 保证 API 的稳定性和向前兼容。简而言之，这意味着你现在写的代码在将来的版本中依旧可以使用。如果你给你的项目升级了 Django 版本，你可能需要更改项目中的小细节，这些可以在每个版本或者你所升级的版本发行说明中的 “向后不兼容改动” 小节进行查看&lt;/releases/index&gt;。</p>\n<section id=\"what-stable-means\">\n<h2>什么是“稳定性”？<a class=\"heading-anchor\" href=\"#what-stable-means\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<p>在此处，稳定意味着：</p>\n<ul>\n<li><p>所有发布的API (在文档中的一切API) 在不提供向后兼容的别名的情况下，都不会被移除或者重命名。</p></li>\n<li><p>如果文档中的 API 添加了新特性（这是极有可能的），新特性不会导致现有方法罢工或者修改方法的含义。也就是说，“稳定性”并不意味着“不变性”。</p></li>\n<li><p>假如因为某些原因，一个“稳定的” API 必须被移除或者被代替，它将会被弃用但仍然会被保留直到至少有两个新特性发布。当调用即将被弃用的方法时，会产生警告。</p>\n<p>有关 Django 是如何编写版本号以及一些功能是如何被弃用的详细信息，请看： ref:official-releases</p>\n</li>\n<li><p>我们只有在某些 API 中的一个 bug 或者 安全问题导致问题完全不能避免的时候，我们才会移除对这些 API 的向后兼容。</p></li>\n</ul>\n</section>\n<section id=\"stable-apis\">\n<h2>稳定的API<a class=\"heading-anchor\" href=\"#stable-apis\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<p>一般来说，文档中的一切都确定是稳定的，除开 internals area &lt;/internals/index&gt; 。</p>\n</section>\n<section id=\"exceptions\">\n<h2>例外<a class=\"heading-anchor\" href=\"#exceptions\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<p>这种稳定性和向后兼容性承诺有一些例外。</p>\n<section id=\"security-fixes\">\n<h3>安全修复<a class=\"heading-anchor\" href=\"#security-fixes\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h3>\n<p>如果我们发现了安全问题 --希望报告者遵照我们的：ref：安全报告政策&lt;reporting-security-issues&gt;--我们会尽一切努力解决它。 这可能意味着打破向后兼容性; 安全性优先于兼容性保证。</p>\n</section>\n<section id=\"apis-marked-as-internal\">\n<h3>API标记为内部<a class=\"heading-anchor\" href=\"#apis-marked-as-internal\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h3>\n<p>某些API在几种方式中被明确标记为 &quot;内部&quot; :</p>\n<ul class=\"simple\">\n<li><p>一些文档提及了这些API并标为“内部”，如果确实如此，我们保留权利修改它。</p></li>\n<li><p>一些函数，方法以及其他对象以下划线“_”开头，这是Python声明其为“私有”的标准方式，如果一个方法以单下划线“_”开头，那么这意味着它是Django内部的一个API</p></li>\n</ul>\n</section>\n</section>","rootId":"api-stability","toc":[{"title":"什么是“稳定性”？","anchor":"what-stable-means","children":[]},{"title":"稳定的API","anchor":"stable-apis","children":[]},{"title":"例外","anchor":"exceptions","children":[{"title":"安全修复","anchor":"security-fixes","children":[]},{"title":"API标记为内部","anchor":"apis-marked-as-internal","children":[]}]}],"breadcrumbs":[{"docname":"misc/index","title":"元文件和杂记","url":"/zh-hans/2.0/misc/"}],"prev":{"docname":"misc/index","title":"元文件和杂记","url":"/zh-hans/2.0/misc/"},"next":{"docname":"misc/design-philosophies","title":"设计理念","url":"/zh-hans/2.0/misc/design-philosophies/"},"formats":{"html":"/zh-hans/2.0/misc/api-stability/","markdown":"/zh-hans/2.0/misc/api-stability.md","json":"/zh-hans/2.0/misc/api-stability.json"},"source":"https://github.com/django/django/blob/stable/2.0.x/docs/misc/api-stability.txt","official":"https://docs.djangoproject.com/zh-hans/2.0/misc/api-stability/","inVersions":["6.1","6.0","5.2","5.1","5.0","4.2","4.1","4.0","3.2","3.1","3.0","2.2","2.1","2.0"],"inLocales":["en","zh-hans","fr","ja","id","pt-br","ko","es","el","pl"]}