Instalasi dan Memulai

Heimdall didistribusikan sebagai modul Go dengan path github.com/gojek/heimdall/v8, dan modul ini mendeklarasikan go 1.25 sebagai versi minimum serta bergantung pada github.com/gojek/hystrix-go/hystrix v1.0.0 dan github.com/stretchr/testify v1.11.1. go.mod:1-8¹

Halaman ini membahas pemasangan modul, import paket, dan satu request pertama yang dijalankan lewat httpclient.NewClient sampai Do. Rincian setiap option dibahas di Option pada httpclient, sedangkan mesin pengulangan di dalam Do dibahas di Siklus Request dan Retry.

Memasang modul lewat go get

Modul dipasang dengan satu perintah berikut, dikutip apa adanya dari README: README.md:33-36²

go get -u github.com/gojek/heimdall/v8

Setelah modul masuk ke go.mod aplikasi, tambahkan import ke berkas .go. Dua paket yang paling sering dipakai adalah httpclient untuk klien biasa dan hystrix untuk klien ber-circuit breaker. README.md:40-46³

import "github.com/gojek/heimdall/v8/httpclient"

Request pertama dengan httpclient.NewClient

NewClient menerima nol atau lebih Option, menyiapkan nilai default terlebih dahulu, lalu menjalankan setiap Option secara berurutan dan menutupnya dengan updateHTTPTimeout. httpclient/client.go:34-49⁶

Pola paling singkat yang ada di contoh repository: buat klien dengan WithHTTPTimeout, set WithRetryCount dan WithRetrier bila perlu pengulangan, lalu panggil Get dengan url dan http.Header. examples/client.go:21-29⁷

timeout := 100 * time.Millisecond

httpClient := httpclient.NewClient(
	httpclient.WithHTTPTimeout(timeout),
	httpclient.WithRetryCount(2),
	httpclient.WithRetrier(heimdall.NewRetrier(heimdall.NewConstantBackoff(10*time.Millisecond, 50*time.Millisecond))),
)

response, err := httpClient.Get(baseURL, headers)

Get hanya membungkus http.NewRequest dengan http.MethodGet, memasang headers ke request.Header, lalu menyerahkan seluruh pekerjaan ke Do. httpclient/client.go:56-67⁸ Karena itu Get dan Post menghasilkan objek *http.Response standar, dan isi body dibaca dengan io.ReadAll. README.md:62-65⁹

Bila *http.Request sudah disusun sendiri, panggil Do langsung; metode ini mengikuti antarmuka http.Do dan tetap mengembalikan *http.Response. README.md:67-76¹⁰ Kedua jalur itu memenuhi kontrak heimdall.Client yang berisi Get, Post, Put, Patch, Delete, Do, dan AddPlugin, serta kontrak heimdall.Doer yang hanya butuh Do(*http.Request) (*http.Response, error). client.go:8-23¹¹

⚠️ Body response wajib ditutup. Contoh di repository memakai defer response.Body.Close() tepat setelah error diperiksa, sebelum body dibaca. examples/client.go:34¹²

Perjalanan satu request dari NewClient ke Do

Diagram berikut menunjukkan urutan pemanggilan pada jalur tanpa retry: NewClient menyiapkan struct Client, menerapkan option, lalu Do meneruskan request ke Doer di dalamnya.

sequenceDiagram
  participant App as Aplikasi
  participant C as httpclient.Client
  participant O as Option
  participant D as heimdall.Doer
  App->>C: NewClient(opts ...Option)
  C->>C: client=http.Client{Timeout: 30s}, retrier=NewNoRetrier()
  loop setiap Option
    C->>O: opt(&client)
    O-->>C: set timeout / retryCount / retrier
  end
  C->>C: updateHTTPTimeout()
  C-->>App: *Client
  App->>C: Do(request)
  C->>D: c.client.Do(request)
  D-->>C: *http.Response, error
  C-->>App: response, BuildMultiError(errs)
%% fig: Urutan pemanggilan dari NewClient sampai Do
%% desc: Aplikasi membuat Client lewat opsi, lalu Do meneruskan request ke Doer di dalamnya dan mengembalikan response beserta gabungan error.

Nilai balik Do adalah response bersama internal.BuildMultiError(errs), sehingga kegagalan dari beberapa percobaan tetap terbawa sebagai satu error gabungan. httpclient/client.go:122-192¹³

Nilai default dan cara option menimpanya

Tanpa option apa pun, klien tetap bisa dipakai karena struct Client sudah diisi di dalam NewClient: client berupa *http.Client dengan Timeout 30 detik, retryCount bernilai 0, dan retrier berupa heimdall.NewNoRetrier(). httpclient/client.go:34-49⁶

graph LR
  DH["defaultHTTPTimeout = 30s"] --> HC["http.Client.Timeout"]
  DR["defaultRetryCount = 0"] --> RC["Client.retryCount"]
  NR["heimdall.NewNoRetrier"] --> RT["Client.retrier"]
  OH["WithHTTPTimeout"] --> HC
  OC["WithRetryCount"] --> RC
  OR["WithRetrier"] --> RT
  style DH fill:#f59e0b,color:#000
  style DR fill:#f59e0b,color:#000
  style NR fill:#f59e0b,color:#000
  style OH fill:#f59e0b,color:#000
  style OC fill:#f59e0b,color:#000
  style OR fill:#f59e0b,color:#000
  style HC fill:#8b5cf6,color:#fff
  style RC fill:#8b5cf6,color:#fff
  style RT fill:#8b5cf6,color:#fff
%% fig: Sumber nilai default dan option pada struct Client
%% desc: Tiga field Client diisi nilai default di NewClient, dan setiap option menimpa field yang sama.

⚠️ updateHTTPTimeout hanya mengubah Timeout bila c.client bertipe *http.Client. Ketika WithHTTPClient diberi Doer lain, seperti myHTTPClient pada contoh, WithHTTPTimeout tidak menyentuh timeout di dalam Doer tersebut; timeout harus diatur sendiri di sana. httpclient/client.go:222-230²¹ Nilai timeout yang dipakai adalah nilai terakhir yang dipasang, karena WithHTTPTimeout menyimpan pointer ke argumennya dan langsung memanggil updateHTTPTimeout. httpclient/options.go:14-21¹⁶

Untuk klien yang dilapisi circuit breaker, gunakan hystrix.NewClient dengan set option tersendiri; pembahasannya ada di Klien Circuit Breaker.