hdsdk

README

Enterprise ready, robust and easy extensible sdk which help to quickly develop backedn services.

SDK用户指南

SDK约定

SDK中支持的环境env定义

• local: 本地环境
• dev: 开发环境
• test: 测试环境
• pre: 预发布环境
• sim: 仿真环境
• prod: 生产环境

SDK能力介绍

• 日志 sdk.Log输出的时候第一个message参数必须要填，后续按照key/value的格式指定额外需要输出的信息，如果有错误信息，key必须指定为err e,g:

  sdk.Log.Debug("message content", "err", errors.New("testerr"), "key1", 1, "key2", "value2")
  

  支持的日志输出级别有:

  • sdk.Log.Trace
  • sdk.Log.Info
  • sdk.Log.Debug
  • sdk.Log.Warn
  • sdk.Log.Error
  • sdk.Log.Fatal
  • sdk.Log.Panic

• 数据库

  • MySQL: 请参考MySQL能力介绍

• 缓存

  • Redis: 请参考Redis能力介绍

• 消息队列

  • RabbitMq: 请参考RabbitMQ能力介绍
  • Kafka: 请参考Kafka能力介绍

SDK快速上手

下面是一个简单的使用hdsdk的数据库能力的示例，代码非常简单，但支持多环境多配置源初始化加载各种配置项，同时数据库支持主备或指定数据库源

type rootConf struct {
    sdk.Config `mapstructure:",squash"`
}

var config rootConf
err := hdsdk.NewConfig("app", "test").Load(&config)
if err != nil {
    utils.LogFatal("load config", "err", err)
}

err = hdsdk.Initialize(config)
if err != nil {
    utils.LogFatal("sdk initialize", "err", err)
}

var total int64
err = hdsdk.Mysql.My().Get(&total, `SELECT COUNT(1) FROM table`)
if err != nil  {
	hdsdk.Logger.Error("db get total", "err", err)
}

SDK初始化

第一步：定义配置结构体

1. 通常我们必须通过自定义一个继承自sdk.Config的结构体来包括sdk配置信息。这里请注意，sdk.Config的tag必须要加上mapstructure:",squash"tag, 因为sdk配置能力底层是通过viper来实现，而viper是通过mapstructure这个库进行配置信息的encode/decode的，加上这个tag告诉viper在读取配置信息的时候将该结构体的字段作为提升到父结构中

type rootConf struct {
    sdk.Config `mapstructure:",squash"`
    // 其他的配置项
    ...
}

1. 其他配置项可以定义在结构体的其他地方并支持嵌套，注意一定要用mapstructuretag来定义和配置文件中一致的配置项名字, e,g: mapstructure:"debug"

type conf struct {
	sdk.Config  `mapstructure:",squash"`
	App confApp `mapstructure:"app"`
}

type confApp struct {
	Debug bool    `mapstructure:"debug"`
	Wxmp confWxmp `mapstructure:"wxmp"`
}

type confWxmp struct {
	AppId string `mapstructure:"app_id"`
}

第二步： 生成配置文件

sdk段落中的全部为sdk自身能力的配置项，例如Etcd能力，Redis能力，MySQL能力，其他的段落可以用来为应用程序进行个性化的定制， 例如：

[sdk]
    [sdk.log]
        # 当前支持日志级别: "trace", "debug", "info", "warn", "error", "fatal", "panic"
        level = "debug"
        # 日志文件名称
        filename = "base.log"
        # 日志结转配置
        [sdk.log.rotate]
            # 日志最大保存时间7天(单位hour)
            max_age = 720
            # 日志切割时间间隔24小时（单位hour)
            rotation_time=24
    [sdk.etcd]
        url = "http://192.168.1.1:2379"
    [sdk.mysql]
        [sdk.mysql.default]
            database = "hdmall_base"
            user = "root"
            host = "127.0.0.1"
            password = ""
            port = 3306
    [sdk.redis.default]
            host = "127.0.0.1"
            port = 6379
            password = ""
            db = 0

