Golang的配置信息處理框架Viper

Viper

項目地址：https://github.com/spf13/viper

本文翻譯自該項目裏README.md文件中的內容

有不少Go語言項目用到了Viper框架，好比：

• Hugo
• EMC RexRay
• Imgur’s Incus
• Nanobox/Nanopack
• Docker Notary
• BloomApi
• doctl
• Clairctl

什麼是Viper

Viper是一個方便Go語言應用程序處理配置信息的庫。它能夠處理多種格式的配置。它支持的特性：

• 設置默認值
• 從JSON、TOML、YAML、HCL和Java properties文件中讀取配置數據
• 能夠監視配置文件的變更、從新讀取配置文件
• 從環境變量中讀取配置數據
• 從遠端配置系統中讀取數據，並監視它們（好比etcd、Consul）
• 從命令參數中讀物配置
• 從buffer中讀取
• 調用函數設置配置信息

爲何要使用Viper

在構建現代應用程序時，您沒必要擔憂配置文件格式; 你能夠專一於構建出色的軟件。
Viper 能夠作以下工做：

• 加載並解析JSON、TOML、YAML、HCL 或 Java properties 格式的配置文件
• 能夠爲各類配置項設置默認值
• 能夠在命令行中指定配置項來覆蓋配置值
• 提供了別名系統，能夠不破壞現有代碼來實現參數重命名
• 能夠很容易地分辨出用戶提供的命令行參數或配置文件與默認相同的區別

Viper讀取配置信息的優先級順序，從高到低，以下：

• 顯式調用Set函數
• 命令行參數
• 環境變量
• 配置文件
• key/value 存儲系統
• 默認值

Viper 的配置項的key不區分大小寫。

設置值

設置默認值

默認值不是必須的，若是配置文件、環境變量、遠程配置系統、命令行參數、Set函數都沒有指定時，默認值將起做用。
例子:

viper.SetDefault("ContentDir", "content")
viper.SetDefault("LayoutDir", "layouts")
viper.SetDefault("Taxonomies", map[string]string{"tag": "tags", "category": "categories"})

讀取配置文件

Viper支持JSON、TOML、YAML、HCL和Java properties文件。
Viper能夠搜索多個路徑，但目前單個Viper實例僅支持單個配置文件。
Viper默認不搜索任何路徑。
如下是如何使用Viper搜索和讀取配置文件的示例。
路徑不是必需的，但最好至少應提供一個路徑，以便找到一個配置文件。

viper.SetConfigName("config") //  設置配置文件名 (不帶後綴)
viper.AddConfigPath("/etc/appname/")   // 第一個搜索路徑
viper.AddConfigPath("$HOME/.appname")  // 能夠屢次調用添加路徑
viper.AddConfigPath(".")               // 好比添加當前目錄
err := viper.ReadInConfig() // 搜索路徑，並讀取配置數據
if err != nil {
    panic(fmt.Errorf("Fatal error config file: %s \n", err))
}

監視配置文件，從新讀取配置數據

Viper支持讓您的應用程序在運行時擁有讀取配置文件的能力。
須要從新啓動服務器以使配置生效的日子已經一去不復返了，由viper驅動的應用程序能夠在運行時讀取已更新的配置文件，而且不會錯過任何節拍。
只須要調用viper實例的WatchConfig函數，你也能夠指定一個回調函數來得到變更的通知。

viper.WatchConfig()
viper.OnConfigChange(func(e fsnotify.Event) {
    fmt.Println("Config file changed:", e.Name)
})

從 io.Reader 中讀取配置

Viper預先定義了許多配置源，例如文件、環境變量、命令行參數和遠程K / V存儲系統，但您並未受其約束。
您也能夠實現本身的配置源，並提供給viper。

viper.SetConfigType("yaml") // or viper.SetConfigType("YAML")

// any approach to require this configuration into your program.
var yamlExample = []byte(`
Hacker: true
name: steve
hobbies:
- skateboarding
- snowboarding
- go
clothing:
  jacket: leather
  trousers: denim
age: 35
eyes : brown
beard: true
`)

viper.ReadConfig(bytes.NewBuffer(yamlExample))

