3、使用viper添加配置文件解析功能

因为配置几乎是每个服务都需要的能力，所以，在使用cobra开发完二进制命令的主题框架后，还需要实现配置文件解析能力。

go项目开发中配置解析源有多种，例如：命令行参数、环境变量、配置文件等。但是推荐的配置解析源是配置文件，因为配置文件更易维护。

Go社区提供了很多优秀的Go包可以读取yaml、json等格式的配置文件，但是目前使用最多的是spf13/viper包

配置文件解析思路

在Go项目开发中，服务的配置能力一般通过以下2步实现：

1. 解析配置文件
2. 读取配置

其中配置文件考虑到易读性，通常的使用格式更加易读的YAML格式。并且使用spf13/viper包来解析。

所以，可以通过设置钩子函数，来让程序运行时加载并读取配置。更新cmd/fg-apiserver/app/server.go文件

package app

import (
	"encoding/json"
	"fmt"
	"github.com/spf13/cobra"
	"github.com/spf13/viper"
	"gitlab.com/onexstack/fastgo/cmd/fg-apiserver/app/options"
)

var configFile string // 配置文件路径

func NewFastGoCommand() *cobra.Command {
	// 创建默认的应用命令行选项
	opts := options.NewServerOptions()

	cmd := &cobra.Command{
		Use:   "fg-apiserver",
		Short: "A very lightweight full go project",
		Long: `A very lightweight full go project, designed to help beginners quickly
		learn Go project development.`,
		SilenceUsage: true,
		RunE: func(cmd *cobra.Command, args []string) error {
			// 将viper中的配置解析到选项opts变量中
			if err := viper.Unmarshal(opts); err != nil {
				return err
			}
			fmt.Println("Hello FastGo!")
			// 对命令行选项进行校验
			if err := opts.Validate(); err != nil {
				return err
			}
			fmt.Printf("Read MySQL host from Viper: %s\n\n", viper.GetString("mysql.host"))
			jsonData, _ := json.MarshalIndent(opts, "", "  ")
			fmt.Println(string(jsonData))

			return nil
		},
		// 设置命令运行时的参数检查，不需要指定命令行参数。例如：./fg-apiserver param1 param2
		Args: cobra.NoArgs,
	}
	// 初始化配置函数，在每个命令运行时调用
	cobra.OnInitialize(onInitialize)

	// cobra 支持持久性标志(PersistentFlag)，该标志可用于它所分配的命令以及该命令下的每个子命令
	// 推荐使用配置文件来配置应用，便于管理配置项
	cmd.PersistentFlags().StringVarP(&configFile, "config", "c", filePath(), "Path to the fg-apiserver configuration file.")
	return cmd
}

上面代码会通过options.NewServerOptions()函数调用，创建了一个配置结构体变量 opts。在RunE方法中，通过viper.Unmarshal(opts) 函数调用，将viper读取配置文件后的配置内容解码到opts配置结构体变量中。

之后调用opts的 Validate方法，来判断配置项是否合法。并使用下面两种方法读取并打印配置项内容：

• 使用viper.GetString读取指定的配置项。viper.Get<Type> 是viper提供的方法可以根据传入的key，来读取配置项的值。key支持层级，例如：mysql.addr ，标识yaml中的以下配置

mysql:
   addr: 127.0.0.1:3306

• 通过配置结构体变量opts 来使用: opts.MySQLOptions.Username
• 使用json.MarshalIndent 读取所有的配置项并打印

上面代码通过cobra.OnInitialize(onInitialize) 调用，指定了程序启动时调用的钩子函数onInitialize ，该函数用来加载并读取配置。

通过下面代码行来给命令程序添加--config / -c选项

cmd.PersistentFlags().StringVarP(&configFile, "config", "c", filePath(), "Path to the fg-apiserver configuration file.")

--config / -c 选项用来指定配置文件路径，并将配置文件的路径保存在configFile变量中，给onInitialize 函数加载解析。

onInitialize 钩子函数定义在cmd/fg-apiserver/app/config.go 文件中

package app

