豆包AI写Retrofit请求实战教程

本文深入剖析 Retrofit 网络请求实战中的四大关键陷阱：baseUrl 必须以斜杠结尾以防路径拼接错误导致 404；RESTful 注解（@GET/@POST/@PUT/@PATCH）需严格按语义选用，直接影响幂等性、缓存与服务端行为；Gson 解析失败往往源于泛型声明不明确、字段映射缺失或空值/混合响应处理不当；而 OkHttpClient 必须显式配置并复用——它才是真正发请求的“执行者”，掌控超时、日志、鉴权拦截器等核心能力。文章戳破“Retrofit 很简单”的错觉，揭示其背后 OkHttp、Gson 和协议设计的深度耦合，帮开发者从“能跑”走向“稳跑”。

为什么 Retrofit.Builder().baseUrl() 必须以斜杠 / 结尾

这是最常导致 404 的隐形陷阱。Retrofit 拼接 URL 时不做智能补全，而是直接字符串拼接：baseUrl + @GET("users") → 如果 baseUrl 是 "https://api.example.com/v1"（缺末尾 /），结果就是 "https://api.example.com/v1users"，路径断裂。

• 正确写法：.baseUrl("https://api.example.com/v1/")（结尾带 /）
• 开发期建议用 BuildConfig 或 gradle.properties 管理多环境 Base URL，避免硬编码
• 测试时可用 MockWebServer 验证最终发出的请求 URL 是否符合预期

@GET、@POST、@PUT 这些注解到底怎么选

不是“能用 POST 就不用 PUT”，RESTful 设计直接影响服务端幂等性、缓存行为和前端容错能力。

• @GET：只用于查询，无请求体，可被浏览器/CDN 缓存；参数走 URL（@Query）或路径（@Path）
• @POST：创建资源，非幂等；有请求体（@Body 或 @FormUrlEncoded + @Field）
• @PUT：完整替换某资源（如更新用户全部字段），幂等；通常也带 @Body
• @PATCH：局部更新（如只改头像），更轻量；服务端需明确支持，否则 fallback 到 PUT
• 别用 @HTTP(method = "post", ...) 替代标准注解——除非你要发 TRACE/OPTIONS 这类冷门方法

GsonConverterFactory.create() 为什么有时解析失败

表面是“JSON 转 POJO 失败”，实际根因往往在类型声明或 Gson 配置不匹配。

• 返回类型必须是具体泛型，比如 Call>，不能写成 Call