Json Toolkit Free

SKILL.md

---
slug: json-toolkit-free
name: json-toolkit-free
version: 1.0.0
displayName: JSON工具箱(免费版)
summary: JSON 数据结构处理优选实践，含校验、命名、空值、日期、数字规范。
license: Proprietary
edition: free
description: 'JSON 数据结构处理优选实践，含校验、命名、空值、日期、数字规范。核心能力：

  - JSON Schema 校验与契约定义

  - 命名规范与一致性管理

  - 空值处理与可选字段策略

  - 日期时间与数字 ID 规范

  - 结构优选实践与 API 响应模式


  适用场景：

  - API 接口设计与契约校验

  - 前后端数据交换格式约定

  - 配置文件与数据持久化

  - 第三方接口对接与数据清洗


  差异化：以"防御式设计"为核心，聚焦不可信输入校验与字段一致性，免费版覆盖个人开发者日常 JSON 处理的高频场景'
tags:
- 集成工具
- 数据规范
- 开发者效率
tools:
- - read
- exec
homepage: https://skillhub.cn
pricing_tier: "L1-入门级"
pricing_model: per_use
suggested_price: "9.9 CNY/per_use"
tools: ["read", "write", "exec"]
tags: "工具,效率,自动化"
---
# JSON 工具箱（免费版）

## 概述

本 Skill 为 Agent 提供 JSON 数据结构处理的优选实践指南。核心理念是"防御式设计"：在处理不可信输入前先校验，在定义 API 响应时先立契约，避免"假设结构正确"的陷阱。免费版覆盖个人开发者高频场景：Schema 校验、命名一致性、空值处理、日期时间、数字 ID、结构优选实践。

## 核心能力

| 能力 | 说明 | 免费版支持 |
|---|---|-----|
| Schema 校验 | 处理前校验不可信输入 | 是 |
| 命名规范 | 统一命名约定与一致性 | 是 |
| 空值处理 | 区分 null 与字段缺失 | 是 |
| 日期时间 | ISO 8601 与时区规范 | 是 |
| 数字与 ID | 大数转字符串、金额处理 | 是 |
| 结构优选实践 | 嵌套层级与统一信封 | 是 |
| API 响应模式 | 错误结构化与请求 ID | 是 |
| 基础序列化 | toJSON 注意事项 | 是 |
| 基础解析安全 | try/catch 与原型污染 | 是 |
| 高级序列化 | Map/Set/BigInt/循环引用 | 否（专业版） |
| 深度解析安全 | reviver 与 BOM 处理 | 否（专业版） |
| Unicode 边界 | 代理对与控制字符 | 否（专业版） |
| 自动化校验流水线 | 批量校验与报告 | 否（专业版） |

### 核心功能执行
用`input_params`参数进行配置。

**输入**: 用户提供核心功能执行所需的指令和必要参数。
**处理**: 解析核心功能执行的输入参数,完成核心逻辑,返回结构化响应。
**输出**: 返回核心功能执行的响应数据,包含状态码、结果和日志。
- 执行此能力时使用`input_params`参数,支持创建/查询/导出操作

### 参数配置与调用
用`config_options`参数进行配置。

**输入**: 用户提供参数配置与调用所需的指令和必要参数。
**处理**: 解析参数配置与调用的输入参数,完成核心逻辑,返回结构化响应。
**输出**: 返回参数配置与调用的响应数据,包含状态码、结果和日志。
- 执行此能力时使用`config_options`参数,支持修改/重置/导入操作

### 结果处理与输出
用`output_format`参数进行配置。

**输入**: 用户提供结果处理与输出所需的指令和必要参数。
**处理**: 解析结果处理与输出的输入参数,完成核心逻辑,返回结构化响应。
**输出**: 返回结果处理与输出的响应数据,包含状态码、结果和日志。
- 执行此能力时使用`output_format`参数,支持导出/保存/转换操作
**能力覆盖范围**：本skill的核心能力覆盖以下场景关键词：数据结构处理优选、含校验、数字规范、核心能力、校验与契约定义、命名规范与一致性、空值处理与可选字、段策略、日期时间与数字、结构优选实践与等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

