configmanager

README

go-config-manager

Per-app configuration stored as JSON in the user config directory. Zero dependencies.

---

For Users

Install

go get github.com/mesopix/go-config-manager

import "github.com/mesopix/go-config-manager"

Usage

tpl := map[string]any{"port": 8080, "debug": true}
c, err := configmanager.LoadAppConfig("myapp", tpl) // always returns a config
if err != nil { ... }

port, _ := c.Get("port")
c.Set("port", 9090)
if err := c.Save(); err != nil { ... }

The file lives at <user config dir>/myapp/config.json; on first run it is created from the template.

Note: JSON numbers come back as float64 from Get.

API Reference

Full API documentation is available on pkg.go.dev.

---

For Developers

Project Structure

.
├── config.go           # Core library: LoadAppConfig, Config, Get, Set, Save
├── config_test.go      # Tests
└── examples/
    └── demo/
        └── main.go     # Runnable demo

Single package at module root, zero external dependencies.

Development Guide

Run tests and static analysis:

go test -v ./...
go vet ./...

Tests use t.TempDir() and override AppData / XDG_CONFIG_HOME / HOME via t.Setenv, so they never touch real user config.

Design Decisions

• No auto-detection of executable name: Renaming the binary would silently create a new config file, losing previous settings. Test binaries would also use different config paths. Multiple binaries in the same project often share one config. The caller explicitly provides appName.
• Re-read after first save: On first run, LoadAppConfig writes the template to disk then reads it back. This ensures numeric types are always float64 (matching subsequent runs), avoiding subtle type mismatches between first and later launches.
• Atomic save: Save() writes to a temp file in the same directory, calls Sync() to flush to disk, then Renames over the target. A crash during save never leaves a half-written config.
• Zero dependencies: Only stdlib (encoding/json, os, path/filepath). Keeps the dependency tree minimal for a utility library.

Release Process

1. Ensure all tests pass: go test -v ./... && go vet ./...

2. Commit all changes to main.

3. Create and push a semantic version tag:

   git tag v0.x.y
   git push origin main --tags
   

4. pkg.go.dev will automatically pick up the new version within minutes.

⚠️ Published tags are immutable — never delete or move them. Use a new version number for any change.

Documentation

Overview

包 configmanager 是一个基于 JSON 文件的轻量级配置存储库。

Index

• type Config
  • func LoadAppConfig(appName string, template map[string]any) (*Config, error)
  • func (c *Config) Get(key string) (any, bool)
  • func (c *Config) Save() error
  • func (c *Config) Set(key string, value any)

Types

type Config

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

Config 持有以磁盘 JSON 文件为后端的配置值。

func LoadAppConfig

func LoadAppConfig(appName string, template map[string]any) (*Config, error)

LoadAppConfig 加载 appName 对应的配置。首次运行时从 template 创建配置文件， 因此除非发生 I/O 或解析错误，否则总会返回一个配置对象。 数值会从磁盘读回，所以类型统一为 float64。

func (*Config) Get

func (c *Config) Get(key string) (any, bool)

Get 返回 key 下存储的值以及它是否存在。 JSON 数值会被反序列化为 float64。

func (*Config) Save

func (c *Config) Save() error

Save 以原子方式把当前值写回 JSON 文件。 先写入临时文件并同步到磁盘，再重命名覆盖目标文件， 这样即使中途崩溃也不会留下写了一半的配置。

func (*Config) Set

func (c *Config) Set(key string, value any)

Set 将 value 存储到 key 下。