13 KiB
go-zero 配置概述 概述 go-zero 提供了一个强大的 conf 包用于加载配置。我们目前支持的 yaml, json, toml 3 种格式的配置文件，go-zero 通过文件后缀会自行加载对应的文件格式。
如何使用 我们使用 github.com/zeromicro/go-zero/core/conf conf 包进行配置的加载。
第一步我们会定义我们的配置结构体，其中定义我们所有需要的依赖。
第二步接着根据配置编写我们对应格式的配置文件。
第三步通过 conf.MustLoad 加载配置。
具体使用例子:
main.go config.yaml package main
import ( "flag"
"github.com/zeromicro/go-zero/core/conf"
)
type Config struct {
Host string json:",default=0.0.0.0"
Port int
}
var f = flag.String("f", "config.yaml", "config file")
func main() { flag.Parse() var c Config conf.MustLoad(*f, &c) println(c.Host) } 我们一般会在程序启动的时候进行配置的加载，同时我们一般也需要定义我们配置所需要的结构体， 在 go-zero 中，我们推荐将所有服务依赖都定义在 config 中，这样以后配置根据 config 就可以查找出所有的依赖。
我们使用 func MustLoad(path string, v interface{}, opts ...Option) 进行加载配置，path 为配置的路径，v 为结构体。 这个方法会完成配置的加载，如果配置加载失败，整个程序会 fatal 停止掉。
当然我们也提供了其他的加载方式，例如：
func Load(file string, v interface{}, opts ...Option) error 其他格式的配置文件 我们目前支持的配置格式如下：
json yaml | yml toml 我们程序会自动通过文件后缀进行对应格式的加载。
当然我们在 conf 包中也提供了对应格式二进制数据加载的方法：
func LoadFromJsonBytes(content []byte, v interface{}) error
func LoadFromTomlBytes(content []byte, v interface{}) error
func LoadFromYamlBytes(content []byte, v interface{}) error 简单示例：
text := []byte(a: foo B: bar)
var val struct { A string B string } _ = LoadFromYamlBytes(text, &val) 注意 对于有些需要自定义 tag 的，为了方便统一，我们目前所有 tag 均为 json tag。
大小写不敏感 conf 目前已经默认自动支持 key 大小写不敏感，例如对应如下的配置我们都可以解析出来：
Host: "127.0.0.1"
host: "127.0.0.1" 环境变量 目前 conf 配置支持环境变量注入，我们有 2 种方式实现
- conf.UseEnv()
var c struct { Name string }
conf.MustLoad("config.yaml", &c, conf.UseEnv())
Name: ${SERVER_NAME} 如上，我们在 Load 时候传入 UseEnv， conf 会自动根据值替换字符串中的${var}或$var 当前环境变量。
- env Tag 注意 env 需要 go-zero v1.4.3 以上版本才支持。
var c struct {
Name string json:",env=SERVER_NAME"
}
conf.MustLoad("config.yaml", &c) 我们可以在 json tag 的后面加上 env=SERVER_NAME 的标签，conf 将会自动去加载对应的环境变量。
注意 我们配置加载的顺序会优先级 env > 配置中的定义 > json tag 中的 default 定义
tag 校验规则 我们可以通过在 tag 中来声明参数接收规则，除此之外，还支持参数的校验，参数校验的规则写在 tag value 中，简单示例如下：
type Config struct {
Name string // 没有任何 tag，表示配置必填
Port int64 json:",default=8080" // 如果配置中没有配置，将会初始成 8080
Path string json:",optional"
}
如果我们在 conf 加载的时候，验证没有通过，将会报出来对应的错误。
目前 go-zero 支持的校验规则如下:
接收规则 说明 示例
optional 当前字段是可选参数，允许为零值(zero value) json:"foo,optional"
options 当前参数仅可接收的枚举值 写法 1：竖线
default 当前参数默认值 json:"gender,default=male"
range 当前参数数值有效范围，仅对数值有效，写法规则详情见下文温馨提示 json:"age,range=[0:120]"
env 当前参数从环境变量获取 json:"mode,env=MODE"
range 表达式值规则
左开右闭区间：(min:max]，表示大于 min 小于等于 max，当 min 缺省时，min 代表数值 0，当 max 缺省时，max 代表无穷大，min 和 max 不能同时缺省
左闭右开区间：[min:max)，表示大于等于 min 小于 max，当 max 缺省时，max 代表数值 0，当 min 缺省时，min 代表无穷大，min 和 max 不能同时缺省
闭区间：[min:max]，表示大于等于 min 小于等于 max，当 min 缺省时，min 代表数值 0，当 max 缺省时，max 代表无穷大，min 和 max 不能同时缺省
开区间：(min:max)，表示大于 min 小于 max，当 min 缺省时，min 代表数值 0，当 max 缺省时，max 代表无穷大，min 和 max 不能同时缺省
更多可以参考 unmarshaler_test.go
inherit 配置继承 在我们日常的配置，会出现很多重复的配置，例如 rpcClientConf 中，每个 rpc 都有一个 etcd 的配置，但是我们大部分的情况下 etcd 的配置都是一样的，我们希望可以只用配置一次 etcd 就可以了。 如下的例子
type Config struct { Etcd discov.EtcdConf UserRpc zrpc.RpcClientConf PortRpc zrpc.RpcClientConf OtherRpc zrpc.RpcClientConf }
const str = ` Etcd: Key: rpcServer" Hosts: - "127.0.0.1:6379" - "127.0.0.1:6377" - "127.0.0.1:6376"
UserRpc: Etcd: Key: UserRpc Hosts: - "127.0.0.1:6379" - "127.0.0.1:6377" - "127.0.0.1:6376"
PortRpc: Etcd: Key: PortRpc Hosts: - "127.0.0.1:6379" - "127.0.0.1:6377" - "127.0.0.1:6376"
OtherRpc: Etcd: Key: OtherRpc Hosts: - "127.0.0.1:6379" - "127.0.0.1:6377" - "127.0.0.1:6376" `
我们必须为每个 Etcd 都要加上 Hosts 等基础配置。
但是如果我们使用了 inherit 的 tag 定义，使用的方式在 tag 中加上 inherit。如下：
// A RpcClientConf is a rpc client config.
RpcClientConf struct {
Etcd discov.EtcdConf json:",optional,inherit"
....
}
这样我们就可以简化 Etcd 的配置，他会自动向上一层寻找配置。
const str = ` Etcd: Key: rpcServer" Hosts: - "127.0.0.1:6379" - "127.0.0.1:6377" - "127.0.0.1:6376"
UserRpc: Etcd: Key: UserRpc
PortRpc: Etcd: Key: PortRpc
OtherRpc: Etcd: Key: OtherRpc `
基础服务配置 service 概述 ServiceConf 这个配置是用来表示我们一个独立服务的配置。他被我们的 rest，zrpc 等引用，当然我们也可以自己简单定义自己的服务。
例如：
package main
import ( "github.com/zeromicro/go-zero/core/conf" "github.com/zeromicro/go-zero/core/service" "github.com/zeromicro/go-zero/zrpc" )
type JobConfig struct { service.ServiceConf UserRpc zrpc.RpcClientConf }
func main() { var c JobConfig conf.MustLoad("config.yaml", &c)
c.MustSetUp()
// do your job
}
如上，我们定义了一个 JobConfig，并且在启动的时候初始设置 MustSetup，这样我们就可以启动了一个服务 service，里面自动集成了 Metrics，Prometheus，Trace，DevServer，Log 等能力。
参数定义 ServiceConf 配置定义如下:
// A ServiceConf is a service config.
type ServiceConf struct {
Name string
Log logx.LogConf
Mode string json:",default=pro,options=dev|test|rt|pre|pro"
MetricsUrl string json:",optional"
// Deprecated: please use DevServer
Prometheus prometheus.Config json:",optional"
Telemetry trace.Config json:",optional"
DevServer devserver.Config json:",optional"
}
参数 类型 默认值 说明 枚举值
Name string - 定义服务的名称，会出现在 log 和 tracer 中
Log logx.LogConf - 参考 log
Mode string pro 服务的环境，目前我们预定义了 dev。在 dev 环境我们会开启反射 dev,test,rt,pre, pro
MetricsUrl string 空 打点上报，我们会将一些 metrics 上报到对应的地址，如果为空，则不上报
Prometheus prometheus.Config - 参考 Prometheus.md
Telemetry trace.Config - 参考 trace.md
DevServer devserver.Config - go-zero 版本 v1.4.3 及以上支持
日志配置 log 概述 LogConf 用于我们 log 相关的配置，logx.MustSetup 提供了我们日志的基础配置能力，简单使用方式如下：
var c logx.LogConf logx.MustSetup(c) logx.Info(context.Background(), "log") // do your job 我们 log 被 serviceConf 引用，他会在服务启动的时候自动初始化完成。
参数定义 LogConf 配置定义如下：
package logx
// A LogConf is a logging config.
type LogConf struct {
ServiceName string json:",optional"
Mode string json:",default=console,options=[console,file,volume]"
Encoding string json:",default=json,options=[json,plain]"
TimeFormat string json:",optional"
Path string json:",default=logs"
Level string json:",default=info,options=[debug,info,error,severe]"
MaxContentLength uint32 json:",optional"
Compress bool json:",optional"
Stat bool json:",default=true" // go-zero 版本 >= 1.5.0 才支持
KeepDays int json:",optional"
StackCooldownMillis int json:",default=100"
// MaxBackups represents how many backup log files will be kept. 0 means all files will be kept forever.
// Only take effect when RotationRuleType is size.
// Even thougth MaxBackups sets 0, log files will still be removed
// if the KeepDays limitation is reached.
MaxBackups int json:",default=0"
// MaxSize represents how much space the writing log file takes up. 0 means no limit. The unit is MB.
// Only take effect when RotationRuleType is size
MaxSize int json:",default=0"
// RotationRuleType represents the type of log rotation rule. Default is daily.
// daily: daily rotation.
// size: size limited rotation.
Rotation string json:",default=daily,options=[daily,size]"
// FileTimeFormat represents the time format for file name, default is 2006-01-02T15:04:05.000Z07:00.
FileTimeFormat string json:",optional"
}
参数 类型 默认值 说明 枚举值 ServiceName string 服务名称 Mode string console 日志打印模式，console 控制台 file, console Encoding string json 日志格式, json 格式 或者 plain 纯文本 json, plain TimeFormat string 日期格式化 Path string logs 日志在文件输出模式下，日志输出路径 Level string info 日志输出级别 debug,info,error,severe MaxContentLength uint32 0 日志长度限制，打印单个日志的时候会对日志进行裁剪，只有对 content 进行裁剪 Compress bool false 是否压缩日志 Stat bool true 是否开启 stat 日志，go-zero 版本大于等于 1.5.0 才支持 KeepDays int 0 日志保留天数，只有在文件模式才会生效 StackCooldownMillis int 100 堆栈打印冷却时间 MaxBackups int 0 文件输出模式，按照大小分割时，最多文件保留个数 MaxSize int 0 文件输出模式，按照大小分割时，单个文件大小 Rotation string daily 文件分割模式， daily 按日期 daily,size FileTimeFormat string 文件名日期格式
Prometheus 配置 prometheus 配置 Config Prometheus 相关配置，我们会在进程中启动启动一个 prometheus 端口。 该配置在 v1.4.3 后已不推荐使用，请使用 https://github.com/zeromicro/go-zero/blob/master/internal/devserver/config.go 替换，详情可参考 基础服务配置
参数定义
// A Config is a prometheus config.
type Config struct {
Host string json:",optional"
Port int json:",default=9101"
Path string json:",default=/metrics"
}
参数 类型 默认值 说明 Host string 监听地址 Port int 9101 监听端口 Path string 监听的路径
Auto Validation 自动配置验证 go-zero 支持通过简单的接口实现来进行自动配置验证。当您需要确保配置值在应用程序启动前满足特定条件时，这个功能特别有用。
工作原理 这项新功能引入了一个在加载后自动检查配置的验证机制。以下是使用方法：
在您的配置结构体中实现 Validator 接口： type YourConfig struct { Name string MaxUsers int }
// 实现 Validator 接口 func (c YourConfig) Validate() error { if len(c.Name) == 0 { return errors.New("name 不能为空") } if c.MaxUsers <= 0 { return errors.New("max users 必须为正数") } return nil } 像往常一样使用配置 - 验证会自动进行： var config YourConfig err := conf.Load("config.yaml", &config) if err != nil { // 这里会捕获加载错误和验证错误 log.Fatal(err) } 主要优势 早期错误检测：在应用程序启动时立即发现配置错误 自定义验证规则：根据应用程序需求定义专属的验证逻辑 简洁集成：无需额外的函数调用 - 验证在加载后自动进行 类型安全：验证与配置结构体紧密绑定 使用示例 这里是一个实际的使用示例：
type DatabaseConfig struct { Host string Port int MaxConns int }
func (c DatabaseConfig) Validate() error { if len(c.Host) == 0 { return errors.New("数据库主机地址不能为空") } if c.Port <= 0 || c.Port > 65535 { return errors.New("端口号无效") } if c.MaxConns <= 0 { return errors.New("最大连接数必须为正数") } return nil } 实现细节 该功能通过在加载配置值后检查配置类型是否实现了 Validator 接口来工作。如果实现了该接口，验证就会自动执行。这种方法保持了向后兼容性，同时为新代码提供了增强的功能。
快速开始 要使用这个功能，只需更新到最新版本的 go-zero 即可。不需要额外的依赖。验证功能适用于所有现有的配置加载方式，包括 JSON、YAML 和 TOML 格式。
最佳实践 保持验证规则简单，专注于配置有效性 使用清晰的错误消息，准确指出问题所在 考虑为所有关键配置值添加验证 记住验证在启动时运行 - 避免耗时操作