1. Wprowadzenie do Vipera

golang viper

Zrozumienie potrzeby rozwiązania konfiguracji w aplikacjach Go

Aby budować niezawodne i łatwe w utrzymaniu oprogramowanie, programiści muszą oddzielić konfigurację od logiki aplikacji. Pozwala to na dostosowywanie zachowania aplikacji bez konieczności zmian w kodzie aplikacji. Rozwiązanie konfiguracyjne umożliwia to oddzielenie poprzez ułatwienie zewnętrznego przechowywania danych konfiguracyjnych.

Aplikacje Go mogą znacznie skorzystać z takiego systemu, zwłaszcza w miarę wzrostu ich złożoności i konfrontacji z różnymi środowiskami wdrożeniowymi, takimi jak rozwój, staging i produkcja. Każde z tych środowisk może wymagać różnych ustawień dla połączeń z bazą danych, kluczy API, numerów portów i nie tylko. Zakodowanie tych wartości może być problematyczne i podatne na błędy, ponieważ prowadzi do utrzymania wielu ścieżek kodu dla różnych konfiguracji i zwiększa ryzyko ujawnienia danych poufnych.

Rozwiązanie konfiguracyjne, takie jak Viper, adresuje te problemy, zapewniając ujednolicone podejście obsługujące różnorodne potrzeby konfiguracyjne oraz formaty.

Przegląd Vipera i jego rola w zarządzaniu konfiguracjami

Viper to kompleksowa biblioteka konfiguracyjna dla aplikacji Go, mająca na celu być rozwiązaniem w przypadku wszystkich potrzeb konfiguracyjnych. Zgodnie z praktykami określonymi w Metodologii Dwunastu Czynników, która zachęca do przechowywania konfiguracji w środowisku, aby osiągnąć przenośność między środowiskami wykonawczymi.

Viper odgrywa kluczową rolę w zarządzaniu konfiguracjami poprzez:

  • Odczytywanie i deserializację plików konfiguracyjnych w różnych formatach, takich jak JSON, TOML, YAML, HCL i inne.
  • Nadpisywanie wartości konfiguracji zmiennymi środowiskowymi, co odpowiada zasadzie zewnętrznej konfiguracji.
  • Wiązanie i odczytywanie flag wiersza poleceń, umożliwiające dynamiczne ustawienie opcji konfiguracyjnych w trakcie wykonywania.
  • Umożliwianie ustawiania domyślnych wartości w aplikacji dla opcji konfiguracyjnych niepodanych z zewnątrz.
  • Obserwowanie zmian w plikach konfiguracyjnych i automatyczne przeładowywanie, co zapewnia elastyczność i zmniejsza czas przestoju związany ze zmianami konfiguracji.

2. Instalacja i Konfiguracja

Instalowanie Vipera za pomocą modułów Go

Aby dodać Vipera do projektu Go, upewnij się, że twój projekt już korzysta z modułów Go do zarządzania zależnościami. Jeśli już masz projekt Go, prawdopodobnie posiadasz plik go.mod w głównym katalogu projektu. Jeśli nie, możesz zainicjować moduły Go, wykonując poniższą komendę:

go mod init <nazwa-modułu>

Zastąp <nazwa-modułu> nazwą lub ścieżką twojego projektu. Gdy moduły Go zostaną zainicjowane w twoim projekcie, możesz dodać Vipera jako zależność:

go get github.com/spf13/viper

Ta komenda pobierze pakiet Vipera i zapisze jego wersję w pliku go.mod.

Inicjowanie Vipera w projekcie Go

Aby zacząć korzystać z Vipera w projekcie Go, musisz najpierw zaimportować pakiet, a następnie utworzyć nową instancję Vipera lub skorzystać z predefiniowanego singletona. Poniżej znajduje się przykład obu metod:

package main

import (
	"fmt"
	"github.com/spf13/viper"
)

func main() {
	// Korzystanie z singletona Vipera, który jest pre skonfigurowany i gotowy do użycia
	viper.SetDefault("nazwaSerwisu", "Mój Niesamowity Serwis")

	// Alternatywnie, tworzenie nowej instancji Vipera
	mójViper := viper.New()
	mójViper.SetDefault("nazwaSerwisu", "Mój Nowy Serwis")

	// Dostęp do wartości konfiguracji za pomocą singletona
	nazwaSerwisu := viper.GetString("nazwaSerwisu")
	fmt.Println("Nazwa Serwisu:", nazwaSerwisu)

	// Dostęp do wartości konfiguracji za pomocą nowej instancji
	nowaNazwaSerwisu := mójViper.GetString("nazwaSerwisu")
	fmt.Println("Nowa Nazwa Serwisu:", nowaNazwaSerwisu)
}

