本文介绍如何处理服务器逐段推送的多个独立 json 对象（如下载进度更新），解决“json 标准仅允许一个顶层值”导致的解析失败问题，并提供文件存储、流式读取与替代方案的专业实践。
在构建 Java REST 客户端时，若服务端以非数组形式、逐块推送多个独立 JSON 对象（即所谓的 JSON Lines 或 NDJSON 格式），直接使用标准 JSON 解析器（如 Jackson 的 ObjectMapper.readValue() 或 Gson 的 fromJson()）会抛出 com.fasterxml.jackson.core.JsonParseException: JSON standard allows only one top level value 错误——因为严格遵循 RFC 8259 的 JSON 规范要求整个文档必须且仅能有一个根值（对象或数组），而连续的 {...}{...}{...} 不符合语法。
✅ 正确做法：采用流式解析（Streaming Parsing）
推荐使用支持 JSON Lines（NDJSON） 的解析方式，即逐行读取、逐个解析独立 JSON 对象。Jackson 提供了开箱即用的支持：
Miller CSV TSV JSON 数据处理器
下载
Miller (mlr) 是一个命令行工具，用于查询、整形和重新格式化名称索引数据，如 CSV、TSV、JSON 和 JSON Lines。它将 awk、sed、cut、join 和 sort 的功能整合到一个专为结构化数据处理而构建的单一工具中。
import com.fasterxml.jackson.core.JsonFactory;
import com.fasterxml.jackson.core.JsonParser;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.io.File;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;
public class ContinuousJsonProcessor {
private static final ObjectMapper mapper = new ObjectMapper();
public static void processContinuousJsonFile(String filePath) throws IOException {
JsonFactory factory = mapper.getFactory();
try (JsonParser parser = factory.createParser(Files.newInputStream(Paths.get(filePath)))) {
// 启用 JSON Lines 模式（允许重复 root）
parser.configure(JsonParser.Feature.ALLOW_UNQUOTED_FIELD_NAMES, true); // 兼容无引号键（如 result）
parser.configure(JsonParser.Feature.ALLOW_SINGLE_QUOTES, true); // 兼容单引号字符串
while (parser.nextToken() != null) {
// 每次遇到 { 开始，解析一个完整对象
JsonNode node = mapper.readTree(parser);
System.out.println("→ 进度：" +
node.path("result").path("percentage").asText() + " | " +
node.path("result").path("result").asText());
}
}
}
public static void main(String[] args) throws IOException {
processContinuousJsonFile("continuous-response.json");
}
}⚠️ 注意：原始示例中字段名（如 result、percentage）未加双引号，属于非标准 JSON。上述代码通过启用 ALLOW_UNQUOTED_FIELD_NAMES 和 ALLOW_SINGLE_QUOTES 实现兼容；生产环境强烈建议服务端返回标准 JSON（所有键和字符串均用双引号包裹）。
? 替代方案对比与选型建议
| 方案 | 适用场景 | 优点 | 缺点 |
|---|---|---|---|
| JSON Lines（逐行解析） | 实时日志、进度流、服务端 SSE/HTTP streaming 响应 | 内存友好、低延迟、无需预加载全量数据 | 需手动处理解析边界，不支持随机访问 |
|
封装为 JSON 数组 [ {...}, {...}, {...} ] |
批量离线测试、小规模响应集合 | 兼容所有标准 JSON 库，结构清晰 | 文件需重写追加，高频写入性能差；大文件易 OOM |
| 单文件 → 多文件（如 progress_001.json, progress_002.json） | 高并发写入、需并行处理 | 无锁、可分布式、易于清理 | 文件系统 I/O 开销增大，管理成本上升 |
| 轻量级嵌入式数据库（如 SQLite / H2） | 需查询、过滤、分页、持久化保障 | ACID 支持、索引加速、事务安全 | 引入额外依赖，增加部署复杂度 |
✅ 最佳实践总结
- ✅ 优先采用 JSON Lines 流式解析：适用于真实服务端持续推送场景（如 HTTP chunked encoding 或 Server-Sent Events），避免内存膨胀；
- ✅ 服务端应输出标准 JSON：确保字段名与字符串均使用双引号，提升跨语言兼容性；
- ✅ 避免动态拼接大 JSON 数组文件：尤其在高频率更新时，频繁重写大文件将严重拖慢 I/O 性能；
- ✅ 超大规模或强一致性需求 → 切换至数据库：例如将每条进度记录作为一行插入 SQLite 表，字段包括 id, timestamp, percentage, status；
- ✅ 单元测试中模拟连续响应：可借助 OkHttp MockWebServer 或 WireMock 模拟分块响应头（Transfer-Encoding: chunked），验证客户端流式处理逻辑。
通过合理选择解析策略与存储模型，你不仅能优雅应对电影下载等长周期任务的进度反馈，还能为未来扩展实时监控、可观测性埋点打下坚实基础。
