Python 使用 json-repair 修复大模型返回的异常 JSON

开发注意事项

避免重复验证

有些开发者习惯先尝试 json.loads()，失败后再调用 repair_json。这其实是浪费资源，因为 json_repair 内部会自动验证 JSON 是否有效。除非你明确需要区分'完全无效'和'可修复'，否则直接使用 repair_json.loads() 即可。

# 不推荐的做法
try:
    obj = json.loads(string)
except json.JSONDecodeError:
    obj = json_repair.loads(string)

# 推荐做法
obj = json_repair.loads(string)

文件读取

除了处理字符串，它也能直接替代 json.load() 从文件或文件描述符中读取数据。

import json_repair

# 方式一：通过文件描述符
with open('data.json', 'rb') as f:
    decoded_object = json_repair.load(f)

# 方式二：更简洁的文件路径读取
try:
    decoded_object = json_repair.from_file('data.json')
except OSError:
    pass

注意：库本身不会捕获 I/O 异常，你需要自行处理文件权限或路径错误。

非拉丁字符处理

默认情况下，输出可能会将中文等非 ASCII 字符转义为 Unicode。如果需要保留原始字符，请传递 ensure_ascii=False。

# 默认行为：转义
repair_json("{'test_chinese_ascii':'统一码'}") 
# 输出：{"test_chinese_ascii":"\u7edf\u4e00\u7801"}

# 保留原字符
repair_json("{'test_chinese_ascii':'统一码'}", ensure_ascii=False)
# 输出：{"test_chinese_ascii":"统一码"}

性能优化

如果你确定输入字符串一定不是有效 JSON，或者对性能有极致要求，可以跳过初始的 json.loads 检查。

from json_repair import repair_json

# 跳过初始验证，速度更快
good_json_string = repair_json(bad_json_string, skip_json_loads=True)

注意：skip_json_loads=True 仅在字符串确实无效时比默认模式快；若字符串本身有效，默认模式可能更优。同时，设置 return_objects=True 通常也更快，因为它避免了序列化回 JSON 字符串的步骤。

严格模式

默认模式下，json_repair 会尽力修复数据。但在某些验证场景下，你可能希望遇到错误直接抛出异常，而不是盲目修复。

from json_repair import repair_json

# 启用严格模式
repair_json(bad_json_string, strict=True)

在严格模式下，遇到重复键、缺失分隔符、多余逗号导致的空键值对等问题时，会抛出 ValueError。这对于校验数据完整性非常有用。

流式修复

对于传输中的流式数据，可以使用 stream_stable=True 参数来保持修复过程的稳定性。

stream_output = repair_json(stream_input, stream_stable=True)

CLI 工具

命令行工具同样支持上述功能，方便在脚本或管道中使用。

# 查看帮助
json_repair -h

# 修复文件并输出到指定目录
json_repair --output target.json input.json

# 严格模式
json_repair --strict input.json

Java 版本参考

如果你在使用 Java 生态，也有对应的实现包。

<dependency>
    <groupId>io.github.du00cs</groupId>
    <artifactId>json-repairj</artifactId>
    <version>0.50.0</version>
</dependency>

使用示例：

import org.jsonrepairj.JsonRepair;
import org.jsonrepairj.ParseResult;

public class Test {
    public static void main(String[] args) {
        String str = "你好，这是我按照 json 格式返回的数据：{\"name\": \"约翰\", \"age\": 30}";
        
        // 修复并输出字符串
        String result = JsonRepair.repairJson(str);
        System.out.println(result);
        
        // 获取更详细的解析结果
        ParseResult result2 = JsonRepair.parseJson(str, true, false);
        System.out.println(result2.getJson().toString());
    }
}