ryanjson-api-usage

分类: 开发与编程 | 上传者: Ryan-CW-Code | 下载: 0 | 版本: v1.0（最新）

RyanJson 公开 API 使用与 RT-Thread 集成指南。用于接口选型、调用顺序、所有权与失败释放、以及 RyanJsonInitHooks 初始化集成；用户问“怎么用/怎么集成/失败谁释放/示例代码”时使用。测试补强转 ryanjson-test-engineering，内部优化转 ryanjson-optimization。

更新日志: Source: GitHub https://github.com/Ryan-CW-Code/RyanJson

目录结构

当前层级: skills/ryanjson-api-usage/

📁 agents/
- 📄 gemini.md 1.6 KB
- 📄 openai.yaml 329 B
📁 references/
- 📄 apiPatterns.md 5.1 KB
- 📄 apiReference.md 6.2 KB
- 📄 beginnerPrimer.md 1.6 KB
- 📄 faultInjectionPlaybook.md 1.9 KB
- 📄 geminiCompat.md 1.2 KB
- 📄 hooksInitPolicy.md 1.4 KB
- 📄 integrationTemplate.md 2.0 KB
- 📄 ownershipAndErrors.md 2.7 KB
- 📄 pitfallsAndDebug.md 3.5 KB
- 📄 quickstart.md 5.0 KB
- 📄 rt-thread-examples.md 4.3 KB
- 📄 terminology.md 180 B
📄 apiPatterns.md 237 B
📄 context.md 1.5 KB
📄 ownership.md 1.3 KB
📄 SKILL.md 5.1 KB
📄 sop.md 1.0 KB

SKILL.md

---
name: ryanjson-api-usage
description: RyanJson 公开 API 使用与 RT-Thread 集成指南。用于接口选型、调用顺序、所有权与失败释放、以及 RyanJsonInitHooks 初始化集成；用户问“怎么用/怎么集成/失败谁释放/示例代码”时使用。测试补强转 ryanjson-test-engineering，内部优化转 ryanjson-optimization。
---

# RyanJson API 使用技能

## 目标
- 给出可落地的公开 API 调用方案（含失败路径与释放责任）。
- 面向“JSON/嵌入式新手”也能理解的解释与最小示例。
- 不讨论内部优化与测试补强。

## 必要输入
- 运行环境（RT-Thread/裸机/其他）与相关宏配置。
- 目标场景（读取/构建/更新/替换/迁移）。
- 约束（内存/性能/代码尺寸/兼容性）。
> 若用户说不清环境，默认假设：可用 `malloc/free/realloc`、单线程、简单对象结构，并在回答中明确这些假设。

## 核心流程
1. 先读 `../shared/ryanJsonCommon.md`，确认宏与失败语义基线。
2. 判断用户是否“新手”：若是，先用 `references/beginnerPrimer.md` 解释术语与最小流程。
3. 用 `references/apiPatterns.md` 选择最小 API 路径。
4. 输出成功/失败路径与所有权清单。
5. 给出最小验证项（返回值/日志/内存检查点）。

## 约束（必须遵守）
- `Get*` 先判空，再 `RyanJsonIsXXX` 判型。
- 同类型更新优先 `Change*Value`，跨类型更新用 `ReplaceByKey/ReplaceByIndex`。
- `Add/Insert` 只接收游离节点，禁止重复挂载。
- `RyanJsonAddItemToObject` 成功后若继续操作子树，重新从根 `GetObjectToKey` 取容器指针。
- 传输输出优先非格式化打印：`RyanJsonPrint(..., RyanJsonFalse, ...)` 或 `RyanJsonPrintPreallocated(..., RyanJsonFalse, ...)`。
- `RyanJsonMinify` 仅做文本清洗，不作为主输出路径。

## 输出格式
1. 前提与结论：宏/环境前提 + API 选型（若有默认假设必须写明）。
2. 最小代码：只用公开 API，包含失败分支。
3. 所有权清单：逐分支说明谁负责释放。
4. 验证建议：最小验证步骤与后续扩展方向。
> 面向新手时，在第 1 段先给“5 步最小流程”，避免术语堆叠。

## 用户问题覆盖（按用户视角路由）
- 如何初始化与注入内存 hooks：`references/hooksInitPolicy.md`、`references/quickstart.md`
- 如何解析 JSON 并读取字段：`references/apiPatterns.md`（A 段）、`references/quickstart.md`
- 如何构建对象/数组并打印：`references/apiPatterns.md`（B/G 段）、`references/quickstart.md`
- 如何同类型更新或跨类型替换：`references/apiPatterns.md`（C/D 段）
- 如何插入/删除/分离节点：`references/apiPatterns.md`（E 段）、`references/ownershipAndErrors.md`
- Add/Insert/Replace 失败谁释放：`references/ownershipAndErrors.md`、`references/quickstart.md`
- 重复 key 如何处理：`references/apiPatterns.md`（F 段）、`RyanJsonStrictObjectKeyCheck`（见共享基线）
- 传输压缩输出与 Minify 区别：`references/apiPatterns.md`（G/H 段）
- RT-Thread 集成与平台差异：`references/rt-thread-examples.md`、`references/integrationTemplate.md`
- 出错/崩溃/边界排查：`references/pitfallsAndDebug.md`、`references/faultInjectionPlaybook.md`
- 需要完整 API 说明：`references/apiReference.md`
- 新手术语与概念：`references/beginnerPrimer.md`
- 内部实现与数据结构问题：`../shared/architecture.md`（若超出公开 API 语义，转 `ryanjson-optimization`）

## 示例
- 用户问“RT-Thread 下如何初始化并解析 JSON？”：走本技能，给出最小可运行 API 路径与失败释放责任。
- 用户问“Add/Insert/Replace 失败谁释放？”：走本技能，列出失败路径与所有权清单。
- 用户问“如何用自定义 malloc/free 初始化？”：走本技能，给出 `RyanJsonInitHooks` 初始化顺序与失败处理。
- 用户问“如何把对象打印成紧凑字符串？”：走本技能，给出 `RyanJsonPrint(..., RyanJsonFalse, ...)` 的最小示例。
- 用户问“如何在对象里更新/替换字段类型？”：走本技能，说明 `Change*Value` 与 `ReplaceByKey` 的选择规则。
- 用户问“如何删除或分离节点？”：走本技能，给出 `Delete/Detach` 的使用与释放责任。

## 参考导航
- 共享基线：`../shared/ryanJsonCommon.md`
- 架构与数据结构：`../shared/architecture.md`
- 注释规范：统一用 Doxygen 风格，类型名/字段语义/API 名保持英文（见共享基线第 9 节）
- 新手入门：`references/beginnerPrimer.md`
- API 快速入口：`references/quickstart.md`
- 场景模板：`references/apiPatterns.md`
- 所有权细则：`references/ownershipAndErrors.md`
- 完整 API：`references/apiReference.md`
- hooks 初始化：`references/hooksInitPolicy.md`
- RT-Thread 示例：`references/rt-thread-examples.md`
- 集成模板：`references/integrationTemplate.md`
- 排障与故障注入：`references/pitfallsAndDebug.md`、`references/faultInjectionPlaybook.md`
- 术语：`references/terminology.md`
- 本地压缩文档：`context.md`、`apiPatterns.md`、`ownership.md`、`sop.md`

登录后下载/点赞/收藏 ❤ 22 | ★ 0

ryanjson-api-usage

目录结构

SKILL.md

举报内容

提示