Доменный клиент

Доменный клиент обеспечивает управление запросами для определённого домена, автоматически поддерживая Cookie и заголовки.

NewDomain

func NewDomain(baseURL string, config ...*Config) (DomainClienter, error)

Создаёт клиент с областью действия домена. Cookie автоматически включены.

// С конфигурацией по умолчанию
dc, err := httpc.NewDomain("https://api.example.com")
if err != nil {
    log.Fatal(err)
}
defer dc.Close()

// С пользовательской конфигурацией
cfg := httpc.DefaultConfig()
cfg.Timeouts.Request = 60 * time.Second
dc, err := httpc.NewDomain("https://api.example.com", cfg)
if err != nil {
    log.Fatal(err)
}
defer dc.Close()

Описание параметров:

Параметр	Тип	Описание
baseURL	string	Базовый URL (должен содержать scheme и host)
config	...*Config	Необязательная конфигурация, без передачи используется DefaultConfig()

Возвращает: интерфейс DomainClienter (не конкретный тип *DomainClient).

HTTP-методы

Все методы принимают относительные пути или абсолютные URL:

// Относительный путь: автоматически объединяется с baseURL
result, err := dc.Get("/users")
result, err := dc.Post("/users", httpc.WithJSON(data))
result, err := dc.Put("/users/1", httpc.WithJSON(data))
result, err := dc.Patch("/users/1", httpc.WithJSON(data))
result, err := dc.Delete("/users/1")
result, err := dc.Head("/users/1")
result, err := dc.Options("/users")

// Абсолютный URL: используется напрямую
result, err := dc.Get("https://other-api.com/data")

Request

result, err := dc.Request(ctx, "GET", "/users", options...)

Универсальный метод запроса с контекстом, поддерживающий управление таймаутом и отменой.

Опции запроса применяются дважды

Доменный клиент применяет опции запроса дважды внутри — один раз для захвата состояния сессии (Cookie, заголовки), второй раз для самого запроса. Избегайте опций с побочными эффектами (например, счётчиков, nonce); при необходимости таких опций используйте базовый Client.

Методы загрузки

func (dc *DomainClient) Download(ctx context.Context, path string, cfg *DownloadConfig, options ...RequestOption) (*DownloadResult, error)

Загружает файл в cfg.FilePath, при этом path присоединяется к baseURL. Сигнатура совпадает с пакетной Download и Client.Download — Download является единым каноническим входом для загрузки во всех трёх случаях. cfg не может быть nil, cfg.FilePath должен быть задан (иначе возвращается ErrEmptyFilePath).

cfg := httpc.DefaultDownloadConfig()
cfg.FilePath = "/tmp/report.pdf"
cfg.Overwrite = true

result, err := dc.Download(ctx, "/files/report.pdf", cfg)

Cookie ответа при загрузке автоматически фиксируются в сессии.

Методы доступа

dc.URL()      // string - базовый URL
dc.Domain()   // string - домен (без порта)
dc.Session()  // *SessionManager - базовый менеджер сессий
dc.Close()    // error - закрытие клиента и освобождение ресурсов

Правила объединения URL

Входной путь	Результат объединения (baseURL = https://api.example.com/v1)
/users	https://api.example.com/v1/users
users	https://api.example.com/v1/users
/users?page=1	https://api.example.com/v1/users?page=1
https://other.com/api	https://other.com/api (абсолютный URL)

WARNING

Только пути с префиксами http:// и https:// распознаются как абсолютные URL; другие протоколы (например, ftp://) не распознаются как абсолютные и присоединяются как относительные пути, что обычно приводит к ошибке запроса.

Интерфейс DomainClienter

type DomainClienter interface {
    Client

    URL() string
    Domain() string

    SetHeader(key, value string) error
    SetHeaders(headers map[string]string) error
    DeleteHeader(key string)
    ClearHeaders()
    GetHeaders() map[string]string

    SetCookie(cookie *http.Cookie) error
    SetCookies(cookies []*http.Cookie) error
    DeleteCookie(name string)
    ClearCookies()
    GetCookies() []*http.Cookie
    GetCookie(name string) *http.Cookie

    Session() *SessionManager
}

Рекомендуется использовать интерфейс, а не конкретный тип, для удобства тестирования и замены реализации.

См. также

• Управление сессиями - подробный справочник по SessionManager
• Доменный клиент и сессии - руководство по использованию
• Интерфейсы - справочник по интерфейсам Client, Doer