GoWind Bootstrap · 声明式应用引导框架

项目亮点

声明式配置驱动：基于 Protobuf 定义的 BootstrapConfig，一份 YAML 配置即可描述完整的应用拓扑——传输层、配置中心、注册发现、日志、追踪、指标、消息代理
SPI 插件注册机制：通过 init() + 空导入实现 Builder 自注册，零胶水代码即可扩展新组件
声明式中间件编排：HTTP/gRPC 中间件通过配置启用和参数化，无需手写一行中间件初始化代码
三层封装，灵活切换：从一行代码启动的全密封模式，到手写 Builder 的完全开放模式，按需选择
多模块依赖隔离：每个适配子包独立 go.mod，用户只引入需要的适配器，不污染依赖树
Cobra 命令行集成：内置命令行支持，通过 -c 参数指定配置文件，开箱即用
多格式配置支持：自动识别 YAML / JSON / Protobuf 二进制格式，平滑迁移

快速开始

安装

go get github.com/tx7do/go-wind-bootstrap

最简示例

config.yaml

app:
  id: my-service
  name: my-service
  version: "1.0.0"
  env: development

server:
  http:
    addr: ":8080"
    middleware:
      recovery: {}
      cors: {}
      logging: {}

logger:
  type: zap
  zap:
    level: info
    format: json

main.go

package main

import (
    "fmt"
    "net/http"
    "os"

    bootstrap "github.com/tx7do/go-wind-bootstrap"
    _ "github.com/tx7do/go-wind-bootstrap/log/zap"
    httpAdapter "github.com/tx7do/go-wind-bootstrap/transport/http"
)

func main() {
    httpAdapter.RegisterServerSetup(func(srv *httpAdapter.Server) {
        srv.GET("/", func(w http.ResponseWriter, r *http.Request) {
            _, _ = fmt.Fprintf(w, "Hello, GoWind!\n")
        })
    })

    if err := bootstrap.RunAppWithFlags(bootstrap.NewCommandFlags()); err != nil {
        os.Exit(1)
    }
}

# 启动
go run main.go

# 指定配置文件
go run main.go -c /path/to/config.yaml

# 测试
curl http://localhost:8080

设计理念

配置即应用

go-wind-bootstrap 的核心思想是声明式配置驱动。应用的完整拓扑——从传输层到消息代理——全部通过一份 Protobuf 定义的 BootstrapConfig 描述。引导引擎读取配置，通过注册的 Builder 自动组装 wind.App：

BootstrapConfig → Builder Registry → wind.Option Chain → wind.App

SPI 自注册模式

每个适配子包通过 init() + 空导入将 Builder 注册到全局注册表。用户只需导入对应的适配器包，框架自动完成组件创建：

import (
    _ "github.com/tx7do/go-wind-bootstrap/log/zap"           // 注册 Zap Logger Builder
    _ "github.com/tx7do/go-wind-bootstrap/transport/http"     // 注册 HTTP Server Builder
    _ "github.com/tx7do/go-wind-bootstrap/transport/grpc"     // 注册 gRPC Server Builder
)

声明式中间件

HTTP 和 gRPC 中间件通过配置文件的 optional 字段启用，参数也通过配置传入。无需编写初始化代码：

server:
  http:
    addr: ":8080"
    middleware:
      recovery:
        stack_trace: true
      cors:
        allowed_origins:
          - "*"
        allowed_methods:
          - GET
          - POST
      logging:
        skip_paths:
          - /health
      request_id:
        header_name: X-Request-ID

三层 API 封装

层次	API	适用场景
全密封	`RunApp` / `RunAppWithFlags`	一行代码启动，自动处理信号监听、配置加载、生命周期
半密封	`BootstrapWithContext`	需要访问 `Context`（配置、App、Cancel）进行定制
开放	`Bootstrap` / `Run`	完全手动控制每一步，适合高级场景

全密封模式

// 最简单：一行启动
bootstrap.RunApp("config.yaml")

// 带 Cobra 命令行
bootstrap.RunAppWithFlags(bootstrap.NewCommandFlags())

半密封模式

bctx, err := bootstrap.BootstrapWithContext(nil, cfg)
if err != nil {
    log.Fatal(err)
}
defer bctx.Cleanup()

// 可在运行前操作 Context
fmt.Println(bctx.Config().GetApp().GetName())

bctx.App().Run(bctx)

开放模式

cfg, _ := bootstrap.LoadConfigFromFile("config.yaml")
app, cleanup, err := bootstrap.Bootstrap(ctx, cfg)
if err != nil {
    log.Fatal(err)
}
defer cleanup()

app.Run(ctx)

服务注册与发现

配置注册中心后，bootstrap 自动管理实例生命周期：

