Retrofit 2调用TMDB API响应无法映射到JSON对象问题排查

1. 核对JSON字段与模型类的映射 #

• 确保模型类字段名和TMDB响应的JSON键完全匹配，注意大小写和命名风格。TMDB用蛇形命名（如total_results），若你的模型用驼峰命名（如totalResults），必须添加@SerializedName注解绑定：

  data class DiscoverMoviesResponse(
      @SerializedName("total_results") val totalResults: Int,
      @SerializedName("results") val movies: List<Movie>,
      // 其他字段逐一对应
  )
  

• 检查字段类型是否严格匹配：比如JSON返回的是数字类型，模型不能定义为字符串；嵌套对象要对应正确的数据类/内部类。

2. 检查Retrofit接口的返回值定义 #

• 确认接口方法的返回类型和响应结构匹配。如果TMDB直接返回DiscoverMoviesResponse结构，接口要这样定义：

  interface TmdbWebService {
      @GET("discover/movie")
      suspend fun getDiscoverMovies(
          @Query("api_key") apiKey: String,
          // 其他必填参数如语言、页码等
      ): Response<DiscoverMoviesResponse>
  }
  

• 若你用了自定义的响应封装类（如ApiResult<T>），要确保封装类的泛型解析逻辑正确，没有把DiscoverMoviesResponse嵌套到错误层级。

3. 验证JSON响应的完整结构 #

• 从日志里复制完整的响应JSON，用GsonFormat等工具自动生成模型类，和你手写的模型对比差异。比如TMDB的发现电影响应最外层就是total_results、results等字段，若你错误地给模型套了data之类的外层对象，就会导致解析后字段为空。

4. 检查Retrofit的转换器配置 #

• 确认已添加正确的JSON转换器，且无自定义逻辑干扰解析：

  val retrofit = Retrofit.Builder()
      .baseUrl("https://api.themoviedb.org/3/")
      .addConverterFactory(GsonConverterFactory.create())
      .build()
  

• 若用了自定义Gson实例，检查是否开启了严格模式、是否禁用了字段匹配策略，导致合法字段被过滤。

5. 直接打印原始响应调试 #

• 在Repository中获取响应后，先打印原始响应体字符串，确认内容是否符合预期：

  suspend fun getDiscoverMovies(): DiscoverMoviesResponse? {
      val response = tmdbWebService.getDiscoverMovies(API_KEY)
      if (response.isSuccessful) {
          // 打印原始JSON字符串
          response.raw().body?.let {
              val rawJson = it.string()
              Log.d("TMDB_RAW", rawJson)
          }
          return response.body()
      }
      return null
  }
  

通过原始JSON可以直接定位是模型映射错误，还是Retrofit配置问题。

内容的提问来源于stack exchange，提问作者greysqrl