viper.Get("name") // 返回 "steve"

Set 調用

viper.Set("Verbose", true)
viper.Set("LogFile", LogFile)

註冊並使用別名

別名能夠實現多個key引用單個值。

viper.RegisterAlias("loud", "Verbose")

viper.Set("verbose", true) 
viper.Set("loud", true)   // 這兩句設置的都是同一個值

viper.GetBool("loud") // true
viper.GetBool("verbose") // true

從環境變量中讀取

Viper 徹底支持環境變量，這是的應用程序能夠開箱即用。
有四個和環境變量有關的方法：

• AutomaticEnv()
• BindEnv(string...) : error
• SetEnvPrefix(string)
• SetEnvKeyReplacer(string...) *strings.Replacer

注意，環境變量時區分大小寫的。

Viper提供了一種機制來確保Env變量是惟一的。經過SetEnvPrefix，在從環境變量讀取時會添加設置的前綴。BindEnv和AutomaticEnv都會使用到這個前綴。

BindEnv須要一個或兩個參數。第一個參數是鍵名，第二個參數是環境變量的名稱。環境變量的名稱區分大小寫。若是未提供ENV變量名稱，則Viper會自動假定該鍵名稱與ENV變量名稱匹配，而且ENV變量爲所有大寫。當您顯式提供ENV變量名稱時，它不會自動添加前綴。

使用ENV變量時要注意，當關聯後，每次訪問時都會讀取該ENV值。Viper在BindEnv調用時不讀取ENV值。

AutomaticEnv與SetEnvPrefix結合將會特別有用。當AutomaticEnv被調用時，任何viper.Get請求都會去獲取環境變量。環境變量名爲SetEnvPrefix設置的前綴，加上對應名稱的大寫。

SetEnvKeyReplacer容許你使用一個strings.Replacer對象來將配置名重寫爲Env名。若是你想在Get()中使用包含-的配置名 ，但但願對應的環境變量名包含_分隔符，就可使用該方法。使用它的一個例子能夠在項目中viper_test.go文件裏找到。
例子：

SetEnvPrefix("spf") // 將會自動轉爲大寫
BindEnv("id")

os.Setenv("SPF_ID", "13") // 一般經過系統環境變量來設置

id := Get("id") // 13

綁定命令行參數

Viper支持綁定pflags參數。
和BindEnv同樣，當綁定方法被調用時，該值沒有被獲取，而是在被訪問時獲取。這意味着應該儘早進行綁定，甚至是在init()函數中綁定。

利用BindPFlag()方法能夠綁定單個flag。
例子：

serverCmd.Flags().Int("port", 1138, "Port to run Application server on")
viper.BindPFlag("port", serverCmd.Flags().Lookup("port"))

你也能夠綁定已存在的pflag集合 (pflag.FlagSet):

pflag.Int("flagname", 1234, "help message for flagname")

pflag.Parse()
viper.BindPFlags(pflag.CommandLine)

i := viper.GetInt("flagname") // 經過viper從pflag中獲取值

使用pflag並不影響其餘庫使用標準庫中的flag。經過導入，pflag能夠接管經過標準庫的flag定義的參數。這是經過調用pflag包中的AddGoFlagSet()方法實現的。
例子：

package main

import (
    "flag"
    "github.com/spf13/pflag"
)

func main() {

    // using standard library "flag" package
    flag.Int("flagname", 1234, "help message for flagname")

    pflag.CommandLine.AddGoFlagSet(flag.CommandLine)
    pflag.Parse()
    viper.BindPFlags(pflag.CommandLine)

    i := viper.GetInt("flagname") // retrieve value from viper

    ...
}

Flag 接口

若是你不想使用pflag，Viper 提供了兩個接口來實現綁定其餘的flag系統。
使用 FlagValue 接口表明單個flag。下面是實現了該接口的簡單的例子：

type myFlag struct {}
func (f myFlag) HasChanged() bool { return false }
func (f myFlag) Name() string { return "my-flag-name" }
func (f myFlag) ValueString() string { return "my-flag-value" }
func (f myFlag) ValueType() string { return "string" }

一旦你實現了該接口，就能夠綁定它：

viper.BindFlagValue("my-flag-name", myFlag{})

