Android应用调用自定义API POST接口报IllegalStateException错误

这个IllegalStateException说白了就是：你的Retrofit+Gson组合期望解析出一个JSON对象（{...}），但你的PHP POST接口实际返回的是JSON数组（[{...}]），格式完全不匹配，直接导致解析失败。

1. 先检查PHP接口的返回格式 #

打开你的PHP POST接口代码，看最后json_encode的是什么数据：

• 如果是直接返回数据库查询的结果集（比如用fetchAll()得到的二维数组），那返回的肯定是JSON数组，示例：

$res = $pdo->query("SELECT * FROM xxx WHERE ...")->fetchAll();
echo json_encode($res);
// 输出：[{"id":1,"name":"test"}, ...]

而你的Android Model类是按单个对象定义的，这就完全对不上了。

两种修正方向： #

方向一：修改PHP返回为对象格式

如果接口本来就该返回单个数据（比如新增/修改后的单条记录），把返回改成单个对象，最好套一层统一的响应结构：

// 获取单条记录示例
$item = $pdo->query("SELECT * FROM xxx WHERE id = ?")->fetch(PDO::FETCH_ASSOC);
// 套统一响应结构（推荐）
echo json_encode([
    'code' => 200,
    'msg' => 'success',
    'data' => $item
]);
// 输出：{"code":200,"msg":"success","data":{"id":1,"name":"test"}}

方向二：修改Android端接收数组

如果接口确实要返回多条数据，把Retrofit的接口声明改成接收数组：
原来的代码：

@POST("your-api-path")
Call<YourModel> submitData(@Body YourRequestModel request);

修改后：

@POST("your-api-path")
Call<List<YourModel>> submitData(@Body YourRequestModel request);

同时确保YourModel类和数组里的单个元素结构完全匹配。

2. 统一API响应格式（强烈推荐） #

不管是GET还是POST，给所有接口加个统一的返回结构（比如上面的code+msg+data），然后Android端写个通用的BaseResponse类：

public class BaseResponse<T> {
    public int code;
    public String msg;
    public T data;
    // 按需添加getter/setter方法
}

这样后续不管返回单个对象还是数组，都可以用Call<BaseResponse<YourModel>>或Call<BaseResponse<List<YourModel>>>来接收，彻底避免格式不匹配的问题。

3. 快速验证方法 #

用Postman调用你的POST接口，看返回的JSON开头是{还是[：

• 开头是[ → 说明返回的是数组，要么改PHP返回对象，要么改Android接收数组
• 开头是{ → 再检查字段名是否和Model类一致（比如PHP里的user_name和Android里的userName是否加了@SerializedName注解做映射）

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