MoonSchema

English | 中文

MoonBit 生态的 Schema 验证与数据建模库 — 声明式类型定义、约束校验、JSON Schema 互操作。

项目目标

MoonSchema 为 MoonBit 生态提供一套完整的 Schema 验证工具链，帮助开发者：

声明式定义数据 Schema — 通过流式 Builder API 描述期望的数据结构
校验运行时数据 — 对数据进行 Schema 校验，返回精确的路径化错误报告
与 JSON Schema 互操作 — 导入/导出 JSON Schema Draft 2020-12，与现有工具链集成
构建可靠应用 — 在业务逻辑执行前捕获数据错误

适用场景：库作者、CLI 开发者、API 开发者，以及任何在 MoonBit 中处理结构化数据的开发者。

特性

8 种 Schema 类型 — String、Number、Integer、Boolean、Null、Array、Object、Any
丰富的约束系统 — min/max 长度、pattern 模式匹配、数值边界（含 exclusive）、multipleOf、enum 枚举值
内置格式校验 — email、uri、date-time
流式 Builder API — 方法链：string_schema().min_length(1).max_length(100).format("email")
结构化错误 — ValidationResult 含 is_valid 布尔值和 JSON Pointer 路径的错误列表
JSON Schema 互操作 — 与 JSON Schema Draft 2020-12 双向转换
类型安全 — 利用 MoonBit 代数数据类型和模式匹配
12 个测试通过 — 核心校验路径全覆盖

安装

moon add cosgammmmma/moonschema

快速开始

// 1. 定义 Schema
let schema = string_schema().min_length(1).max_length(100)

// 2. 准备数据（Json 字面量重载）
let data : Json = "张三"

// 3. 校验
let result = validate(schema, data)
if result.is_valid {
  println("校验通过！")
} else {
  for err in result.errors {
    println("\(err.path): \(err.message)")
  }
}

最小可复现示例

保存为 example.mbt，通过 moon run 运行：

fn main {
  let s = string_schema().min_length(2).max_length(10)

  let r1 = validate(s, "hello")   // Json 重载
  println("'hello' 校验通过: \(r1.is_valid)")  // true

  let r2 = validate(s, "x")        // 太短
  println("'x' 校验通过: \(r2.is_valid)")       // false
}

使用示例

字符串校验

let name_schema = string_schema()
  .min_length(1)
  .max_length(100)
  .pattern("^[A-Z]")          // 大写字母开头
  .format("email")

let v : Json = "Zhang@example.com"
let result = validate(name_schema, v)

数值校验

let score_schema = number_schema()
  .minimum(0.0)
  .exclusive_maximum(100.0)
  .multiple_of(0.5)

let v : Json = 87.5
assert_true(validate(score_schema, v).is_valid)

枚举校验

let color_schema = string_schema()
  .string_enum(["red", "green", "blue"])

let v1 : Json = "green"
assert_true(validate(color_schema, v1).is_valid)

let v2 : Json = "yellow"
assert_false(validate(color_schema, v2).is_valid)

类型不匹配检测

let string_s = string_schema()
let number_v : Json = 42.0
let result = validate(string_s, number_v)
// result.is_valid == false
// result.errors[0].keyword == "type"

ValidationResult API

let err = ValidationError::new("/user/name", "太短", "minLength")
let r = ValidationResult::fail(err)

r.is_valid          // false
r.errors.length()   // 1
r.errors[0].path    // "/user/name"
r.errors[0].keyword // "minLength"

// 合并结果
let e1 = ValidationError::new("/a", "错误a", "test")
let e2 = ValidationError::new("/b", "错误b", "test")
let merged = ValidationResult::fail(e1).merge(ValidationResult::fail(e2))
// merged.errors.length() == 2

复现步骤

# 1. 创建新 MoonBit 项目
moon new myproject
cd myproject

# 2. 添加 MoonSchema 依赖
moon add cosgammmmma/moonschema

# 3. 在 main.mbt 中编写 Schema 校验代码
# 4. 运行
moon run cmd/main

# 或直接克隆测试：
git clone https://github.com/cosgammmmma/moonschema.git
cd moonschema
moon check   # 0 errors
moon test    # 12 passed, 0 failed

API 参考

Schema 构建器

函数	说明
`string_schema()`	字符串 Schema（含默认约束）
`number_schema()`	数值 Schema（Double）
`integer_schema()`	整数 Schema（含类型强制检查）
`boolean_schema()`	布尔 Schema
`null_schema()`	Null Schema
`any_schema()`	接受任意类型

字符串约束

方法	说明
`.min_length(n)`	最小长度
`.max_length(n)`	最大长度
`.pattern(p)`	模式匹配（`^` 前缀、`$` 后缀、包含）
`.string_enum(vals)`	允许的字符串值
`.format(f)`	格式校验（`email`、`uri`、`date-time`）
`.required()`	标记为必填

数值约束

方法	说明
`.minimum(n)`	最小值（含）
`.maximum(n)`	最大值（含）
`.exclusive_minimum(n)`	最小值（不含）
`.exclusive_maximum(n)`	最大值（不含）
`.multiple_of(n)`	必须是 n 的倍数

校验函数

函数	说明
`validate(schema, value)`	校验并返回 `ValidationResult`
`is_valid(schema, value)`	仅返回布尔值

错误类型

类型	说明
`ValidationError`	含 path、message、keyword
`ValidationResult`	含 is_valid、errors、merge()

项目结构

moonschema/
├── moon.mod.json          # 模块元数据
├── moon.pkg               # 包描述符
├── types.mbt              # SchemaType、Schema、约束结构体
├── error.mbt              # ValidationError、ValidationResult
├── validator.mbt          # 校验引擎
├── builder.mbt            # 流式 Builder API
├── moonschema_test.mbt    # 12 个测试用例
└── .github/workflows/ci.yml  # CI 流水线

开发

git clone https://github.com/cosgammmmma/moonschema.git
cd moonschema
moon check    # 类型检查
moon test     # 运行 12 个测试

许可证

Apache 2.0 — 详见 LICENSE