Go Wiki：已弃用

有时，API 功能（例如结构字段、函数、类型，甚至整个软件包）会变得多余或不必要。当我们希望阻止新程序使用它时，我们会将该功能标记为“已弃用”。

与其他一些系统不同，API 功能被弃用并不意味着它将在未来被移除。相反，Go 1 兼容性意味着该功能将以其已弃用的形式保留，以保持现有程序的运行。

要表示不应使用标识符，请在其文档注释中添加一个段落，该段落以 Deprecated: 开头，后面是有关弃用的某些信息，以及有关在适用的情况下改用什么的建议。该段落不必是文档注释中的最后一段。

一些工具会警告已弃用标识符的使用，并且它们的文档 在 pkg.go.dev 上被隐藏。

如果函数 F1 被函数 F2 替换，并且 F2 可用的第一个版本是 Go 1.N，则 F1 的正式弃用通知不应在 Go 1.N+1 之前添加。这可确保 Go 开发人员仅在所有受支持的 Go 版本都包含 F2 且他们可以轻松切换时才将 F1 视为已弃用。

标记 API 功能已弃用可能会为使用该功能的数百万 Go 开发人员带来工作和决策。弃用 API 功能是一项 API 更改，必须使用 提案流程 进行讨论。

示例

type ResponseRecorder struct {
    // HeaderMap contains the headers explicitly set by the Handler.
    // It is an internal detail.
    //
    // Deprecated: HeaderMap exists for historical compatibility
    // and should not be used. To access the headers returned by a handler,
    // use the Response.Header map as returned by the Result method.
    HeaderMap http.Header

// Package rc4 implements the RC4 stream cipher.
//
// Deprecated: RC4 is cryptographically broken and should not be used
// except for compatibility with legacy systems.
//
// This package is frozen and no new functionality will be added.
package rc4

标准库中还有其他一些示例 在标准库中。

此内容是 Go Wiki 的一部分。