[app]
    debug=false
    # 微信小程序
    [app.wxmp]
        app_id="xxxxxxxxxxxxxx"

第三步：加载并实例化配置

1. 通常我们使用Load()函数来加载配置，Load()函数会先尝试加载本地配置，默认行为会在某些环境下会再尝试加载远程配置
2. 相同配置项优先级从高到低为：

• 环境配置（高）
• 文件配置（中）
• 远程配置（低）

同一个配置变量如果在多个配置源中出现，最终生效的为高优先级配置源中的值, 例如文件配置中app.wxmp.app_id=1，远程配置中app.wxmp.app_id=0, 那么最终生效的值为0 3. 一般来说，我们会指定环境env，如果env为空，则默认加载仅包含日志配置的最小配置

var Config conf
err := NewConfig("test", "local").Load(&Config)
if err != nil {
    utils.LogFatal("sdk initialize", "err", err)
}

在代码中，我们通过NewConfig(app, env)实例化再通过Load()或LoadLocal()或LoadRemote()函数加载应用程序的所有配置信息，然后unmarshal成我们自定义的配置结构实例

• app: 加载配置的时候必须指定应用的名字
• env: 加载什么环境的配置, 可以为空，如果为空，仅初始化日志配置
• args: 通过不同选项函数来自定义加载配置的行为

var Config conf
err := NewConfig("test", "local").Load(&Config)
if err != nil {
    utils.LogFatal("sdk initialize", "err", err)
}

配置实例化时可以通过不同的选项函数改变默认行为，例如下面就指定了加载指定的配置文件

options := make([]hdsdk.ConfigOption, 0)
if configFile != "" {
    options = append(options, hdsdk.WithConfigFile(configFile))
}

var Config conf
err := NewConfig("test", "local", options...).Load(&Config)
if err != nil {
    utils.LogFatal("sdk initialize", "err", err)
}

要开启远程配置能力，必须在Load()时候指定第二个参数为远程配置变量，并且env不为空或者local， 两个条件缺一远程配置能力都不会初始化

var Config conf
var RemoteConfig remoteConf 
err := NewConfig("test", "test", options...).Load(&Config, &RemoteConfig)
if err != nil {
    utils.LogFatal("sdk initialize", "err", err)
}

我们可以直接调用hdsdk的UpdateRemoteConfig方法更新远程配置数据, 不过要注意此时hdsdk需要初始化完毕, 例如：

RemoteConfig.xxx.yyy = "xxx"

err := hdsdk.UpdateRemoteConfig(RemoteConfig)
if err != nil  {
    utils.LogFatal("update remote config", "err", err)
}

第四步：初始化SDK

在我们获取到实例化的配置后，我们需要通过读取已经实例化好的配置来初始化SDK的各项能力

err = sdk.Initialize(&conf)
if err != nil {
    log.Fatalf("msg=\"sdk initialize\" error=\"%v\"", err)
}

配置参考

1. 配置类型

• 默认配置文件类型为toml类型，可以NewConfig()的时候通过WithConfigType()选项函数来改变
• 相关函数
• WithConfigType()： 指定配置文件的类型，支持类型同viper的支持类型，默认为toml

1. 远程配置

• 除无环境和local环境外，运行Load()函数会默认加载远程配置，默认行为可以NewConfig()的时候通过WithDisableRemoteEnvs()选项函数来改变
• 加载远程配置时会优先以本地配置sdk.etcd.url定义的值来加载远程配置，如果无sdk.etcd.url本地配置默认使用URL: http://127.0.0.1:2379
• 远程配置加载成功，默认开启远程配置监控，如果远程配置项有变化，30秒钟后生效。该默认行为可以NewConfig()的时候通过WithWatch()选项函数来改变
• 可以单独使用LoadRemote()函数来仅加载远程配置而忽略本地配置，注意这个时候本地配置的sdk.etcd.url不生效，默认从http://127.0.0.1:2379加载，默认行为可以NewConfig()的时候通过WithRemote()选项函数来改变
• 远程配置默认保存在/setting/app/<app>key下面，该默认行为可以NewConfig()的时候通过WithRemote()选项函数来改变
• 相关函数
  • WithRemote()： 定义远程配置提供者的信息
  • WithDisableRemoteEnvs()： 定义在哪些环境不开启远程配置功能
  • WithWatch()： 用来开关远程配置监控以及定义远程配置更改生效时间

