mulan

README

Mulan 木兰

Mulan 是一个面向 Go 应用的轻量级启动框架。
它把 命令行入口、配置加载、环境变量注入、日志初始化、服务生命周期管理 这些常见能力收拢到一起，适合拿来做服务程序的统一启动层。

特性

• 基于 cobra 的命令行入口
• 基于 viper 的配置加载
• 自动读取环境变量
• 默认加载 .env
• 内置 version 命令
• 统一管理多个服务的 Serve / Shutdown / Close
• 默认接入 zap 日志
• 支持启动前预初始化逻辑

安装

go get github.com/virzz/mulan

适用场景

你可以用它来做：

• HTTP 服务启动器
• 多服务组合启动
• 带配置文件和环境变量的应用入口
• 需要优雅关闭的服务程序
• 统一 CLI 风格的微服务项目

核心概念

1. Meta

Meta 用来描述应用自身信息：

• ID：应用唯一标识
• Name：应用名
• CNName：中文名
• Description：描述
• Version：版本号
• Commit：提交号
• BuildAt：构建时间

这些信息会被内置的 version 命令使用。

2. App

App 是框架的入口对象，负责：

• 管理根命令
• 加载配置
• 绑定环境变量
• 注册服务
• 执行启动逻辑
• 处理优雅退出

3. Servicer

接入 App 的服务都需要实现下面接口：

type Servicer interface {
    Serve() error
    Shutdown(context.Context) error
    Close() error
}

• Serve()：启动服务
• Shutdown(ctx)：优雅关闭
• Close()：立即关闭

快速开始

下面是一个最小可运行示例。

package main

import (
	"context"
	"fmt"
	"net/http"
	"time"

	"github.com/gin-gonic/gin"
	"github.com/virzz/mulan"
)

type Config struct {
	Web WebConfig `json:"web" yaml:"web"`
}

type WebConfig struct {
	Port int `json:"port" yaml:"port"`
}

type WebService struct {
	engine *gin.Engine
	server *http.Server
	cfg    *WebConfig
}

func NewWebService(cfg *WebConfig) *WebService {
	engine := gin.Default()
	engine.GET("/", func(c *gin.Context) {
		c.String(200, "Hello, Mulan!")
	})

	return &WebService{
		engine: engine,
		server: &http.Server{
			Addr:    fmt.Sprintf(":%d", cfg.Port),
			Handler: engine,
		},
		cfg: cfg,
	}
}

func (w *WebService) Serve() error {
	go w.server.ListenAndServe()
	return nil
}

func (w *WebService) Shutdown(ctx context.Context) error {
	shutdownCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()
	return w.server.Shutdown(shutdownCtx)
}

func (w *WebService) Close() error {
	return w.server.Close()
}

func main() {
	conf := &Config{}

	meta := &mulan.Meta{
		ID:          "com.example.demo",
		Name:        "demo",
		CNName:      "示例服务",
		Description: "demo service",
		Version:     "1.0.0",
		Commit:      "dev",
		BuildAt:     time.Now().Format(time.RFC3339),
	}

	app := mulan.New(meta, conf)

	webSrv := NewWebService(&conf.Web)
	app.AddService(webSrv)

	if err := app.Execute(context.Background()); err != nil {
		panic(err)
	}
}

配置加载

框架会按下面方式加载配置：

配置文件优先级

1. 命令行参数指定 -c / --config
2. 当前目录下默认配置文件 config.*
3. 环境变量

默认内置参数

-c, --config   配置文件路径
-d, --debug    调试级别，可重复传入

例如：

go run . --config ./config.yaml
go run . -d
go run . -d -d

环境变量规则

执行 app.Execute() 时会自动设置环境变量绑定规则：

• 前缀：app.Name
• . 会转成 _
• - 会转成 _

例如应用名为：

demo

配置字段类似：

web:
  port: 8080

则可以通过环境变量覆盖：

DEMO_WEB_PORT=8080

.env 支持

创建应用时会自动尝试加载当前目录下的 .env 文件。

示例：

DEMO_WEB_PORT=8080

版本命令

框架内置了 version 命令，也支持别名 v：

go run . version
go run . v

输出内容可能包含：

• Name
• CNName
• ID
• Version
• Commit
• BuildAt
• Description

如果 Commit 或 BuildAt 没有手动传入，框架会尝试从构建信息里读取。

常用用法

添加服务

app.AddService(webSrv, jobSrv, grpcSrv)

多个服务会被统一托管。

添加自定义命令

app.AddCommand(cmd1, cmd2)

注意：version 是内置命令，不能被重复注册。

添加 FlagSet

app.AddFlagSet(fs)

绑定 flags 到配置系统

app.BindFlags()

如果你希望把命令行参数也映射到配置系统，可以显式调用这个方法。

启动前预处理

app.SetPreInit(func(ctx context.Context) error {
    // 比如初始化外部资源、校验环境、注册监控
    return nil
})

自定义日志

app.SetLogger(logger)

生命周期说明

默认执行逻辑大致如下：

1. 创建 App
2. 注册服务
3. 加载配置
4. 执行 preInit
5. 调用所有服务的 Serve()
6. 监听退出信号
7. 收到信号后执行：
   • SIGTERM：调用 Shutdown(ctx)
   • 中断信号：调用 Close()

这让服务既能支持快速退出，也能支持优雅关闭。

推荐项目结构

你可以按下面方式组织启动代码：

.
├── cmd/
│   └── app/
│       └── main.go
├── internal/
│   ├── config/
│   ├── server/
│   └── biz/
├── config.yaml
└── .env

如果你的项目有多个服务，可以把 HTTP、gRPC、任务消费者分别实现成不同的 Servicer，再统一注册到 App。

一个简单配置示例

web:
  port: 8080

对应配置结构体：

