# moon-uri-template 项目目标

- 状态：Draft 0.1
- 日期：2026-07-23
- 对应规约：[SPEC.md](SPEC.md)

## 1. 愿景

为 MoonBit 生态提供一个可信、易用、跨后端的 RFC 6570 Level 4 URI Template 基础库，使开发者不再依赖手工字符串拼接构造 URI，并为 HTTP 客户端、OpenAPI 工具、SDK 生成器和超媒体应用提供可长期复用的标准组件。

## 2. 项目成果目标

项目结束时应交付：

1. 一个纯 MoonBit 的 RFC 6570 Level 4 实现；
2. 一个稳定、精简且具有文档的公共 API；
3. 一个可直接运行的 URI Template CLI；
4. 一套可证明兼容性的标准测试；
5. JS、Wasm、Native 多后端验证；
6. 完整 README、API 文档、示例和设计说明；
7. 自动化 CI；
8. mooncakes.io 可安装版本；
9. 清晰的第三方来源与开源许可证说明；
10. 可追踪的 Issue、提交、测试和发布记录。

## 3. 用户目标

### 3.1 库使用者

库使用者应该能在五分钟内：

- 安装包；
- 解析一个模板；
- 传入字符串变量；
- 展开得到 URI；
- 理解并处理解析错误。

在十五分钟内应该能：

- 使用列表与关联数组；
- 理解 Prefix 与 Explode；
- 知道 `{var}` 与 `{+var}` 的安全差异；
- 将库接入自己的 HTTP 或 OpenAPI 工具。

### 3.2 CLI 使用者

CLI 使用者应该能：

- 校验一个模板；
- 查看模板引用了哪些变量；
- 从 JSON 文件加载变量；
- 展开模板；
- 在模板错误时获得准确位置和可理解的提示。

### 3.3 生态库作者

HTTP、OpenAPI 和代码生成工具作者应该能：

- 缓存解析后的模板并重复展开；
- 不依赖 CLI 使用核心库；
- 在不同 MoonBit 后端获得一致结果；
- 依靠稳定的类型和错误模型进行集成；
- 使用标准测试结果评估实现可信度。

## 4. 优先级

### P0：必须完成

- Level 1–4 模板解析；
- 八类标准表达式；
- 字符串、列表、关联数组；
- Prefix 与 Explode；
- Unicode 和百分号编码；
- 未定义值与空值语义；
- 结构化错误；
- RFC 示例测试；
- 通用 RFC 6570 测试集；
- `validate`、`variables`、`expand` CLI；
- README 与可运行示例；
- CI；
- mooncakes.io 发布。

P0 任一核心项缺失时，不得宣称“RFC 6570 完整实现”。

### P1：应该完成

- `inspect` CLI；
- 模板最低兼容等级查询；
- 去重且保持顺序的变量列表；
- JSON 变量适配器；
- 可配置资源限制；
- 性质测试或随机测试；
- 与至少两个成熟实现的差异测试；
- 基准测试；
- 一个真实集成示例，例如 OpenAPI URL 生成或 HTTP 客户端。

### P2：可以延期

- NFC 规范化适配器；
- 流式输出接口；
- 编译期模板校验实验；
- 额外语言绑定；
- 编辑器诊断集成；
- 非标准反向匹配实验。

P2 功能不得阻塞 P0 的正确性、测试和文档。

## 5. 可量化成功指标

### 5.1 标准兼容性

- RFC 6570 Level 1–4 正文示例：100% 通过；
- 选定的通用兼容性测试集：100% 通过，或对无法采用的用例逐条公开说明；
- 八类操作符均具有标量、列表、关联数组及边界测试；
- Prefix、Explode、空值和未定义值均有独立测试。

### 5.2 工程质量

- `moon check`：通过；
- `moon test`：通过；
- `moon fmt --check`：通过；
- JS、Wasm、Native：在承诺范围内通过 CI；
- 核心公开 API 有文档注释；
- README 中所有可执行示例通过测试；
- 公共 API 变化通过 `moon info` 审查；
- 发布标签和 CHANGELOG 一致。

### 5.3 可用性

- 新用户从 README 复制最小示例即可运行；
- 错误信息包含类别和源位置；
- CLI 对有效输入返回状态码 0，对无效输入返回非零状态码；
- 相同模板和有序输入在不同后端产生逐字节一致结果；
- 典型模板可解析一次并重复展开。

### 5.4 开源与赛事交付

- 仓库公开可访问；
- 根目录包含 OSI 认可的许可证；
- 上游测试数据具有来源、版本和许可证记录；
- 存在 CI、测试、示例和完整 README；
- 发布到 mooncakes.io；
- 有连续、有意义的 Git 提交；
- 项目边界、未支持能力和安全限制明确；
- 项目申报书中的承诺可以逐项映射到仓库证据。

## 6. 里程碑

下面按四周开发周期规划，可根据实际报名和验收时间压缩，但不得跳过质量门。

### M0：立项与基线

目标：

- 建立公开仓库；
- 选择项目许可证；
- 初始化 MoonBit 模块和包；
- 建立 README 骨架、SPEC、GOALS、CHANGELOG；
- 配置基础 CI；
- 导入并记录标准测试数据来源。

完成证据：

- `moon check` 通过；
- CI 首次成功；
- Issue 列表和里程碑公开；
- 申报材料可以引用仓库。

### M1：解析器与 Level 1–2

目标：

- 模板文本与表达式扫描；
- 变量名称和操作符解析；
- 结构化语法错误与位置；
- 标量值模型；
- `{var}`、`{+var}`、`{#var}`；
- 基础 Unicode 与百分号编码。

质量门：

