go-common/docs/config.md

配置工具文档

概述

配置工具提供了从外部文件加载和管理应用配置的功能，支持数据库、OSS、Redis、CORS、MinIO、邮件、短信等常用服务的配置。

功能特性

• 支持从外部JSON文件加载配置
• 支持数据库配置（MySQL、PostgreSQL、SQLite）
• 支持OSS对象存储配置（阿里云、腾讯云、AWS、七牛云等）
• 支持Redis配置
• 支持CORS配置（与middleware包集成）
• 支持MinIO配置
• 支持邮件配置（SMTP）
• 支持短信配置（阿里云短信）
• 自动设置默认值
• 自动生成数据库连接字符串（DSN）
• 自动生成Redis地址

配置文件格式

配置文件采用JSON格式，支持以下配置项：

{
  "database": {
    "type": "mysql",
    "host": "localhost",
    "port": 3306,
    "user": "root",
    "password": "password",
    "database": "testdb",
    "charset": "utf8mb4",
    "maxOpenConns": 100,
    "maxIdleConns": 10,
    "connMaxLifetime": 3600
  },
  "oss": {
    "provider": "aliyun",
    "endpoint": "oss-cn-hangzhou.aliyuncs.com",
    "accessKeyId": "your-access-key-id",
    "accessKeySecret": "your-access-key-secret",
    "bucket": "your-bucket-name",
    "region": "cn-hangzhou",
    "useSSL": true,
    "domain": "https://cdn.example.com"
  },
  "redis": {
    "host": "localhost",
    "port": 6379,
    "password": "",
    "database": 0,
    "maxRetries": 3,
    "poolSize": 10,
    "minIdleConns": 5,
    "dialTimeout": 5,
    "readTimeout": 3,
    "writeTimeout": 3
  },
  "cors": {
    "allowedOrigins": ["*"],
    "allowedMethods": ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"],
    "allowedHeaders": ["Content-Type", "Authorization", "X-Requested-With", "X-Timezone"],
    "exposedHeaders": [],
    "allowCredentials": false,
    "maxAge": 86400
  },
  "minio": {
    "endpoint": "localhost:9000",
    "accessKeyId": "minioadmin",
    "secretAccessKey": "minioadmin",
    "useSSL": false,
    "bucket": "test-bucket",
    "region": "us-east-1",
    "domain": "http://localhost:9000"
  },
  "email": {
    "host": "smtp.example.com",
    "port": 587,
    "username": "your-email@example.com",
    "password": "your-email-password",
    "from": "your-email@example.com",
    "fromName": "Your App Name",
    "useTLS": true,
    "useSSL": false,
    "timeout": 30
  },
  "sms": {
    "accessKeyId": "your-aliyun-access-key-id",
    "accessKeySecret": "your-aliyun-access-key-secret",
    "region": "cn-hangzhou",
    "signName": "Your Sign Name",
    "templateCode": "SMS_123456789",
    "endpoint": "",
    "timeout": 10
  }
}

使用方法

1. 加载配置文件

import "github.com/go-common/config"

// 从文件加载配置（支持绝对路径和相对路径）
config, err := config.LoadFromFile("/path/to/config.json")
if err != nil {
    log.Fatal(err)
}

// 或者从字节数组加载
data := []byte(`{"database": {...}}`)
config, err := config.LoadFromBytes(data)

2. 获取数据库配置

// 获取数据库配置对象
dbConfig := config.GetDatabase()
if dbConfig != nil {
    fmt.Printf("Database: %s@%s:%d/%s\n", 
        dbConfig.User, dbConfig.Host, dbConfig.Port, dbConfig.Database)
}

// 获取数据库连接字符串（DSN）
dsn, err := config.GetDatabaseDSN()
if err != nil {
    log.Fatal(err)
}
// MySQL: "root:password@tcp(localhost:3306)/testdb?charset=utf8mb4&parseTime=True&loc=UTC"
// PostgreSQL: "host=localhost port=5432 user=root password=password dbname=testdb timezone=UTC sslmode=disable"
// 注意：数据库时间统一使用UTC时间

3. 获取OSS配置

ossConfig := config.GetOSS()
if ossConfig != nil {
    fmt.Printf("OSS Provider: %s\n", ossConfig.Provider)
    fmt.Printf("Endpoint: %s\n", ossConfig.Endpoint)
    fmt.Printf("Bucket: %s\n", ossConfig.Bucket)
}

4. 获取Redis配置

