Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

[インデックス 14790] ファイルの概要

コミット

このコミットは、Go言語の標準ライブラリ net/http パッケージにおける TimeoutHandler のドキュメント（godoc）を、実際のコードの変更に合わせて同期させることを目的としています。具体的には、TimeoutHandler のタイムアウト指定が int64 型のナノ秒 (ns) から time.Duration 型に変更されたにもかかわらず、ドキュメントが古い記述のままになっていた点を修正しています。

GitHub上でのコミットページへのリンク

https://github.com/golang/go/commit/98edf09e674b0f02cb32c48de22dcb21ca50df2d

元コミット内容

commit 98edf09e674b0f02cb32c48de22dcb21ca50df2d
Author: Matthew Dempsky <mdempsky@google.com>
Date:   Thu Jan 3 10:06:04 2013 -0800

    net/http: Sync TimeoutHandler godoc with code.
    
    TimeoutHandler was changed from "ns int64" to "dt time.Duration" on
    Nov 30, 2011, but the godoc still refers to "ns".
    
    R=golang-dev, bradfitz
    CC=golang-dev
    https://golang.org/cl/7031050
---\n src/pkg/net/http/server.go | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/src/pkg/net/http/server.go b/src/pkg/net/http/server.go
index 89a46f06bb..721be80293 100644
--- a/src/pkg/net/http/server.go
+++ b/src/pkg/net/http/server.go
@@ -1327,7 +1327,7 @@ func (srv *Server) ListenAndServeTLS(certFile, keyFile string) error {
 // TimeoutHandler returns a Handler that runs h with the given time limit.
 //
 // The new Handler calls h.ServeHTTP to handle each request, but if a
-// call runs for more than ns nanoseconds, the handler responds with
+// call runs for longer than its time limit, the handler responds with
 // a 503 Service Unavailable error and the given message in its body.
 // (If msg is empty, a suitable default message will be sent.)
 // After such a timeout, writes by h to its ResponseWriter will return

変更の背景

このコミットの背景には、Go言語の net/http パッケージにおける TimeoutHandler のAPI変更があります。2011年11月30日に、TimeoutHandler のタイムアウト期間を指定する引数の型が int64 (ナノ秒単位) から time.Duration に変更されました。この変更は、Go言語における時間表現の標準化と、より型安全で読みやすいAPI設計への移行の一環として行われたと考えられます。

しかし、APIの変更後も、その機能に関するドキュメント（godoc）が更新されず、古い ns (ナノ秒) という記述が残っていました。これにより、開発者がドキュメントを参照した際に、実際のコードの挙動とドキュメントの内容に齟齬が生じ、混乱を招く可能性がありました。このコミットは、このようなドキュメントとコードの不一致を解消し、開発者体験を向上させることを目的としています。

前提知識の解説

Go言語の time.Duration 型

Go言語の time パッケージには、期間（duration）を表すための Duration 型が定義されています。これは int64 のエイリアスであり、ナノ秒単位で時間を内部的に保持します。しかし、time.Duration 型の大きな利点は、time.Second, time.Minute, time.Hour などの定数と組み合わせて、より人間が読みやすい形で期間を表現できる点です。

例えば、5秒間を表す場合、int64 であれば 5 * 1000 * 1000 * 1000 (50億ナノ秒) と記述する必要がありますが、time.Duration を使用すれば 5 * time.Second と簡潔に記述できます。これにより、コードの可読性が大幅に向上し、単位変換ミスなどのバグを防ぐことができます。

net/http パッケージと TimeoutHandler

net/http パッケージは、Go言語でHTTPクライアントおよびサーバーを構築するための標準ライブラリです。WebアプリケーションやAPIサーバーを開発する上で不可欠な機能を提供します。

http.TimeoutHandler は、HTTPリクエストの処理に時間制限を設けるためのミドルウェア（http.Handler をラップする http.Handler）です。このハンドラは、指定された時間内にラップされたハンドラが処理を完了しない場合、HTTP 503 Service Unavailable エラーをクライアントに返します。これは、サーバーが過負荷になったり、バックエンドサービスが応答しない場合に、クライアントが無限に待機するのを防ぎ、より良いユーザーエクスペリエンスを提供するために重要です。

godoc

godoc は、Go言語のソースコードからドキュメントを生成するためのツールです。Go言語では、関数、型、変数などの宣言の直前に書かれたコメントがドキュメントとして扱われ、godoc コマンドや pkg.go.dev のようなオンラインサービスで閲覧できます。godoc は、Go言語の「ドキュメントはコードと共に生きる」という哲学を体現しており、コードとドキュメントの一貫性を保つことが推奨されています。

技術的詳細

このコミットは、src/pkg/net/http/server.go ファイル内の TimeoutHandler のgodocコメントを修正しています。

元のコメントでは、タイムアウトの指定方法について「ns nanoseconds（ナノ秒）」という表現が使われていました。これは、TimeoutHandler の引数が int64 型でナノ秒単位の値を直接受け取っていた時代の記述です。

// call runs for more than ns nanoseconds, the handler responds with

しかし、APIが time.Duration 型に変更されたことで、引数はもはや直接的なナノ秒の int64 ではなく、time.Duration 型の値を期待するようになりました。time.Duration は内部的にはナノ秒ですが、外部からは time.Second や time.Minute といった単位で扱われることが一般的です。

この変更を受けて、ドキュメントの記述もより抽象的で、time.Duration の意図に沿ったものに修正されました。具体的には、「ns nanoseconds」という具体的な単位の記述を削除し、「its time limit（その時間制限）」という表現に変更されています。

// call runs for longer than its time limit, the handler responds with

この修正により、ドキュメントは現在のAPIの挙動と完全に一致し、開発者が TimeoutHandler を使用する際に誤解が生じる可能性がなくなりました。これは、APIの変更に伴うドキュメントの追従という、ソフトウェア開発における重要なメンテナンス作業の一例です。

コアとなるコードの変更箇所

変更は src/pkg/net/http/server.go ファイルの1箇所のみです。

--- a/src/pkg/net/http/server.go
+++ b/src/pkg/net/http/server.go
@@ -1327,7 +1327,7 @@ func (srv *Server) ListenAndServeTLS(certFile, keyFile string) error {
 // TimeoutHandler returns a Handler that runs h with the given time limit.
 //
 // The new Handler calls h.ServeHTTP to handle each request, but if a
-// call runs for more than ns nanoseconds, the handler responds with
+// call runs for longer than its time limit, the handler responds with
 // a 503 Service Unavailable error and the given message in its body.
 // (If msg is empty, a suitable default message will be sent.)
 // After such a timeout, writes by h to its ResponseWriter will return

コアとなるコードの解説

変更された行は、TimeoutHandler のgodocコメントの一部です。

  • 変更前: // call runs for more than ns nanoseconds, the handler responds with
  • 変更後: // call runs for longer than its time limit, the handler responds with

この変更は、TimeoutHandler の引数が int64 型のナノ秒 (ns) から time.Duration 型に変更されたことに伴うドキュメントの修正です。

元のコメントでは、タイムアウトの単位が「ナノ秒」であることと、引数名が「ns」であることが明示されていました。これは、APIが直接ナノ秒の整数値を受け取っていた時代の正確な記述でした。

しかし、APIが time.Duration に変更されたことで、開発者は 5 * time.Second のように、より抽象的な Duration 型の値を渡すようになりました。この Duration 型は内部的にはナノ秒で表現されますが、外部からは「時間制限」として扱われるべきです。

新しいコメント「its time limit」は、この time.Duration の概念をより適切に表現しています。これにより、ドキュメントはAPIの現在のシグネチャとセマンティクスに完全に合致し、開発者が TimeoutHandler を使用する際に、引数に time.Duration 型の「時間制限」を渡すという意図を明確に理解できるようになります。

この修正は機能的な変更ではなく、ドキュメントの正確性を高めるためのものです。しかし、正確なドキュメントは、ライブラリの使いやすさと開発者の生産性にとって非常に重要です。

関連リンク

参考にした情報源リンク

  • コミットメッセージ内の https://golang.org/cl/7031050 は、この変更がGoのコードレビューシステム（Gerrit）でどのように議論され、承認されたかを示すリンクです。これは、Go言語の公式リポジトリにおける変更履歴を追跡する上で非常に有用な情報源となります。
  • Go言語の公式ドキュメント（pkg.go.dev）は、Go言語の標準ライブラリに関する最も信頼できる情報源です。
  • Go言語のブログや公式リポジトリのコミット履歴は、特定の変更の背景や意図を理解する上で役立ちます。