リクエストオプション

リクエストオプションは関数型の設定項目で、RequestOption タイプを通じてリクエストメソッドに渡し、きめ細かなリクエスト制御を実現します。

result, err := client.Post(url,
    httpc.WithJSON(data),
    httpc.WithBearerToken(token),
    httpc.WithQuery("page", 1),
)

すべてのオプションは自由に組み合わせ可能で、渡された順に適用されます。

リクエストヘッダー

WithHeader

func WithHeader(key, value string) RequestOption

単一のリクエストヘッダーを設定します。キーと値はセキュリティ検証を通過します（CRLF インジェクション対策）。

result, err := client.Get(url,
    httpc.WithHeader("X-Custom", "value"),
)

WithHeaderMap

func WithHeaderMap(headers map[string]string) RequestOption

リクエストヘッダーを一括設定します。

result, err := client.Get(url,
    httpc.WithHeaderMap(map[string]string{
        "Accept":        "application/json",
        "X-Request-ID":  "abc123",
    }),
)

WithUserAgent

func WithUserAgent(userAgent string) RequestOption

User-Agent ヘッダーを設定します。WithHeader("User-Agent", ...) の便利なラッパーです。

認証

WithBasicAuth

func WithBasicAuth(username, password string) RequestOption

HTTP Basic 認証を設定します。ユーザー名は空にできず、認証情報の長さに制限があります。

result, err := client.Get(url,
    httpc.WithBasicAuth("admin", "password"),
)

WithBearerToken

func WithBearerToken(token string) RequestOption

Authorization: Bearer <token> ヘッダーを設定します。Token は空にできません。

result, err := client.Get(url,
    httpc.WithBearerToken("eyJhbGciOiJIUzI1NiIs..."),
)

リクエストボディ

WithJSON

func WithJSON(data any) RequestOption

JSON リクエストボディを設定します。自動的に Content-Type: application/json が追加されます。

result, err := client.Post(url,
    httpc.WithJSON(map[string]any{
        "name":  "test",
        "email": "[email protected]",
    }),
)

WithXML

func WithXML(data any) RequestOption

XML リクエストボディを設定します。自動的に Content-Type: application/xml が追加されます。

WithForm

func WithForm(data map[string]string) RequestOption

URL エンコードフォームのリクエストボディを設定します。自動的に Content-Type: application/x-www-form-urlencoded が追加されます。

result, err := client.Post(url,
    httpc.WithForm(map[string]string{
        "username": "admin",
        "password": "secret",
    }),
)

WithFormData

func WithFormData(data *FormData) RequestOption

multipart/form-data リクエストボディを設定します。ファイルとフィールドの混合アップロードに対応します。

result, err := client.Post(url,
    httpc.WithFormData(&httpc.FormData{
        Fields: map[string]string{"description": "upload"},
        Files: map[string]*httpc.FileData{
            "file": {Filename: "doc.pdf", Content: fileBytes},
        },
    }),
)

WithFile

func WithFile(fieldName, filename string, content []byte) RequestOption

ファイルアップロードの便利な関数。自動的に multipart リクエストボディを構築します。ファイル名はパストラバーサル対策の処理を通過します。

result, err := client.Post(url,
    httpc.WithFile("upload", "report.csv", csvBytes),
)

WithBinary

func WithBinary(data []byte, contentType ...string) RequestOption

バイナリリクエストボディを設定します。デフォルトの Content-Type は application/octet-stream で、カスタマイズ可能です。

result, err := client.Post(url,
    httpc.WithBinary(imageBytes, "image/png"),
)

WithBody

func WithBody(data any, kind ...BodyKind) RequestOption

汎用リクエストボディ設定。自動検出と明示的なタイプ指定に対応します。

自動検出ルール（デフォルト BodyAuto）：

入力タイプ	Content-Type
string	text/plain; charset=utf-8
[]byte	application/octet-stream
map[string]string	application/x-www-form-urlencoded
*FormData	multipart/form-data
io.Reader	設定なし（呼び出し元が処理）
その他のタイプ	application/json

