通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 Java 的 Azure JSON 共享库 - 版本 1.1.0

  • 项目

生成文档

Azure JSON 为 JSON 提供共享基元、抽象和帮助程序。

入门

先决条件

添加包

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-json</artifactId>
  <version>1.1.0</version>
</dependency>

关键概念

JsonSerializable

JsonSerializable 用于定义如何使用流式序列化对对象进行 JSON 序列化和反序列化，其中对象本身管理其处理方式的逻辑。 接口提供一个基于 toJson 实例的 API，用于处理将 对象写入 到 ， JsonWriter 以及一个静态 fromJson API，实现必须提供该 API 来定义如何通过从 JsonReader读取来创建对象，如果未提供 UnsupportedOperationException 实现，则将引发 。

JsonToken

JsonToken 是一个基本枚举，指示 JSON 流中的当前状态。

JsonReader

JsonReader 提供基本、读取基元和装箱基元类型，以及读取数组、映射和对象以及用于读取 JSON 的 API 的便利性。 JsonReader 提供 是为了允许任何基础 JSON 分析程序（例如 Jackson 或 GSON）实现它，前提是实现通过此包的 test-jar () JsonReaderContractTests 提供的测试。

JsonReader 在调用 之前 nextToken 不会在 JSON 流中向前推进，这意味着 JsonReader.getInt ，可以无限期地调用 并返回相同的整数，而不会出错，直到 nextToken 推进 JSON 流向前。

JsonReader允许在 JSON 类型之间进行类型转换，例如尝试将 JSON 字符串转换为数字，反之亦然;对于常用的非标准 JSON 值（例如 NaN、、INF-INF、 Infinity和 -Infinity），则允许类型转换。

JsonReader不获取 JSON 输入源的所有权，因此，如果使用 或 Reader提供 InputStream JSON，则不会关闭任何资源。

嵌套限制

JsonReader的泛型 readUntyped API 跟踪所读取对象的嵌套深度。 如果嵌套超过 的阈值 1000， IllegalStateException 则会引发 以防止 StackOverflowError。

JsonWriter

JsonWriter 提供基本、编写基元和装箱基元类型，以及编写数组、映射和对象以及用于编写 JSON 的 API 的便利性。 JsonWriter 提供 是为了允许任何基础 JSON 编写器（例如 Jackson 或 GSON）实现它，前提是实现通过包的 test-jar (JsonWriterContractTests) 提供的测试。

JsonWriter允许使用 或 写入常用的非标准 JSON 值，例如 NaN、INF、-INFInfinity、 和 -Infinity。writeRawValuewriteNumberField

JsonWriter当写入为字段writeNumberFieldwriteBinaryFieldwriteBooleanField、Boolean、Number、 或 String 时，如果需要写入空byte[]字段，则不会写入 null 、、 或 writeStringField值，请使用 。writeNullField

JsonWriter 必须定期刷新，以确保写入到它的内容刷新到基础容器类型，通常为 OutputStream 或 Writer。 未能刷新可能会导致内容丢失。 关闭 会 JsonWriter 刷新内容，因此最佳做法 JsonWriter 是在 try-with-resources 块中使用 ，在该 JsonWriter 块中，使用完成后会关闭 。

JsonWriter不获取 JSON 输出源的所有权，因此，如果 JSON 正在写入 或 Writer，OutputSteam则不会关闭任何资源。

JSON 状态管理

若要确保正在写入的 JSON 有效，请使用 JsonWriteContext 维护 JSON 的状态，JsonWriter并在每次尝试写入时都会验证操作是否有效。 的 JsonWriter 实现必须确保正确跟踪状态，例如，当未写入任何内容时，JSON 状态必须为 ROOT ，并且 ROOT 不允许写入 JSON 字段名称。

JsonProvider

JsonProvider 是一个服务提供程序接口，允许 JsonReader使用类路径上的实现创建 和 JsonWriter。 JsonProvider 如果类路径上找不到实现，还可以创建此包提供的默认实现。

JsonOptions

JsonOptions包含 的所有 实现都必须遵循 的配置JsonReaderJsonWriter。 目前，只有一种配置用于确定 JSON 读取和写入中是否支持非数字数字NaN、、INFInfinity-INF、、 和 -Infinity ，并且默认设置true为 ，即允许非数字数字。

提供 SPI 实现

JsonReader和 JsonWriter 是 和 JsonProviders 用于JsonProvider启用从类路径加载实现的服务提供程序接口。 Azure JSON 包提供了一个默认实现，如果在类路径上找不到该实现，将使用该实现。 若要提供自定义实现，请在自己的包中实现 JsonReader、 JsonWriter和 JsonProvider ，并指示该包提供 的 JsonProvider实例。 若要确保实现正确，请包含 test Azure JSON 的作用域依赖项，并扩展 JsonReaderContractTests、 JsonWriterContractTests和 JsonProviderContractTests。 这些测试概述了 、 JsonWriter和 JsonProvider 设置JsonReader的所有基本协定要求，并测试了一些复杂的方案，以提供对任何实现的验证。

示例

有关如何使用 Azure JSON 的深入示例，请查看 示例自述 文件。

疑难解答

如果遇到任何 bug，请通过 GitHub 问题提交问题 ，或查看 适用于 Azure Java SDK 的 StackOverflow。

后续步骤

开始使用 使用 Azure Core 生成的 Azure 库。

供稿

有关参与此存储库的详细信息，请参阅 参与指南。

  1. 分支
  2. 创建功能分支 (git checkout -b my-new-feature)
  3. () git commit -am 'Add some feature' 提交更改
  4. 推送到分支 (git push origin my-new-feature)
  5. 创建新的拉取请求

曝光数