W powyższym kodzie, metoda SetDefault jest używana do zdefiniowania domyślnej wartości dla klucza konfiguracji. Metoda GetString pobiera wartość. Po uruchomieniu tego kodu, zostaną wyświetlone nazwy serwisów skonfigurowane za pomocą zarówno instancji singletona, jak i nowej instancji.

3. Odczytywanie i Zapisywanie Plików Konfiguracyjnych

Praca z plikami konfiguracyjnymi stanowi podstawową funkcję Vipera. Umożliwia to zewnętrzne przechowywanie konfiguracji aplikacji, co pozwala na aktualizację bez konieczności ponownego kompilowania kodu. Poniżej omówimy konfigurację różnych formatów oraz pokażemy, jak odczytywać i zapisywać do tych plików.

Konfigurowanie formatów plików (JSON, TOML, YAML, HCL, itp.)

Viper obsługuje kilka formatów konfiguracji, takich jak JSON, TOML, YAML, HCL, itp. Aby rozpocząć, należy ustawić nazwę i typ pliku konfiguracyjnego, którego ma poszukiwać Viper:

v := viper.New()

v.SetConfigName("app")  // Nazwa pliku konfiguracyjnego bez rozszerzenia
v.SetConfigType("yaml") // lub "json", "toml", "yml", "hcl", itp.

// Ścieżki wyszukiwania pliku konfiguracyjnego. Dodaj wiele ścieżek, jeśli lokalizacja pliku konfiguracyjnego się różni.
v.AddConfigPath("$HOME/.appconfig") // Typowa lokalizacja konfiguracji użytkownika w systemie UNIX
v.AddConfigPath("/etc/appconfig/")  // Ścieżka konfiguracji systemowej w systemie UNIX
v.AddConfigPath(".")                // Bieżący katalog

Odczytywanie i zapisywanie plików konfiguracyjnych

Gdy instancja Vipera wie, gdzie szukać plików konfiguracyjnych i czego szukać, możesz poprosić go o odczytanie konfiguracji:

if err := v.ReadInConfig(); err != nil {
    if _, ok := err.(viper.ConfigFileNotFoundError); ok {
        // Plik konfiguracyjny nie został znaleziony; można zignorować, jeśli jest to pożądane, lub inaczej obsłużyć
        log.Printf("Nie znaleziono pliku konfiguracyjnego. Używanie wartości domyślnych lub zmiennych środowiskowych.")
    } else {
        // Plik konfiguracyjny został znaleziony, ale wystąpił inny błąd
        log.Fatalf("Błąd odczytu pliku konfiguracyjnego, %s", err)
    }
}

Aby zapisać modyfikacje z powrotem do pliku konfiguracyjnego lub utworzyć nowy, Viper oferuje kilka metod. Oto jak zapisać bieżącą konfigurację do pliku:

err := v.WriteConfig() // Zapisuje bieżącą konfigurację w wcześniej zdefiniowanej ścieżce ustawionej przez `v.SetConfigName` i `v.AddConfigPath`
if err != nil {
    log.Fatalf("Błąd zapisu pliku konfiguracyjnego, %s", err)
}

Ustalanie domyślnych wartości konfiguracji

Wartości domyślne służą jako fallback w przypadku gdy klucz nie został ustawiony w pliku konfiguracyjnym lub zmiennych środowiskowych:

v.SetDefault("ContentDir", "content")
v.SetDefault("LogLevel", "debug")
v.SetDefault("Database.Port", 5432)

// Bardziej skomplikowana struktura danych dla wartości domyślnej
viper.SetDefault("Taxonomies", map[string]string{
    "tag":       "tags",
    "category":  "categories",
})

4. Zarządzanie zmiennymi środowiskowymi i flagami

Viper nie jest ograniczony tylko do plików konfiguracyjnych - może również zarządzać zmiennymi środowiskowymi i flagami wiersza poleceń, co jest szczególnie przydatne przy pracy z ustawieniami specyficznymi dla środowiska.

Wiązanie zmiennych środowiskowych i flag do Vipera

Wiązanie zmiennych środowiskowych:

v.AutomaticEnv() // Automatyczne wyszukiwanie kluczy zmiennych środowiskowych, które pasują do kluczy Vipera

v.SetEnvPrefix("APP") // Prefiks dla zmiennych środowiskowych, aby odróżnić je od innych
v.BindEnv("port")     // Wiązanie zmiennej środowiskowej PORT (np. APP_PORT)

