用途
android-retrofit 是一份面向 Android 开发者的实践指南,主题是使用 Retrofit 搭建和使用类型安全的 HTTP 网络层。资料以“2025 年现代 Android 最佳实践”为定位,给出实现网络层时应遵循的做法,并配有接口定义与配置代码示例。
主要能力
指南按主题组织,覆盖以下方面:
-
URL 操作:通过替换块与查询参数实现动态 URL。动态路径使用相对 URL 中的 {name} 与参数上的 @Path("name");单个查询参数使用 @Query("key");复杂查询使用 @QueryMap Map<String, String> 传递动态参数集合。
-
请求体与表单数据:可将对象作为 JSON 请求体发送,或使用表单编码/多部分格式。@Body 使用已配置的转换器(JSON)序列化对象;@FormUrlEncoded 以 application/x-www-form-urlencoded 发送数据,配合 @Field 使用;@Multipart 以 multipart/form-data 发送数据,配合 @Part 使用。
-
请求头操作:可为方法静态设置请求头,也可通过参数动态设置。静态请求头使用 @Headers;动态请求头使用 @Header;请求头映射使用 @HeaderMap;全局请求头使用 OkHttp 拦截器。
-
Kotlin 支持与响应处理:使用挂起函数时有两种返回类型选择。直接返回请求体(如 User)会返回反序列化后的主体,非 2xx 响应会抛出 HttpException;返回 Response<User> 可访问状态码、请求头和错误体,非 2xx 结果不会抛出异常。
-
Hilt 与序列化配置:在 Hilt 模块中以单例方式提供 Retrofit 实例,示例包含 Json 配置(ignoreUnknownKeys、coerceInputValues)、OkHttpClient 配置(日志拦截器、连接超时)以及 Retrofit 构建(baseUrl、client、转换器工厂)。
-
仓库层错误处理:建议始终在 Repository 层处理网络异常,以保持 UI 状态干净。示例使用 runCatching 包裹直接返回请求体的调用,并在 onFailure 中处理 UnknownHostException、SocketTimeoutException 等具体异常。
-
检查清单:包括对所有网络调用使用挂起函数;如需处理特定状态码(如 401 Unauthorized)优先使用 Response<T>;使用 @Path 和 @Query 而非手动拼接 URL 字符串;为 OkHttpClient 配置日志(调试用)和合理的超时;将 API DTO 映射为领域模型以解耦各层。
使用方式
资料以接口定义和配置代码示例的形式呈现,开发者可参照示例在项目中定义服务接口、配置 OkHttpClient 与 Retrofit 实例、在仓库层封装调用并处理异常。示例中出现的 baseUrl 为 https://api.github.com/,仅作为配置演示。
适用场景
适用于需要在 Android 应用中实现网络层、使用 Retrofit 进行类型安全 HTTP 请求的开发场景,尤其是采用 Kotlin 协程、Hilt 依赖注入和 JSON 序列化的现代 Android 项目。
限制
资料未提供具体的安装命令、依赖版本、支持的平台范围、收费或价格信息,也未说明实际运行效果或性能数据,这些内容暂未提供。