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

このコミットは、Go言語の標準ライブラリ net/http パッケージにおける DefaultTransport のドキュメンテーションを明確化することを目的としています。具体的には、DefaultTransport がネットワーク接続をどのように確立し、再利用するかについての記述を修正し、より正確な情報を提供するものです。

コミット

commit a7c57b05e9b51194c534d41a232739921aa2f45d
Author: Brad Fitzpatrick <bradfitz@golang.org>
Date:   Tue Dec 4 20:14:58 2012 -0800

    net/http: clarify DefaultTransport docs
    
    Fixes #4281
    
    R=golang-dev, adg
    CC=golang-dev
    https://golang.org/cl/6872053

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

https://github.com/golang/go/commit/a7c57b05e9b51194c534d41a232739921aa2f45d

このコミットの元の内容は、「net/http: DefaultTransport のドキュメントを明確化する」というものです。これは、DefaultTransport の動作に関する既存のドキュメントが不正確であったため、その説明を修正し、ユーザーが DefaultTransport の挙動を正しく理解できるようにすることを意図しています。特に、接続の確立と再利用に関する記述が焦点となっています。

変更の背景

Go言語の net/http パッケージは、HTTPクライアントとサーバーを構築するための基本的な機能を提供します。その中で、http.DefaultClient は、特別な設定なしにHTTPリクエストを行うための便利なクライアントです。この DefaultClient は内部的に http.DefaultTransport を使用して実際のネットワーク通信を行います。

以前の DefaultTransport のドキュメントには、「各 Do の呼び出しに対して新しいネットワーク接続を確立する」という記述がありました。しかし、これは DefaultTransport の実際の動作とは異なっていました。DefaultTransport は、パフォーマンス向上のために接続の再利用（コネクションプーリング）を行います。つまり、一度確立された接続は、後続のリクエストのためにキャッシュされ、再利用される可能性があります。

このドキュメントの不正確さは、開発者が DefaultTransport の挙動について誤解を招く可能性がありました。例えば、リクエストごとに新しい接続が確立されると誤解し、接続のオーバーヘッドを過度に心配したり、不必要な最適化を試みたりするかもしれません。このコミットは、このような誤解を解消し、DefaultTransport の実際の動作を正確に反映するために行われました。

前提知識の解説

このコミットを理解するためには、以下のGo言語の net/http パッケージに関する基本的な概念を理解しておく必要があります。

net/http パッケージ: Go言語の標準ライブラリで、HTTPクライアントとサーバーの実装を提供します。WebアプリケーションやAPIクライアントを開発する際に中心的に使用されます。
http.Client: HTTPリクエストを行うためのクライアント構造体です。Get, Post, Do などのメソッドを提供します。
http.DefaultClient: http.Client のデフォルトインスタンスです。特別な設定なしにHTTPリクエストを行う際に便利です。
http.Transport: http.Client が実際にネットワーク通信を行うためのインターフェース http.RoundTripper の実装の一つです。TCP接続の確立、TLSハンドシェイク、HTTPリクエストの送信、レスポンスの受信、コネクションプーリングなどを担当します。
http.DefaultTransport: http.Transport のデフォルトインスタンスです。http.DefaultClient が内部的に使用します。この DefaultTransport は、HTTP/1.x のコネクションプーリングをサポートしており、パフォーマンスのために接続を再利用します。
http.RoundTripper インターフェース: RoundTrip(*http.Request) (*http.Response, error) メソッドを持つインターフェースです。HTTPリクエストを送信し、HTTPレスポンスを受け取るための単一の抽象化を提供します。http.Client はこのインターフェースを介して実際の通信を行います。
コネクションプーリング (Connection Pooling): HTTP/1.x において、複数のHTTPリクエストで同じTCP接続を再利用する技術です。これにより、TCP接続の確立（3ウェイハンドシェイク）やTLSハンドシェイクのオーバーヘッドを削減し、パフォーマンスを向上させることができます。
HTTPプロキシ: クライアントとサーバーの間でHTTPリクエストを中継するサーバーです。環境変数 $HTTP_PROXY や $http_proxy で指定されたプロキシサーバーを使用するように DefaultTransport は設定されています。
$HTTP_PROXY / $http_proxy 環境変数: HTTPプロキシサーバーのアドレスを指定するための環境変数です。
$NO_PROXY / $no_proxy 環境変数: プロキシを使用しないホストのリストを指定するための環境変数です。

技術的詳細

このコミットの技術的な詳細は、src/pkg/net/http/transport.go ファイル内の DefaultTransport のドキュメンテーションコメントの変更に集約されます。

