Golang实现函数式选项模式API设计的插件库options-gen的使用

options-gen是一个代码生成器，可以帮助你创建类似于Dave Cheney提出的函数式选项模式API。它能自动为你的服务/客户端等生成选项配置代码。

安装

go install github.com/kazhuravlev/options-gen/cmd/options-gen@latest

使用示例

基本用法

package mypkg

import (
	"io"
	"log"
)

//go:generate options-gen -out-filename=options_generated.go -from-struct=Options
type Options struct {
	logger     log.Logger `option:"mandatory"`  // 必填选项
	listenAddr string     `option:"mandatory" validate:"required,hostname_port"`
	closer     io.Closer  `validate:"required"`
}

运行生成命令：

go generate ./...

这会生成options_generated.go文件，包含选项构造函数：

// options_generated.go
package mypkg

import (
	"log"
)

func NewOptions(
	// 必填选项，作为参数强制要求
	logger log.Logger,
	listenAddr string,
	// 可选选项
	other ...Option,
) {
	// ...
}

// Validate会检查所有选项是否符合要求
func (o *Options) Validate() error {
	// ...
}

使用生成的选项

package mypkg

import "fmt"

type Component struct {
	opts Options // 嵌入选项结构体
}

func New(opts Options) (*Component, error) { // 构造函数
	if err := opts.Validate(); err != nil {    // 验证选项
		return nil, fmt.Errorf("cannot validate options: %w", err)
	}

	return &Component{opts: opts}, nil // 嵌入选项
}

在main.go中使用：

package main

func main() {
	c, err := mypkg.New(mypkg.NewOptions( /* ... */))
	if err != nil {
		panic(err)
	}
}

泛型支持

//go:generate options-gen -from-struct=Options
type Options[T any] struct {
	addr string   `option:"mandatory" validate:"required,hostname_port"`
	ch   <-chan T `option:"mandatory"`
}

真实世界的HTTP客户端示例

//go:generate options-gen -from-struct=Options
type Options struct {
	httpClient  *http.Client  `option:"mandatory"`
	baseURL     string        `option:"mandatory" validate:"required,url"`
	token       string        `validate:"required"`
	timeout     time.Duration `default:"30s" validate:"min=1s,max=5m"`
	maxRetries  int           `default:"3" validate:"min=0,max=10"`
	userAgent   string        `default:"options-gen/1.0"`
}

type Client struct {
	opts Options
}

func NewClient(opts Options) (*Client, error) {
	if err := opts.Validate(); err != nil {
		return nil, fmt.Errorf("validate options: %w", err)
	}
	
	return &Client{opts: opts}, nil
}

// 使用：
client, err := NewClient(NewOptions(
	httpClient,
	"https://api.example.com",
	WithToken("secret-token"),
	WithTimeout(10*time.Second),
))

配置选项

字段排除

//go:generate options-gen -from-struct=Options -exclude="internal*;debug*"
type Options struct {
	addr         string `option:"mandatory" validate:"required,hostname_port"`
	internalConn net.Conn // 排除：匹配"internal*"
	debugMode    bool     // 排除：匹配"debug*"
	logLevel     string   // 包含
}

自定义选项类型名称

//go:generate options-gen -from-struct=Options -out-setter-name=HTTPOption
type Options struct {
	timeout time.Duration
	headers map[string]string
}

// 生成的代码将使用HTTPOption而不是OptOptionsSetter

多个选项结构体

当包中有多个选项结构体时，可以使用out-prefix避免命名冲突：

// client_options.go
//go:generate options-gen -from-struct=ClientOptions -out-prefix=Client -out-filename=client_options_generated.go
type ClientOptions struct {
	timeout time.Duration `option:"mandatory"`
	retries int          `default:"3"`
}

// server_options.go  
//go:generate options-gen -from-struct=ServerOptions -out-prefix=Server -out-filename=server_options_generated.go
type ServerOptions struct {
	listenAddr string `option:"mandatory" validate:"required,hostname_port"`
	maxConns   int    `default:"100"`
}

// 生成的函数将是：
// - NewClientOptions()和ClientOption
// - NewServerOptions()和ServerOption

验证和默认值

自定义验证器

import (
	"github.com/go-playground/validator/v10"
)

type Options struct {
	age      int    `validate:"adult"`
	username string `validate:"required,alphanum"`
}

func (Options) Validator() *validator.Validate {
	v := validator.New()
	v.RegisterValidation("adult", func(fl validator.FieldLevel) bool {
		return fl.Field().Int() >= 18
	})
	return v
}

默认值

options-gen提供几种定义默认值的方式：

1. 使用tag

//go:generate options-gen -from-struct=Options
type Options struct {
	pingPeriod  time.Duration `default:"3s" validate:"min=100ms,max=30s"`
	name        string        `default:"unknown" validate:"required"`
	maxAttempts int           `default:"10" validate:"min=1,max=10"`
	eps         float32       `default:"0.0001" validate:"gt=0"`
}

1. 使用变量

//go:generate options-gen -from-struct=Options -defaults-from=var
type Options struct {
	httpClient *http.Client
}

var defaultOptions = Options{
	httpClient: &http.Client{},
}

1. 使用函数

//go:generate options-gen -from-struct=Options -defaults-from=func
type Options struct {
	httpClient *http.Client
}

func getDefaultOptions() Options {
	return Options{
		httpClient: &http.Client{},
	}
}

1. 禁用默认值

//go:generate options-gen -from-struct=Options -defaults-from=none
type Options struct {
	name string `default:"joe"`  // 不会生效
}

检查字段是否设置

//go:generate options-gen -from-struct=Options -with-isset
type Options struct {
	name string
}

// 使用：
opts := NewOptions(WithName("alice"))
if opts.IsSet(optFieldName) {
	// name被明确设置为"alice"
}

变长参数设置器

//go:generate options-gen -from-struct=Options
type Options struct {
	// 默认：接受[]string
	tags []string
	// 变长：接受多个string参数
	labels []string `option:"variadic=true"`
}

// 使用：
opts := NewOptions(
	WithTags([]string{"api", "v2"}),
	WithLabels("prod", "us-east-1", "critical"),
)

为外部包结构生成选项

虽然不能直接使用--from-struct=github.com/user/pkg.StructName，但可以使用类型别名：

package myapp

import (
	"github.com/gorilla/websocket"
	"github.com/redis/go-redis/v9"
)

// 为外部结构创建类型别名
type WebsocketOptions = websocket.Dialer

//go:generate options-gen -from-struct=WebsocketOptions
// 这将为websocket.Dialer的所有导出字段生成设置器

// 也可以别名并扩展外部结构
type RedisOptions redis.Options

//go:generate options-gen -from-struct=RedisOptions
// 为redis.Options的所有字段生成设置器

// 泛型外部类型的示例
type CacheOptions[T any] = genericpkg.Cache[T]

//go:generate options-gen -from-struct=CacheOptions

贡献

开发过程非常简单：

1. 在GitHub上fork仓库
2. 克隆你的fork
3. 为你的目标创建新分支
4. 安装Task（类似Make但更简单）
5. 运行task check检查工作副本是否准备就绪
6. 实现你的目标！
7. 再次运行task check确认一切正常
8. 创建Pull Request

options-gen提供了强大的功能来简化Golang中的函数式选项模式实现，通过代码生成减少了模板代码的编写，同时保持了类型安全和良好的API设计。