1. 本地配置

• 可以单独使用LoadLocal()函数仅获取本地配置， 例如从本地配置文件和环境变量中加载配置， 注意这个时候不会处理远程配置
• 默认从当前目录以及当前目录的上级目录下搜索setting/app/<app>/<app>.<env>.toml， 默认搜索条件可以NewConfig()的时候通过WithConigDir()和WithConfigFilename()选项函数来改变
• 如果需要指定配置文件，可以NewConfig()的时候通过WithConfigFile()选项函数来指定, 注意这个时候不会进行配置文件智能搜索
• 相关函数
  • WithConfigDir()： 增加智能搜索的目录，可以有多个，搜索的时候会自动加入指定目录和指定目录的上级目录
  • WithConfigFilename()： 在指定的目录下搜索文件名，不需要带文件名后缀

1. 测试用例配置

有时候我们在单元测试的时候缺少缺少配置文件，我们可以尝试直接定义配置内容并读取加载

const configTestMysql = `
[sdk]
    [sdk.log]
        filename = "demo.log"
        [sdk.log.rotate]
            # 最大保存时间7天(单位hour)
            max_age = 168
            # 日志切割时间间隔24小时（单位hour)
            rotation_time=24
    [sdk.mysql]
        [sdk.mysql.default]
            database = "mysql"
            user = "root"
            password = ""
            host = "127.0.0.1"
            port = 3306

var conf testConf
err := NewConfig("test", "local").ReadString(configTestMysql).Load(&conf)
if err != nil {
    utils.LogFatal("sdk initialize", "err", err)
}

Documentation

Overview

Package hdsdk 提供各类底层能力的直接访问方式，SDK包在使用前必须要初始化

首先必须创建一个继承自sdk.BaseConfig的配置struct e,g:

   import hdget

		type XXXConfig struct {
			*sdk.Config `mapstructure:",squash"`
     }

Index

• Variables
• func Initialize(configer types.Configer) error
• func UpdateRemoteConfig(v any) error
• type Config
  • func (c *Config) GetEtcdConfig() interface{}
  • func (c *Config) GetGraphConfig() interface{}
  • func (c *Config) GetKafkaConfig() interface{}
  • func (c *Config) GetLogConfig() interface{}
  • func (c *Config) GetMysqlConfig() interface{}
  • func (c *Config) GetNosqlConfig() interface{}
  • func (c *Config) GetRabbitmqConfig() interface{}
  • func (c *Config) GetRedisConfig() interface{}
• type ConfigOption
  • func WithConfigDir(args ...string) ConfigOption
  • func WithConfigFile(filepath string) ConfigOption
  • func WithConfigFilename(filename string) ConfigOption
  • func WithConfigType(configType string) ConfigOption
  • func WithDisableRemoteEnvs(args ...string) ConfigOption
  • func WithEnvPrefix(envPrefix string) ConfigOption
  • func WithRemote(provider, url, path string) ConfigOption
  • func WithRoot(args ...string) ConfigOption
  • func WithWatch(enabled bool, effectDelay int) ConfigOption
• type OptionFile
• type OptionRemote
• type OptionWatch
• type SdkProvider
• type ViperConfig
  • func NewConfig(app, env string, options ...ConfigOption) *ViperConfig
  • func (c *ViperConfig) Load(configVars ...any) error
  • func (c *ViperConfig) LoadLocal(localConfigVar any) error
  • func (c *ViperConfig) LoadRemote(remoteConfigVar any) error
  • func (c *ViperConfig) Read(data []byte) *ViperConfig
  • func (c *ViperConfig) ReadString(s string) *ViperConfig

Variables

var (
	Logger   types.LogProvider   // 日志能力
	Mysql    types.DbProvider    // mysql数据库能力
	Redis    types.CacheProvider // redis缓存能力
	Rabbitmq types.MqProvider    // rabbitmq能力
	Kafka    types.MqProvider    // kafka能力
	Neo4j    types.GraphProvider // 图数据库能力
	Etcd     types.KvProvider    // kv能力
)

var (
	LogProvider = &SdkProvider{
		Kind:     types.SdkCategoryLog,
		Name:     "log",
		Instance: &log.LoggerImpl{},
	}
)

Functions

func Initialize

func Initialize(configer types.Configer) error

Initialize 初始化SDK, 指定的配置文件里面有什么配置就配置什么能力

func UpdateRemoteConfig

func UpdateRemoteConfig(v any) error

UpdateRemoteConfig 更新远程配置 nolint: staticcheck

Types

type Config

type Config struct {
	Sdk *types.SdkConfigItem `mapstructure:"sdk"`
}

func (*Config) GetEtcdConfig

func (c *Config) GetEtcdConfig() interface{}

GetEtcdConfig 获取etcd配置

func (*Config) GetGraphConfig

func (c *Config) GetGraphConfig() interface{}

GetGraphConfig 获取图数据库配置

func (*Config) GetKafkaConfig

func (c *Config) GetKafkaConfig() interface{}

GetKafkaConfig 获取Kafka消息队列配置

func (*Config) GetLogConfig

func (c *Config) GetLogConfig() interface{}

GetLogConfig 获取日志配置

func (*Config) GetMysqlConfig

func (c *Config) GetMysqlConfig() interface{}

GetMysqlConfig 获取数据库配置

func (*Config) GetNosqlConfig

func (c *Config) GetNosqlConfig() interface{}

GetNosqlConfig 获取非SQL配置

func (*Config) GetRabbitmqConfig

func (c *Config) GetRabbitmqConfig() interface{}

GetRabbitmqConfig 获取消息队列配置

func (*Config) GetRedisConfig

func (c *Config) GetRedisConfig() interface{}

GetRedisConfig 获取缓存配置

type ConfigOption

type ConfigOption func(config *ViperConfig)

func WithConfigDir

func WithConfigDir(args ...string) ConfigOption

func WithConfigFile

func WithConfigFile(filepath string) ConfigOption

func WithConfigFilename

func WithConfigFilename(filename string) ConfigOption

func WithConfigType

func WithConfigType(configType string) ConfigOption

func WithDisableRemoteEnvs

func WithDisableRemoteEnvs(args ...string) ConfigOption

func WithEnvPrefix

func WithEnvPrefix(envPrefix string) ConfigOption

func WithRemote

func WithRemote(provider, url, path string) ConfigOption

func WithRoot

func WithRoot(args ...string) ConfigOption

func WithWatch

func WithWatch(enabled bool, effectDelay int) ConfigOption

type OptionFile

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

type OptionRemote

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

type OptionWatch

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

type SdkProvider

type SdkProvider struct {
	Kind     types.SdkType  // 底层能力类型
	Name     string         // 底层能力名字
	Instance types.Provider // 底层能力实现实例
}

SdkProvider 底层能力实例

type ViperConfig

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

ViperConfig 命令行配置

func NewConfig

func NewConfig(app, env string, options ...ConfigOption) *ViperConfig

NewConfig args[0]为env

func (*ViperConfig) Load

func (c *ViperConfig) Load(configVars ...any) error

func (*ViperConfig) LoadLocal

func (c *ViperConfig) LoadLocal(localConfigVar any) error

LoadLocal 从各个配置源获取配置数据, 并加载到configVar中， 同名变量配置高的覆盖低的 - remote: kvstore配置（低） - configFile: 文件配置(中） - env: 环境变量配置(高)

func (*ViperConfig) LoadRemote

func (c *ViperConfig) LoadRemote(remoteConfigVar any) error

func (*ViperConfig) Read

func (c *ViperConfig) Read(data []byte) *ViperConfig

func (*ViperConfig) ReadString

func (c *ViperConfig) ReadString(s string) *ViperConfig