# json-repair-java

**Repository Path**: mud-consumption/json-repair-java

## Basic Information

- **Project Name**: json-repair-java
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-06
- **Last Updated**: 2026-05-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# json-repair-java

[json-repair](https://github.com/mangiucugna/json_repair) 的 Java 移植版本 —— 修复来自 LLM、API、日志和用户输入的格式错误的 JSON。

- 修复缺失的引号、逗号、括号、注释、多余文本以及截断的值
- 可作为 `ObjectMapper.readValue()` / 标准 JSON 解析的替代回退方案
- 支持基于 JSON Schema 的引导式修复与校验
- 提供 CLI 界面，支持文件/流处理

## 功能特性

| 修复类型 | 处理示例 |
|--------|-----------------|
| 缺失引号 | `{key: "value"}` → `{"key": "value"}` |
| 单引号 | `{'key': 'value'}` → `{"key": "value"}` |
| 缺失闭合括号 | `{"key": "value"` → `{"key": "value"}` |
| 尾随逗号 | `[1, 2, 3,]` → `[1, 2, 3]` |
| 缺失冒号 | `{"key" "value"}` → `{"key": "value"}` |
| 注释 | `#`、`//`、`/* */` 会被移除 |
| 截断的 JSON | `{"key": "value` → `{"key": "value"}` |
| 未加引号的布尔值/null | `{key: true, other: null}` |
| 代码块标记 | ````json\n{...}\n```` 会被解除包装 |
| 流式稳定性 | 针对流式部分 JSON 的确定性状态处理 |
| Schema 引导修复 | 填充默认值、类型转换、丢弃无效项 |

## 使用方式

### Maven

```xml
<dependency>
    <groupId>com.jsonrepair</groupId>
    <artifactId>json-repair-java</artifactId>
    <version>1.0.0</version>
</dependency>
```

从源码构建：

```bash
git clone <repo-url>
cd json-repair-java
mvn package
```

### 基础修复

最简单的方式：

```java
import com.jsonrepair.JsonRepair;

// 类似于 json.loads() 的快捷方法，直接返回解析后的对象
Map<?, ?> obj = (Map<?, ?>) JsonRepair.loads("{'key': 'value'}");
```

如果需要更精细的控制，使用 `repairJson`：

```java
Object result = JsonRepair.repairJson(jsonStr, returnObjects, skipJsonLoads, logging, streamStable, strict);
```

6 个参数说明：

| 参数 | 类型 | 说明 |
|------|------|------|
| `jsonStr` | `String` | 要修复的 JSON 字符串 |
| `returnObjects` | `boolean` | `true` 返回解析后的 Java 对象（Map/List），`false` 返回修复后的 JSON 字符串 |
| `skipJsonLoads` | `boolean` | `true` 跳过初始的合法 JSON 校验，直接进入修复流程 |
| `logging` | `boolean` | `true` 同时返回修复日志（返回类型为 `List<Object>`，第 0 项为结果，第 1 项为日志） |
| `streamStable` | `boolean` | `true` 保证流式场景下，逐步追加输入时已有结果保持稳定 |
| `strict` | `boolean` | `true` 遇到结构问题直接抛出异常，不做自动修复 |

常用场景：

```java
// 返回 JSON 字符串（全部 false）
String json = (String) JsonRepair.repairJson("{\"key\": \"value\"", false, false, false, false, false);

// 返回 Java 对象
Map<?, ?> obj = (Map<?, ?>) JsonRepair.repairJson("{'key': 'value'}", true, false, false, false, false);

// 严格模式：结构有问题就抛异常
JsonRepair.repairJson(badJson, true, false, false, false, true);

// 流式稳定：适合处理 LLM 流式输出的部分 JSON
Object result = JsonRepair.repairJson(streamPartialJson, true, false, false, true, false);
```

### 从文件修复

```java
Object result = JsonRepair.fromFile("broken.json");
```

### 严格模式

```java
// 遇到结构问题时抛出 IllegalArgumentException，而非尝试修复
JsonRepair.repairJson(badJson, true, false, false, false, true);
```

### 基于 Schema 的引导修复

```java
Map<String, Object> schema = Map.of(
    "type", "object",
    "properties", Map.of("value", Map.of("type", "integer")),
    "required", List.of("value")
);

// 自动将 "1" 转换为 1，填充缺失的必填字段
Map<?, ?> result = (Map<?, ?>) JsonRepair.repairJson(
    "{\"value\": \"1\"}", true, false, false, false, false, schema, "standard"
);
```

### 日志输出

```java
@SuppressWarnings("unchecked")
List<Object> result = (List<Object>) JsonRepair.repairJson(json, true, false, true, false, false);
Map<?, ?> repaired = (Map<?, ?>) result.get(0);
List<Map<String, String>> log = (List<Map<String, String>>) result.get(1);
```

### 流式稳定性

```java
Object result = JsonRepair.repairJson(streamPartialJson, true, false, false, true, false);
```

### JSON 输出格式化

```java
String json = JsonRepair.toJsonString(obj, false, 2); // 美观打印，2 空格缩进
String ascii = JsonRepair.toJsonString(obj, true, 0);  // 转义非 ASCII 字符
```

## 命令行 (CLI)

```bash
java -jar json-repair-java.jar [filename] [options]

选项:
  -i, --inline            直接替换原文件内容
  -o, --output FILE       将输出写入指定文件
  --ensure_ascii          转义非 ASCII 字符
  --indent N              缩进空格数（默认: 2）
  --skip-json-loads       跳过初始校验
  --schema FILE           用于引导修复的 JSON Schema 文件
  --strict                遇到结构问题时抛出异常，而非尝试修复
  --schema-repair-mode MODE  standard（默认）或 salvage
```

从标准输入读取：

```bash
echo '{"key": "value"' | java -jar json-repair-java.jar
```

## 工作原理

该解析器遵循 JSON 的 BNF 定义，在遇到格式错误的结构时应用启发式规则进行修复：

- **缺失括号**: 检测 EOF 处未闭合的对象/数组，自动追加闭合分隔符
- **缺失引号**: 对看起来像字符串的未加引号的键/值（非数字、非 true/false/null）自动添加引号
- **引号错位**: 通过上下文分析（解析器下一步期望的是键、值还是分隔符）来判断引号字符是分隔符还是字面量
- **注释**: `#`、`//` 和 `/* */` 在词法分析阶段被移除
- **尾随逗号**: 在闭合分隔符前跳过
- **代码块标记**: 移除开头的 ````json` 和结尾的 ```` 标记
- **截断处理**: EOF 处不完整的字符串会被闭合；不完整的容器会被终止

## 许可证

Apache 2.0

本项目为 Python 库 [json-repair](https://github.com/mangiucugna/json_repair)（作者：Stefano Baccianella）的 Java 移植版本。