Glacier Framework

go get github.com/mylxsw/glacier

import "github.com/mylxsw/glacier/starter/app"
...

// 方法一：快捷启动应用
app.MustStart("1.0", 3, func(app *app.App) error {
	// 这里完成应用的初始化
	// ...
	return nil
})

// 方法二： 分步骤启动应用
ins := app.Create("1.0", 3)
// 应用初始化
// ...
app.MustRun(ins)

app.MustStart("1.0", 3, func(ins *app.App) error {
	ins.AddStringFlag("listen", ":8080", "http listen address")
	
	ins.Provider(web.Provider(
		listener.FlagContext("listen"),
		web.SetRouteHandlerOption(func(cc infra.Resolver, router web.Router, mw web.RequestMiddleware) {
			router.Get("/", func(ctx web.Context) web.Response {
				return ctx.JSON(web.M{})
			})
		}),
	))
	return nil
})

// Resolve
resolver.Resolve(func(db *sql.DB) {...})
err := resolver.Resolve(func(db *sql.DB) error {...})

// Call
resolver.Call(func(userRepo UserRepo) {...})
// Call 带有返回值
// 这里的 err 是依赖注入过程中的错误，比如依赖对象创建失败
// results 是一个类型为 []interface{} 的数组，数组中按次序包含了 callback 函数的返回值，以下面的代码为例，其中
// results[0] - string
// results[1] - error
results, err := resolver.Call(func(userRepo UserRepo) (string, error) {...})
// 由于每个返回值都是 interface{} 类型，因此在使用时需要执行类型断言，将其转换为具体的类型再使用
returnValue := results[0].(string)
returnErr := results[1].(error)

// AutoWire
// 假设我们有一个 UserRepo，创建该结构体时需要数据库的连接实例
type UserRepo struct {
  db *sql.DB `autowire:"@"`
}

userRepo := UserRepo{}
resolver.AutoWire(&userRepo)

// 现在 userRepo 中的 db 参数已经自动被设置为了数据库连接对象，可以继续执行后续的操作了

type Provider struct{}

func (Provider) Register(binder infra.Binder) {
	... // 这里可以使用 binder 向 IOC 容器注册当前模块中的实例创建方法
}

package repo

type UserRepo struct {
  db *sql.DB
}

func (repo *UserRepo) Login(username, password string) (*User, error) {...}
func (repo *UserRepo) GetUser(username string) (*User, error) {...}

package repo

type Provider struct {}

func (Provider) Register(binder infra.Binder) {
  binder.Singleton(func(db *sql.DB) *UserRepo { return &UserRepo {db: db} })
}

ins := app.Default("1.0")
...
ins.MustSingleton(func() (*sql.DB, error) {
	return sql.Open("mysql", "user:pwd@tcp(ip:3306)/dbname")
})
// 在这里加载模块的 Provider
ins.Provider(repo.Provider{})
...
app.MustRun(ins)

type Provider struct{}

func (Provider) Register(binder infra.Binder) {
	binder.MustSingleton(func(conf *configs.Config) *grpc.Server { return ... })
}

func (Provider) Boot(resolver infra.Resolver) {
	resolver.MustResolve(func(serv *grpc.Server) {
		protocol.RegisterMessageServer(serv, NewEventService())
		protocol.RegisterHeartbeatServer(serv, NewHeartbeatService())
	})
}

func (Provider) Daemon(_ context.Context, app infra.Resolver) {
	app.MustResolve(func(
		serv *grpc.Server, conf *configs.Config, gf graceful.Graceful,
	) {
		listener, err := net.Listen("tcp", conf.GRPCListen)
		...
		gf.AddShutdownHandler(serv.GracefulStop)
		...
		if err := serv.Serve(listener); err != nil {
			log.Errorf("GRPC Server has been stopped: %v", err)
		}
	})
}

// 创建自定义模块，初始化了 Glacier 框架内置的 Web 框架
type Provider struct{}

func (Provider) Aggregates() []infra.Provider {
	return []infra.Provider{
		// 加载了 web 模块，为应用提供 web 开发支持
		web.Provider(
			listener.FlagContext("listen"), // 从命令行参数 listen 获取监听端口
			web.SetRouteHandlerOption(s.routes), // 设置路由规则
			web.SetExceptionHandlerOption(func(ctx web.Context, err interface{}) web.Response {
				log.Errorf("error: %v, call stack: %s", err, debug.Stack())
				return nil
			}), // Web 异常处理
		),
	}
}

func (Provider) routes(cc infra.Resolver, router web.Router, mw web.RequestMiddleware) {
	router.Controllers(
		"/api",
		// 这里添加控制器
		controller.NewWelcomeController(cc),
		controller.NewUserController(cc),
	)
}

func (Provider) Register(app infra.Binder) {}

type DemoService struct {
	resolver infra.Resolver
	stopped chan interface{}
}

// Init 可选方法，用于在 Service 启动之前初始化一些参数
func (s *DemoService) Init(resolver infra.Resolver) error {
	s.resolver = resolver
	s.stopped = make(chan interface{})
	return nil
}