redisConfig := config.GetRedis()
if redisConfig != nil {
    fmt.Printf("Redis: %s:%d\n", redisConfig.Host, redisConfig.Port)
}

// 获取Redis地址（格式: host:port）
addr := config.GetRedisAddr()
// 输出: "localhost:6379"

5. 获取CORS配置

// 获取CORS配置（返回middleware.CORSConfig类型，可直接用于中间件）
corsConfig := config.GetCORS()

// 使用CORS中间件
import "github.com/go-common/middleware"
chain := middleware.NewChain(
    middleware.CORS(corsConfig),
)

6. 获取MinIO配置

minioConfig := config.GetMinIO()
if minioConfig != nil {
    fmt.Printf("MinIO Endpoint: %s\n", minioConfig.Endpoint)
    fmt.Printf("Bucket: %s\n", minioConfig.Bucket)
}

配置项说明

DatabaseConfig 数据库配置

字段	类型	说明	默认值
Type	string	数据库类型: mysql, postgres, sqlite	-
Host	string	数据库主机	-
Port	int	数据库端口	-
User	string	数据库用户名	-
Password	string	数据库密码	-
Database	string	数据库名称	-
Charset	string	字符集（MySQL使用）	utf8mb4
MaxOpenConns	int	最大打开连接数	100
MaxIdleConns	int	最大空闲连接数	10
ConnMaxLifetime	int	连接最大生存时间（秒）	3600
DSN	string	数据库连接字符串（如果设置，优先使用）	-

OSSConfig OSS配置

字段	类型	说明
Provider	string	提供商: aliyun, tencent, aws, qiniu
Endpoint	string	端点地址
AccessKeyID	string	访问密钥ID
AccessKeySecret	string	访问密钥
Bucket	string	存储桶名称
Region	string	区域
UseSSL	bool	是否使用SSL
Domain	string	自定义域名（CDN域名）

RedisConfig Redis配置

字段	类型	说明	默认值
Host	string	Redis主机	-
Port	int	Redis端口	6379
Password	string	Redis密码	-
Database	int	Redis数据库编号	0
MaxRetries	int	最大重试次数	3
PoolSize	int	连接池大小	10
MinIdleConns	int	最小空闲连接数	5
DialTimeout	int	连接超时时间（秒）	5
ReadTimeout	int	读取超时时间（秒）	3
WriteTimeout	int	写入超时时间（秒）	3
Addr	string	Redis地址（如果设置，优先使用）	-

CORSConfig CORS配置

字段	类型	说明	默认值
AllowedOrigins	[]string	允许的源	["*"]
AllowedMethods	[]string	允许的HTTP方法	["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"]
AllowedHeaders	[]string	允许的请求头	["Content-Type", "Authorization", "X-Requested-With", "X-Timezone"]
ExposedHeaders	[]string	暴露给客户端的响应头	[]
AllowCredentials	bool	是否允许发送凭证	false
MaxAge	int	预检请求的缓存时间（秒）	86400

MinIOConfig MinIO配置

字段	类型	说明
Endpoint	string	MinIO端点地址
AccessKeyID	string	访问密钥ID
SecretAccessKey	string	密钥
UseSSL	bool	是否使用SSL
Bucket	string	存储桶名称
Region	string	区域
Domain	string	自定义域名

EmailConfig 邮件配置

字段	类型	说明	默认值
Host	string	SMTP服务器地址	-
Port	int	SMTP服务器端口	587
Username	string	发件人邮箱	-
Password	string	邮箱密码或授权码	-
From	string	发件人邮箱地址（如果为空，使用Username）	Username
FromName	string	发件人名称	-
UseTLS	bool	是否使用TLS	false
UseSSL	bool	是否使用SSL	false
Timeout	int	连接超时时间（秒）	30

SMSConfig 短信配置（阿里云短信）

字段	类型	说明	默认值
AccessKeyID	string	阿里云AccessKey ID	-
AccessKeySecret	string	阿里云AccessKey Secret	-
Region	string	区域（如：cn-hangzhou）	cn-hangzhou
SignName	string	短信签名	-
TemplateCode	string	短信模板代码	-
Endpoint	string	服务端点（可选，默认使用区域端点）	-
Timeout	int	请求超时时间（秒）	10

完整示例

示例1：加载配置并使用

package main

import (
    "log"
    
    "github.com/go-common/config"
    "github.com/go-common/middleware"
    "gorm.io/driver/mysql"
    "gorm.io/gorm"
)

