#moonfig

#目录

• 项目目标
• 功能特性
• 安装
• 快速开始
• 示例
• 开发路线图
• 文档
• 许可证

#项目目标

#功能特性

• 类型安全配置：复用 MoonBit 原生 derive(FromJson) 派生机制，支持提取到结构体。本库负责配置值到 Json 的映射和错误翻译，并对容易混淆的类型做额外检查，无需额外的代码生成器。
• 严格类型转换：取值与提取按声明类型进行检查，对常见的跨类型写法报错，避免隐式转换；唯一的加宽是整数→浮点（get_float），需要严格时用 get_float_strict。特定类型（如 BigInt、自定义 FromJson 等）则遵循其自身规则。
• 多格式支持：JSON、INI、dotenv、YAML、TOML、XML、CBOR 字节或自建的 Value 树都能作为来源，换格式不用改上层声明
• 自动发现格式：Detector 先认文件后缀，再看内容；无法判断时报 UnknownFormat 并列出候选后缀
• 热更新：build_live() 保留来源清单，Watcher::poll() 检测文件变化并替换快照；坏配置不会生效
• 多层来源：内存默认值、配置文件、环境变量、命令行参数按加入顺序叠加，后加的覆盖先加的
• 按键合并：后加入的来源只覆盖先加入来源的同名键，同名之外的键全部保留
• 错误信息明确：MissingKey / TypeMismatch / ParseError / UnknownFormat，错误消息包含键名、期望类型与实际类型
• 来源可追：origin_of / origins() 按路径反查来源，snapshot() 导出路径、值与来源；展示用的 label 按需生成
• 可校验：按键用规则表，结构体用 Validate，启动时一次暴露缺失、越界和未知键

#安装

moon add MuVirus/moonfig

import {
  "MuVirus/moonfig/core" @config,
  "MuVirus/moonfig/core/format/json_format" @jsonfmt,
}

别名显式写出来。 省略别名时 MoonBit 按目录名绑定，核心会变成 @core，实测能编译； 本项目统一写 @config / @jsonfmt，短，且目录再调整时用户的写法不用跟着改。

git clone https://github.com/MuVirus/moonfig.git
cd moonfig
moon update
moon test
moon run examples/multi_source -- --log-level=debug

#快速开始

using @config { type Config, type StringSource }
using @jsonfmt { type JsonFormat }

let cfg = Config::new()
  .add(StringSource::new("{\"db\":{\"host\":\"localhost\",\"port\":5432}}", JsonFormat::new()))
  .add(StringSource::new("{\"db\":{\"port\":6543}}", JsonFormat::new()))
  .build()

cfg.get_string("db.host")   // "localhost"   ← 第一个来源提供，未被覆盖
cfg.get_int("db.port")      // 6543          ← 第二个来源覆盖

#示例

#类型安全

using @config {type Config, type StringSource}
using @jsonfmt {type JsonFormat, extract_from}

let cfg = Config::new()
  .add(StringSource::new("{\"db\":{\"port\":\"5432\"}}", JsonFormat::new()))
  .build()

cfg.get_string("db.port")   // "5432"
cfg.get_int("db.port")      // 报错：key 'db.port': expected Int, got Str

struct TextPort {
  port : String
} derive(FromJson)

struct NumericPort {
  port : Int
} derive(FromJson)

let text : TextPort = extract_from(cfg, "db")       // port = "5432"
let numeric : NumericPort = extract_from(cfg, "db") // 报错：key 'db.port': expected Int, got Str

#按键取值

using @config {type Config, type MemorySource, type Value}

let cfg = Config::new()
  .add(
    MemorySource::new(
      Value::table({
        "db": Value::table({ "host": Value::str("localhost"), "port": Value::int(5432L) }),
        "debug": Value::bool(false),
        "ratio": Value::float(0.5),
      }),
    ),
  )
  .build()

cfg.get_string("db.host")        // "localhost"
cfg.get_int("db.port")           // 5432
cfg.get_bool("debug")            // false
cfg.get_float("ratio")           // 0.5
cfg.get_float("db.port")         // 5432.0，整数按浮点加宽
cfg.get_float_strict("db.port")  // 报错：expected Float, got Int

#多来源叠加

using @config {type Config, type StringSource}
using @jsonfmt {type JsonFormat}
using @inifmt {type IniFormat}
using @dotenvfmt {type DotenvFormat}

let cfg = Config::new()
  .add(StringSource::new("{\"db\":{\"host\":\"localhost\",\"port\":5432}}", JsonFormat::new())) // 默认值
  .add(StringSource::new("[db]\nport = 6000\n", IniFormat::new()))                              // 配置文件
  .add(StringSource::new("db.port=6543", DotenvFormat::new()))                                  // 环境覆盖
  .build()

cfg.get_string("db.host")   // "localhost"   只有第一个来源提供
cfg.get_int("db.port")      // 6543          最后加入的赢

#文件

import {
  "MuVirus/moonfig/file_source" @file_source,
}

using @config {type Config}
using @file_source {type FileSource}
using @jsonfmt {type JsonFormat}