// Start 用于 Service 的启动
func (s *DemoService) Start() error {
	for {
		select {
		case <-s.stopped:
			return nil
		default:
			... // 业务代码
		}
	}
}

// Stop 和 Reload 都是可选方法
func (s *DemoService) Stop() { s.stopped <- struct{}{} }
func (s *DemoService) Reload() { ... }

ins := app.Create("1.0")
...
ins.Service(&service.DemoService{})
...
app.MustRun(ins)

type Provider struct{}
func (Provider) Register(binder infra.Binder) {...}

// 只有当 config.AuthType == ldap 的时候才会加载当前 Provider
func (Provider) ShouldLoad(config *config.Config) bool {
	return str.InIgnoreCase(config.AuthType, []string{"ldap"})
}

type Provider struct {}
func (Provider) Register(binder infra.Binder) {...}

func (Provider) Priority() int {
	return 10
}

// Password 该结构体时 /complex 接口的返回值定义
type Password struct {
	Password string `json:"password"`
}

// Glacier 框架初始化
ins := app.Default("1.0")
...
// 添加命令行参数 listen，指定默认监听端口 :8080
ins.AddStringFlag("listen", ":8080", "http listen address")
...
ins.Provider(web.Provider(
	// 使用命令行 flag 的 listener builder
	listener.FlagContext("listen"), 
	// 设置路由规则
	web.SetRouteHandlerOption(func(resolver infra.Resolver, r web.Router, mw web.RequestMiddleware) {
		...
		r.Get("/simple", func(ctx web.Context, gen *password.Generator) web.Response {
			...
			return ctx.JSON(web.M{"password": pass})
		})
		
		r.Get("/complex", func(ctx web.Context, gen *password.Generator) Password {...})
	}),
))

app.MustRun(ins)

type Provider struct{}

// Aggregates 实现 infra.ProviderAggregate 接口
func (Provider) Aggregates() []infra.Provider {
	return []infra.Provider{
		web.Provider(
			confListenerBuilder{},
			web.SetRouteHandlerOption(routes),
			web.SetMuxRouteHandlerOption(muxRoutes),
			web.SetExceptionHandlerOption(exceptionHandler),
		),
	}
}

// Register 实现 infra.Provider 接口
func (Provider) Register(binder infra.Binder) {}

// exceptionHandler 异常处理器
func exceptionHandler(ctx web.Context, err interface{}) web.Response {
	return ctx.JSONWithCode(web.M{"error": fmt.Sprintf("%v", err)}, http.StatusInternalServerError)
}

// routes 注册路由规则
func routes(resolver infra.Resolver, router web.Router, mw web.RequestMiddleware) {
	mws := make([]web.HandlerDecorator, 0)
	// 添加 web 中间件
	mws = append(mws,
		mw.AccessLog(log.Module("api")),
		mw.CORS("*"),
	)

	// 注册控制器，所有的控制器 API 都以 `/api` 作为接口前缀
	router.WithMiddleware(mws...).Controllers(
		"/api",
		controller.NewServerController(resolver),
		controller.NewClientController(resolver),
	)
}

func muxRoutes(resolver infra.Resolver, router *mux.Router) {
	resolver.MustResolve(func() {
		// 添加 prometheus metrics 支持
		router.PathPrefix("/metrics").Handler(promhttp.Handler())
		// 添加健康检查接口支持
		router.PathPrefix("/health").Handler(HealthCheck{})
	})
}

// 创建自定义的 listener 构建器，从配置对象中读取 listen 地址
type confListenerBuilder struct{}

func (l confListenerBuilder) Build(resolver infra.Resolver) (net.Listener, error) {
	return listener.Default(resolver.MustGet((*config.Server)(nil)).(*config.Server).HTTPListen).Build(resolver)
}

type UserController struct {...}

// NewUserController 控制器创建方法，返回 web.Controller 接口
func NewUserController() web.Controller { return &UserController{...} }

// Register 注册当前控制器关联的路由规则
func (ctl UserController) Register(router web.Router) {
	router.Group("/users/", func(router web.Router) {
		router.Get("/", u.Users).Name("users:all")
		router.Post("/", u.Add)
		router.Post("/{id}/", u.Update)
		router.Get("/{id}/", u.User).Name("users:one")
		router.Delete("/{id}/", u.Delete).Name("users:delete")
	})

	router.Group("/users-helper/", func(router web.Router) {
		router.Get("/names/", u.UserNames)
	})
}

// 读取 JSON 请求参数，直接返回实例，会以 json 的形式返回给客户端
func (ctl UserController) Add(ctx web.Context, userRepo repository.UserRepo) (*repository.User, error) {
	var userForm *UserForm
	if err := ctx.Unmarshal(&userForm); err != nil {
		return nil, web.WrapJSONError(fmt.Errorf("invalid request: %v", err), http.StatusUnprocessableEntity)
	}
	ctx.Validate(userForm, true)
	...
	return ...
}

// 直接返回错误，如果 error 不为空，则返回错误给客户端
func (ctl UserController) Delete(ctx web.Context, userRepo repository.UserRepo) error {
	userID := ctx.PathVar("id")
	...
	return userRepo.DeleteID(userID)
}