明示的なタイプ指定：

// 自動検出（デフォルト）
result, _ := client.Post(url, httpc.WithBody(data))

// JSON を強制
result, _ := client.Post(url, httpc.WithBody(data, httpc.BodyJSON))

// XML を強制
result, _ := client.Post(url, httpc.WithBody(data, httpc.BodyXML))

定数	意味
BodyAuto	自動検出（デフォルト）
BodyJSON	JSON を強制
BodyXML	XML を強制
BodyForm	フォームを強制
BodyBinary	バイナリを強制
BodyMultipart	multipart を強制（*FormData が必要）

クエリパラメータ

WithQuery

func WithQuery(key string, value any) RequestOption

単一のクエリパラメータを設定します。

result, err := client.Get(url,
    httpc.WithQuery("page", 1),
    httpc.WithQuery("limit", 10),
)

WithQueryMap

func WithQueryMap(params map[string]any) RequestOption

クエリパラメータを一括設定します。

result, err := client.Get(url,
    httpc.WithQueryMap(map[string]any{
        "page":  1,
        "limit": 10,
        "sort":  "created_at",
    }),
)

Cookie

WithCookie

func WithCookie(cookie http.Cookie) RequestOption

単一の Cookie を追加します。セキュリティ検証を通過します。

result, err := client.Get(url,
    httpc.WithCookie(http.Cookie{Name: "session", Value: "abc123"}),
)

WithCookies

func WithCookies(cookies []http.Cookie) RequestOption

Cookie を一括追加します。WithCookie を複数回呼び出すよりも効率的です。容量を事前に割り当て、1 回の走査ですべての Cookie を検証します。

cookies := []http.Cookie{
    {Name: "session_id", Value: "abc123"},
    {Name: "user_pref", Value: "dark_mode"},
    {Name: "lang", Value: "en"},
}
result, err := client.Get("https://api.example.com",
    httpc.WithCookies(cookies),
)

WithCookieMap

func WithCookieMap(cookies map[string]string) RequestOption

シンプルな Cookie を一括追加します。name-value のみが必要なケースに適しています。

result, err := client.Get(url,
    httpc.WithCookieMap(map[string]string{
        "session_id": "abc123",
        "lang":       "ja",
    }),
)

WithCookieString

func WithCookieString(cookieString string) RequestOption

生の Cookie ヘッダー文字列から Cookie を追加します。

result, err := client.Get(url,
    httpc.WithCookieString("session=abc123; lang=ja"),
)

WithSecureCookie

func WithSecureCookie(securityConfig *CookieSecurityConfig) RequestOption

リクエスト Cookie のセキュリティ属性（Secure、HttpOnly、SameSite）の検証を強制します。

オプションの順序

このオプションは適用時にすでに存在する Cookie のみを検証します。WithSecureCookie はすべての WithCookie/WithCookies/WithCookieMap/WithCookieString の後に配置する必要があります。そうしないと、後から追加された Cookie は検証されません。順序に依存しないセッションレベルの Cookie セキュリティ検証が必要な場合は、SessionManager.SetCookieSecurity を使用してください。

// 正しい順序：まず Cookie を追加してから検証
result, err := client.Get(url,
    httpc.WithCookie(sessionCookie),
    httpc.WithCookieMap(otherCookies),
    httpc.WithSecureCookie(httpc.StrictCookieSecurityConfig()),
)

リクエスト制御

WithContext

func WithContext(ctx context.Context) RequestOption

リクエストコンテキストを設定します。タイムアウトとキャンセルに対応します。コンテキストは nil にできません。

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

result, err := client.Get(url, httpc.WithContext(ctx))

WithTimeout

func WithTimeout(timeout time.Duration) RequestOption

単一リクエストのタイムアウトを設定します。クライアントのデフォルトタイムアウトをオーバーライドします。範囲：0 ～ 30 分。

result, err := client.Get(url, httpc.WithTimeout(5*time.Second))

WithMaxRetries

func WithMaxRetries(maxRetries int) RequestOption