## 使用场景

1. **API 接口设计**：定义请求与响应的 JSON Schema，用 `additionalProperties: false` 拒绝未知字段，提前发现契约违反。
2. **前后端数据交换**：统一命名约定（JS 生态用 camelCase，Python 用 snake_case），避免 `userId` 与 `user_name` 混用造成混淆。
3. **配置文件处理**：处理外部配置 JSON 时先校验 Schema，避免缺字段或类型错误导致运行时崩溃。
4. **第三方接口对接**：解析第三方 API 返回的 JSON 时用 try/catch 包裹，避免格式错误中断流程。

## 不适用场景

以下场景JSON工具箱(免费版)不适合处理：

- 实时流数据处理
- 小规模数据手动分析
- 非结构化文本情感分析

## 触发条件

需要数据分析、报表生成、统计洞察、数据可视化时使用。不适用于非本工具能力范围的需求。

## 快速开始

> 上手时间：< 60 秒。本 Skill 为纯指令型，无需安装依赖。

### Step 1：定义 Schema 校验

```json
{
  "type": "object",
  "properties": {
    "id": {"type": "string"},
    "name": {"type": "string"},
    "price_cents": {"type": "integer"}
  },
  "required": ["id", "name"],
  "additionalProperties": false
}
```

### Step 2：处理空值

```json
{
  "id": "9007199254740993",
  "name": "示例",
  "deleted_at": null
}
```

### Step 3：规范日期与数字

```json
{
  "created_at": "2026-07-18T14:30:00Z",
  "price_cents": 1999,
  "user_id": "9007199254740993"
}
```

**响应解析**: 完成完成后,查看输出响应确认任务状态。成功时输出包含解析摘要和响应数据;失败时根据错误信息排查问题,查阅错误解析章节获取恢复步骤。

## 示例

### 命名约定对照表

| 生态 | 约定 | 示例 |
|:-----|:-----|:-----|
| JavaScript / TypeScript | camelCase | `userId`、`createdAt` |
| Python / Ruby | snake_case | `user_id`、`created_at` |
| Go | PascalCase（导出字段） | `UserID`、`CreatedAt` |
| 数据库列 | snake_case | `user_id`、`created_at` |

### 空值处理策略

| 场景 | 策略 | 示例 |
|---:|---:|---:|
| 字段为 null | 表示"显式置空" | `{"deleted_at": null}` |
| 字段缺失 | 表示"从未设置" | 不输出该字段 |
| 可选字段 | 省略优于 null | 可选字段无值时不输出 |
| 数组 | 用空数组表示"无元素" | `"tags": []` |

### 数字处理规范

| 场景 | 规范 | 理由 |
|:---:|:---:|:---:|
| 大 ID（> 2^53） | 字符串 | JS 精度损失 |
| 金额 | 字符串或整数分 | 避免浮点误差 |
| 坐标 | 字符串（高精度） | 避免精度损失 |
| 计数 | 整数 | 无小数需求 |

## 优选实践

1. **处理前必校验**：所有不可信输入先校验 JSON Schema，不假设结构正确。
2. **为 API 响应定义 Schema**：提前发现契约违反，而非等消费方报错。
3. **严格上下文拒绝未知字段**：`additionalProperties: false` 拒绝未知字段，避免"宽进严出"。
4. **命名约定统一**：同一 payload 内不混用 camelCase 与 snake_case。
5. **集合用复数**：`"users": []` 而非 `"user": []`，语义清晰。
6. **区分 null 与缺失**：null 表示"显式置空"，缺失表示"从未设置"，二者含义不同。
7. **可选字段省略**：无值时省略字段，减少 payload 体积，意图更清晰。
8. **日期用 ISO 8601**：`"2026-07-18T14:30:00Z"`，含时区或 UTC 的 `Z` 后缀。
9. **大数转字符串**：ID 超过 2^53 用字符串，避免 JS 精度损失。
10. **金额不用浮点**：用字符串 `"19.99"` 或整数分 `1999`，避免浮点误差。
11. **嵌套不超过 3 层**：超过则扁平化或拆分到相关端点。
12. **统一 API 信封**：`{"data": ..., "meta": ..., "errors": ...}` 标准结构。
13. **分页避免无界列表**：大数组必须分页，含 `next`/`prev` 链接或游标。

