Go语言中常见100问题-#11 API设计如何处理可选配置？
API设计如何处理可选配置？
在设计API时，可能会遇到一个问题：如何处理可选配置？有效的解决可选配置问题可以提高API的灵活性。本文通过一个具体示例说明处理可选配置的一些方法。该示例的要求是设计一个对外提供创建HTTP服务器的库函数。函数定义如下：
func NewServer(addr string, port int) (*http.Server, error) {
// ...
}
假设上面的库函数已有人在愉快的使用。但是，在某些时候，有用户开始抱怨这个函数只提供addr和port初始化，缺少其他参数初始化（像写入超时设置和连接上下文等）。如果提供其他参数的初始化，需要修改NewServer函数，破坏了兼容性，迫使调用方也必须修改代码。与此同时，我们希望程序能够更加灵活，实现如下的逻辑。
-
如果未设置端口，则使用默认端口
-
如果端口为负，则返回错误
-
如果端口为0，则使用随机端口
-
否则，使用客户端提供的端口
怎么优雅的实现上述要求呢？下面来看看一些处理方法。
方法一 配置结构体
由于Go语言不支持函数可选参数，所以一种可能的方法是使用配置结构体来表达哪些是强制性参数，哪些是可选参数。例如，强制参数可以作为函数参数存在，而可选参数可以在Config结构体中处理。
type Config struct {
Port int
}
func NewServer(addr string, cfg Config) {
}
通过结构体方式修复了新增参数兼容性的问题，如果以后要添加新的参数，在Config结构体中定义即可。但是，这种方法没有解决上面端口设置策略逻辑。同时，我们应该注意如果没有初始化Config结构体字段，它会被初始为对应的零值。
-
整数的零值为0
-
浮点数的零值为0.0
-
字符串的零值为“”
-
切片、map、通道、指针、接口和函数的零值为nil
因此，在下面的示例中，结构体c1和c2是等价的。
c1 := httplib.Config{
Port: 0,
}
c2 := httplib.Config{
}
为了实现端口设置逻辑策略，我们需要找到一种方法来区分是用户特意设置端口为0还是没有设置端口（默认为0）。一种可能的解决方法是将Config结构体中的参数设置为对应类型的指针。使用*int，可以区分出值为0和没有设置值（零指针为nil)之间的差异。
type Config struct {
Port *int
}
虽然将Config结构体中的参数设置为指针有效，但是也有几个缺点：
第一个是客户端需要提供整数指针不方便，需要先创建一个整数变量，然后取整数变量的地址赋值给Config,像下面这样。只赋值一个字段问题不大，但是整个Config有很多字段，使用起来就不方便了。此外，添加的选项越多，代码就越复杂。
port := 0
config := httplib.Config{
Port: &port,
}
第二个是在使用这个库的时候，如果采用默认的配置，客户端需要传递一个空结构对象，代码如下。这行代码看起来不直观友好，使用者不一定了解传空有特定的含义在里面。
httplib.NewServer("localhost", httplib.Config{})
方法二 创建者模式
在GoF设计模式书中，有一种模式叫创建者模式，该模式描述的是各种对象如何创建的问题。其核心理念是将对象的创建和对象本身分开，对于上述的Config结构体，需要有一个额外的结构ConfigBuilder，负责接收配置并创建Config对象。下面来看一个具体实现的例子，看看它是如何优雅实现我们所有需求的。
type Config struct {
Port int
}
type ConfigBuilder struct {
port *int
}
func (b *ConfigBuilder) Port(
port int) *ConfigBuilder {
b.port = &port
return b
}
func (b *ConfigBuilder) Build() (Config, error) {
cfg := Config{}
if b.port == nil {
cfg.Port = defaultHTTPPort
} else {
if *b.port == 0 {
cfg.Port = randomPort()
} else if *b.port < 0 {
return Config{}, errors.New("port should be positive")
} else {
cfg.Port = *b.port
}
}
return cfg, nil
}
func NewServer(addr string, config Config) (*http.Server, error) {
// ...
}
ConfigBuilder结构体包含客户端配置项，并对外暴露一个Port方法用来设置端口值。通常，ConfigBuilder的配置方法会返回它本身，像上面的Port方法第一个返回值是*ConfigBuilder类型，以便可以使用方法链式调用连续设置配置项（像builder.Foo("foo").Bar("bar")）。此外，ConfigBuilder还对外提供了一个Build方法，该方法会处理端口设置策略相关逻辑，并返回一个Config对象。
NOTE:建造者模式并不是只有一种实现方法。例如，有些人可能这样一种方法，即将定义端口值的逻辑放在Port方法里面而不是Build内部。本文的重点是介绍可以通过建造者模式创建对象，而不是枚举分析每种可能的建造者实现方法。
然后，客户端可以通过下面的代码来实现server的初始化(假设上面的实现放在httplib包中)。首先，客户端创建一个ConfigBuilder对象，用它来设置一个可选字段（像本文的端口）。然后，调用它的Build方法并检查错误信息，如果正确无误，则将配置传给NewServer创建一个server对象。
builder := httplib.ConfigBuilder{}
builder.Port(8080)
cfg, err := builder.Build()
if err != nil {
return err
}
server, err := httplib.NewServer("localhost", cfg)
if err != nil {
return err
}
采用上述实现方法使得端口管理更方便，不需传递整数指针，因为Port方法接收整数参数。但是，如果客户想要使用默认配置，仍然需要传一个空的配置结构体。
builder := httplib.ConfigBuilder{}
cfg, err := builder.Build()
if err != nil {
return err
}
server, err := httplib.NewServer("localhost", cfg)
为什么将端口的异常值校验放在Build方法中而不是Port中，是因为我们想保持链式调用能力，函数就不能返回错误。如果客户端可以传递多个选项，但想精确处理端口无效的情况，会使错误处理更加复杂。这种情况下，更好的处理方法是采用下面的选项模式。
方法三 选项模式
选项模式是解决本文问题的第三种方法，尽管实现起来有细微的差别，但主要思想如下：
-
有一个未导出的结构体，它包含各配置项：options结构体
-
每个配置项都是返回一个相同类型的函数：type Option func(options *options) error. 例如，WithPort接收一个表示端口的int参数，并返回一个表示如何更新 options 结构体的Option函数。
下面是采用选项模式解决本文的问题，代码如下. WithPort返回的是一个闭包函数，并且是匿名的， 它引用函数体外的变量port. 该闭包函数是Option类型，并且实现了端口验证逻辑。options中的每个字段都需要创建一个类似于WithPort对外可导出函数，验证输入参数并更新options结构体中对应的字段值。
type options struct {
port *int
}
type Option func(options *options) error
func WithPort(port int) Option {
return func(options *options) error {
if port < 0 {
return errors.New("port should be positive")
}
options.port = &port
return nil
}
}
采用选项模式时，NewServer实现代码如下。将选项字段作为可变参数传递，因此需要遍历所有选项字段来设置配置结构体值。
func NewServer(addr string, opts ...Option) (
*http.Server, error) {
var options options
for _, opt := range opts {
err := opt(&options)
if err != nil {
return nil, err
}
}
// At this stage, the options struct is built and contains the config
// Therefore, we can implement our logic related to port configuration
var port int
if options.port == nil {
port = defaultHTTPPort
} else {
if *options.port == 0 {
port = randomPort()
} else {
port = *options.port
}
}
// ...
}
NewServer 内部首先创建一个空的 options结构体，然后，遍历每个可变参数opts, 执行它们更改option结构中的字段值，最后实现端口策略逻辑。 因为 NewServer 第二个参数是可变参数，所以调用方可以传递任意个参数，例如，下面传递端口和超时时间两个参数。
server, err := httplib.NewServer("localhost",
httplib.WithPort(8080),
httplib.WithTimeout(time.Second))
假如客户端需要默认配置，调用时就不用提供参数，调用代码如下。
server, err := httplib.NewServer("localhost")
本文讲述三种处理配置值的方法，虽然建造者模式相比配置结构体更好，但它有一些小缺点，使得选项模式成为Go语言中的惯用方法，它提供了一种方便且优雅设置对象字段值的方法，像Go中的gRPC库就采用了这种选项模式。