|
| 1 | +# API 高频回答模板 |
| 2 | + |
| 3 | +## 范围 |
| 4 | +- 本页用于统一高频 API 问题的回答骨架，减少遗漏宏前提、失败路径和所有权。 |
| 5 | +- 详细 API 选择仍以 `apiPatterns.md`、`quickstart.md`、`ownershipAndErrors.md` 为准。 |
| 6 | + |
| 7 | +## 通用输出骨架 |
| 8 | +1. 前提：环境、hooks、宏前提。 |
| 9 | +2. 最小方案：只保留当前问题需要的公开 API。 |
| 10 | +3. 失败路径：逐个说明返回 false/NULL 时怎么退出。 |
| 11 | +4. 所有权：明确谁释放、何时转移。 |
| 12 | +5. 验证点：用户最小可检查项。 |
| 13 | + |
| 14 | +## 模板 1：最小初始化 / Parse + Get |
| 15 | +- 前提： |
| 16 | + - `RyanJsonInitHooks` 必须先于任何 Json API。 |
| 17 | + - `Get*` 前先判空，再 `RyanJsonIsXXX` 判型。 |
| 18 | +- 最小方案： |
| 19 | + - `InitHooks -> Parse -> GetObjectByKey -> IsXXX -> GetXXXValue -> Delete(root)` |
| 20 | +- 失败路径： |
| 21 | + - hooks 失败：立即返回。 |
| 22 | + - Parse 失败：立即返回。 |
| 23 | + - key 缺失或类型不符：释放 root 后返回。 |
| 24 | +- 所有权： |
| 25 | + - `root` 由调用方在结束时 `RyanJsonDelete`。 |
| 26 | +- 验证点： |
| 27 | + - 错 key / 错类型 / 非法 JSON 都不会崩溃。 |
| 28 | + |
| 29 | +## 模板 2：Create + Add + PrintPreallocated |
| 30 | +- 前提： |
| 31 | + - 输出缓冲由调用方管理。 |
| 32 | + - 传输输出优先非格式化打印。 |
| 33 | +- 最小方案： |
| 34 | + - `InitHooks -> CreateObject -> Add*ToObject -> PrintPreallocated(..., RyanJsonFalse, ...) -> Delete(root)` |
| 35 | +- 失败路径： |
| 36 | + - 任一 Add 失败：删除 root 后返回。 |
| 37 | + - 预分配打印失败：删除 root 后返回。 |
| 38 | +- 所有权： |
| 39 | + - `root` 始终由调用方清理。 |
| 40 | + - 输出缓冲不需要 `RyanJsonFree`。 |
| 41 | +- 验证点： |
| 42 | + - 容量不足时返回失败，缓冲不被当作成功输出使用。 |
| 43 | + |
| 44 | +## 模板 3：Replace 失败谁释放 |
| 45 | +- 前提： |
| 46 | + - 只讨论 `ReplaceByKey/ReplaceByIndex`，不要混入 Add/Insert 语义。 |
| 47 | +- 最小方案： |
| 48 | + - 先构造 `newItem`，再调用 `RyanJsonReplaceBy*`。 |
| 49 | +- 失败路径： |
| 50 | + - Replace 返回 false：调用方复用或 `RyanJsonDelete(newItem)`。 |
| 51 | +- 所有权： |
| 52 | + - Replace 成功：`newItem` 转移给父节点。 |
| 53 | + - Replace 失败：`newItem` 仍归调用方。 |
| 54 | +- 验证点： |
| 55 | + - 失败后 `newItem` 仍可访问，且原树未被破坏。 |
| 56 | + |
| 57 | +## 模板 4：Add/Insert 失败谁释放 |
| 58 | +- 前提： |
| 59 | + - 先确认 `item` 是否为游离节点。 |
| 60 | + - 不要把 Add/Insert 失败语义套成 Replace。 |
| 61 | +- 最小方案： |
| 62 | + - `Create item -> IsDetachedItem -> Add/Insert` |
| 63 | +- 失败路径： |
| 64 | + - 游离节点失败：当前实现下通常由库侧清理，不要盲目二次释放。 |
| 65 | + - 非游离节点失败：返回 false，但库不会替你破坏原树。 |
| 66 | +- 所有权： |
| 67 | + - 成功后转移给父节点。 |
| 68 | + - 失败后是否仍归调用方，取决于节点是否游离和具体 API 路径。 |
| 69 | +- 验证点： |
| 70 | + - 已挂树节点重复插入不会破坏原树。 |
| 71 | + |
| 72 | +## 模板 5：Detach 后怎么重挂 |
| 73 | +- 前提： |
| 74 | + - `Detach` 成功后节点归调用方。 |
| 75 | +- 最小方案： |
| 76 | + - `detached = Detach* -> AddItem*/Insert` |
| 77 | +- 失败路径： |
| 78 | + - 重挂失败：按目标 API 的失败语义处理 `detached`。 |
| 79 | +- 所有权： |
| 80 | + - `Detach` 后必须“重挂”或“释放”。 |
| 81 | +- 验证点： |
| 82 | + - 迁移前后旧父节点和新父节点结构都可验证。 |
| 83 | + |
| 84 | +## 模板 6：Print 还是 Minify |
| 85 | +- 前提： |
| 86 | + - 先区分“树输出”还是“已有文本清洗”。 |
| 87 | +- 最小方案： |
| 88 | + - 树输出：`RyanJsonPrint(..., RyanJsonFalse, ...)` 或 `RyanJsonPrintPreallocated(..., RyanJsonFalse, ...)` |
| 89 | + - 文本清洗：`RyanJsonMinify` |
| 90 | +- 失败路径： |
| 91 | + - Print 失败：按输出 API 释放或回退。 |
| 92 | + - Minify 失败：按输入缓冲与长度约束处理。 |
| 93 | +- 所有权： |
| 94 | + - `RyanJsonPrint` 的返回缓冲由调用方 `RyanJsonFree`。 |
| 95 | + - `Minify` 不负责生成新的树或接管输入缓冲。 |
| 96 | +- 验证点： |
| 97 | + - 不要把 `Minify` 当成主打印路径。 |
0 commit comments