let cfg = Config::new()
  .add(FileSource::new("config/app.json", JsonFormat::new()))
  .build()

#环境变量

import {
  "MuVirus/moonfig/env_source" @env_source,
}

using @config {type Config}
using @env_source {type EnvSource}

let cfg = Config::new()
  .add(EnvSource::new("APP_"))  // APP_DB_PORT=6543 → db.port
  .build()

#命令行参数

import {
  "MuVirus/moonfig/cli_source" @cli_source,
}

using @config {type Config}
using @cli_source {type CliSource, type CliValueStyle}

let cfg = Config::new()
  .add(
    CliSource::new()
      .with_value_style(CliValueStyle::Separate)  // --start 0
      .with_positional(0, "command")              // simulate
      .with_positional(1, "model")                // model.fmu
      .with_array("tag")                          // --tag a --tag b → ["a", "b"]
      .with_short_option("p", "db.port"),         // -p 5432
  )
  .build()

• 默认 CliValueStyle::Equals 只认 --key=value；Separate 只认 --key value。另一种写法报错，不静默忽略（Equals 下的 --key value 只是开关加位置参数）。
• 裸 --key 是布尔 true，--no-key 是 false；短选项要先登记，取值写法跟着风格走（-p=5432 或 -p 5432），布尔短选项可连写 -vq。
• .with_array("tag") 声明的路径写几次就收成数组；.with_positional(0, "command") 把第 0 个位置参数映射到键。
• 没声明成数组的重复键后写的赢；标量和层级互相挡路时报错。
• -- 之后全是位置参数；没映射的位置参数和没登记的短选项忽略。标签不带值，密码不会漏进日志。

#自动发现格式

using @config {type Config}
using @file_source {type FileSource}
using @format_detect {type Detector}
using @jsonfmt {type JsonFormat}
using @tomlfmt {type TomlFormat}
using @yamlfmt {type YamlFormat}

let detector = Detector::new([
  JsonFormat::new(),
  TomlFormat::new(),
  YamlFormat::new(),
])

let cfg = Config::new()
  .add(FileSource::auto("config/app.toml", detector))
  .build()

#热更新

using @config {type Config, type Rule}
using @file_source {type FileSource}
using @format_detect {type Detector}
using @jsonfmt {type JsonFormat}
using @hot_reload {type Watcher}

let live = Config::new()
  .add(FileSource::auto("config/app.json", Detector::new([JsonFormat::new()])))
  .build_live()

let watcher = @hot_reload.watch(
  live,
  interval=1000,
  on_change=fn(cfg) { println("port = \{cfg.get_int("db.port")}") },
  on_error=fn(error) { println("新配置没生效：\{error}") },
)

// 由调用方的定时器或事件循环调用；返回 true 表示检测到变化并尝试 reload
watcher.poll()

// 也可以手动重载并带校验规则
live.reload(rules=[Rule::int_range("db.port", 1L, 65535L)])
watcher.stop()

#来源追踪

using @config {type Config, type MemorySource, type Value}

let cfg = Config::new()
  .add(
    MemorySource::new(
      Value::table({ "db": Value::table({ "port": Value::int(5432L) }) }),
    ),
  )
  .build()

let origin = cfg.origin_of("db.port").unwrap()
origin.kind()           // SourceKind::Memory
origin.label()          // "memory"
origin.path().to_string() // "db.port"
cfg.origins()           // [Origin { ... }]，只列叶子路径
cfg.snapshot()          // [Entry { ... }]，路径、值、来源一起导出

#提取到结构体

using @jsonfmt {extract_from}

struct DbCfg {
  host : String
  port : Int
} derive(FromJson)

let db : DbCfg = extract_from(cfg, "db")

using @jsonfmt {extract_from, Int64Text}

struct OrderCfg {
  id : Int64Text
} derive(FromJson)

let order : OrderCfg = extract_from(cfg, "order")
order.id.to_int64()   // 9007199254740993，超出 Double 精确范围也不丢

#校验

using @config {type Rule}

cfg.validate([
  Rule::int_range("db.port", 1L, 65535L),
  Rule::one_of("log.level", ["debug", "info", "warn", "error"]),
  Rule::allowed_keys("db", ["host", "port"]),
])

using @jsonfmt {extract_validated_from}

impl @config.Validate for DbCfg with fn validate(self, prefix) {
  @config.check_int_range(prefix.add("port"), self.port.to_int64(), 1L, 65535L)
}

let db : DbCfg = extract_validated_from(cfg, "db")

#出错时

try {
  cfg.get_int("db.host")
} catch {
  e => println(e)
}

#开发路线图

#文档

• moon doc —— 生成 API 文档到 _build/doc/
• moon doc --serve —— 启动本地预览（默认 http://127.0.0.1:3000）
• examples/ —— 5 个可运行示例，索引里列了各自的运行命令
• moon coverage analyze -- -f summary —— 跑测试并打印覆盖率摘要
• docs/AGENTS.md —— 文档索引与写作规范
• docs/design/cli-args.md —— 命令行参数的解析设计
• docs/design/format-detect.md —— 自动发现格式的设计
• docs/design/hot-reload.md —— 热更新的设计

#许可证