{"id":13411036,"url":"https://github.com/golobby/config","last_synced_at":"2025-03-14T16:33:37.619Z","repository":{"id":40643489,"uuid":"215410533","full_name":"golobby/config","owner":"golobby","description":"A lightweight yet powerful configuration manager for the Go programming language","archived":false,"fork":false,"pushed_at":"2023-01-05T16:42:47.000Z","size":211,"stargazers_count":360,"open_issues_count":3,"forks_count":30,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-07-31T20:44:36.864Z","etag":null,"topics":["config","config-management","config-manager","configuration","configuration-files","configuration-management","configuration-manager","dot-env","dotenv","env","environment","environment-variables","go","golang","json-configuration","os-variables","toml","yaml","yaml-configuration"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/golobby.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-10-15T22:51:19.000Z","updated_at":"2024-06-23T13:46:40.000Z","dependencies_parsed_at":"2023-02-04T07:31:38.909Z","dependency_job_id":null,"html_url":"https://github.com/golobby/config","commit_stats":null,"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/golobby%2Fconfig","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/golobby%2Fconfig/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/golobby%2Fconfig/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/golobby%2Fconfig/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/golobby","download_url":"https://codeload.github.com/golobby/config/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243610711,"owners_count":20319013,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["config","config-management","config-manager","configuration","configuration-files","configuration-management","configuration-manager","dot-env","dotenv","env","environment","environment-variables","go","golang","json-configuration","os-variables","toml","yaml","yaml-configuration"],"created_at":"2024-07-30T20:01:10.984Z","updated_at":"2025-03-14T16:33:37.279Z","avatar_url":"https://github.com/golobby.png","language":"Go","readme":"[![Go Reference](https://pkg.go.dev/badge/github.com/golobby/config.svg)](https://pkg.go.dev/github.com/golobby/config)\n[![CI](https://github.com/golobby/config/actions/workflows/ci.yml/badge.svg)](https://github.com/golobby/config/actions/workflows/ci.yml)\n[![CodeQL](https://github.com/golobby/config/workflows/CodeQL/badge.svg)](https://github.com/golobby/config/actions?query=workflow%3ACodeQL)\n[![Go Report Card](https://goreportcard.com/badge/github.com/golobby/config)](https://goreportcard.com/report/github.com/golobby/config)\n[![Coverage Status](https://coveralls.io/repos/github/golobby/config/badge.svg)](https://coveralls.io/github/golobby/config?branch=master)\n[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)  \n\n# Config\nGoLobby Config is a lightweight yet powerful configuration manager for Go projects.\nIt takes advantage of Dot-env (.env) files and OS environment variables alongside config files (JSON, YAML, and TOML) to meet all of your requirements.\n\n## Documentation\n### Required Go Version\nIt requires Go `v1.16` or newer versions.\n\n### Installation\nTo install this package run the following command in the root of your project.\n\n```bash\ngo get github.com/golobby/config/v3\n```\n\n### Quick Start\nThe following example demonstrates how to use a JSON configuration file.\n\n```go\n// The configuration struct\ntype MyConfig struct {\n    App struct {\n        Name string\n        Port int\n    }\n    Debug      bool\n    Production bool\n    Pi         float64\n}\n\n// Create an instance of the configuration struct\nmyConfig := MyConfig{}\n\n// Create a feeder that provides the configuration data from a JSON file\njsonFeeder := feeder.Json{Path: \"config.json\"}\n\n// Create a Config instance and feed `myConfig` using `jsonFeeder`\nc := config.New()\nc.AddFeeder(jsonFeeder)\nc.AddStruct(\u0026myConfig)\nerr := c.Feed()\n\n// Or use method chaining:\n// err := config.New().AddFeeder(jsonFeeder).AddStruct(\u0026myConfig).Feed()\n\n// Use `myConfig`...\n```\n\n### Feeders\nFeeders provide the configuration data.\nThe GoLobby Config package supports the following feeders out of the box.\n\n* `Json`: It feeds using a JSON file.\n* `Yaml`: It feeds using a YAML file.\n* `Toml`: It feeds using a TOML file.\n* `DotEnv`: It feeds using a dot env (.env) file.\n* `Env`: It feeds using OS environment variables.\n\nYou can also create your custom feeders by implementing the `Feeder` interface or use third-party feeders.\n\n#### Json Feeder\nThe `Json` feeder uses Go built-in `json` package to load JSON files.\nThe snippet below shows how to use the `Json` feeder.\n\n```go\njsonFeeder := feeder.Json{Path: \"sample1.json\"}\nc := config.New().AddFeeder(jsonFeeder)\n```\n\n#### Yaml Feeder\nThe `Yaml` feeder uses the [YAML package](https://github.com/go-yaml/yaml) (v3) to load YAML files.\nThe snippet below shows how to use the `Yaml` feeder.\n\n```go\nyamlFeeder := feeder.Yaml{Path: \"sample1.yaml\"}\nc := config.New().AddFeeder(yamlFeeder)\n```\n\n#### Toml Feeder\nThe `Toml` feeder uses the [BurntSushi TOML package](https://github.com/BurntSushi/toml) to load TOML files.\nThe snippet below shows how to use the `Toml` feeder.\n\n```go\ntomlFeeder := feeder.Toml{Path: \"sample1.toml\"}\nc := config.New().AddFeeder(tomlFeeder)\n```\n\n#### DotEnv Feeder\nThe `DotEnv` feeder uses the [GoLobby DotEnv](https://github.com/golobby/dotenv) package to load `.env` files.\nThe example below shows how to use the `DotEnv` feeder.\n\nThe `.env` file: https://github.com/golobby/config/blob/v3/assets/.env.sample1\n\n```go\ntype MyConfig struct {\n    App struct {\n        Name string `env:\"APP_NAME\"`\n        Port int    `env:\"APP_PORT\"`\n    }\n    Debug      bool    `env:\"DEBUG\"`\n    Production bool    `env:\"PRODUCTION\"`\n    Pi         float64 `env:\"PI\"`\n    IDs        []int   `env:\"IDS\"`\n}\n\nmyConfig := MyConfig{}\ndotEnvFeeder := feeder.DotEnv{Path: \".env\"}\nerr := config.New().AddFeeder(dotEnvFeeder).AddStruct(\u0026myConfig).Feed()\n```\n\nYou must add a `env` tag for each field that determines the related dot env variable.\nIf there isn't any value for a field in the related file, it ignores the struct field.\nYou can read more about this feeder in the [GoLobby DotEnv](https://github.com/golobby/dotenv) package repository.\n\n#### Env Feeder\nThe `Env` feeder is built on top of the [GoLobby Env](https://github.com/golobby/env) package.\nThe example below shows how to use the `Env` feeder.\n\n```go\ntype MyConfig struct {\n    App struct {\n        Name string `env:\"APP_NAME\"`\n        Port int    `env:\"APP_PORT\"`\n    }\n    Debug      bool     `env:\"DEBUG\"`\n    Production bool     `env:\"PRODUCTION\"`\n    Pi         float64  `env:\"PI\"`\n    IPs        []string `env:\"IPS\"`\n    IDs        []int16  `env:\"IDS\"`\n}\n\n_ = os.Setenv(\"APP_NAME\", \"Shop\")\n_ = os.Setenv(\"APP_PORT\", \"8585\")\n_ = os.Setenv(\"DEBUG\", \"true\")\n_ = os.Setenv(\"PRODUCTION\", \"false\")\n_ = os.Setenv(\"PI\", \"3.14\")\n_ = os.Setenv(\"IPS\", \"192.168.0.1\", \"192.168.0.2\")\n_ = os.Setenv(\"IDS\", \"10, 11, 12, 13\")\n\nmyConfig := MyConfig{}\nenvFeeder := feeder.DotEnv{}\nerr := config.New().AddFeeder(envFeeder).AddStruct(\u0026myConfig).Feed()\n```\n\nYou must add a `env` tag for each field that determines the related OS environment variable name.\nIf there isn't any value for a field in OS environment variables, it ignores the struct field.\nYou can read more about this feeder in the [GoLobby Env](https://github.com/golobby/env) package repository.\n\n### Multiple Feeders\nOne of the key features in the GoLobby Config package is feeding using multiple feeders.\nLately added feeders overrides early added ones.\n\nThe example below demonstrates how to use a JSON file as the main configuration feeder and override the configurations with dot env and os variables.\n\n* JSON file: https://github.com/golobby/config/blob/v3/assets/sample1.json\n* DotEnv file: https://github.com/golobby/config/blob/v3/assets/.env.sample2\n* Env (OS) variables: Defined in the Go code!\n\n```go\ntype MyConfig struct {\n    App struct {\n        Name string `env:\"APP_NAME\"`\n        Port int    `env:\"APP_PORT\"`\n    }\n    Debug      bool    `env:\"DEBUG\"`\n    Production bool    `env:\"PRODUCTION\"`\n    Pi         float64 `env:\"PI\"`\n    IDs        []int32 `env:\"IDS\"`\n}\n\n_ = os.Setenv(\"PRODUCTION\", \"true\")\n_ = os.Setenv(\"APP_PORT\", \"6969\")\n_ = os.Setenv(\"IDs\", \"6, 9\")\n\nmyConfig := MyConfig{}\n\nfeeder1 := feeder.Json{Path: \"sample1.json\"}\nfeeder2 := feeder.DotEnv{Path: \".env.sample2\"}\nfeeder3 := feeder.Env{}\n\nerr := config.New().AddFeeder(feeder1, feeder2, feeder3).AddStruct(\u0026myConfig).Feed()\n\nfmt.Println(c.App.Name)   // Blog  [from DotEnv]\nfmt.Println(c.App.Port)   // 6969  [from Env]\nfmt.Println(c.Debug)      // false [from DotEnv]\nfmt.Println(c.Production) // true  [from Env]\nfmt.Println(c.Pi)         // 3.14  [from Json]\nfmt.Println(c.IDs)        // 6, 9  [from Env]\n```\n\nWhat happened?\n\n* The `Json` feeder as the first feeder sets all the struct fields from the JSON file.\n* The `DotEnv` feeder as the second feeder overrides existing fields.\n  The `APP_NAME` and `DEBUG` fields exist in the `.env.sample2` file.\n* The `Env` feeder as the last feeder overrides existing fields, as well.\n  The `APP_PORT` and `PRODUCTION` fields are defined in the OS environment.\n  \n### Setup Method\n\nThe `Setup()` method runs automatically after feeding.\nYou can use this method for post-processing logics.\n\n```go\ntype Region int\n\nconst (\n    Asia Region = iota\n    Europe\n    America\n    Else\n)\n\ntype Config struct {\n    RegionId int `env:\"REGION\"`\n    Region   Region\n}\n\nfunc (c *Config) Setup() error {\n    if fc.RegionId == 0 {\n        fc.Region = Asia\n    } else if fc.RegionId == 1 {\n        fc.Region = Europe\n    } else if fc.RegionId == 2 {\n        fc.Region = America\n    } else if fc.RegionId == 3 {\n        fc.Region = Else\n    } else {\n        return errors.New(\"invalid region\")\n    }\n    return nil\n}\n\n_ = os.Setenv(\"REGION\", \"2\")\n\nmyConfig := Config{}\nf := feeder.Env{}\n\nerr := config.New().AddFeeder(f).AddStruct(\u0026myConfig).Feed()\n\nfmt.Println(c.Region) // America (2)\n```\n\n### Re-feed\nYou can re-feed the structs every time you need to.\nJust call the `Feed()` method again.\n\n```go\nc := config.New().AddFeeder(feeder).AddStruct(\u0026myConfig)\nerr := c.Feed()\n\n// Is it time to re-feed?\nerr = c.Feed()\n\n// Use `myConfig` with updated data!\n```\n\n### Listener\nOne of the GoLobby Config features is the ability to update the configuration structs without redeployment.\nIt takes advantage of OS signals to handle this requirement.\nConfig instances listen to the \"SIGHUP\" operating system signal and refresh structs (call the `Feed()` method).\n\nTo enable the listener for a Config instance, you should call the `SetupListener()` method.\nIt gets a fallback function and calls it when the `Feed()` method fails and returns an error.\n\n```go\nc := config.New().AddFeeder(feeder).AddStruct(\u0026myConfig)\nc.SetupListener(func(err error) {\n    fmt.Println(err)\n})\n\nerr := c.Feed()\n```\n\nYou can send the `SIGHUP` signal to your running application with the following shell command.\n\n```shell script\nKILL -SIGHUP [YOUR-APP-PROCESS-ID]\n```\n\nYou can get your application process ID using the `ps` command.\n\n## See Also\n* [GoLobby/DotEnv](https://github.com/golobby/dotenv):\n  A lightweight package for loading dot env (.env) files into structs for Go projects\n* [GoLobby/Env](https://github.com/golobby/env):\n  A lightweight package for loading OS environment variables into structs for Go projects\n* [GoLobby/Container](https://github.com/golobby/container):\n  A lightweight yet powerful IoC dependency injection container for Go projects\n\n## License\nGoLobby Config is released under the [MIT License](http://opensource.org/licenses/mit-license.php).\n","funding_links":[],"categories":["配置","Go","Configuration","配置管理 `配置解析库`","Uncategorized","配置管理"],"sub_categories":["标准CLI","Standard CLI","Advanced Console UIs","标准 CLI"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgolobby%2Fconfig","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgolobby%2Fconfig","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgolobby%2Fconfig/lists"}