注册：应用启动后（AfterStart 钩子）以真实监听端点注册——配置 ":0" 随机端口时会等待绑定完成后取实际端口；
注销：优雅停机时（BeforeStop 钩子）在服务器停止前摘除实例；
任一注册中心注册失败会注销已注册实例并触发优雅停机。

客户端服务发现按需选用两条路径（go-wind core 不含发现概念）：

// 路径一：gRPC 经 resolver 按服务名寻址（负载均衡用 gRPC 内置 round_robin）
import "github.com/tx7do/go-wind-plugins/resolver"

conn, err := grpc.NewClient("wind:///user-service",
    grpc.WithResolvers(resolver.NewBuilder(ctx.Registry("etcd"))),
    grpc.WithDefaultServiceConfig(`{"loadBalancingPolicy":"round_robin"}`),
)

// 路径二：任意客户端用 selector 直接挑选实例
import "github.com/tx7do/go-wind-plugins/selector"

balancer := selector.NewWatchedBalancer(ctx.Registry("etcd"), selector.RoundRobin())
defer balancer.Close()
inst, err := balancer.Pick(ctx, "user-service")

ctx.Registry("etcd") 返回 bootstrap 装配好的注册中心实例（GetService/Watch/Register/Deregister），resolver 与 selector 来自 go-wind-plugins。

架构总览

graph TB
    Config["BootstrapConfig<br/>YAML / JSON / Protobuf"]
    Engine["Bootstrap Engine<br/>Builder Registry + Resolver"]
    App["wind.App<br/>生命周期管理"]

    Config -->|"加载配置"| Engine
    Engine -->|"Server Builder"| Server["Server<br/>HTTP · gRPC · TCP · WebSocket · ..."]
    Engine -->|"Log Builder"| Logger["Logger<br/>Zap · Zerolog · Slog · ..."]
    Engine -->|"Registry Action"| Registry["Registry<br/>Consul · Etcd · Nacos · ..."]
    Engine -->|"Config Action"| ConfigSrc["Config Source<br/>File · Etcd · Nacos · ..."]
    Engine -->|"Tracer Builder"| Tracer["Tracer<br/>OTLP"]
    Engine -->|"Metrics Builder"| Metrics["Metrics<br/>Prometheus · OTLP"]
    Engine -->|"Broker Builder"| Broker["Broker<br/>Kafka · RabbitMQ · Redis · ..."]
    Server --> App
    Logger --> App
    Registry --> App
    ConfigSrc --> App
    Tracer --> App
    Metrics --> App
    Broker --> App

支持的组件

传输层（Server）

类型	常量	适配器
HTTP	`http`	`transport/http` ✅
gRPC	`grpc`	`transport/grpc` ✅
HTTP/3	`http3`	—
GraphQL	`graphql`	—
SSE	`sse`	—
WebSocket	`websocket`	—
TCP	`tcp`	—
UDP	`udp`	—
KCP	`kcp`	—
Thrift	`thrift`	—
tRPC	`trpc`	—
WebTransport	`webtransport`	—

日志（Logger）

类型	常量
Zap ✅	`zap`
Zerolog	`zerolog`
Slog	`slog`
Logrus	`logrus`
Charm	`charm`
Phuslu	`phuslu`
Loki	`loki`
Sentry	`sentry`
阿里云	`aliyun`
腾讯云	`tencent`
CloudWatch	`cloudwatch`

配置中心（Config）

类型	常量
File	`file`
Etcd	`etcd`
Nacos	`nacos`
Consul	`consul`
Apollo	`apollo`
Kubernetes	`kubernetes`
Redis	`redis`
Zookeeper	`zookeeper`
Vault	`vault`
Polaris	`polaris`

服务注册发现（Registry）

类型	常量
Consul	`consul`
Etcd	`etcd`
Nacos	`nacos`
Zookeeper	`zookeeper`
Polaris	`polaris`
Eureka	`eureka`
Kubernetes	`kubernetes`
ServiceComb	`service_comb`

分布式追踪（Tracer）

类型	常量
OTLP	`otlp`

指标监控（Metrics）

类型	常量
Prometheus	`prometheus`
OTLP	`otlp`

消息代理（Broker）

类型	常量
Kafka	`kafka`
RabbitMQ	`rabbitmq`
Redis	`redis`
NATS	`nats`
MQTT	`mqtt`
Pulsar	`pulsar`
Azure Service Bus	`azuresb`
Google Pub/Sub	`gcpubsub`
NSQ	`nsq`
RocketMQ	`rocketmq`
SQS	`sqs`
STOMP	`stomp`

数据库（Database）

