本教程详细介绍了在 Java 中使用 Gson 库反序列化包含动态键的 json 结构。针对常见的 retrofit2 响应中出现 NULL 值的问题，我们将通过一个具体的股票数据 JSON 示例，演示如何正确地将 JSON 中的动态日期时间键映射到 Java POJO 中的 map 类型，从而有效解决反序列化失败的挑战，确保数据能够被准确解析。
引言：动态 JSON 键的挑战
在与 restful api 交互时，我们经常会遇到 json 响应中包含动态键值对的情况。例如，金融数据、日志记录或某些配置信息可能使用日期时间、用户id或产品代码作为 json 对象的键。传统的 pojo（plain old java Object）映射通常要求 json 键与 pojo 字段名静态一致，但在动态键场景下，直接使用固定字段名会导致 gson 等反序列化库无法识别这些动态键，从而导致对应的 pojo 字段为 null。
本文将以一个典型的股票市场数据 JSON 结构为例，该结构中包含动态的日期时间键，我们将展示如何使用 Gson 库优雅且高效地解决这一反序列化难题。
问题分析：原始 POJO 结构及其局限性
考虑以下股票数据 JSON 响应的片段：
{ "Meta Data": { "1. Information": "intraday (5min) open, high, low, close prices and volume", // ... 其他元数据 }, "Time Series (5min)": { "2022-10-26 19:40:00": { "1. open": "135.0600", "2. high": "135.0700", // ... 其他数据 }, "2022-10-26 19:05:00": { "1. open": "135.3500", // ... 其他数据 } // ... 更多动态日期键 } }
在这个 JSON 结构中，”Meta Data” 部分的键是固定的，可以直接映射到 MetaData POJO。然而，”Time Series (5min)” 部分则包含了一系列以日期时间字符串为键的子对象，这些日期时间键是动态变化的。
原始的 POJO 设计尝试将 DailyQuote 类中的 “Time Series (5min)” 映射到一个名为 TimeSeries 的 POJO，而 TimeSeries 内部又包含了一个 Map
立即学习“Java免费学习笔记（深入）”；
// DailyQuote.java (原始部分) public class DailyQuote { @SerializedName("Meta Data") @Expose private MetaData metaData; @SerializedName("Time Series (5min)") @Expose private TimeSeries timeSeries; // 这里将 "Time Series (5min)" 映射到一个 TimeSeries 对象 // ... getter/setter } // TimeSeries.java (原始) public class TimeSeries { @Expose private Map<String, date> dates; // TimeSeries 内部又包含一个 Map // ... constructor, getter/setter }
这种设计的问题在于，JSON 结构中 “Time Series (5min)” 键所对应的值直接就是一个包含动态日期键的对象，而不是一个内部再包含 dates 字段的对象。换句话说，JSON 中没有一个名为 dates 的子键来容纳那些动态日期键值对。因此，当 Gson 尝试解析时，它会发现 TimeSeries POJO 中声明的 dates 字段在 JSON 响应中找不到对应的键，导致 timeSeries 内部的 dates 字段最终为 null。
解决方案：直接映射到 Map 类型
当 JSON 对象中的键是动态的，且其值类型固定时，最直接有效的方法是将该 JSON 对象在父级 POJO 中直接映射到 Java 的 Map
对于本例，”Time Series (5min)” 下的每个动态日期键都对应一个结构固定的 date 对象。因此，我们应该将 DailyQuote 类中的 timeSeries 字段直接声明为 Map
修正后的 DailyQuote 类：
import com.google.gson.annotations.Expose; import com.google.gson.annotations.SerializedName; import java.util.Map; // 引入 Map public class DailyQuote { @SerializedName("Meta Data") @Expose private MetaData metaData; // 关键修改：直接将 "Time Series (5min)" 映射为 Map<String, date> @SerializedName("Time Series (5min)") @Expose private Map<String, date> timeSeries; // 注意这里直接是 Map<String, date> /** * 无参构造函数，用于序列化 */ public DailyQuote() { } /** * 带参构造函数 * @param metaData 元数据 * @param timeSeries 时间序列数据 */ public DailyQuote(MetaData metaData, Map<String, date> timeSeries) { this.metaData = metaData; this.timeSeries = timeSeries; } public MetaData getMetaData() { return metaData; } public void setMetaData(MetaData metaData) { this.metaData = metaData; } public Map<String, date> getTimeSeries() { return timeSeries; } public void setTimeSeries(Map<String, date> timeSeries) { this.timeSeries = timeSeries; } }
MetaData 类（保持不变）：
MetaData 类结构正确，因为其内部的键（如 “1. Information”, “2. symbol” 等）都是固定的。
import com.google.gson.annotations.Expose; import com.google.gson.annotations.SerializedName; public class MetaData { @SerializedName("1. Information") @Expose private String _1Information; @SerializedName("2. Symbol") @Expose private String _2Symbol; @SerializedName("3. Last Refreshed") @Expose private String _3LastRefreshed; @SerializedName("4. Interval") @Expose private String _4Interval; @SerializedName("5. Output Size") @Expose private String _5OutputSize; @SerializedName("6. Time Zone") @Expose private String _6TimeZone; public MetaData() { } public MetaData(String _1Information, String _2Symbol, String _3LastRefreshed, String _4Interval, String _5OutputSize, String _6TimeZone) { this._1Information = _1Information; this._2Symbol = _2Symbol; this._3LastRefreshed = _3LastRefreshed; this._4Interval = _4Interval; this._5OutputSize = _5OutputSize; this._6TimeZone = _6TimeZone; } public String get1Information() { return _1Information; } public void set1Information(String _1Information) { this._1Information = _1Information; } public String get2Symbol() { return _2Symbol; } public void set2Symbol(String _2Symbol) { this._2Symbol = _2Symbol; } public String get3LastRefreshed() { return _3LastRefreshed; } public void set3LastRefreshed(String _3LastRefreshed) { this._3LastRefreshed = _3LastRefreshed; } public String get4Interval() { return _4Interval; } public void set4Interval(String _4Interval) { this._4Interval = _4Interval; } public String get5OutputSize() { return _5OutputSize; } public void set5OutputSize(String _5OutputSize) { this._5OutputSize = _5OutputSize; } public String get6TimeZone() { return _6TimeZone; } public void set6TimeZone(String _6TimeZone) { this._6TimeZone = _6TimeZone; } }
date 类（保持不变）：
date 类也结构正确，因为它描述的是每个动态日期键下的固定字段（”1. open”, “2. high” 等）。
import com.google.gson.annotations.Expose; import com.google.gson.annotations.SerializedName; public class date { @SerializedName("1. open") @Expose private String _1Open; @SerializedName("2. high") @Expose private String _2High; @SerializedName("3. low") @Expose private String _3Low; @SerializedName("4. close") @Expose private String _4Close; @SerializedName("5. volume") @Expose private String _5Volume; public date() { } public date(String _1Open, String _2High, String _3Low, String _4Close, String _5Volume) { this._1Open = _1Open; this._2High = _2High; this._3Low = _3Low; this._4Close = _4Close; this._5Volume = _5Volume; } public String get1Open() { return _1Open; } public void set1Open(String _1Open) { this._1Open = _1Open; } public String get2High() { return _2High; } public void set2High(String _2High) { this._2High = _2High; } public String get3Low() { return _3Low; } public void set3Low(String _3Low) { this._3Low = _3Low; } public String get4Close() { return _4Close; } public void set4Close(String _4Close) { this._4Close = _4Close; } public String get5Volume() { return _5Volume; } public void set5Volume(String _5Volume) { this._5Volume = _5Volume; } @Override public String toString() { return "List:{" + "Open='" + get1Open() + ''' + ", High='" + get2High() + ''' + ", Low='" + get3Low() + ''' + ", Close='" + get4Close() + ''' + ", Volume='" + get5Volume(); } }
示例与应用
在 Retrofit2 等网络请求库中，一旦您定义了正确的 POJO 结构，Gson 将能够自动处理反序列化过程。例如，您的 Retrofit 接口方法可以声明返回 Call
import retrofit2.Call; import retrofit2.http.GET; public interface StockApiService { @GET("query?function=TIME_SERIES_INTRADAY&symbol=IBM&interval=5min&apikey=YOUR_API_KEY") Call<DailyQuote> getIntradayTimeSeries(); }
当您执行 call.enqueue() 并收到响应时，Gson 会将 JSON 响应体正确地映射到 DailyQuote 实例。您可以通过 dailyQuote.getTimeSeries() 获取到一个 Map
// 示例：如何访问解析后的数据 DailyQuote dailyQuote = response.body(); if (dailyQuote != null && dailyQuote.getTimeSeries() != null) { for (Map.Entry<String, date> entry : dailyQuote.getTimeSeries().entrySet()) { String timestamp = entry.getKey(); date quoteData = entry.getValue(); System.out.println("Timestamp: " + timestamp + ", Open: " + quoteData.get1Open() + ", Close: " + quoteData.get4Close()); } }
注意事项与最佳实践
-
@SerializedName 注解： 当 JSON 键包含空格、特殊字符或与 Java 字段命名规范不符时（例如 Meta Data、Time Series (5min) 或 1. open），务必使用 @SerializedName(“JSON Key Name”) 注解来指定对应的 JSON 键名。这确保了 Gson 能够正确地将 JSON 键映射到 Java 字段。
-
@Expose 注解： 如果您在使用 GsonBuilder 构建 Gson 实例时启用了 excludeFieldsWithoutExposeAnnotation()（例如 new GsonBuilder().excludeFieldsWithoutExposeAnnotation().create()），那么所有需要参与序列化或反序列化的字段都必须带有 @Expose 注解。这有助于更精细地控制哪些字段应该被处理。
-
避免过度设计： 仔细分析 JSON 结构是构建正确 POJO 的关键。如果一个 JSON 对象直接代表一个键值对集合（即它的所有子键都是动态的，且这些键的值类型相同），那么就应该直接将其映射为 Map
，而不是为其再创建一个包含 Map 的额外 POJO。过度嵌套会增加代码复杂性并可能导致反序列化错误。 -
调试技巧： 当反序列化出现 null 值或数据不完整时，首先检查以下几点：
- JSON 结构与 POJO 映射是否完全匹配： 使用在线 JSON 格式化工具（如 JSONLint）验证 JSON 结构，并与您的 POJO 定义逐层对比。
- 字段名称与 @SerializedName 是否正确： 确保 @SerializedName 中的字符串与 JSON 键完全一致（包括大小写和特殊字符）。
- 数据类型是否匹配： 确保 POJO 字段的数据类型与 JSON 值的数据类型兼容（例如，JSON 中的数字字符串应映射到 String 或 BigDecimal，而不是直接 int 或 double，除非您有自定义 TypeAdapter）。
- 检查网络响应： 确保实际接收到的 JSON 响应与您预期的 JSON 结构一致。
总结
处理包含动态键的 JSON 结构是数据解析中的常见场景。通过将 JSON 中动态键的部分直接映射到 Java 的 Map
