contract

Documentation

Index

• Constants
• type App
• type CacheService
• type Config
• type DBConfig
  • func (conf *DBConfig) FormatDsn() (string, error)
• type DBOption
• type Distributed
• type Env
• type IDService
• type Kernel
• type Log
• type ORMService
• type RedisConfig
  • func (config *RedisConfig) UniqKey() string
• type RedisOption
• type RedisService
• type RememberFunc
• type Trace
• type TraceContext

Constants

const (
	// EnvProduction 代表生产环境
	EnvProduction = "prod"
	// EnvTesting 代表测试环境
	EnvTesting = "testing"
	// EnvDevelopment 代表开发环境
	EnvDevelopment = "dev"

	// EnvKey 是环境变量服务字符串凭证
	EnvKey = "nice:env"
)

const (
	TraceKeyTraceID  = "trace_id"
	TraceKeySpanID   = "span_id"
	TraceKeyCspanID  = "cspan_id"
	TraceKeyParentID = "parent_id"
	TraceKeyMethod   = "method"
	TraceKeyCaller   = "caller"
	TraceKeyTime     = "time"
)

const AppKey = "nice:app"

AppKey 定义字符串凭证

const CacheKey = "nice:cache"

const (
	// ConfigKey is config key in container
	ConfigKey = "nice:config"
)

const DistributedKey = "nice:distributed"

DistributedKey 定义字符串凭证

const IDKey = "nice:id"

const KernelKey = "nice:kernel"

const LogKey = "nice:log"

const ORMKey = "nice:orm"

ORMKey 代表 ORM的服务

const RedisKey = "nice:redis"

const TraceKey = "nice:trace"

Types

type App

type App interface {
	// AppID 表示当前这个app的唯一id, 可以用于分布式锁等
	AppID() string
	// Version 定义当前版本
	Version() string
	//BaseFolder 定义项目基础地址
	BaseFolder() string
	// ConfigFolder 定义了配置文件的路径
	ConfigFolder() string
	// LogFolder 定义了日志所在路径
	LogFolder() string
	// ProviderFolder 定义业务自己的服务提供者地址
	ProviderFolder() string
	// MiddlewareFolder 定义业务自己定义的中间件
	MiddlewareFolder() string
	// CommandFolder 定义业务定义的命令
	CommandFolder() string
	// RuntimeFolder 定义业务的运行中间态信息
	RuntimeFolder() string
	// TestFolder 存放测试所需要的信息
	TestFolder() string
	// AppFolder 定义业务代码所在的目录，用于监控文件变更使用
	AppFolder() string
	// LoadAppConfig 加载新的AppConfig，key为对应的函数转为小写下划线，比如ConfigFolder => config_folder
	LoadAppConfig(kv map[string]string)
}

App 定义接口

type CacheService

type CacheService interface {
	// Get 获取某个key对应的值
	Get(ctx context.Context, key string) (string, error)
	// GetObj 获取某个key对应的对象, 对象必须实现 https://pkg.go.dev/encoding#BinaryUnMarshaler
	GetObj(ctx context.Context, key string, model interface{}) error
	// GetMany 获取某些key对应的值
	GetMany(ctx context.Context, keys []string) (map[string]string, error)

	// Set 设置某个key和值到缓存，带超时时间
	Set(ctx context.Context, key string, val string, timeout time.Duration) error
	// SetObj 设置某个key和对象到缓存, 对象必须实现 https://pkg.go.dev/encoding#BinaryMarshaler
	SetObj(ctx context.Context, key string, val interface{}, timeout time.Duration) error
	// SetMany 设置多个key和值到缓存
	SetMany(ctx context.Context, data map[string]string, timeout time.Duration) error
	// SetForever 设置某个key和值到缓存，不带超时时间
	SetForever(ctx context.Context, key string, val string) error
	// SetForeverObj 设置某个key和对象到缓存，不带超时时间，对象必须实现 https://pkg.go.dev/encoding#BinaryMarshaler
	SetForeverObj(ctx context.Context, key string, val interface{}) error

	// SetTTL 设置某个key的超时时间
	SetTTL(ctx context.Context, key string, timeout time.Duration) error
	// GetTTL 获取某个key的超时时间
	GetTTL(ctx context.Context, key string) (time.Duration, error)

	// Remember 实现缓存的Cache-Aside模式, 先去缓存中根据key获取对象，如果有的话，返回，如果没有，调用RememberFunc 生成
	Remember(ctx context.Context, key string, timeout time.Duration, rememberFunc RememberFunc, model interface{}) error

	// Calc 往key对应的值中增加step计数
	Calc(ctx context.Context, key string, step int64) (int64, error)
	// Increment 往key对应的值中增加1
	Increment(ctx context.Context, key string) (int64, error)
	// Decrement 往key对应的值中减去1
	Decrement(ctx context.Context, key string) (int64, error)

	// Del 删除某个key
	Del(ctx context.Context, key string) error
	// DelMany 删除某些key
	DelMany(ctx context.Context, keys []string) error
}