import (
	"github.com/spf13/cobra"
	"github.com/spf13/viper"
	"os"
	"path/filepath"
	"strings"
)

const (
	// defaultHomeDir 定义放置 fastgo 服务配置的默认目录.
	defaultHomeDir = ".fastgo"

	// defaultConfigName 指定 fastgo 服务的默认配置文件名.
	defaultConfigName = "fg-apiserver.yaml"
)

// onInitialize 设置需要读取的配置文件名、环境变量，并将其内容读取到 viper 中.
func onInitialize() {
	if configFile != "" {
		// 从命令行选项指定的配置文件中读取
		viper.SetConfigFile(configFile)
	} else {
		// 使用默认配置文件路径和名称
		for _, dir := range searchDirs() {
			// 将dir目录加入到配置文件的搜索路径
			viper.AddConfigPath(dir)
		}
		// 设置配置文件格式问YAML
		viper.SetConfigType("yaml")
		// 配置文件名称（没有文件扩展名）
		viper.SetConfigName(defaultConfigName)
	}
	// 读取环境变量并设置前缀
	setupEnvironmentVariables()
	// 读取配置文件.如果指定了配置文件名，则使用指定的配置文件，否则在注册的搜索路径中搜索
	_ = viper.ReadInConfig()
}

// 返回默认的配置文件搜索目录
func searchDirs() []string {
	// 获取用户主目录
	homeDir, err := os.UserHomeDir()
	// 如果获取用户主目录失败，则打印错误信息并退出程序
	cobra.CheckErr(err)
	return []string{filepath.Join(homeDir, defaultHomeDir), "."}
}

// setupEnvironmentVariables 配置环境变量规则.
func setupEnvironmentVariables() {
	// 允许 viper 自动匹配环境变量
	viper.AutomaticEnv()
	// 设置环境变量前缀
	viper.SetEnvPrefix("FASTGO")
	// 替换环境变量 key 中的分隔符 '.' 和 '-' 为 '_'
	replacer := strings.NewReplacer(".", "_", "-", "_")
	viper.SetEnvKeyReplacer(replacer)
}

// filePath 获取默认配置文件的完整路径.
func filePath() string {
	home, err := os.UserHomeDir()
	// 如果不能获取用户主目录，则记录错误并返回空路径
	cobra.CheckErr(err)
	return filepath.Join(home, defaultHomeDir, defaultConfigName)
}

创建配置文件结构体

可以通过viper.Get<Type> 来访问配置项的值，也可以通过配置项结构体变量来引用配置项的值，例如opts.MySQLOptions.Username 。

实际开发中建议通过 opts.MySQLOptions.Username 方式来访问配置项的值，更易维护。

配置项结构体位于cmd/fg-apiserver/app/options/options.go 文件中，放在这里是因为配置项结构体的创建、校验方法代码量较大，为了提高可维护性，统一保存在cmd/fg-apiserver/app/options 目录中

cmd/fg-apiserver/app/options/options.go 内容如下

package options

import (
	"fmt"
	"net"
	"strconv"
	"time"
)

type MySQLOption struct {
	Addr                  string        `json:"addr,omitempty" mapstructure:"addr"`
	Username              string        `json:"username,omitempty" mapstructure:"username"`
	Password              string        `json:"-" mapstructure:"password"`
	Database              string        `json:"database" mapstructure:"database"`
	MaxIdleConnections    int           `json:"max-idle-connections,omitempty" mapstructure:"max-idle-connections,omitempty"`
	MaxOpenConnections    int           `json:"max-open-connections,omitempty" mapstructure:"max-open-connections"`
	MaxConnectionLifeTime time.Duration `json:"max-connection-life-time,omitempty" mapstructure:"max-connection-life-time"`
}

func NewMYSQLOption() *MySQLOption {
	return &MySQLOption{
		Addr:                  "127.0.0.1:3306",
		Username:              "onex",
		Password:              "onex",
		Database:              "onex",
		MaxIdleConnections:    100,
		MaxOpenConnections:    100,
		MaxConnectionLifeTime: time.Duration(10) * time.Second,
	}
}

