Retrofit请求报Expected BEGIN_OBJECT but was STRING错误排查

Expected BEGIN_OBJECT but was STRING at line 1 column 1 path $

这是Gson反序列化的典型错误：解析器预期读取到JSON对象（以{起始），但实际接收到的响应内容是纯字符串，和预先定义的解析结构不匹配。

• 未做响应状态校验：当前onResponse回调里没有先判断response.isSuccessful()，当接口返回4xx/5xx错误（比如参数校验失败、路由404、服务端500）时，响应体一般是HTML错误页或者纯文本错误信息，不会被解析成User对象，强行读取body就会触发解析异常
• 返回结构不匹配：你直接定义Call<User>期望响应体直接是User字段结构，但绝大多数后端接口会做通用响应包装，User实体实际是包裹在data这类字段下的，直接解析顶层结构必然失败
• Retrofit配置缺失：如果创建Retrofit实例时没有添加GsonConverterFactory，框架不会自动把JSON响应转成实体对象，也会报类似错误

1. 先加原始响应日志定位根因
   在回调中先打印接口实际返回的原始内容，不要上来就直接解析实体：

@Override
public void onResponse(Call<User> call, Response<User> response) {
    // 打印原始响应内容
    Log.e("response code", String.valueOf(response.code()));
    try {
        String rawContent = response.errorBody() != null ? response.errorBody().string() : new Gson().toJson(response.body());
        Log.e("raw response", rawContent);
    } catch (IOException e) {
        e.printStackTrace();
    }
    // 先判断请求是否成功
    if (!response.isSuccessful()) {
        Toast.makeText(getApplicationContext(), "请求错误，状态码：" + response.code(), Toast.LENGTH_LONG).show();
        return;
    }
    // 成功后再处理实体
    if (response.body() != null) {
        Toast.makeText(getApplicationContext(), response.body().toString(), Toast.LENGTH_LONG).show();
    }
}

2. 按实际返回结构调整实体定义
   如果日志显示接口返回是带外层包装的结构（比如包含success、message、data三个顶层字段），先定义通用响应包装类：

public class ApiResponse<T> {
    public boolean success;
    public String message;
    public T data;
}

同步修改接口定义：

@FormUrlEncoded
@Headers({"Accept: application/json"})
@POST("/api/register")
Call<ApiResponse<User>> register(@Field("name") String name,
                               @Field("email") String email,
                               @Field("national_id") String national_id,
                               @Field("phone") String phone,
                               @Field("password") String password,
                               @Field("password_confirmation") String password_confirmation);

后续回调中通过response.body().data获取User实例即可。
3. 检查Retrofit初始化配置
确认创建Retrofit实例时已经添加Gson转换器，否则不会自动完成JSON到实体的转换：

Retrofit retrofit = new Retrofit.Builder()
        .baseUrl("你的服务端根地址")
        .addConverterFactory(GsonConverterFactory.create()) // 这行配置不能遗漏
        .build();

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