类型	常量	适配器
GORM（MySQL/Postgres/SQLite/SQLServer 等）	`gorm`	`database/gorm` ✅
MongoDB	`mongodb`	`database/mongodb` ✅
ClickHouse	`clickhouse`	`database/clickhouse` ✅
Doris	`doris`	`database/doris` ✅
Elasticsearch	`elasticsearch`	`database/elasticsearch` ✅
OpenSearch	`opensearch`	`database/opensearch` ✅
InfluxDB	`influxdb`	`database/influxdb` ✅
Cassandra	`cassandra`	`database/cassandra` ✅
Qdrant（向量）	`qdrant`	`database/qdrant` ✅
Milvus（向量）	`milvus`	`database/milvus` ✅
Neo4j（图）	`neo4j`	`database/neo4j` ✅
Weaviate（向量）	`weaviate`	`database/weaviate` ✅
Ent	—	`database/ent`（泛型 Helper，非 SPI 注册）

关系型/文档型/搜索型引擎升级 go-crud 后同步获得向量检索能力（go-crud/vector 契约：GORM+pgvector、Elasticsearch knn、OpenSearch knn、MongoDB Atlas $vectorSearch、ClickHouse/Doris 距离函数）。

声明式中间件

HTTP 中间件

中间件	配置字段	说明
Recovery	`recovery`	异常恢复，可选 `stack_trace`
CORS	`cors`	跨域资源共享，支持 `allowed_origins/methods/headers` 等
Logging	`logging`	请求日志，可选 `skip_paths`
Request ID	`request_id`	请求 ID 注入，可选 `header_name`
Tracing	`tracing`	OpenTelemetry 链路追踪
Rate Limit	`rate_limit`	限流
Timeout	`timeout`	请求超时

gRPC 中间件

中间件	配置字段	说明
Recovery	`recovery`	异常恢复
Logging	`logging`	请求日志
Tracing	`tracing`	OpenTelemetry 链路追踪
Validate	`validate`	请求校验

路由注册

追加式注册（推荐）

适配器提供 RegisterServerSetup 追加式注册 API，支持代码生成器和手写代码共存：

// generated_routes.go（代码生成器自动生成）
func init() {
    httpAdapter.RegisterServerSetup(func(srv *httpAdapter.Server) {
        srv.GET("/v1/users", listUsers)
        srv.POST("/v1/users", createUser)
    })
}

// main.go（用户手写代码）
func init() {
    httpAdapter.RegisterServerSetup(func(srv *httpAdapter.Server) {
        srv.GET("/health", healthCheck)
    })
}

gRPC 服务注册

grpcAdapter.RegisterServiceRegistrar(func(srv *grpc.Server) {
    pb.RegisterGreeterServer(srv, &greeterService{})
})

项目结构

go-wind-bootstrap/
├── conf/                        # 独立 go.mod · Protobuf 配置定义
│   └── proto/bootstrap/v1/      # .proto 源文件
│       ├── bootstrap.proto      # 顶层 BootstrapConfig
│       ├── app.proto            # 应用元数据
│       ├── server.proto         # 传输层 + 中间件配置
│       ├── config.proto         # 配置中心
│       ├── registry.proto       # 服务注册发现
│       ├── log.proto            # 日志系统
│       ├── tracer.proto         # 分布式追踪
│       ├── metrics.proto        # 指标监控
│       └── broker.proto         # 消息代理
├── *.go                         # 根 go.mod · 引导引擎核心
│   ├── bootstrap.go             # 入口：Bootstrap / Run / RunApp
│   ├── builder.go               # Builder 注册表（SPI）
│   ├── context.go               # Context 生命周期封装
│   ├── cli.go                   # Cobra 命令行封装
│   ├── types.go                 # 组件类型常量
│   ├── server_builder.go        # Server 解析器
│   ├── config_builder.go        # Config 解析器
│   ├── registry_builder.go      # Registry 解析器
│   ├── log_builder.go           # Logger 解析器
│   ├── tracer_builder.go        # Tracer 解析器
│   ├── metrics_builder.go       # Metrics 解析器
│   └── broker_builder.go        # Broker 解析器
├── log/zap/                     # 独立 go.mod · Zap Logger 适配器
├── transport/http/              # 独立 go.mod · HTTP 适配器 + 中间件 + std driver
├── transport/grpc/              # 独立 go.mod · gRPC 适配器 + 中间件
└── _examples/
    ├── quickstart/              # 最简示例：一行代码启动
    ├── yaml_config/             # YAML 配置加载示例
    └── custom_builder/          # 自定义 Builder 示例

技术栈

层级	技术	说明
语言	Go 1.22+	高性能编译型语言
框架	go-wind	微服务生命周期骨架
插件	go-wind-plugins	可插拔功能模块库
配置定义	Protobuf + buf.build	声明式配置，契约优先
配置格式	YAML / JSON / Protobuf Binary	多格式自动识别
命令行	Cobra	CLI 参数解析