CacheService 缓存服务

type Config

type Config interface {
	// IsExist 检查一个属性是否存在
	IsExist(key string) bool

	// Get 获取一个属性值
	Get(key string) interface{}
	// GetBool 获取一个bool属性
	GetBool(key string) bool
	// GetInt 获取一个int属性
	GetInt(key string) int
	// GetFloat64 获取一个float64属性
	GetFloat64(key string) float64
	// GetTime 获取一个time属性
	GetTime(key string) time.Time
	// GetString 获取一个string属性
	GetString(key string) string
	// GetIntSlice 获取一个int数组属性
	GetIntSlice(key string) []int
	// GetStringSlice 获取一个string数组
	GetStringSlice(key string) []string
	// GetStringMap 获取一个string为key，interface为val的map
	GetStringMap(key string) map[string]interface{}
	// GetStringMapString 获取一个string为key，string为val的map
	GetStringMapString(key string) map[string]string
	// GetStringMapStringSlice 获取一个string为key，数组string为val的map
	GetStringMapStringSlice(key string) map[string][]string

	// Load 加载配置到某个对象
	Load(key string, val interface{}) error
}

Config 定义了配置文件服务，读取配置文件，支持点分割的路径读取 例如: .Get("app.name") 表示从app文件中读取name属性 建议使用 yaml 属性, https://yaml.org/spec/1.2/spec.html

type DBConfig

type DBConfig struct {
	// 以下配置关于dsn
	WriteTimeout string `yaml:"write_timeout"` // 写超时时间
	Loc          string `yaml:"loc"`           // 时区
	Port         int    `yaml:"port"`          // 端口
	ReadTimeout  string `yaml:"read_timeout"`  // 读超时时间
	Charset      string `yaml:"charset"`       // 字符集
	ParseTime    bool   `yaml:"parse_time"`    // 是否解析时间
	Protocol     string `yaml:"protocol"`      // 传输协议
	Dsn          string `yaml:"dsn"`           // 直接传递dsn，如果传递了，其他关于dsn的配置均无效
	Database     string `yaml:"database"`      // 数据库
	Collation    string `yaml:"collation"`     // 字符序
	Timeout      string `yaml:"timeout"`       // 连接超时时间
	Username     string `yaml:"username"`      // 用户名
	Password     string `yaml:"password"`      // 密码
	Driver       string `yaml:"driver"`        // 驱动
	Host         string `yaml:"host"`          // 数据库地址

	// 以下配置关于连接池
	ConnMaxIdle     int    `yaml:"conn_max_idle"`     // 最大空闲连接数
	ConnMaxOpen     int    `yaml:"conn_max_open"`     // 最大连接数
	ConnMaxLifetime string `yaml:"conn_max_lifetime"` // 连接最大生命周期
	ConnMaxIdletime string `yaml:"conn_max_idletime"` // 空闲最大生命周期

	// 以下配置关于gorm
	*gorm.Config // 集成gorm的配置
}

