# cfg

**Repository Path**: pkg33/cfg

## Basic Information

- **Project Name**: cfg
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-24
- **Last Updated**: 2025-09-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Go配置管理库 (cfg)

一个简单易用的Go配置管理库，支持TOML格式的模块化配置管理，具有智能配置对比和独立模块使用特性。

## 特性

- 🚀 **简单易用**: 提供简洁的API接口
- 📦 **模块化**: 支持按模块管理配置
- 🔄 **独立使用**: 各模块可独立注册和使用，无需等待其他模块
- 🧠 **智能配置**: 自动对比默认配置与文件配置，智能选择配置源
- 📝 **TOML格式**: 使用TOML作为配置文件格式
- 🛡️ **类型安全**: 基于结构体的类型安全配置
- 🔧 **自动生成**: 无配置文件时自动生成默认配置文件
- 🔄 **配置同步**: 配置差异时自动更新配置文件

## 安装

```bash
go get gitee.com/pkg33/cfg
```

## 快速开始

### 1. 定义配置结构体

```go
// cmd/pkg/database/cfg.go
package database

import cfg "gitee.com/pkg33/cfg"

type DBCfg struct {
    Host     string `toml:"host"`
    Port     int    `toml:"port"`
    Username string `toml:"username"`
    Password string `toml:"password"`
    Database string `toml:"database"`
    MaxConns int    `toml:"max_conns"`
    Timeout  int    `toml:"timeout"`
}

var Cfg = &DBCfg{
    Host:     "localhost",
    Port:     3306,
    Username: "root",
    Password: "password",
    Database: "myapp",
    MaxConns: 100,
    Timeout:  30,
}

func Init() {
    cfg.MustRegister("database", Cfg)
}
```

### 2. 使用配置

```go
// cmd/main.go
package main

import (
    "fmt"
    "gitee.com/pkg33/cfg"
    "gitee.com/pkg33/cfg/cmd/pkg/database"
)

func main() {
    // 独立使用各模块配置（注册后立即可用）
    database.Init()
    dbCfg := cfg.Get("database").(*database.DBCfg)
    fmt.Printf("数据库: %s:%d/%s\n", dbCfg.Host, dbCfg.Port, dbCfg.Database)
    
    // 其他模块也可以独立使用
    // http.Init()
    // redis.Init()
}
```

### 3. 智能配置管理

配置库会自动处理以下场景：

- **无配置文件**: 自动生成默认配置文件
- **配置一致**: 使用内存中的默认配置（性能更好）
- **配置差异**: 使用文件配置覆盖默认配置，并更新配置文件

```go
// 各模块独立使用，无需统一加载
database.Init()  // 注册并自动处理配置
http.Init()     // 注册并自动处理配置  
redis.Init()    // 注册并自动处理配置
```

## API

### 核心函数

```go
// 注册模块配置并自动处理配置加载，失败则panic
func MustRegister(moduleName string, configInstance interface{})

// 加载配置，失败则panic（保持向后兼容）
func MustLoad()

// 获取模块配置
func Get(moduleName string) interface{}

// 生成默认配置文件
func GenerateDefaultConfig() error
```

### 配置管理器

```go
// 创建配置管理器
func NewCfgManager(configPath string) *CfgManager

// 获取全局配置管理器
func GetGlobalManager(configPath ...string) *CfgManager

// 注册模块配置并自动处理配置加载
func (cm *CfgManager) Register(moduleName string, configInstance interface{}) error

// 加载配置（保持向后兼容）
func (cm *CfgManager) Load() error

// 重新加载配置
func (cm *CfgManager) Reload() error
```

## 配置文件格式

配置文件使用TOML格式：

```toml
[database]
host = "localhost"
port = 3306
username = "root"
password = "password"
database = "myapp"
max_conns = 100
timeout = 30

[http]
host = "0.0.0.0"
port = 8080
read_timeout = 30
write_timeout = 30

[http.cors]
enabled = true
allow_origins = ["*"]
allow_methods = ["GET", "POST", "PUT", "DELETE"]

[redis]
addr = "localhost:6379"
password = ""
db = 0
pool_size = 10
```

## 完整示例

### 项目结构

```
cmd/
├── main.go
└── pkg/
    ├── database/
    │   └── config.go
    ├── http/
    │   └── config.go
    └── redis/
        └── config.go
cfg.toml
```

### 运行示例

```bash
cd cmd
go run main.go
```

输出示例：

```
数据库地址: localhost:3306
HTTP服务端口: 8080
Redis地址: localhost:6379, PoolSize: 10
```

## 高级特性

### 独立模块使用

各模块可以独立注册和使用，无需等待其他模块：

```go
// 模块A
database.Init()
dbCfg := cfg.Get("database").(*database.DBCfg)

// 模块B（可以独立使用）
http.Init()
httpCfg := cfg.Get("http").(*http.HTTPCfg)

// 模块C（可以独立使用）
redis.Init()
redisCfg := cfg.Get("redis").(*redis.RedisCfg)
```

### 智能配置对比

配置库会自动对比默认配置与文件配置：

- **配置一致**: 使用内存中的默认配置，性能更好
- **配置差异**: 使用文件配置覆盖默认配置，并更新配置文件
- **无配置文件**: 自动生成包含所有已注册模块的默认配置文件

### 嵌套结构体支持

支持复杂的嵌套结构体配置：

```go
type HTTPCfg struct {
    Host         string  `toml:"host"`
    Port         int     `toml:"port"`
    Cors         CorsCfg `toml:"cors"`
}

type CorsCfg struct {
    Enabled      bool     `toml:"enabled"`
    AllowOrigins []string `toml:"allow_origins"`
    AllowMethods []string `toml:"allow_methods"`
}
```

对应的TOML配置：

```toml
[http]
host = "0.0.0.0"
port = 8080

[http.cors]
enabled = true
allow_origins = ["*"]
allow_methods = ["GET", "POST", "PUT", "DELETE"]
```

## 注意事项

1. 配置实例必须是指针类型
2. 结构体字段需要使用 `toml` 标签
3. 默认配置文件名为 `cfg.toml`
4. 支持嵌套结构体配置
5. 各模块可独立使用，无需统一加载
6. 配置对比使用深度比较，确保准确性