// 返回 web.Response，可以使用多种格式返回，如 ctx.Nil, ctx.API, ctx.JSON, ctx.JSONWithCode, ctx.JSONError, ctx.YAML, ctx.Raw, ctx.HTML, ctx.HTMLWithCode, ctx.Error 等
func (u UserController) Users(ctx web.Context, userRepo repository.UserRepo, roleRepo repository.RoleRepo) web.Response {
	page := ctx.IntInput("page", 1)
	perPage := ctx.IntInput("per_page", 10)
	...
	return ctx.JSON(web.M{
		"users": users,
		"next":  next,
		"search": web.M{
			"name":  name,
			"phone": phone,
			"email": email,
		},
	})
}

// routes 注册路由规则
func routes(resolver infra.Resolver, router web.Router, mw web.RequestMiddleware) {
	mws := make([]web.HandlerDecorator, 0)
	// 添加 web 中间件
	mws = append(mws,
		mw.AccessLog(log.Module("api")),
		mw.CORS("*"),
	)

	// 注册控制器，所有的控制器 API 都以 `/api` 作为接口前缀
	router.WithMiddleware(mws...).Controllers(
		"/api",
		controller.NewUserController(),
	)
}

ins.Provider(event.Provider(
  func(cc infra.Resolver, listener event.Listener) {
    listener.Listen(func(event CronEvent) {
      log.Debug("a new cron task executed")
      // 执行监听到定时任务执行事件后要触发的操作
    })
  },
  // 设置事件管理器选项
  event.SetStoreOption(func(cc infra.Resolver) event.Store {
    // 设置使用默认的内存事件存储
    return event.NewMemoryEventStore(true, 100)
  }),
))

ins.Async(func(publisher event.Publisher) {
  for i := 0; i < 10; i++ {
    publisher.Publish(CronEvent{GoroutineID: uint64(i)})
  }
})

// 设置事件管理器选项
event.SetStoreOption(func(cc infra.Resolver) event.Store {
	// 设置使用默认的内存事件存储
	return event.NewMemoryEventStore(true, 100)
})

type Provider struct{}
func (Provider) Register(binder infra.Binder) {...}

func (Provider) Aggregates() []infra.Provider {
	return []infra.Provider{
		// 加载 scheduler 定时任务模块
		scheduler.Provider(
			func(resolver infra.Resolver, creator scheduler.JobCreator) {
				// 添加一个名为 test-job 的任务，每隔 10s 执行一次
				_ = cr.Add("test-job", "@every 10s", TestJob)
				// 添加一个名称为 test-timeout-job 的任务，每隔 5s 执行一次
				// 通过 AddAndRunOnServerReady 添加的任务会在服务启动时先执行一次
				_ = creator.AddAndRunOnServerReady(
					"test-timeout-job", 
					"@every 5s",
					// 使用 scheduler.WithoutOverlap 包装的函数，当前一次调度还没有执行完毕，本次调度的时间已到，本次调度将会被取消
					scheduler.WithoutOverlap(TestTimeoutJob).SkipCallback(func() { 
						... // 当前一个任务还没有执行完毕时，当前任务会被跳过，跳过时会触发该函数的执行
					}),
				)
			},
		),
	}
}

scheduler.Provider(
	func(resolver infra.Resolver, creator scheduler.JobCreator) {...},
	// 设置分布式锁
	scheduler.SetLockManagerOption(func(resolver infra.Resolver) scheduler.LockManagerBuilder {
		// get redis instance
		redisClient := resolver.MustGet(&redis.Client{}).(*redis.Client)
		return func(name string) scheduler.LockManager {
			// create redis lock
			return redisLock.New(redisClient, name, 10*time.Minute)
		}
	}),
)

// import "github.com/mylxsw/glacier/log"

// 默认设置，使用 asteria 日志框架
// import asteria "github.com/mylxsw/asteria/log"
log.SetDefaultLogger(asteria.Module("glacier"))
// 使用标准库中的日志包，Glacier 对标准库日志包进行了简单封装
log.SetDefaultLogger(log.StdLogger())

ins := app.Default("1.0")
...
// 设置使用标准库日志包，不输出 DEBUG 日志
ins.WithLogger(log.StdLogger(log.DEBUG))
...

type Logger interface {
	Debug(v ...interface{})
	Debugf(format string, v ...interface{})
	Info(v ...interface{})
	Infof(format string, v ...interface{})
	Error(v ...interface{})
	Errorf(format string, v ...interface{})
	Warning(v ...interface{})
	Warningf(format string, v ...interface{})
	// Critical 关键性错误，遇到该日志输出时，应用直接退出
	Critical(v ...interface{})
	// Criticalf 关键性错误，遇到该日志输出时，应用直接退出
	Criticalf(format string, v ...interface{})
}

ins := app.Create("1.0")
ins.WithShutdownTimeoutFlagSupport(5 * time.Second)
...

// Provider 中获取 `gf.Graceful` 实例，注册关闭时的处理函数
resolver.MustResolve(func(gf graceful.Graceful) {
	gf.AddShutdownHandler(func() {
		...
	})
})