#MoonFlagKit

#核心特性

• 布尔开关与多变体实验 (Multivariate Flags)：支持基础的 Boolean 开关，同时支持定义多个 Variant（如 control, treatment_red, treatment_blue）并进行自定义重量级配比分桶。
• 富运算符匹配规则 (Rich Operators)：支持强大的属性与上下文过滤。运算符包含：Eq (等于), Ne (不等于), Gt (大于), Lt (小于), Ge (大于等于), Le (小于等于), Contains (包含子串), In (列表内), NotIn (列表外)。
• 决策审计日志 (Audit Trail)：在评估每个 Flag 时，会完整地在 Decision 中记录详尽的审计 trace，方便调试与审计决策路径。
• 配置服务提供者 (Config Provider)：内置了基于标准 @json 的 JsonConfigProvider，支持直接从 JSON 格式的配置文件中加载复杂的 Flag、Variant 以及 Rules。
• 稳健的分桶哈希算法：采用确定性的哈希算法进行 Subject 分桶分发，确保在相同 Salt 和 Subject 下分桶的高稳定性与一致性。
• 配置有效性自检 (Diagnostics)：自检诊断功能可以快速发现命名冲突、不合法的 rollout 比例以及多变体权重之和不为 100 等配置问题。

#公共 API

• evaluate(flag, context) -> Decision：评估单个功能的开关状态。
• evaluate_all(flags, context) -> Array[Decision]：批量评估一组开关状态。
• explain(decision) -> String：格式化输出带有审计日志的决策结果。
• validate_flags(flags) -> Array[FlagDiagnostic]：诊断自检 Flag 列表。
• JsonConfigProvider::new(json_string)：创建 JSON 开关配置源提供者。
• parse_flags(input)：解析行导向的简易文本配置（适配兼容旧版格式，支持多变体规则扩展）。

#核心代码示例

let promo_flag : @moonflagkit.Flag = {
  name: "promo_banner",
  enabled: true,
  default_enabled: false,
  rollout: 100,
  salt: "promo_salt",
  rules: [
    @moonflagkit.AllowVariant("vip_user", "treatment_b"),
    @moonflagkit.WhenVariant("plan", In, "pro,enterprise", "treatment_a")
  ],
  is_multivariate: true,
  variants: [
    { name: "control", weight: 50 },
    { name: "treatment_a", weight: 30 },
    { name: "treatment_b", weight: 20 }
  ],
  default_variant: "control"
}

let context : @moonflagkit.EvalContext = {
  subject: "user_bob",
  environment: "production",
  attributes: [
    { key: "plan", value: "pro" }
  ]
}

let decision = @moonflagkit.evaluate(promo_flag, context)
println(@moonflagkit.explain(decision))

#JSON 配置文件格式

{
  "flags": [
    {
      "name": "multivariate_promo_banner",
      "enabled": true,
      "default_enabled": false,
      "rollout": 100,
      "salt": "promo_salt",
      "is_multivariate": true,
      "default_variant": "control",
      "variants": [
        { "name": "control", "weight": 50 },
        { "name": "treatment_red", "weight": 30 },
        { "name": "treatment_blue", "weight": 20 }
      ],
      "rules": [
        { "type": "AllowVariant", "subject": "vip_user_1", "variant": "treatment_blue" },
        { "type": "WhenVariant", "key": "plan", "op": "In", "value": "pro,enterprise", "variant": "treatment_red" }
      ]
    }
  ]
}

#本地开发与指令自查

# 对项目进行类型检查
moon check

# 代码格式化自检
moon fmt --deny-warn

# 自动生成公共接口 .mbti 自检
moon info --deny-warn

# 运行所有单元与集成测试
moon test

# 运行 CLI 演示程序
moon run cmd/main

#平台仓库链接

• GitHub: https://github.com/q0w1ertyuiop/MoonFlagKit
• GitLink: https://www.gitlink.org.cn/a18265059561/MoonFlagKit
• Mooncakes 注册包: q0w1ertyuiop/moonflagkit

#依赖声明 (Mooncakes)

q0w1ertyuiop/moonflagkit