JEP 540 提议为 JDK 28 引入简单 JSON API

2026 年 8 月 17 日 · 3 分钟阅读 · A N M Bazlur Rahman

JEP 540（Simple JSON API，孵化器）已从 Candidate 状态推进到 Proposed to Target 状态，目标版本为 JDK 28。它将新增一个由 JDK 提供的紧凑 API，用于在没有外部依赖的情况下解析、导航和生成符合 RFC 8259 的 JSON 文档。如果该提案进入 Targeted 状态并最终交付，API 将随孵化中的 jdk.incubator.json 模块一同发布，在该模块中，API 可能会根据开发者反馈发生不兼容变更或被移除。

该提案刻意比 Jackson 和 Gson 这类库的范围更窄。它不包含数据绑定和流式处理，也不提供宽松解析模式或任何语法扩展。相反，它专注于常见任务，例如读取配置文件、检查 REST 响应或生成小型 JSON 负载。API 以 Json 类和密封的 JsonValue 接口为核心。JsonValue 允许六个非密封子接口，分别表示 JSON 对象、数组、字符串、数字、布尔值和 null。所有实例都是不可变且线程安全的。

使用 Json.parse(String) 或 Json.parse(char[]) 解析完整的在内存文档，会返回一个 JsonValue：

String body = ...; // JSON response body
int temperature = Json.parse(body)
    .get("properties")
    .get("periods")
    .get(0)
    .get("temperature")
    .asInt();

核心设计选择是直接在 JsonValue 上声明访问方法，这样调用者无需反复对中间值进行强制类型转换即可遍历对象和数组。对非对象调用 get(String)、对非数组调用 get(int)、请求不存在的成员，或使用无效索引，都会抛出 JsonValueException。

主要的易用性权衡体现在文档构造上。JSON 值通过对应接口上的工厂方法创建：

JsonObject document = JsonObject.of(Map.of(
    "service", JsonString.of("web_server"),
    "id", JsonNumber.of(3),
    "active", JsonBoolean.of(true)
));

在 JsonValue 上调用 toString() 会生成紧凑的 JSON，而 Json.toDisplayString(...) 则生成用于展示的格式化表示。显式工厂使每个值的 JSON 类型一目了然，但同时也增加了仪式感，因为普通的 Java 字符串、数字和布尔值必须先包装后才能放入对象或数组中。因此，构造易用性很可能成为孵化期间反馈的重点领域之一。

严格性是另一个决定性选择。解析器不提供宽松模式，因此会拒绝注释、尾随逗号以及其他语法扩展。它还拒绝重复的对象成员名，尽管 RFC 8259 只是建议名称应唯一，并未将唯一性作为绝对要求。否则，不同的解析器可能会保留第一个值、保留最后一个值、保留所有出现，或拒绝整个文档，这使得重复名称成为互操作性风险。

无效语法和重复名称会产生非受检的 JsonParseException，其中会记录检测到错误的从零开始的行号和位置。其公共 API 不暴露结构化的 JSON 路径。

密封的值层次结构还能与模式匹配自然配合。对于将标识符作为 JSON 数字或字符串输出的生产者，可以使用类型模式 switch 来处理：

long id = switch (json.get("id")) {
    case JsonNumber number -> number.asLong();
    case JsonString string -> Long.parseLong(string.asString());
    default -> throw new JsonValueException("Unexpected id type");
};

转换方法遵循 as... 命名约定。asInt() 和 asLong() 要求该值是在目标类型范围内的精确整数值。asDouble() 将数字转换为有限的 double，但可能会舍入或丢失精度。asBoolean()、asMap() 和 asList() 将布尔值、对象和数组以 Java 值的形式暴露出来。这些 map 和 list 视图是不可修改的，并且仍然包含 JsonValue 实例，而不是递归转换后的 Java 基本类型。对错误的 JSON 类型应用转换会抛出 JsonValueException。

对于可选对象成员，tryGet(String) 返回一个 Optional，当成员不存在时为空。如果对不是 JSON 对象的值调用它，仍然会抛出 JsonValueException。该 API 还区分缺失成员和显式包含 JSON null 的成员：对于后者，tryGet() 返回包含 JsonNull 的 Optional，而 tryValue() 则返回空的 Optional。

JEP 198（Light-Weight JSON API）是 2014 年创建的一个更广泛的提案，但一直未能交付。新设计专注于不可变的内存值层次结构，并将对象映射、流式处理、模式验证和高级定制留给现有的 JSON 生态系统。

如果 JEP 540 成为 Targeted 状态并交付，类路径应用程序需要使用 --add-modules jdk.incubator.json 显式解析孵化器模块。孵化期将允许 OpenJDK 社区在 API 进一步演进之前评估其导航模型、异常语义、数值转换和构造易用性。

关于作者

A N M Bazlur Rahman

A N M Bazlur Rahman 是 Hammerspace 的资深员工软件工程师，也是 Java Champion，专注于 Java 及现代 Java 相关技术。在日常工程工作之外，Bazlur 还以导师、作者、演讲者和开源贡献者的身份深度参与全球 Java 社区。他创立并主持孟加拉 Java 用户组（JUGBD），自 2013 年起组织聚会和会议以推广 Java 知识。Bazlur 还是 InfoQ 的贡献编辑和 Foojay.io 的编辑，这两个平台是全球 Java 专业人士最受尊敬的平台之一。他撰写了几本孟加拉语 Java 编程书籍，包括畅销书《Java Programming》，帮助数千名开发者用母语学习该语言。他的最新英文著作《Modern Concurrency in Java》（O'Reilly Media）探讨了 Java 通过虚拟线程和结构化并发不断演进的并发模型。