// Możesz także dopasować zmienne środowiskowe o różnych nazwach do kluczy w aplikacji
v.BindEnv("database_url", "DB_URL") // W ten sposób Viper będzie używał wartości zmiennej środowiskowej DB_URL jako klucza "database_url" w konfiguracji

Wiązanie flag za pomocą pflag, pakietu Go do parsowania flag:

var port int

// Definicja flagi za pomocą pflag
pflag.IntVarP(&port, "port", "p", 808, "Port dla aplikacji")

// Wiązanie flagi do klucza Vipera
pflag.Parse()
if err := v.BindPFlag("port", pflag.Lookup("port")); err != nil {
    log.Fatalf("Błąd wiązania flagi do klucza, %s", err)
}

Obsługa konfiguracji specyficznej dla środowiska

Aplikacja często musi działać inaczej w różnych środowiskach (rozwój, staging, produkcja, itp.). Viper może pobierać konfiguracje ze zmiennych środowiskowych, które mogą nadpisywać ustawienia w pliku konfiguracyjnym, pozwalając na konfiguracje specyficzne dla środowiska:

v.SetConfigName("config") // Domyślna nazwa pliku konfiguracyjnego

// Konfiguracja może być nadpisywana przez zmienne środowiskowe
// z prefiksem APP i resztą klucza w dużej literze
v.SetEnvPrefix("APP")
v.AutomaticEnv()

// W środowisku produkcyjnym możesz użyć zmiennej środowiskowej APP_PORT, aby nadpisać domyślny port
fmt.Println(v.GetString("port")) // Wynik będzie wartością zmiennej środowiskowej APP_PORT, jeśli jest ustawiona, w przeciwnym razie wartością z pliku konfiguracyjnego lub domyślną

Pamiętaj, aby w razie potrzeby obsłużyć różnice między środowiskami w kodzie aplikacji na podstawie wczytanych konfiguracji przez Vipera.

5. Obsługa zdalnego magazynu kluczy/wartości

Viper zapewnia solidne wsparcie dla zarządzania konfiguracją aplikacji przy użyciu zdalnych magazynów kluczy/wartości, takich jak etcd, Consul czy Firestore. Pozwala to na scentralizowane i dynamiczne aktualizacje konfiguracji w systemach rozproszonych. Ponadto Viper umożliwia bezpieczne zarządzanie wrażliwą konfiguracją poprzez szyfrowanie.

Integracja Vipera z zdalnymi magazynami kluczy/wartości (etcd, Consul, Firestore, itp.)

Aby zacząć korzystać z Vipera z zdalnymi magazynami kluczy/wartości, musisz wykonać puste importowanie pakietu viper/remote w aplikacji Go:

import _ "github.com/spf13/viper/remote"

Przyjrzyjmy się przykładowi integracji z etcd:

import (
    "log"

    "github.com/spf13/viper"
    _ "github.com/spf13/viper/remote"
)

func initRemoteConfig() {
    viper.SetConfigType("json") // Ustaw typ pliku konfiguracyjnego zdalnego
    viper.AddRemoteProvider("etcd", "http://127...1:4001", "/config/myapp.json")
  
    err := viper.ReadRemoteConfig() // Próba odczytania zdalnej konfiguracji
    if err != nil {
        log.Fatalf("Błąd odczytu zdalnej konfiguracji: %v", err)
    }
  
    log.Println("Pomyślnie odczytano zdalną konfigurację")
}

func main() {
    initRemoteConfig()
    // Tutaj umieść logikę aplikacji
}

W tym przykładzie Viper łączy się z serwerem etcd działającym pod adresem http://127...1:4001 i odczytuje konfigurację znajdującą się pod ścieżką /config/myapp.json. Przy pracy z innymi magazynami takimi jak Consul, zamień "etcd" na "consul" i dostosuj parametry specyficzne dla dostawcy.

Zarządzanie zaszyfrowanymi konfiguracjami

Wrażliwe konfiguracje, takie jak klucze API czy dane uwierzytelniające bazy danych, nie powinny być przechowywane w postaci zwykłego tekstu. Viper pozwala przechowywać zaszyfrowane konfiguracje w magazynie kluczy/wartości i deszyfrować je w aplikacji.

Aby skorzystać z tej funkcji, upewnij się, że zaszyfrowane ustawienia są przechowywane w magazynie kluczy/wartości, a następnie skorzystaj z AddSecureRemoteProvider Vipera. Oto przykład wykorzystania tego z etcd:

import (
    "log"

    "github.com/spf13/viper"
    _ "github.com/spf13/viper/remote"
)