## 常见问题

### Q1：为什么建议用字符串表示大 ID？

A：JavaScript 安全整数上限是 2^53（约 9007 万亿）。超过该值的整数在 JSON.parse 后会丢失精度，如 `9007199254740993` 会变成 `9007199254740992`。用字符串可避免该问题。

### Q2：null 和字段缺失有什么区别？

A：null 表示"字段存在但值为空"（如已删除的记录 `deleted_at: null`）；字段缺失表示"从未设置过"。消费方逻辑可能不同，Schema 中应明确标注哪些字段可空。

### Q3：为什么金额不能用浮点数？

A：浮点数无法精确表示十进制小数（如 0.1 + 0.2 != 0.3）。金额计算会产生累计误差。建议用字符串 `"19.99"` 或整数分 `1999`（表示 19.99 元）。

### Q4：日期时间为什么用字符串而非时间戳？

A：(1) 字符串可读，便于调试；(2) 时间戳整数在不同语言精度不一（秒/毫秒）；(3) ISO 8601 字符串含时区信息，避免歧义。

### Q5：免费版是否支持循环引用序列化？

A：免费版仅提示"检测循环引用"。循环引用的深度处理（如 flatted 库）需使用专业版。

## 已知限制

本免费体验版限制以下高级功能：
- 高级序列化（Map/Set/BigInt/循环引用处理）（专业版支持）
- 深度解析安全（reviver 函数与 BOM 处理）（专业版支持）
- Unicode 边界处理（代理对与控制字符）（专业版支持）
- 自动化校验流水线（批量校验与报告）（专业版支持）
- 自定义 replacer 与 reviver 模板（专业版支持）

解锁全部功能请使用专业版：json-toolkit-pro
- 当前为免费版本,如需完整功能请升级到付费版获取全部能力
## 依赖说明

### 运行环境
- **Agent 平台**：支持 SKILL.md 的任意 AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等）
- **操作系统**：Windows / macOS / Linux
- **编程语言**：任意支持 JSON 的语言（JavaScript / Python / Go / Java 等）

### 依赖详情
| 依赖项 | 类型 | 是否必需 | 获取方式 |
|:------|------:|:------|:------|
| LLM API | API | 必需 | 由 Agent 平台内置 LLM 提供 |
| JSON Schema 校验库（可选） | 库 | 可选 | 各语言生态均有（如 JS 的 ajv、Python 的 jsonschema） |
| 标准库 JSON 模块 | 运行时 | 必需 | 各语言标准库自带（JSON.parse / json.loads 等） |

### API Key 配置
- **本 Skill 基于指令驱动**：无需额外 API Key，纯 Markdown 优选实践指南

### 可用性分类
- **分类**：MD（纯 Markdown 指令，无需 exec 命令行执行能力）
- **说明**：基于 Markdown 的 AI Skill，通过自然语言指令驱动 Agent 遵循 JSON 处理优选实践

## 错误处理

| 错误场景 | 原因 | 处理方式 |
|---:|:---|---:|
| 配置错误 | 参数缺失或格式错误 | 检查依赖说明中的配置要求 |
| 运行时错误 | 运行环境不满足 | 确认运行环境符合依赖说明 |
| 网络错误 | 连接超时或不可达 | 执行ping命令测试网络连通性,检查防火墙和代理设置连接后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案 |

## 输出格式
```json
{
  "success": true,
  "data": {
    "result": "JSON工具箱(免费版)处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "jsonkit"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}
```