RyanJson/skills/ryanjson-api-usage/references/faultInjectionPlaybook.md

故障注入与稳定性验证（主机侧可选）

范围

• 用于主机侧或实验环境验证失败路径。
• RT-Thread 板端资源紧张时可不执行本流程。
• 所有权口径见 ownershipAndErrors.md。

目标

• 验证分配失败场景下的可恢复性。
• 覆盖 Parse/Create/Add/Insert/Replace/Print 的失败分支。

注入策略

• 固定第 N 次分配失败（稳定复现）。
• 按概率失败（压力回归）。
• 按调用点标签失败（精确定位）。

包装器示例

#include <stdint.h>
#include <stddef.h>
#include <stdlib.h>
#include "RyanJson.h"

typedef struct
{
    uint32_t allocCount;
    uint32_t failAt;
} jsonFaultState_t;

static jsonFaultState_t gFaultState = {0U, 0U};

static void *faultMalloc(size_t size)
{
    gFaultState.allocCount++;
    if ((0U != gFaultState.failAt) && (gFaultState.allocCount == gFaultState.failAt))
    {
        return NULL;
    }
    return malloc(size);
}

static void faultFree(void *ptr)
{
    free(ptr);
}

static void *faultRealloc(void *ptr, size_t size)
{
    gFaultState.allocCount++;
    if ((0U != gFaultState.failAt) && (gFaultState.allocCount == gFaultState.failAt))
    {
        return NULL;
    }
    return realloc(ptr, size);
}

建议检查点

• Parse 失败：返回 NULL，无泄漏。
• Add/Insert 失败：返回 false；游离 item 由库侧清理，非游离 item 失败不消费。
• Replace 失败：返回 false，item 仍由调用方持有（可继续复用或释放）。
• Print 失败：返回 NULL，原 Json 树仍可正常释放。

结果判定

• 无崩溃。
• 无泄漏。
• 返回值与所有权语义与头文件一致。

依据（仓库内）

• RyanJson/RyanJsonItem.c：RyanJsonInsert、RyanJsonReplaceByKey/ByIndex
• test/unityTest/cases/core/testCreate.c、test/unityTest/cases/core/testReplace.c
• test/fuzzer/cases/fuzzerCreate.c、test/fuzzer/cases/fuzzerReplace.c