type ServerOptions struct {
	MySQLOptions *MySQLOption `json:"mysql" mapstructure:"mysql"`
}

// NewServerOptions 创建带有默认值的 ServerOptions 实例.
func NewServerOptions() *ServerOptions {
	return &ServerOptions{
		MySQLOptions: NewMYSQLOption(),
	}
}
func (o *ServerOptions) Validate() error {
	// 验证MySQL地址格式
	if o.MySQLOptions.Addr == "" {
		return fmt.Errorf("MySQL server address cannot be empty")
	}
	// 检查地址格式是否为host:port
	host, portStr, err := net.SplitHostPort(o.MySQLOptions.Addr)
	if err != nil {
		return fmt.Errorf("Invalid MySQL address format '%s': %w", o.MySQLOptions.Addr, err)
	}
	// 验证端口是否为数字
	port, err := strconv.Atoi(portStr)
	if err != nil || port < 1 || port > 65535 {
		return fmt.Errorf("Invalid MySQL port: %s", portStr)
	}
	// 验证主机名是否为空
	if host == "" {
		return fmt.Errorf("MySQL hostname cannot be empty")
	}

	// 验证凭据和数据库名
	if o.MySQLOptions.Username == "" {
		return fmt.Errorf("MySQL username cannot be empty")
	}

	if o.MySQLOptions.Password == "" {
		return fmt.Errorf("MySQL password cannot be empty")
	}

	if o.MySQLOptions.Database == "" {
		return fmt.Errorf("MySQL database name cannot be empty")
	}

	// 验证连接池参数
	if o.MySQLOptions.MaxIdleConnections <= 0 {
		return fmt.Errorf("MySQL max idle connections must be greater than 0")
	}

	if o.MySQLOptions.MaxOpenConnections <= 0 {
		return fmt.Errorf("MySQL max open connections must be greater than 0")
	}

	if o.MySQLOptions.MaxIdleConnections > o.MySQLOptions.MaxOpenConnections {
		return fmt.Errorf("MySQL max idle connections cannot be greater than max open connections")
	}

	if o.MySQLOptions.MaxConnectionLifeTime <= 0 {
		return fmt.Errorf("MySQL max connection lifetime must be greater than 0")
	}

	return nil
}

上述代码定义ServerOptions类型的结构体变量，该结构体变量保存了fg-apiserver服务需要用到的所有配置项，例如：MySQLOptions。每个配置项都有mapstructure 标签，非常重要，用来指定结构体字段对应YAML中的同名键，例如MySQLOptions结构体变量中的Addr字段对应了以下YAML键(mysql.addr)

mysql:
  addr: 127.0.0.1:3306

上面代码还提供了NewServerOptions函数，用来快速创建一个带有默认值的*ServerOptions类型的结构体，通过该函数创建一个具有默认值的配置变量opts，再更新opts中的字段值有以下优点：

• 可以便捷创建一个带有默认值的结构体变量，变量中的值都是推荐、可用的值
• 开发者可以根据需要只更新需要的配置项，其他配置项使用默认的值，可以提高配置应用的效率

*ServerOptions 结构体类型的Validate函数用来校验配置项的值是否合法，避免非常配置项带来的程序异常。

Validate函数中的校验逻辑可以借助ai生成。

执行命令，编译并运行程序

(base) dujie@MacBook-Pro fastgo % go build -v -o _output/fg-apiserver cmd/fg-apiserver/main.go
gitlab.com/onexstack/fastgo/cmd/fg-apiserver/app
command-line-arguments
(base) dujie@MacBook-Pro fastgo % ./_output/fg-apiserver -c configs/fg-apiserver.yaml         
/Users/dujie/.fastgo/fg-apiserver.yaml
configs/fg-apiserver.yaml
******
Hello FastGo!
Read MySQL host from Viper: 127.0.0.1:3306

fastgo1234
{
  "mysql": {
    "addr": "127.0.0.1:3306",
    "username": "fastgo",
    "database": "fastgo",
    "max-idle-connections": 100,
    "max-open-connections": 100,
    "max-connection-life-time": 10000000000
  }
}