# RyanJson 核心优化工作流

## 范围
- 本页仅覆盖“优化执行流程”。
- 交付结构见 `optimizationTemplate.md`。
- 模块风险细节见 `moduleHotspots.md`。
- 执行入口、覆盖目录、脚本参数基线见 `../../shared/ryanJsonCommon.md`。

## 0) 前置条件（必须）
- 在任何业务入口、测试入口、fuzzer 入口先调用 `RyanJsonInitHooks`。
- 默认建议使用统一封装分配器（即便最终仍转发到 `malloc/free/realloc`），便于统计和故障注入。
- 未初始化 hooks 时，不执行优化结论对比（避免基线不可比）。
- 当前实现没有默认 hooks 回退（全局 hooks 初始为 `NULL`），因此该前置条件是硬约束。

## 1) 定义问题边界
- 明确是“行为错误修复”还是“性能/内存优化”。
- 明确是否允许改变历史行为（默认不允许）。
- 明确目标平台（32 位/64 位、是否 RTOS、是否启用 ASan/UBSan）。

## 2) 建立可比较基线
- 功能：跑与改动模块相关的单元测试。
- 资源：记录内存峰值、分配次数、失败路径泄漏结果。
- 稳定性：保留至少一个历史 crash 样本回归。
- 覆盖：确认目标分支 true/false 双向是否可达。

## 2.1) 回归入口策略
- 本地常规回归：先跑 `run_local_*`。
- 需要细调矩阵/并发/覆盖时，再直调 `scripts/ci/*`。

## 3) 聚焦热点模块
- `RyanJsonParse.c`：数字解析、字符串转义、Unicode 代理对、状态推进。
- `RyanJsonPrint.c`：预分配边界、append 失败路径、double 打印策略。
- `RyanJsonItem.c`：Add/Insert/Replace/Detach/Delete 的所有权与链安全。
- `RyanJson.c`：Compare 有序/无序路径、深度与回溯。

## 4) 设计最小改动
- 优先修复内存安全与语义一致性，再做微优化。
- 新防御逻辑要区分可恢复错误（返回 false/NULL）与不可恢复错误（启用 `RyanJsonEnableAssert` 时可 assert）。
- 避免引入额外常驻内存；若必须引入，先得到明确授权。

## 5) 同步测试策略
- 不新增散文件，补到现有分类测试。
- 单元测试覆盖确定性语义，fuzzer 覆盖组合路径与未知输入。
- 新增每个分支至少一个触发样本，必要时固化到 corpus。

## 6) 交付与复核
- 给出改动原因、收益、代价、兼容影响。
- 给出“已验证/未验证”边界。
- 给出剩余风险和下一轮优化建议。

## 常见反模式
- 只看覆盖率，不看语义断言。
- 通过 assert 处理用户输入错误。
- 为了覆盖率引入会改变行为的冗余逻辑。

## 依据（仓库内）
- `RyanJson/RyanJson.c`：`RyanJsonInitHooks` 与全局 hooks 初始状态
- `RyanJson/RyanJson.h`：`Add/Insert`、`Replace` 失败语义注释
- `test/unityTest/cases/core/testCreate.c`、`test/unityTest/cases/core/testReplace.c`：失败所有权与宏分支断言
- `test/fuzzer/entry.c`：fuzzer 入口与稳定性回归链路
- `../../shared/ryanJsonCommon.md`：统一执行入口与覆盖口径