#MoonContract

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

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

项目为 2026 MoonBit 国产基础软件生态开源大赛 8 月 Hackathon 原创参赛项目。

#功能

读取 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。

#文档

#质量检查

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 验证成功请求和无效请求。