- Level 1–2 RFC 示例全部通过；
- 非法模板测试完成；
- 中文、空格、保留字符测试完成；
- Parser 与 Encoder 保持独立。

### M2：Level 3

目标：

- 多变量表达式；
- `. / ; ? &` 操作符；
- 未定义值和空值；
- 操作符属性表；
- 变量列表和最低 Level 查询。

质量门：

- Level 3 RFC 示例全部通过；
- 每个操作符具有边界测试；
- 不存在手工散落的查询分隔符拼接逻辑；
- 同一输入重复展开结果一致。

### M3：Level 4

目标：

- 列表；
- 关联数组；
- Prefix；
- Explode；
- Unicode 码点级截断；
- 完整通用兼容性测试集。

质量门：

- Level 4 RFC 示例全部通过；
- 标准测试集达到发布要求；
- 空列表、空关联数组和组合值测试完成；
- 多后端结果一致。

### M4：CLI、集成与发布

目标：

- `validate`；
- `variables`；
- `expand`；
- 可选 `inspect`；
- JSON 变量加载；
- 真实集成示例；
- README、API 文档和安全说明；
- 性能基线；
- mooncakes.io 发布。

质量门：

- CLI 示例可直接运行；
- CI 全绿；
- `moon fmt` 和 `moon info` 已执行；
- LICENSE、THIRD_PARTY、CHANGELOG 完整；
- 发布版本可由 README 复现。

## 7. 建议任务分解

### 解析

- 定义源位置；
- 扫描 Literal 与 Expression；
- 解析 Operator；
- 解析 VariableSpec；
- 解析 Prefix 与 Explode；
- 错误恢复或首错返回策略；
- 模板变量去重。

### 编码

- 非保留字符判断；
- 保留字符判断；
- UTF-8 编码；
- `%HH` 输出；
- 普通允许集合；
- 保留展开允许集合；
- Unicode Prefix；
- 非法百分号输入测试。

### 展开

- 操作符规则表；
- 标量展开；
- 列表非 Explode；
- 列表 Explode；
- 关联数组非 Explode；
- 关联数组 Explode；
- 未定义值；
- 空值；
- 输出长度限制。

### 产品化

- CLI 参数解析；
- JSON 值转换；
- README；
- 可测试文档示例；
- CI；
- 性能基准；
- mooncakes.io 元数据；
- 发布流程。

## 8. 非目标

本项目成功不依赖以下成果：

- 成为完整 URL/URI 解析库；
- 实现 HTTP Client；
- 实现 Web Framework；
- 支持 OpenAPI 全标准；
- 支持任意模板编程；
- 实现 URI 到变量的通用反向匹配；
- 追求极端微基准而牺牲正确性；
- 通过增加无关功能达到代码行数；
- 复制其他语言实现的内部结构。

项目规模应来自完整标准支持、清晰实现、测试和工程质量，而不是无意义扩展。

## 9. 风险与应对

### Unicode 处理错误

风险：MoonBit 字符串表示、Unicode 码点、UTF-8 字节和 Prefix 长度混淆。

应对：

- 编码逻辑独立成包；
- 使用标准 UTF-8 API；
- 对 BMP、非 BMP、Emoji 和组合字符分别测试；
- 跨后端比较逐字节输出。

### 操作符组合爆炸

风险：八类操作符乘以三种值类型和两种修饰符，产生大量重复分支。

应对：

- 使用操作符属性表；
- 将标量、列表、关联数组展开分层；
- 使用表驱动测试；
- 优先建立参考矩阵再编码。

### 看似兼容、实际漏掉边界

风险：简单示例通过，但空值、未定义值、Explode 和保留字符行为错误。

应对：

- 以 RFC 示例和通用测试集作为验收门；
- 对每个 bug 增加回归测试；
- 与成熟实现进行差异测试；
- 不在测试未完成前宣称完整兼容。

### 范围膨胀

风险：同时开发 URI Parser、HTTP Client、OpenAPI 和路由器。

应对：

- P0 只围绕解析与展开；
- 新需求先记录为 Issue，不直接进入当前里程碑；
- 任何新增能力必须说明与 RFC 6570 核心目标的关系。

### 上游测试数据许可证

风险：直接复制标准测试文件但未记录来源和许可。

应对：

- 固定上游版本或 commit；
- 保留许可证；
- 添加 `THIRD_PARTY.md`；
- README 明确测试数据不属于原创成果。

## 10. 项目完成定义

只有同时满足以下条件，项目才算完成：

1. `SPEC.md` 中所有“必须”条款均已实现或有公开例外说明；
2. P0 功能全部完成；
3. RFC Level 1–4 示例和选定标准测试集达到发布门槛；
4. 三后端承诺范围均有自动化证据；
5. README 可让新用户独立安装并运行；
6. CLI 能校验、查看变量和展开模板；
7. 公共 API 和错误模型经过审查；
8. 开源许可证及第三方来源合规；
9. 已发布可安装版本；
10. 仓库中的代码、测试、文档和提交历史足以复现申报目标。

## 11. 冲刺优秀项目的附加目标

在核心完成后，可以通过以下内容提高展示和长期维护价值：

- 提供交互式 Web Demo，所有展开逻辑仍来自同一 MoonBit 核心库；
- 展示一个 OpenAPI 或 HTTP 客户端真实集成；
- 发布兼容性矩阵和基准报告；
- 提供错误位置高亮；
- 提供不同后端输出一致性的自动报告；
- 撰写一篇 RFC 6570、Unicode 和 URI 编码实现文章；
- 为其他 MoonBit 生态项目提交接入示例或 PR。

这些附加目标不得以牺牲标准兼容性、测试和文档为代价。