igo

README

igo

集成链路追踪的后端服务框架 例子

依赖库

• web框架 gin
• 数据库 (mysql,pgsql,mssql,clickhouse) gorm
• 配置文件 viper
• 依赖注入 fx
• 链路追踪 opentelemetry
• 缓存
  • redis go-redis
• 日志 slog
• 消息系统
  • rabbitmq rabbitmq/amqp091-go
• 定时任务 cron 计划支持

接口服务

基于gin实现的类RPC编码风格的restful服务，可方便的再rpc和传统的gin.handlefunc之前切换.

特性

• 支持链路追踪包含日志关联
• 使用RPC风格编码restful接口
• 自动生成接口文档 (openapi 3.0)
• 日志敏感词过滤
• 支持原始http/gin风格，解决rpc模式无法处理如websocket等需求问题

路由方法

标准的RPC风格

建议使用此风格，此风格对自动创建文档并做一些列内置的处理，帮你减少恨过工作

func(context.Context, in *structRequest) (out *structResponse, err error)

定义

• ctx 上下文关联
• in 入参 必须是结构体指针 如果没有参数 可以使用 *web.Empty 内置类型
• out 结果 必须是结构体指针

不带固定响应

有些情况下 不需要响应固定的结构 比如SSE服务器推送技术 或者websocket

func(context.Context, in *structRequest) error

如何使用

srv := app.CreateWebServer()
route := srv.Router()
route.Get("/user/:id", getUser)

type GetUserOption struct{
    // 通过 tag 标记此参数是url部分的变量
    ID string `uri:"id" comment:"用户的id"`
}

type UserInfo struct{
    ...
}

// getUser 这里的注释会在文档中显示
func getUser(ctx context.Context, in *GetUserOption) (*UserInfo, error){
    // 通过ctx 日志可以携带trace信息
    slog.InfoCtx("get user info", "id",in.ID)
    // 通过codes.New 返回error
    return nil, codes.NewBadRequest("some err")
}

绑定请求 / 验证

和gin保持一致 可以绑定query，header，form表单，json请求体，url参数等

query绑定 使用tag:jquery json gin默认使用form tag进行绑定且仅对get请求有效 为了更好的通用性 这里使用tag:query进行绑定

验证则遵循 gin风格

type QueryRequestDemo struct{
    Field1   string `json:"field" binding:"required"`
    UrlParam string `uri:"id"`
}

使用原始gin风格

srv := app.CreateWebServer()
r := srv.GinEngine() // 替换掉 srv.Router()
route.GET("/user/:id", func(*gin.Context){
    // todo
})

在RPC风格里使用gin.Context

func hello(ctx context.Context, in *structRequest) error {
    ginCtx,ok:=web.GinContext(ctx)
    if ok{
        ginCtx.String(200,"hello")
    }
    return nil
}

链路追踪和日志

内部使用slog做为日志系统，为了进行链路关联 请使用slog的Ctx方法返回日志

默认使用框架的内的database/redis/http自带trace 请使用带有context.Context的方法进行操作

func hello(ctx context.Context){
    slog.InfoCtx(ctx,"msg。。。。", "field_key","field_value")
}

Documentation

Index

• Variables
• func Conf() config.Provider
• func GetTraceID(c context.Context) string
• func NewTraceSlogHandler(w io.Writer, addSource bool, lvl slog.Leveler) slog.Handler
• func SetConfig(path string)
• type AppInfo
• type Application
  • func New(info AppInfo) *Application
  • func (app *Application) CreateWebServer(opts ...web.Option) *web.Server
  • func (app *Application) Invoke(funcs ...any)
  • func (app *Application) Provide(provide ...any)
  • func (app *Application) Run(srv ...any)
• type Servicer

Variables

var LogPrivacyAttrKey = []string{
	"password",
	"token",
	"secretkey",
	"accesskey",
}

Functions

func Conf

func Conf() config.Provider

Conf 返回默认配置文件

func GetTraceID

func GetTraceID(c context.Context) string

func NewTraceSlogHandler

func NewTraceSlogHandler(w io.Writer, addSource bool, lvl slog.Leveler) slog.Handler

NewTraceSlogHandler 集成trace的slog handler

func SetConfig

func SetConfig(path string)

Types

type AppInfo

type AppInfo struct {
	// app name
	Name string
	// 描述
	Description string
	// 版本号
	Version string
}

type Application

type Application struct {
	// contains filtered or unexported fields
}

func New

func New(info AppInfo) *Application

func (*Application) CreateWebServer

func (app *Application) CreateWebServer(opts ...web.Option) *web.Server

func (*Application) Invoke

func (app *Application) Invoke(funcs ...any)

Invoke 注册调用

func (*Application) Provide

func (app *Application) Provide(provide ...any)

Provide 依赖注入构造器

func (*Application) Run

func (app *Application) Run(srv ...any)

type Servicer

type Servicer interface {
	Start(context.Context) error
	Stop(context.Context) error
}

Servicer 服务接口