扩展自定义 Builder

当内置适配器不满足需求时，可以注册自定义 Builder：

// 注册自定义 Registry Builder
bootstrap.MustRegisterRegistryAction(bootstrap.RegistryTypeConsul,
    func(ctx context.Context, appCfg *v1.App, endpoints []string) (func(), error) {
        // 创建 Consul 注册中心...
        return func() { /* cleanup */ }, nil
    },
)

// 注册自定义 Broker Builder
bootstrap.MustRegisterBrokerBuilder(bootstrap.BrokerTypeKafka,
    func(ctx context.Context, cfg *v1.Broker) (func(), error) {
        // 创建 Kafka Broker...
        return func() { /* cleanup */ }, nil
    },
)

字段映射代码生成

各适配器里"配置字段 → 上游选项"的机械映射由 protoc-gen-fieldmap 生成：每个适配器旁一份 mapping.spec.yaml 声明映射规则，生成的 mapping.gen.go 提供强类型映射函数（如 MapSQLOptions、NewMinioConfig），需特殊处理的字段（复合选项、TLS 装载、模式联动）以 skip: true 记录并保留在适配器手工段。

# 调整某适配器的映射规则后重新生成（以 database/gorm 为例）
go run github.com/tx7do/go-wind-toolkit/protoc-gen-fieldmap@latest \
  -I conf/proto -spec database/gorm/mapping.spec.yaml -out .

spec 中写了 proto 上不存在的字段名、或对不兼容类型用了 cast/guard，生成阶段直接报错——上游配置面变更时先跑一次生成，漂移即刻暴露。完整维护约定（风格选择、guard/cast 规则、手工段边界、AI 代理守则）见 docs/fieldmap-conventions.md。

保持手写的适配器（生成收益不足，勿硬凑）：

transport/http、transport/grpc 等服务器适配器——中间件链、TLS、keepalive 等控制流支配，机械字段占比低；
log/zap、log/zerolog、log/logrus、log/phuslu、log/charm——level/format/writer 三组 switch 支配一切；
多数 MQ 类 transport/broker（kafka、nats、mqtt…）——仅 1~2 个机械字段，认证皆为复合选项；
database/ent——不走 SPI 注册，映射面仅 4 个位置参数；
workflow/*、ai/*——字段个位数且为嵌套复合配置。

各适配器 spec 中 skip: true 的字段即"有意不映射"的完整清单（复合选项、TLS 装载、proto 有字段但实现未消费的部分）。

License

MIT License

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
_examples		_examples
ai		ai
broker		broker
cache		cache
conf		conf
config		config
database		database
docs		docs
integration		integration
log		log
oss		oss
registry		registry
script_engine		script_engine
tlsutil		tlsutil
tracer/otlp		tracer/otlp
transport		transport
workflow		workflow
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
README_en.md		README_en.md
README_ja.md		README_ja.md
ai_builder.go		ai_builder.go
bootstrap.go		bootstrap.go
broker_builder.go		broker_builder.go
builder.go		builder.go
cache_builder.go		cache_builder.go
cli.go		cli.go
config_builder.go		config_builder.go
context.go		context.go
context_test.go		context_test.go
database_builder.go		database_builder.go
go.mod		go.mod
go.sum		go.sum
log_builder.go		log_builder.go
metrics_builder.go		metrics_builder.go
registry_builder.go		registry_builder.go
registry_instance.go		registry_instance.go
resolver.go		resolver.go
script_engine_builder.go		script_engine_builder.go
server_builder.go		server_builder.go
server_endpoints.go		server_endpoints.go
storage_builder.go		storage_builder.go
tag.sh		tag.sh
tracer_builder.go		tracer_builder.go
types.go		types.go
upgrade.ps1		upgrade.ps1
upgrade.sh		upgrade.sh
workflow_builder.go		workflow_builder.go

Latest commit

History

Folders and files

Repository files navigation

GoWind Bootstrap · 声明式应用引导框架

项目亮点

快速开始

安装

最简示例

设计理念

配置即应用

SPI 自注册模式

声明式中间件

三层 API 封装

全密封模式

半密封模式

开放模式

服务注册与发现

架构总览

支持的组件

传输层（Server）

日志（Logger）

配置中心（Config）

服务注册发现（Registry）

分布式追踪（Tracer）

指标监控（Metrics）

消息代理（Broker）

数据库（Database）

声明式中间件

HTTP 中间件

gRPC 中间件

路由注册

追加式注册（推荐）

gRPC 服务注册

项目结构

技术栈

扩展自定义 Builder

字段映射代码生成

相关项目

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages