# flags

**Repository Path**: zhenghexcs/flags

## Basic Information

- **Project Name**: flags
- **Description**: Flags 是一个用于解析命令行参数和环境变量的 Go 库，支持通过结构体定义参数并自动解析。
- **Primary Language**: Go
- **License**: BSD-4-Clause
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-04-17
- **Last Updated**: 2025-08-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: flag

## README

# Flags Library

`Flags` 是一个用于解析命令行参数和环境变量的 Go 库，支持通过结构体定义参数并自动解析。

## 特性

- 支持命令行参数和环境变量的解析，**命令行参数优先级高于环境变量**。
- 支持多种数据类型：`int`、`uint`、`string`、`float64`、`bool`、`slice`。
- 支持通过结构体定义参数，简化参数管理。
- 支持默认值、参数描述、自动帮助信息。
- 兼容标准库 `flag`，易于集成到现有项目。
- 代码简洁，易于扩展。

## 安装

确保你的项目使用 Go 1.13 或更高版本。

```bash
go get gitee.com/zhenghexcs/flags
```

## 快速开始

### 1. 设置单个参数

使用 `SetFlag` 方法设置命令行参数和环境变量。

```go
package main

import (
    "fmt"
    "gitee.com/zhenghexcs/flags"
)

func main() {
    // 设置参数
    flags.SetFlag("port", "APP_PORT", "Server port", "8080")
    flags.SetFlag("debug", "APP_DEBUG", "Enable debug mode", "false")

    // 解析参数
    flags.Parse()

    // 获取参数值
    port := flags.GetFlagByInt("port")
    debug := flags.GetFlagByBool("debug")

    fmt.Printf("Port: %d, Debug: %v\n", port, debug)
}
```

运行程序时，可以通过命令行或环境变量传递参数：

```bash
APP_PORT=9090 go run main.go --port=8081 --debug=true
```

运行程序时输入 `-h` 查看帮助信息：

```bash
go run main.go -h
```

输出示例：

```
Usage of main:
  -debug string
        Enable debug mode (default "false")
  -port string
        Server port (default "8080")
```

**注意**：如果同时设置了环境变量和命令行参数，最终会使用命令行参数的值。例如：

```bash
APP_PORT=9090 go run main.go --port=8081
```

最终 `port` 的值为 `8081`，因为命令行参数的优先级高于环境变量。

### 2. 使用结构体定义参数

通过结构体定义参数，并使用 `SetFlagByStruct` 和 `LoadStruct` 方法自动解析。

```go
package main

import (
    "fmt"
    "gitee.com/zhenghexcs/flags"
)

type Config struct {
    Port  int      `flag:"Server port"`
    Debug bool     `flag:"Enable debug mode"`
    Hosts []string `flag:"Allowed hosts"`
}

func main() {
    config := &Config{
        Port:  8080,
        Debug: false,
        Hosts: []string{"localhost", "127.0.0.1"},
    }

    // 设置参数
    flags.SetFlagByStruct(config)

    // 解析参数
    flags.Parse()

    // 加载参数到结构体
    flags.LoadStruct(config)

    fmt.Printf("Config: %+v\n", config)
}
```

运行程序时，可以通过命令行或环境变量传递参数：

```bash
APP_PORT=9090 go run main.go --debug=true --hosts="example.com,localhost"
```

运行程序时输入 `-h` 查看帮助信息：

```bash
go run main.go -h
```

输出示例：

```
Usage of main:
  -debug string
        Enable debug mode (default "false")
  -hosts string
        Allowed hosts (default "localhost,127.0.0.1")
  -port string
        Server port (default "8080")
```

**注意**：如果同时设置了环境变量和命令行参数，最终会使用命令行参数的值。例如：

```bash
APP_PORT=9090 go run main.go --port=8081
```

最终 `config.Port` 的值为 `8081`。

### 3. 支持的数据类型

以下是支持的数据类型及对应的获取方法：

| 数据类型   | 命令行方法             | 环境变量方法         |
|------------|------------------------|----------------------|
| `int`      | `GetFlagByInt`         | `GetEnvByInt`        |
| `uint`     | `GetFlagByUint`        | `GetEnvByUint`       |
| `string`   | `GetFlagByString`      | `GetEnvByString`     |
| `float64`  | `GetFlagByFloat64`     | `GetEnvByFloat64`    |
| `bool`     | `GetFlagByBool`        | `GetEnvByBool`       |
| `[]string` | `GetFlagBySlice`       | `GetEnvBySlice`      |

### 4. 示例

#### 设置和获取单个参数

```go
flags.SetFlag("name", "APP_NAME", "Application name", "myapp")
flags.Parse()
name := flags.GetFlagByString("name")
fmt.Println("App Name:", name)
```

#### 使用结构体定义参数

```go
type AppConfig struct {
    Name string `flag:"Application name"`
}
config := &AppConfig{Name: "myapp"}
flags.SetFlagByStruct(config)
flags.Parse()
flags.LoadStruct(config)
fmt.Println("App Config:", config)
```

## 使用建议

- 推荐优先使用结构体方式统一管理参数，便于维护和扩展。
- 切片类型参数建议用英文逗号分隔，如 `--hosts="a.com,b.com"`。
- 支持通过环境变量和命令行参数混合配置，方便在不同环境下部署。

## 常见问题

- **参数优先级？**  
  命令行参数 > 环境变量 > 默认值。

- **如何自定义帮助信息？**  
  参数描述通过 `SetFlag` 的第三个参数或结构体 `flag` 标签指定。

- **支持哪些 Go 版本？**  
  Go 1.13 及以上。

## 贡献

欢迎提交 Issue 和 Pull Request 来改进此库。

## 许可证

BSD 4-Clause License