Plan 9とGo言語のブログ

主にPlan 9やGo言語の日々気づいたことを書きます。

Goで非推奨(Deprecated)や撤回(Retracted)を明示する方法

Go

最近のGoには、関数やパッケージを非推奨と扱う方法があります。まとまっていると便利かなと思うので、種類ごとにまとめてみました。GoDocコメントを多用するので、GoDocを書き慣れていない場合は以下も参考にしてください。

blog.lufia.org

関数と型を非推奨にする

関数コメントに、// Deprecated: ではじまる段落を追加します。

// Parse parses a string of the form <status>=<status>.
//
// Deprecated: Use ParseStatusMap instead.
func Parse(src string) (map[Status]Status, error) {
    ...
}

型の場合も同様に。

// Error is the interface that wraps Error method. 
//
/// Deprecated: Use error instead.
type Error interface {
    ...
}

これを含んだバージョンをリリースすると、GoDocでは以下のように表示されます。

関数名と並んでDEPRECATEDと描画されている様子

ただし、関数や型の非推奨化を検出するLinterは存在します*1が、標準のツールでは警告等を出力しません。これはおそらく、非推奨だとしても互換性を維持するために関数は残り続ける習慣があるので、使い続けても支障はないためじゃないかなと思っています。

互換性を維持しつつ変更を加える方法は、以下の記事が参考になります。

変数と定数を非推奨にする

これも // Deprecated: コメントを追加します。

// ZP is the zero Point.
//
// Deprecated: Use a literal image.Point{} instead.
var ZP Point

定数も同様。

const (
    ...
    // Deprecated: Use TypeReg instead.
    TypeRegA = '\x00'
    ...
)

定数をまとめて非推奨にしたい場合はconstの前に書きます。

// Seek whence values.
//
// Deprecated: Use io.SeekStart, io.SeekCurrent, and io.SeekEnd.
const (
    SEEK_SET int = 0 // seek relative to the origin of the file
    SEEK_CUR int = 1 // seek relative to the current offset
    SEEK_END int = 2 // seek relative to the end
)

2023年現在、変数または定数の場合は、GoDocの上では特別な表示をしていません。

構造体のフィールドを非推奨にする

型そのものではなく、一部のフィールドだけ非推奨としたい場合は、該当フィールドのコメントに // Deprecated: ではじまる段落を追加します。

type FileHeader struct {
    ...
    // ModifiedTime is an MS-DOS-encoded time.
    //
    // Deprecated: Use Modified instead.
    ModifiedTime uint16
    ...
}

行コメントの場合はこのように。

// PipeNode holds a pipeline with optional declaration
type PipeNode struct {
    ...
    Line     int             // The line number in the input. Deprecated: Kept for compatibility.
    ...
}

2023年現在、GoDocの上では特別な表示をしていません。

モジュールの特定バージョンを撤回する

壊れた状態でリリースしたしまったとか、関数名をtypoしていた等でバージョンを撤回したい場合があると思います。この場合は、go.mod にretractディレクティブを追加して、新しいバージョンを公開します。

retract v0.1.0 // Contains a misleading function name.

retractディレクティブでバージョンを示すと、モジュール上では撤回されたバージョンとして扱われます。GoDocでの表示はこのようになります。

撤回されたフラグが描画されている様子

また、撤回されたバージョンを参照したとき、goコマンドによって以下のような警告が出力されます。

go: warning: github.com/mackerelio/checkers@v0.1.0: retracted by module author: Contains a misleading function name.

retract ディレクティブは複数のバージョンをまとめて撤回したりもできます。詳細はドキュメントを参照してください。

モジュールそのものを非推奨にする

新しいメジャーバージョンを公開したので古いほうを非推奨としたい、またはメンテナンスを縮小するので非推奨としたい場合にはモジュールそのものを非推奨とすることもできます。

この場合は、go.mod のmoduleディレクティブに // Deprecated: を書きます。

// Deprecated: Use github.com/gomodule/redigo instead.
module github.com/garyburd/redigo

GoDocでの表示はこのようになります。

モジュールは非推奨と警告を出している様子

公式のドキュメントは以下です。

*1:staticcheck等