Go Wiki: 已弃用

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

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

要指示不应使用某个标识符，请在其文档注释中添加一个段落，该段落以 Deprecated: 开头，后跟有关弃用的信息，以及一个关于改用什么替代品的建议（如果适用）。该段落不必是文档注释中的最后一段。

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

如果函数 F1 被函数 F2 替换，并且 F2 可用的第一个版本是 Go 1.N，则不应在 Go 1.N+1 之前添加 F1 的官方弃用通知。这确保了当所有受支持的 Go 版本都包含 F2 并且可以轻松切换时，Go 开发人员才会看到 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

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