type Config struct {
    Web WebConfig `json:"web" yaml:"web"`
}

type WebConfig struct {
    Port int `json:"port" yaml:"port"`
}

设计目标

Mulan 不想替你决定业务逻辑怎么写，它主要解决的是“应用怎么启动”和“服务怎么统一管理”这类通用问题。

它更适合做：

• 项目入口层
• 服务编排层
• 配置装配层
• 生命周期管理层

注意事项

• Serve() 建议尽快返回错误，避免吞错
• Shutdown(ctx) 应尽量实现优雅关闭
• Close() 适合兜底快速关闭
• 配置结构体建议同时补上 json 和 yaml tag
• 如果你需要将 flags 与配置系统联动，记得调用 BindFlags()

许可证

本项目基于 MIT 开源。

Documentation

Overview

Example

package main

import (
	"context"
	"fmt"
	"net/http"
	"time"

	"github.com/gin-gonic/gin"

	"github.com/virzz/mulan"
	"github.com/virzz/mulan/service"
)

type (
	WebConfig struct {
		Port int `json:"port" yaml:"port"`
	}

	WebService struct {
		engine *gin.Engine
		server *http.Server
		cfg    *WebConfig
	}
)

var _ service.Servicer = (*WebService)(nil)

func (w *WebService) Serve() error {
	go w.server.ListenAndServe()
	return nil
}

func (w *WebService) Shutdown(ctx context.Context) error {
	shutdownCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()
	return w.server.Shutdown(shutdownCtx)
}

func (w *WebService) Close() error {
	return w.server.Close()
}

func NewWebService(cfg *WebConfig, route func(gin.IRouter)) *WebService {
	engine := gin.Default()
	route(engine)
	return &WebService{
		engine: engine,
		server: &http.Server{
			Handler: engine,
			Addr:    fmt.Sprintf(":%d", cfg.Port),
		},
		cfg: cfg,
	}
}

type Config struct {
	Web WebConfig `json:"web" yaml:"web"`
}

var (
	Version string = "1.0.0"
	Commit  string = "dev"
	BuildAt string = time.Now().Format(time.RFC3339)

	Conf = &Config{}
)

func main() {
	meta := &mulan.Meta{
		ID:          "com.virzz.mulan.example",
		Name:        "example",
		Description: "ExampleService",
		Version:     Version,
		Commit:      Commit,
		BuildAt:     BuildAt,
	}
	std := mulan.New(meta, Conf)

	routerFunc := func(api gin.IRouter) {
		api.Handle("GET", "/", func(c *gin.Context) {
			c.String(200, "Hello, World!")
		})
	}
	webSrv := NewWebService(&Conf.Web, routerFunc)

	std.AddService(webSrv)

	if err := std.Execute(context.Background()); err != nil {
		panic(err)
	}
}

Index

• func UnmarshalConfigOpt(dc *mapstructure.DecoderConfig)
• type ActionFunc
• type App
  • func New(meta *Meta, cfg any) *App
  • func (app *App) AddCommand(cmd ...*cobra.Command) *App
  • func (app *App) AddFlagSet(fs ...*pflag.FlagSet) *App
  • func (app *App) AddService(srvs ...service.Servicer) *App
  • func (app *App) BindFlags() *App
  • func (app *App) Close() error
  • func (app *App) Conf() any
  • func (app *App) Execute(ctx context.Context, action ...ActionFunc) (err error)
  • func (app *App) RootCmd() *cobra.Command
  • func (app *App) Serve() error
  • func (app *App) SetLogger(log *zap.Logger) *App
  • func (app *App) SetPreInit(f PreInitFunc) *App
  • func (app *App) SetVersionCmd(cmd *cobra.Command) *App
  • func (app *App) Shutdown(ctx context.Context) error
  • func (app *App) UnmarshalConfig(cfg any) error
• type Meta
• type PreInitFunc

Examples

• Package

Functions

func UnmarshalConfigOpt

func UnmarshalConfigOpt(dc *mapstructure.DecoderConfig)

Types

type ActionFunc

type ActionFunc func(cmd *cobra.Command, args []string) error

type App

type App struct {
	*Meta
	// contains filtered or unexported fields
}

func New

func New(meta *Meta, cfg any) *App

func (*App) AddCommand

func (app *App) AddCommand(cmd ...*cobra.Command) *App

func (*App) AddFlagSet

func (app *App) AddFlagSet(fs ...*pflag.FlagSet) *App

AddFlagSet 添加 FlagSet 到 rootCmd，可选绑定到 viper

func (*App) AddService

func (app *App) AddService(srvs ...service.Servicer) *App

func (*App) BindFlags

func (app *App) BindFlags() *App

BindFlags 绑定 rootCmd 的 flags 到 viper（可选调用）

func (*App) Close

func (app *App) Close() error

func (*App) Conf

func (app *App) Conf() any

func (*App) Execute

func (app *App) Execute(ctx context.Context, action ...ActionFunc) (err error)

func (*App) RootCmd

func (app *App) RootCmd() *cobra.Command

func (*App) Serve

func (app *App) Serve() error

func (*App) SetLogger

func (app *App) SetLogger(log *zap.Logger) *App

func (*App) SetPreInit

func (app *App) SetPreInit(f PreInitFunc) *App

func (*App) SetVersionCmd

func (app *App) SetVersionCmd(cmd *cobra.Command) *App

func (*App) Shutdown

func (app *App) Shutdown(ctx context.Context) error

func (*App) UnmarshalConfig

func (app *App) UnmarshalConfig(cfg any) error

type Meta

type Meta struct {
	ID          string
	Name        string
	CNName      string
	Description string
	Version     string
	Commit      string
	BuildAt     string
}

type PreInitFunc

type PreInitFunc func(context.Context) error