func main() {
    // 加载配置
    cfg, err := config.LoadFromFile("./config.json")
    if err != nil {
        log.Fatal(err)
    }

    // 使用数据库配置
    dsn, err := cfg.GetDatabaseDSN()
    if err != nil {
        log.Fatal(err)
    }
    
    db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{})
    if err != nil {
        log.Fatal(err)
    }

    // 使用Redis配置
    redisAddr := cfg.GetRedisAddr()
    fmt.Printf("Redis Address: %s\n", redisAddr)

    // 使用CORS配置
    corsConfig := cfg.GetCORS()
    chain := middleware.NewChain(
        middleware.CORS(corsConfig),
    )

    // 使用OSS配置
    ossConfig := cfg.GetOSS()
    if ossConfig != nil {
        fmt.Printf("OSS Provider: %s\n", ossConfig.Provider)
    }

    // 使用MinIO配置
    minioConfig := cfg.GetMinIO()
    if minioConfig != nil {
        fmt.Printf("MinIO Endpoint: %s\n", minioConfig.Endpoint)
    }
}

示例2：部分配置

配置文件可以只包含需要的配置项：

{
  "database": {
    "type": "mysql",
    "host": "localhost",
    "port": 3306,
    "user": "root",
    "password": "password",
    "database": "testdb"
  },
  "redis": {
    "host": "localhost",
    "port": 6379
  }
}

未配置的部分会返回nil，需要在使用前检查：

cfg, _ := config.LoadFromFile("./config.json")

dbConfig := cfg.GetDatabase()
if dbConfig != nil {
    // 使用数据库配置
}

ossConfig := cfg.GetOSS()
if ossConfig == nil {
    // OSS未配置
}

示例3：使用DSN字段

如果配置文件中直接提供了DSN，会优先使用：

{
  "database": {
    "type": "mysql",
    "dsn": "root:password@tcp(localhost:3306)/testdb?charset=utf8mb4&parseTime=True"
  }
}

dsn, err := cfg.GetDatabaseDSN()
// 直接返回配置中的DSN，不会重新构建

API 参考

LoadFromFile(filePath string) (*Config, error)

从文件加载配置。

参数：

• filePath: 配置文件路径（支持绝对路径和相对路径）

返回： 配置对象和错误信息

LoadFromBytes(data []byte) (*Config, error)

从字节数组加载配置。

参数：

• data: JSON格式的配置数据

返回： 配置对象和错误信息

(c *Config) GetDatabase() *DatabaseConfig

获取数据库配置。

返回： 数据库配置对象（可能为nil）

(c *Config) GetDatabaseDSN() (string, error)

获取数据库连接字符串。

返回： DSN字符串和错误信息

(c *Config) GetOSS() *OSSConfig

获取OSS配置。

返回： OSS配置对象（可能为nil）

(c *Config) GetRedis() *RedisConfig

获取Redis配置。

返回： Redis配置对象（可能为nil）

(c *Config) GetRedisAddr() string

获取Redis地址（格式: host:port）。

返回： Redis地址字符串

(c *Config) GetCORS() *middleware.CORSConfig

获取CORS配置，并转换为middleware.CORSConfig类型。

返回： CORS配置对象（如果配置为nil，返回默认配置）

(c *Config) GetMinIO() *MinIOConfig

获取MinIO配置。

返回： MinIO配置对象（可能为nil）

(c *Config) GetEmail() *EmailConfig

获取邮件配置。

返回： 邮件配置对象（可能为nil）

(c *Config) GetSMS() *SMSConfig

获取短信配置。

返回： 短信配置对象（可能为nil）

注意事项

1. 配置文件路径：

   • 支持绝对路径和相对路径
   • 相对路径基于当前工作目录

2. 默认值：

   • 配置加载时会自动设置默认值
   • 如果配置项为nil，对应的Get方法会返回nil

3. DSN优先级：

   • 如果配置中设置了DSN字段，会优先使用
   • 否则会根据配置项自动构建DSN

4. 配置验证：

   • 当前版本不进行配置验证，请确保配置正确
   • 建议在生产环境中添加配置验证逻辑

5. 安全性：

   • 配置文件可能包含敏感信息（密码、密钥等）
   • 建议将配置文件放在安全的位置，不要提交到版本控制系统
   • 可以使用环境变量或配置管理服务

6. 数据库时区：

   • 数据库时间统一使用UTC时间存储
   • DSN中会自动设置UTC时区（MySQL: loc=UTC, PostgreSQL: timezone=UTC）
   • 时区转换应在应用层处理，使用datetime工具包进行时区转换

配置文件示例

完整配置文件示例请参考 config/example.json