MoonBit-native OpenAPI contract validation and deterministic mock toolkit

openapi

contract

validation

mock

testing

Download zip

Author

Han-Wentao

Version

0.1.1

License

MIT

Repository

github.com/Han-Wentao/mooncontract

Last updated

7 days ago

Downloads

159

Dependencies

#MoonContract

MoonContract 是一个使用 MoonBit 原生实现的 OpenAPI 3.0 契约校验、确定性 Mock 和用例回放工具包。它面向 API 开发、联调和 CI，让接口规范不只是一份文档，而是可以直接执行的正确性约束。

加载 OpenAPI -> 编译路由与引用 -> 校验 HTTP 交互 -> 生成确定性 Mock -> 回放契约用例

当前维护版本为 0.1.1。本轮关注校验正确性、Mock 响应优先级和可复现的跨后端质量验证，不是另建项目或补齐提交次数。详见维护技术报告与量化结果。

#功能

读取 OpenAPI 3.0.x JSON 和常用 YAML 规范。
解析路径、操作、参数、请求体、响应和组件 Schema。
解析本地 $ref，诊断缺失引用和循环引用。
编译静态/参数化路由，拒绝重复 operationId 和歧义路由。
校验 path、query、header、cookie 参数和 JSON 请求体。
校验响应状态码、媒体类型和 JSON 响应体。
按 example、default、enum 和 Schema 约束生成确定性 Mock。
离线回放正向与负向契约用例。
提供 lint、check、mock 和 serve 命令。
输出稳定的文本或 JSON 诊断，供开发者与 CI 使用。

#快速开始

环境要求：MoonBit 工具链。native CLI 和服务还需要系统 C 编译器。

git clone https://github.com/Han-Wentao/mooncontract.git
cd mooncontract

moon check --target wasm-gc --deny-warn
moon test --target wasm-gc

检查 OpenAPI 规范：

moon run cmd/mooncontract --target native -- \
  lint --spec examples/petstore/openapi.yaml

回放契约用例：

moon run cmd/mooncontract --target native -- \
  check \
  --spec examples/petstore/openapi.yaml \
  --cases examples/petstore/cases.json

离线生成一个 Mock 响应：

moon run cmd/mooncontract --target native -- \
  mock \
  --spec examples/petstore/openapi.yaml \
  --request examples/petstore/request.json \
  --seed 42

启动开发用 HTTP Mock 服务：

moon run cmd/mooncontract --target native -- \
  serve --spec examples/petstore/openapi.yaml --port 4010

curl http://127.0.0.1:4010/pets/7

服务默认只监听 127.0.0.1:4010，请求正文上限为 1 MiB。

#CLI

mooncontract lint  --spec FILE [--format text|json]
mooncontract check --spec FILE --cases FILE [--format text|json] [--seed N]
mooncontract mock  --spec FILE --request FILE [--seed N] [--status CODE]
mooncontract serve --spec FILE [--host HOST] [--port PORT] [--seed N]

退出码：0 表示成功，1 表示契约或用例校验失败，2 表示命令、文件或规范无法处理。

#作为库使用

在 moon.pkg 中按职责导入公开包：

import {
  "Han-Wentao/mooncontract/src/openapi",
  "Han-Wentao/mooncontract/src/contract",
  "Han-Wentao/mooncontract/src/mock",
}

let document = @openapi.parse_json(source).unwrap()
let contract = @contract.compile(document).unwrap()
let request = @contract.HttpRequest::new(@openapi.Get, "/pets/7")
let validation = contract.validate_request(request)
let response = @mock.MockEngine::new(contract).respond(request)

公开 API 由各包的 pkg.generated.mbti 文件记录，并在 CI 中通过 moon info 保持同步。

#项目边界

MoonContract 不做以下工作：

不测量运行耗时，不采集性能样本，不管理性能基线或判断性能回归。
不生成 MoonBit 服务端/客户端代码，不创建应用脚手架。
不提取 API 供 AI Agent 调用，不实现通用 Web 框架。
不支持 OpenAPI 3.1、外部网络 $ref、状态化 Mock 场景或流量代理。
HTTP Mock 服务仅用于开发和测试，不是生产服务器。

这些边界使项目与此前的 MoonBench、cogna-dev/mapi 和 Showichiro/moon_openapi_cli 保持独立。详细对比见 docs/COMPARISON.md。

#文档

#本轮维护质量

对同一组自建边界用例实测，不以源码行数或提交数量替代质量：

指标	原版本 0.1.0	本轮修复后
与 python-jsonschema 4.23.0 的共享语义一致数	72 / 90	90 / 90
Mock 状态选择（6 种声明顺序 × 显式/隐式状态）	18 / 30	30 / 30
常规测试块	46	53

90 个差分用例在常规 53 个测试块之外生成并执行，不能相加当作覆盖率。这些结果不代表全量 OpenAPI/JSON Schema 一致性，也没有证明比其他软件更快。本地已验证 wasm-gc/wasm/js；native 测试和真实 HTTP 服务由 CI 验证，以对应提交的 CI 结果为准。

复现对标（Python 仅是开发测试依赖，不进入库的运行时）：

python -m venv .venv-quality
# Linux/macOS 激活；Windows 使用 .venv-quality\Scripts\Activate.ps1
. .venv-quality/bin/activate
python -m pip install -r tools/quality-requirements.txt
python tools/compare_schema.py --target wasm-gc

CI 固定 MoonBit 0.10.4+2cc641edf、Ubuntu 24.04、Python 3.11 和对标器版本，在四后端执行差分测试并上传原始 JSON 报告。

#质量检查

moon fmt --check
moon check --target wasm-gc --deny-warn
moon check --target wasm --deny-warn
moon check --target js --deny-warn
moon check --target native --deny-warn
moon test --target wasm-gc
moon test --target native

GitHub Actions 还会启动真实 HTTP Mock 服务并使用 curl 验证成功请求和无效请求。