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

Create a default_config.json template file and embed it:

//go:embed default_config.json
var defaultConfigJSON []byte

c, err := configmanager.LoadAppConfig("myapp", defaultConfigJSON) // 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 embedded JSON 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/
        ├── default_config.json  # Embedded default config template
        └── 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 embedded JSON defaults 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

• Constants
• type CheckResult
• type Config
  • func LoadAppConfig(appName string, defaultJSON []byte) (*Config, error)
  • func (c *Config) DeclaredVersion() string
  • func (c *Config) Get(key string) (any, bool)
  • func (c *Config) Meta() map[string]any
  • func (c *Config) ResolveVersion(schemaVersion string)
  • func (c *Config) ResolvedVersion() string
  • func (c *Config) Save() error
  • func (c *Config) Set(key string, value any)
• type FieldDef
• type FieldType
• type Schema
  • func ParseSchema(data []byte) (Schema, error)
  • func (s Schema) Check(data map[string]any) CheckResult
  • func (s Schema) Normalize(data map[string]any) (map[string]any, error)
• type SchemaFile
  • func ParseSchemaFile(data []byte) (*SchemaFile, error)
• type SchemaMeta

Constants

const UnknownVersion = "UNKNOWN"

UnknownVersion 表示无法识别的数据版本号。

Types

type CheckResult

type CheckResult int

CheckResult 表示 data 相对于 schema 的校验状态。

const (
	Valid           CheckResult = iota // 严格符合 schema
	MissingDefaults                    // 仅缺少带默认值的非必填字段
	ExtraFields                        // 仅有 schema 未定义的多余字段
	MissingAndExtra                    // 既缺带默认值的字段，又有多余字段
	Invalid                            // 必填缺失或类型不匹配
)

type Config

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

Config 持有以磁盘 JSON 文件为后端的配置值。 data 存储完整的 {meta, fields} 两层结构。

func LoadAppConfig

func LoadAppConfig(appName string, defaultJSON []byte) (*Config, error)

LoadAppConfig 加载 appName 对应的配置。首次运行时从 defaultJSON 创建配置文件， 因此除非发生 I/O 或解析错误，否则总会返回一个配置对象。 defaultJSON 应为合法的 JSON 对象（如通过 //go:embed 嵌入的模板文件）。 数值会从磁盘读回，所以类型统一为 float64。

func (*Config) DeclaredVersion

func (c *Config) DeclaredVersion() string

DeclaredVersion 返回 config.json 中声明的数据版本号。 无法识别时返回 UnknownVersion。

func (*Config) Get

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

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

func (*Config) Meta

func (c *Config) Meta() map[string]any

Meta 返回 data 中 "meta" 层的 map（只读访问）。

func (*Config) ResolveVersion

func (c *Config) ResolveVersion(schemaVersion string)

ResolveVersion 在 schema 校验通过后调用，将 resolvedVersion 设为 schema 的 meta.version。若 schemaVersion 为空则设为 UnknownVersion。

func (*Config) ResolvedVersion

func (c *Config) ResolvedVersion() string

ResolvedVersion 返回经 schema 校验后确定的实际数据版本号。 未经校验或无法识别时返回 UnknownVersion。

func (*Config) Save

func (c *Config) Save() error

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

func (*Config) Set

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

Set 将 value 存储到 fields 层的 key 下。

type FieldDef

type FieldDef struct {
	Type     FieldType
	Required bool
	Default  any // nil 表示无默认值；仅当 Required 为 false 时有意义
}

FieldDef 描述一个配置键：期望类型、是否必填，以及可选的默认值（仅在非必填时生效）。

type FieldType

type FieldType int

FieldType 表示配置字段期望的 JSON 类型。

const (
	TypeString FieldType = iota // JSON 字符串
	TypeFloat                   // JSON 数值（float64）
	TypeBool                    // JSON 布尔值
	TypeArray                   // JSON 数组
	TypeObject                  // JSON 对象
)

type Schema

type Schema map[string]FieldDef

Schema 是以配置键名为索引的字段定义集合。 它有意独立于 Config，使调用方自行掌控 schema 与校验生命周期。

func ParseSchema

func ParseSchema(data []byte) (Schema, error)

ParseSchema 从 JSON 字节中解析出 Schema（仅提取 fields 部分）。 客户端可通过返回的 SchemaFile 访问 meta 信息。

func (Schema) Check

func (s Schema) Check(data map[string]any) CheckResult

Check 只读检查 data 相对于 schema 的状态，不修改 data。

func (Schema) Normalize

func (s Schema) Normalize(data map[string]any) (map[string]any, error)

Normalize 返回 data 的规范化副本：补全缺失的默认值，删除多余字段。 原 data 不会被修改。仅当 Check 结果为 MissingDefaults / ExtraFields / MissingAndExtra 时才能成功转换；其他状态返回 error。

type SchemaFile

type SchemaFile struct {
	Meta   SchemaMeta          `json:"meta"`
	Fields map[string]FieldDef `json:"fields"`
}

SchemaFile 是 schema.json 的顶层结构，将元数据与字段定义分组。

func ParseSchemaFile

func ParseSchemaFile(data []byte) (*SchemaFile, error)

ParseSchemaFile 从 JSON 字节中解析出完整的 SchemaFile（含 meta）。

type SchemaMeta

type SchemaMeta struct {
	Version string `json:"version"`
}

SchemaMeta 是 schema 文件的元数据部分，由客户端自行填充。