変更前は、DefaultTransport のドキュメンテーションは以下のようになっていました。

// DefaultTransport is the default implementation of Transport and is
// used by DefaultClient.  It establishes a new network connection for
// each call to Do and uses HTTP proxies as directed by the
// $HTTP_PROXY and $NO_PROXY (or $http_proxy and $no_proxy)
// environment variables.

この記述の主要な問題点は、「It establishes a new network connection for each call to Do」（各 Do の呼び出しに対して新しいネットワーク接続を確立する）という部分でした。これは DefaultTransport の実際の動作と矛盾していました。DefaultTransport は、内部的にコネクションプーリングメカニズム（Transport 構造体の MaxIdleConnsPerHost などによって制御される）を持っており、アイドル状態の接続を再利用します。

変更後、ドキュメンテーションは以下のように修正されました。

// DefaultTransport is the default implementation of Transport and is
// used by DefaultClient. It establishes network connections as needed
// and caches them for reuse by subsequent calls. It uses HTTP proxies
// as directed by the $HTTP_PROXY and $NO_PROXY (or $http_proxy and
// $no_proxy) environment variables.

この修正により、以下の点が明確化されました。

接続の確立方法: 「It establishes a new network connection for each call to Do」から「It establishes network connections as needed」（必要に応じてネットワーク接続を確立する）に変更されました。これにより、リクエストごとに必ず新しい接続が確立されるわけではないことが示唆されます。
接続の再利用: 「and caches them for reuse by subsequent calls」（そして、後続の呼び出しのためにそれらをキャッシュして再利用する）という記述が追加されました。これは、DefaultTransport がコネクションプーリングを行い、接続を再利用するメカニズムを持っていることを明確に示しています。

この変更は、コードの動作自体を変更するものではなく、その動作に関するドキュメンテーションの正確性を向上させるものです。これにより、net/http パッケージを使用する開発者が、DefaultTransport のパフォーマンス特性（特に接続の再利用による効率性）を正しく理解できるようになります。

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

diff --git a/src/pkg/net/http/transport.go b/src/pkg/net/http/transport.go
index 0aec1ae51b..48f7ac0e53 100644
--- a/src/pkg/net/http/transport.go
+++ b/src/pkg/net/http/transport.go
@@ -28,10 +28,10 @@ import (
 )
 
 // DefaultTransport is the default implementation of Transport and is
-// used by DefaultClient.  It establishes a new network connection for
-// each call to Do and uses HTTP proxies as directed by the
-// $HTTP_PROXY and $NO_PROXY (or $http_proxy and $no_proxy)
-// environment variables.
+// used by DefaultClient. It establishes network connections as needed
+// and caches them for reuse by subsequent calls. It uses HTTP proxies
+// as directed by the $HTTP_PROXY and $NO_PROXY (or $http_proxy and
+// $no_proxy) environment variables.
 var DefaultTransport RoundTripper = &Transport{Proxy: ProxyFromEnvironment}
 
 // DefaultMaxIdleConnsPerHost is the default value of Transport\'s

コアとなるコードの解説

上記の diff は、src/pkg/net/http/transport.go ファイル内の DefaultTransport 変数の宣言直前にあるコメントブロックの変更を示しています。

- で始まる行: 変更前の行を示します。
+ で始まる行: 変更後の行を示します。

具体的には、以下の2行が変更されています。

変更前: It establishes a new network connection for 変更後: It establishes network connections as needed この変更は、「各 Do 呼び出しに対して新しいネットワーク接続を確立する」という誤った記述を、「必要に応じてネットワーク接続を確立する」というより正確な記述に修正しています。これにより、接続が常に新しく確立されるわけではないことが示唆されます。
変更前: each call to Do and uses HTTP proxies as directed by the 変更後: and caches them for reuse by subsequent calls. It uses HTTP proxies この変更は、変更前の行の後半部分を削除し、代わりに「そして、後続の呼び出しのためにそれらをキャッシュして再利用する」という記述を追加しています。これは、DefaultTransport がコネクションプーリングを行い、既存の接続を再利用する機能を持っていることを明確に示しています。その後の「It uses HTTP proxies」は、プロキシに関する記述が引き続き適用されることを示しています。

これらの変更は、DefaultTransport の実際の動作（コネクションプーリングによる接続の再利用）を正確に反映するようにドキュメンテーションを更新するものです。

参考にした情報源リンク

GitHub上のコミットページ: https://github.com/golang/go/commit/a7c57b05e9b51194c534d41a232739921aa2f45d
Go言語の公式ドキュメント (pkg.go.dev)
Go言語の net/http パッケージに関する一般的な知識

comemo