Go Wiki：已棄用

有時，結構欄位、函式、類型，甚至整個套件等 API 功能會變得多餘或不必要。當我們想要阻止新程式使用它時，我們會將該功能標記為「已棄用」。

與其他一些系統不同，API 功能被棄用並不表示它將在未來被移除。相反地，Go 1 相容性表示該功能將以其已棄用的形式保留，以使現有程式繼續執行。

若要表示不應使用識別碼，請在其文件註解中新增一段落，以 已棄用： 開頭，後面接著一些有關棄用的資訊，以及適用的話，建議使用什麼來取代。該段落不必是文件註解中的最後一段落。

有些工具會針對已棄用識別碼的使用發出警告，而它們的文件 會隱藏在 pkg.go.dev 上。

如果函式 F1 正在被函式 F2 取代，且 F2 可用的第一個版本是 Go 1.N，則不應在 Go 1.N+1 之前為 F1 新增官方棄用公告。這可確保 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

標準函式庫中還有其他一些範例 in the standard library。

此內容是 Go Wiki 的一部分。