func initSecureRemoteConfig() {
    const secretKeyring = "/ścieżka/do/sekretnego/keyring.gpg" // Ścieżka do pliku z pierścieniem kluczy

    viper.SetConfigType("json")
    viper.AddSecureRemoteProvider("etcd", "http://127...1:4001", "/config/myapp.json", secretKeyring)
  
    err := viper.ReadRemoteConfig()
    if err != nil {
        log.Fatalf("Nie można odczytać zdalnej konfiguracji: %v", err)
    }

    log.Println("Pomyślnie odczytano i odszyfrowano zdalną konfigurację")
}

func main() {
    initSecureRemoteConfig()
    // Tutaj umieść logikę aplikacji
}

W powyższym przykładzie użyto AddSecureRemoteProvider, określając ścieżkę do pierścienia GPG zawierającego klucze niezbędne do odszyfrowania.

6. Obserwowanie i Obsługa Zmian Konfiguracji

Jedną z potężnych funkcji Vipera jest zdolność do monitorowania i reagowania na zmiany konfiguracji w czasie rzeczywistym, bez konieczności ponownego uruchamiania aplikacji.

Monitorowanie Zmian Konfiguracji i Ponowne Odczytywanie Konfiguracji

Viper korzysta z pakietu fsnotify do obserwowania zmian w pliku konfiguracyjnym. Możesz skonfigurować obserwatora, aby wyzwalano zdarzenia za każdym razem, gdy plik konfiguracyjny się zmieni:

import (
    "log"

    "github.com/fsnotify/fsnotify"
    "github.com/spf13/viper"
)

func watchConfig() {
    viper.WatchConfig()
    viper.OnConfigChange(func(e fsnotify.Event) {
        log.Printf("Zmieniono plik konfiguracyjny: %s", e.Name)
        // Tutaj możesz odczytać zaktualizowaną konfigurację, jeśli to konieczne
        // Wykonaj dowolną akcję, taką jak ponowna inicjalizacja usług czy aktualizacja zmiennych
    })
}

func main() {
    viper.SetConfigName("myapp")
    viper.AddConfigPath(".")
    err := viper.ReadInConfig()
    if err != nil {
        log.Fatalf("Błąd odczytu pliku konfiguracyjnego, %s", err)
    }

    watchConfig()
    // Tutaj umieść logikę aplikacji
}

Wyzwalacze do Aktualizacji Konfiguracji w Działającej Aplikacji

W działającej aplikacji możesz chcieć aktualizować konfiguracje w odpowiedzi na różne wyzwalacze, takie jak sygnał, zadanie oparte na czasie lub żądanie interfejsu API. Możesz tak skonstruować swoją aplikację, by odświeżała swój wewnętrzny stan na podstawie ponownego odczytu konfiguracji przez Vipera:

import (
    "os"
    "os/signal"
    "syscall"
    "time"
    "log"

    "github.com/spf13/viper"
)

func setupSignalHandler() {
    signalChannel := make(chan os.Signal, 1)
    signal.Notify(signalChannel, syscall.SIGHUP) // Nasłuchiwanie sygnału SIGHUP

    go func() {
        for {
            sig := <-signalChannel
            if sig == syscall.SIGHUP {
                log.Println("Otrzymano sygnał SIGHUP. Ponowne wczytywanie konfiguracji...")
                err := viper.ReadInConfig() // Ponowne odczytanie konfiguracji
                if err != nil {
                    log.Printf("Błąd ponownego odczytu konfiguracji: %s", err)
                } else {
                    log.Println("Konfiguracja została pomyślnie ponownie wczytana.")
                    // Przestaw swoją aplikację na nową konfigurację tutaj
                }
            }
        }
    }()
}

func main() {
    viper.SetConfigName("mojaaplikacja")
    viper.AddConfigPath(".")
    err := viper.ReadInConfig()
    if err != nil {
        log.Fatalf("Błąd odczytu pliku konfiguracyjnego: %s", err)
    }

    setupSignalHandler()
    for {
        // Główna logika aplikacji
        time.Sleep(10 * time.Second) // Symulowanie pracy
    }
}

W tym przykładzie konfigurujemy obsługę sygnału w celu nasłuchiwania sygnału SIGHUP. Po otrzymaniu sygnału Viper ponownie wczytuje plik konfiguracyjny, a aplikacja powinna następnie zaktualizować konfiguracje lub stan zgodnie z potrzebami.

Zawsze pamiętaj, aby przetestować te konfiguracje, aby upewnić się, że Twoja aplikacja może sprawnie obsłużyć dynamiczne aktualizacje.