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

在標準庫中還有一些其他示例。