DBConfig 代表数据库连接的所有配置

func (*DBConfig) FormatDsn

func (conf *DBConfig) FormatDsn() (string, error)

FormatDsn 生成dsn

type DBOption

type DBOption func(container framework.Container, config *DBConfig) error

DBOption 代表初始化的时候的选项

type Distributed

type Distributed interface {
	// Select 分布式选择器, 所有节点对某个服务进行抢占，只选择其中一个节点
	// ServiceName 服务名字
	// appID 当前的AppID
	// holdTime 分布式选择器hold住的时间
	// 返回值
	// selectAppID 分布式选择器最终选择的App
	// err 异常才返回，如果没有被选择，不返回err
	Select(serviceName string, appID string, holdTime time.Duration) (selectAppID string, err error)
}

Distributed 分布式服务

type Env

type Env interface {
	// AppEnv 获取当前的环境，建议分为development/testing/production
	AppEnv() string

	// IsExist 判断一个环境变量是否有被设置
	IsExist(string) bool
	// Get 获取某个环境变量，如果没有设置，返回""
	Get(string) string
	// All 获取所有的环境变量，.env和运行环境变量融合后结果
	All() map[string]string
}

Env 定义环境变量的获取服务

type IDService

type IDService interface {
	NewID() string
}

type Kernel

type Kernel interface {
	// HttpEngine 提供gin的Engine结构
	HttpEngine() http.Handler
}

Kernel 接口提供框架最核心的结构

type Log

type Log interface {
	GetZap() *zap.Logger
	Panic(msg string, fields ...zapcore.Field)
	Fatal(msg string, fields ...zapcore.Field)
	Error(msg string, fields ...zapcore.Field)
	Warn(msg string, fields ...zapcore.Field)
	Info(msg string, fields ...zapcore.Field)
	Debug(msg string, fields ...zapcore.Field)
	Trace(msg string, fields ...zapcore.Field)
}

Log 定义了日志服务协议

type ORMService

type ORMService interface {
	GetDB(option ...DBOption) (*gorm.DB, error)
}

ORMService 表示传入的参数

type RedisConfig

type RedisConfig struct {
	*redis.Options
}

RedisConfig 为nice定义的Redis配置结构

func (*RedisConfig) UniqKey

func (config *RedisConfig) UniqKey() string

UniqKey 用来唯一标识一个RedisConfig配置

type RedisOption

type RedisOption func(container framework.Container, config *RedisConfig) error

RedisOption 代表初始化的时候的选项

type RedisService

type RedisService interface {
	// GetClient 获取redis连接实例
	GetClient(option ...RedisOption) (*redis.Client, error)
}

RedisService 表示一个redis服务

type RememberFunc

type RememberFunc func(ctx context.Context, container framework.Container) (interface{}, error)

RememberFunc 缓存的Remember方法使用，Cache-Aside模式对应的对象生成方法

type Trace

type Trace interface {

	// WithTrace WithContext register new trace to context
	WithTrace(c context.Context, trace *TraceContext) context.Context
	// GetTrace From trace context
	GetTrace(c context.Context) *TraceContext
	// NewTrace generate a new trace
	NewTrace() *TraceContext
	// StartSpan generate cspan for child call
	StartSpan(trace *TraceContext) *TraceContext

	// ToMap traceContext to map for logger
	ToMap(trace *TraceContext) map[string]string

	// ExtractHTTP GetTrace By Http
	ExtractHTTP(req *http.Request) *TraceContext
	// InjectHTTP Set Trace to Http
	InjectHTTP(req *http.Request, trace *TraceContext) *http.Request
}

type TraceContext

type TraceContext struct {
	TraceID  string // traceID global unique
	ParentID string // 父节点SpanID
	SpanID   string // 当前节点SpanID
	CspanID  string // 子节点调用的SpanID, 由调用方指定

	Annotation map[string]string // 标记各种信息
}

TraceContext Trace define struct according Google Dapper