コア概念

以下の概念を理解すれば、HTTPC の全体像を素早く把握できます。

2 層 API アーキテクチャ

HTTPC は標準ライブラリ net/http における http.Get と http.Client の関係に対応する、2 つの等価なリクエスト方式を提供します：

パッケージレベル関数 — 設定不要、内部で遅延初期化されるデフォルトクライアントを共有します。スクリプトや一回限りのリクエストに適しています：

result, err := httpc.Get("https://api.example.com/data")

Client インスタンス — 設定、コネクションプール、ライフサイクルを完全に制御します。長期間実行するサービスに適しています：

client, err := httpc.NewDefault()
defer func() { _ = client.Close() }()
result, err := client.Get("https://api.example.com/data")

両方式とも同じリクエストオプション（WithHeader、WithJSON…）を受け取り、同じ *Result 型を返します。パッケージレベル関数は Client インスタンスの薄いラッパーです。

ヒント

どちらを使うべきか？一回限りのリクエストや迅速なプロトタイピング → パッケージレベル関数。本番サービス、カスタム設定やコネクションプール管理が必要 → Client インスタンス。

設定体系：Config と With* オプション

HTTPC は設定を 2 つの独立した階層に分離し、混乱を回避します：

階層	手段	スコープ	代表フィールド
インスタンス設定	`Config` 構造体	クライアントの全ライフサイクル	タイムアウト、リトライポリシー、コネクションプール、TLS
リクエストオプション	`WithXxx()` 関数	単一リクエスト	`WithHeader`、`WithJSON`、`WithTimeout`

インスタンス設定は Config 構造体で New() に渡されます。DefaultConfig() から始めて、必要に応じてフィールドを修正します：

cfg := httpc.DefaultConfig()
cfg.Timeouts.Request = 60 * time.Second
cfg.Retry.MaxRetries = 5
client, err := httpc.New(cfg)

リクエストオプションは呼び出しごとに渡され、インスタンスレベルのデフォルトを補完または上書きします：

result, err := client.Get(url,
    httpc.WithHeader("Authorization", "Bearer "+token),
    httpc.WithTimeout(30*time.Second),
)

プリセット設定（SecureConfig()、PerformanceConfig() など）を出発点としても利用できます。設定 API を参照してください。

リクエストライフサイクル

各リクエストは以下のフローを経由します：

text

オプション適用 → ミドルウェアチェーン（存在する場合）→ エンジン実行 → リトライ（必要時）→ Result 返却
      ↑                                         ↑
   With* 関数                    コネクションプール / TLS / プロキシ / SSRF チェック

オプション適用 — With* 関数がヘッダー、ボディ、タイムアウトなどを設定
ミドルウェアチェーン — カスタムロギング、メトリクス、監査ロジック（Config.Middleware で設定）
エンジン実行 — コネクションプール再利用、TLS ハンドシェイク、HTTP/2 ネゴシエーション、SSRF 検証
リトライ — リトライ可能なエラー（タイムアウト、5xx、429 など）発生時に自動的に指数バックオフでリトライ
Result — レスポンスデータ、リクエストメタ情報、リトライ統計を含む。GC が自動回収、手動解放不要

セキュアなデフォルト

HTTPC はデフォルトでセキュア（secure by default）であり、追加設定なしで以下を提供します：

TLS 1.2+ 強制暗号化
SSRF 防護 — プライベート/予約 IP アドレス（127.0.0.1、10.x、192.168.x など）への接続をブロック
CRLF インジェクション防止 — リクエストヘッダーと URL を自動検証
レスポンスボディサイズ制限 — デフォルト 10MB、メモリ枯渇を防止

内部サービス（VPN、イントラネット）に接続するには、Security.AllowPrivateIPs = true を設定するか、SSRFExemptCIDRs で選択的許可リストを使用してください。セキュリティ概要を参照してください。

エラーモデル

HTTPC はネットワーク層エラーと HTTP ステータスコードを区別します：

ネットワーク層エラー（接続失敗、タイムアウト、TLS エラーなど）→ error として返却。errors.As で ClientError を抽出し、分類とリトライ可否を確認可能
HTTP ステータスコード（4xx、5xx）→ error としては返却されない。result.IsSuccess() などのメソッドで確認が必要

result, err := client.Get(url)
if err != nil {
    // ネットワーク層エラー — リクエストが正常に完了しなかった
    var clientErr *httpc.ClientError
    if errors.As(err, &clientErr) {
        log.Printf("エラータイプ: %s, リトライ可能: %v", clientErr.Code(), clientErr.IsRetryable())
    }
    return err
}
// リクエスト完了 — HTTP ステータスコードを確認
if !result.IsSuccess() {
    log.Printf("HTTP エラー: %d", result.StatusCode())
}

エラー処理を参照してください。

コア概念 ​

2 層 API アーキテクチャ ​

設定体系：Config と With* オプション ​

リクエストライフサイクル ​

セキュアなデフォルト ​

エラーモデル ​