# 两分钟评审指南

MoonBit URI Template 把模板和变量变成 RFC 6570 Level 4 URL，并在发送请求前发现缺失参数、类型错误和 OpenAPI 配置问题。解析、展开与 OpenAPI 分析都在 MoonBit 中实现，Mooncakes、Node SDK 和 CLI 共用核心。

Mooncakes 已有 Magic486、JSJ222 的同类库。本项目的区别是带差异解释的标准验证、可定位的错误、批量配置预检，以及真实 API 描述和下游客户端接入；逐项比较见 [COMPARISON.md](COMPARISON.md)。

## 一条命令试用

安装 Node.js 22+ 后运行（从 npm 获取固定版本）：

```sh
npx --yes --package moonbit-uri-template@0.6.1 uri-template expand '/users/{id}{?page}' --vars '{"id":"42","page":"2"}'
```

预期输出 `/users/42?page=2`。MoonBit 用户执行 `moon add cjyhjy/uri_template@0.6.1`；[API](API.md) 和 [SDK](SDK.md) 提供完整用法。发布包、来源证明与干净安装核验见 [RELEASE.md](RELEASE.md)。

## 三组证据

| 要验证的能力 | 结果及边界 | 可检查的证据 |
| --- | --- | --- |
| 标准语义 | 270 条上游用例；644 条跨语言差分中 583 条三方完全一致，其余分歧逐条解释；四个 MoonBit 后端验收 | [CONFORMANCE.md](CONFORMANCE.md)、[当前验证报告](../reports/verification.json) |
| 真实描述回归 | 200 个服务商、12,963 个接口的固定哈希回归集；60 份 JSON/YAML 对照。它检验回归和已约定规则，不证明所有真实 API 都正确 | [OPENAPI.md](OPENAPI.md)、[回归报告](../reports/openapi-corpus.json)、[YAML 对照](../reports/openapi-yaml-parity.json) |
| 下游可用性 | MoonBit 原生客户端真实 HTTPS 记录；固定 Octokit 原版/适配版均通过 59 项上游测试。历史客户端依赖分别为 0.4.0/0.5.1，是自行实施的接入实验 | [原生客户端](../integrations/moonbit-github/README.md)、[Octokit 接入](../integrations/octokit-endpoint/README.md) |

## 从源码复现

需要 Python 3.9+、Node.js 22+；bootstrap 下载并校验锁定工具链：

```sh
python3 tools/bootstrap.py && npm ci --ignore-scripts && npm test
npm run release:package
node tools/openapi_corpus.mjs check --download --baseline testdata/openapi-corpus/baseline.json
node tools/verify_yaml_corpus.mjs --download
```

`npm test` 包含四后端、SDK/CLI、差分回放和独立包消费者；打包命令会解压产物重新测试。网络数据由后两条命令按摘要获取；当前提交的执行结果见 [Actions](https://github.com/cjyhjy/moonbit-uri-template/actions)。

定位错误、升级比较和增量更新见 [SDK](SDK.md)；固定负载性能及限制见 [PERFORMANCE.md](PERFORMANCE.md)；浏览器演示运行 `npm run playground`。