使用 FlagValueSet 接口表明一組flag。下面是實現了該接口的簡單的例子：

type myFlagSet struct {
    flags []myFlag
}

func (f myFlagSet) VisitAll(fn func(FlagValue)) {
    for _, flag := range flags {
        fn(flag)
    }
}

一旦你實現了該接口，就能夠綁定它：

fSet := myFlagSet{
    flags: []myFlag{myFlag{}, myFlag{}},
}
viper.BindFlagValues("my-flags", fSet)

支持遠程 Key/Value 存儲

啓用該功能，須要導入viper/remot包：

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

Viper 能夠從例如etcd、Consul的遠程Key/Value存儲系統的一個路徑上，讀取一個配置字符串（JSON, TOML, YAML或HCL格式）。
這些值優先於默認值，但會被從磁盤文件、命令行flag、環境變量的配置所覆蓋。

Viper 使用 crypt 來從 K/V 存儲系統裏讀取配置，這意味着你能夠加密儲存你的配置信息，而且能夠自動解密配置信息。加密是可選的。

您能夠將遠程配置與本地配置結合使用，也能夠獨立使用。

crypt 有一個命令行工具能夠幫助你存儲配置信息到K/V存儲系統，crypt默認使用 http://127.0.0.1:4001 上的etcd。

$ go get github.com/xordataexchange/crypt/bin/crypt
$ crypt set -plaintext /config/hugo.json /Users/hugo/settings/config.json

確認你的值被設置：

$ crypt get -plaintext /config/hugo.json

有關crypt如何設置加密值或如何使用Consul的示例，請參閱文檔。

遠程 Key/Value 存儲例子 - 未加密的

viper.AddRemoteProvider("etcd", "http://127.0.0.1:4001","/config/hugo.json")
viper.SetConfigType("json") // 由於不知道格式，因此須要指定，支持的格式有"json"、"toml"、"yaml"、"yml"、"properties"、"props"、"prop"
err := viper.ReadRemoteConfig()

遠程 Key/Value 存儲例子 - 加密的

viper.AddSecureRemoteProvider("etcd","http://127.0.0.1:4001","/config/hugo.json","/etc/secrets/mykeyring.gpg")
viper.SetConfigType("json") // 由於不知道格式，因此須要指定，支持的格式有"json"、"toml"、"yaml"、"yml"、"properties"、"props"、"prop"
err := viper.ReadRemoteConfig()

監視etcd的變化 - 未加密的

// 您能夠建立一個新的viper實例
var runtime_viper = viper.New()

runtime_viper.AddRemoteProvider("etcd", "http://127.0.0.1:4001", "/config/hugo.yml")
runtime_viper.SetConfigType("yaml") // 由於不知道格式，因此須要指定，支持的格式有"json"、"toml"、"yaml"、"yml"、"properties"、"props"、"prop"

// 從遠程讀取配置
err := runtime_viper.ReadRemoteConfig()

// 解析配置到runtime_conf中
runtime_viper.Unmarshal(&runtime_conf)

// 經過一個goroutine遠程的配置變化
go func(){
    for {
        time.Sleep(time.Second * 5) // delay after each request

        // currently, only tested with etcd support
        err := runtime_viper.WatchRemoteConfig()
        if err != nil {
            log.Errorf("unable to read remote config: %v", err)
            continue
        }

            // 解析新的配置到一個結構體變量中，你也可使用channel實現一個信號通知的方式
        runtime_viper.Unmarshal(&runtime_conf)
    }
}()

獲取值

在Viper中，有一些根據值的類型獲取值的方法。存在一下方法：

• Get(key string) : interface{}
• GetBool(key string) : bool
• GetFloat64(key string) : float64
• GetInt(key string) : int
• GetString(key string) : string
• GetStringMap(key string) : map[string]interface{}
• GetStringMapString(key string) : map[string]string
• GetStringSlice(key string) : []string
• GetTime(key string) : time.Time
• GetDuration(key string) : time.Duration
• IsSet(key string) : bool

若是Get函數未找到值，則返回對應類型的一個零值。能夠經過 IsSet() 方法來檢測一個健是否存在。
例子:

viper.GetString("logfile") // Setting & Getting 不區分大小寫
if viper.GetBool("verbose") {
    fmt.Println("verbose enabled")
}

訪問嵌套鍵

訪問方法也接受嵌套的鍵。例如，若是加載瞭如下JSON文件：

{
    "host": {
        "address": "localhost",
        "port": 5799
    },
    "datastore": {
        "metric": {
            "host": "127.0.0.1",
            "port": 3099
        },
        "warehouse": {
            "host": "198.0.0.1",
            "port": 2112
        }
    }
}

Viper能夠經過.分隔符來訪問嵌套的字段：

GetString("datastore.metric.host") // (returns "127.0.0.1")

這遵照前面確立的優先規則; 會搜索路徑中全部配置，直到找到爲止。
例如，上面的文件，datastore.metric.host和 datastore.metric.port都已經定義（而且可能被覆蓋）。若是另外 datastore.metric.protocol的默認值，Viper也會找到它。

可是，若是datastore.metric值被覆蓋（經過標誌，環境變量，Set方法，...），則全部datastore.metric的子鍵將會未定義，它們被優先級更高的配置值所「遮蔽」。

最後，若是存在相匹配的嵌套鍵，則其值將被返回。例如：

{
    "datastore.metric.host": "0.0.0.0",
    "host": {
        "address": "localhost",
        "port": 5799
    },
    "datastore": {
        "metric": {
            "host": "127.0.0.1",
            "port": 3099
        },
        "warehouse": {
            "host": "198.0.0.1",
            "port": 2112
        }
    }
}

GetString("datastore.metric.host") // returns "0.0.0.0"

提取子樹配置

能夠從viper中提取子樹。例如, viper配置爲:

app:
  cache1:
    max-items: 100
    item-size: 64
  cache2:
    max-items: 200
    item-size: 80

執行後：

subv := viper.Sub("app.cache1")

subv 就表明：

max-items: 100
item-size: 64

假如咱們有以下函數：

func NewCache(cfg *Viper) *Cache {...}

它的功能是根據配置信息建立緩存緩存。如今很容易分別建立這兩個緩存：

cfg1 := viper.Sub("app.cache1")
cache1 := NewCache(cfg1)

cfg2 := viper.Sub("app.cache2")
cache2 := NewCache(cfg2)

解析配置

您還能夠選擇將全部或特定值解析到struct、map等。
有兩個方法能夠作到這一點：

• Unmarshal(rawVal interface{}) : error
• UnmarshalKey(key string, rawVal interface{}) : error

例如：

type config struct {
    Port int
    Name string
    PathMap string `mapstructure:"path_map"`
}

var C config

err := Unmarshal(&C)
if err != nil {
    t.Fatalf("unable to decode into struct, %v", err)
}

使用單個viper仍是多個viper

Viper隨時準備使用開箱即用。沒有任何配置或初始化也可使用Viper。因爲大多數應用程序都但願使用單個存儲中心進行配置，所以viper包提供了此功能。它相似於一個單例模式。

在上面的全部示例中，他們都演示瞭如何使用viper的單例風格的方式。

使用多個viper實例

您還能夠建立多不一樣的viper實例以供您的應用程序使用。每實例都有本身獨立的設置和配置值。每一個實例能夠從不一樣的配置文件，K/V存儲系統等讀取。viper包支持的全部函數也都有對應的viper實例方法。
例子：

x := viper.New()
y := viper.New()

x.SetDefault("ContentDir", "content")
y.SetDefault("ContentDir", "foobar")

//...

當使用多個viper實例時，用戶須要本身管理每一個實例。

問答

問：爲何不使用INI文件？

答：Ini文件很是糟糕。沒有標準格式，並且很難驗證。Viper設計使用JSON、TOML或YAML文件。若是有人真的想要添加此功能，項目的做者很樂意合併它。指定應用程序容許的格式很容易。

問：爲何叫「Viper」？

答：Viper是Cobra項目的同伴。雖然二者均可以徹底獨立運做，但它們一塊兒能夠爲您的應用程序作很是多的基礎工做。

問：爲何叫「Cobra」？答：還能爲commander取一個更好的名字嗎？