単一リクエストの最大リトライ回数を設定します。クライアント設定をオーバーライドします。範囲：0-10。

result, err := client.Get(url, httpc.WithMaxRetries(3))

WithFollowRedirects

func WithFollowRedirects(follow bool) RequestOption

リダイレクトに追従するかどうかを制御します。

// リダイレクト追従を禁止
result, err := client.Get(url, httpc.WithFollowRedirects(false))

WithMaxRedirects

func WithMaxRedirects(maxRedirects int) RequestOption

単一リクエストの最大リダイレクト回数を設定します。範囲：0-50。

0 値の意味

0 はリダイレクトを無効にしません。エンジンは 0 を「明示的に未設定」のセンチネル値として扱い、デフォルト上限（10）にフォールバックするため、WithMaxRedirects(0) はこのオプションを省略した場合と等価です。リダイレクト追従を完全に無効にするには、代わりに WithFollowRedirects(false) を使用してください。

WithAllowPrivateIPs

func WithAllowPrivateIPs(allow bool) RequestOption

単一リクエストでクライアントの SSRF ポリシーを上書きします。allow が true の場合、そのリクエストは localhost やプライベート/予約済み IP 範囲（127.0.0.0/8、10.0.0.0/8、192.168.0.0/16、169.254.0.0/16 など）にアクセスでき、この種のアドレスへのリダイレクトも追従します。false の場合、クライアントで Security.AllowPrivateIPs=true が設定されていても、当該リクエストでは SSRF 防護が強制的に有効になります。

セキュリティヒント

これは SSRF 防護の単一リクエスト用エスケープハッチであり、デフォルトで安全なクライアント（AllowPrivateIPs=false）が時折内部サービス、ループバックアドレス、ローカル開発サーバーにアクセスする必要があるシナリオに適しています。

リクエスト URL が信頼でき、かつ信頼できないユーザー入力に由来するものでない場合にのみ有効にしてください。クライアント全体で内部サービスへのアクセスが必要な場合は、Config で直接 Security.AllowPrivateIPs=true を設定してください。

// デフォルトクライアントはプライベート IP をブロック。この呼び出しではリクエスト単位で許可
result, err := httpc.Get("http://localhost:8080/health",
    httpc.WithAllowPrivateIPs(true),
)

WithStreamBody

func WithStreamBody(stream bool) RequestOption

ストリーミングモードを有効にすると、レスポンスボディはメモリにキャッシュされません。

重要な制限

ストリーミングモードは**Download 経由でのみ有効**です。標準リクエストメソッド（Get/Post/Put/Patch/Delete/Head/Options/Request）と組み合わせた場合、レスポンスボディは完全に読み込まれて Result に変換され、その後基盤のストリームが閉じられます——返される Result のレスポンスボディは空になり、呼び出し側はそのストリームを消費できません。

大きなファイルをメモリにキャッシュせずに本当にストリーミングダウンロードするには、Download を使用してください。

コールバック

WithOnRequest

func WithOnRequest(callback func(req RequestMutator) error) RequestOption

リクエスト送信前のコールバックを登録します。チェーン登録が可能で、追加順に実行されます。コールバックがエラーを返すとリクエストが中止されます。

result, err := client.Get(url,
    httpc.WithOnRequest(func(req httpc.RequestMutator) error {
        log.Printf("送信 %s %s", req.Method(), req.URL())
        return nil
    }),
)

WithOnResponse

func WithOnResponse(callback func(resp ResponseMutator) error) RequestOption

レスポンス受信後のコールバックを登録します。チェーン登録が可能で、追加順に実行されます。

result, err := client.Get(url,
    httpc.WithOnResponse(func(resp httpc.ResponseMutator) error {
        log.Printf("レスポンス受信: %d %s", resp.StatusCode(), resp.Status())
        return nil
    }),
)

関連項目

• 定数とタイプ - BodyKind 定数とタイプエイリアス
• インターフェース定義 - RequestMutator、ResponseMutator インターフェース
• リクエストとレスポンス - リクエストオプションの使用ガイド