mcpField
A
android-retrofit

android-retrofit

github.com/rcosteira79开发172150 次安装7 周前更新
代码仓库

关于 android-retrofit

面向使用协程、kotlinx.serialization 和 Hilt 的 Android 开发者的 Retrofit 网络技能。内容涵盖端点返回类型、认证策略，以及在 repository 边界内处理网络错误和 DTO。

主要功能

  1. 01Suspend 端点设计
  2. 02直接返回正文与 Response 的用法
  3. 03OkHttp 和 JSON 配置
  4. 04基于拦截器的令牌认证
  5. 05在 repository 层映射错误

适用场景

  1. 01定义 Retrofit 服务方法
  2. 02选择缺少认证令牌时的行为
  3. 03为宽松格式的 API 配置 JSON 处理
  4. 04避免传输错误进入 ViewModel

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/rcosteira79/android-skills --skill android-retrofit

安装后在 Claude Code 中输入/android-retrofit确认已加载。

详细介绍

使用 Retrofit 进行 Android 网络通信

使用协程、kotlinx.serialization 和 Hilt 配置现代 Android Retrofit。本参考涵盖容易出错的决策，而非服务接口、Hilt 模块连线和转换器配置等标准样板代码。

服务接口

将每个端点声明为 suspend 函数。直接返回正文类型——对于非 2xx 响应，Retrofit 会抛出 HttpException，因此可以在存储库边界进行简洁的 try/catch。只有在需要状态码、响应头或错误正文时才使用 Response<T>（例如服务器端验证消息）：

// Direct body — throws HttpException on non-2xx; the common case
@GET("users/{user}/repos")
suspend fun listRepos(@Path("user") user: String): List<Repo>

// Response wrapper — only when you need code/headers/error body
@GET("users/{user}")
suspend fun getUser(@Path("user") user: String): Response<User>

“以防万一”将每个端点都包装在 Response<T> 中，会迫使调用方检查 isSuccessful，并在只关心正文时也处理可空正文——不要这样做。

OkHttp 和 JSON

标准连线配置（在 Hilt @Module/@Provides @Singleton 中）：HttpLoggingInterceptor，其级别受 BuildConfig.DEBUG 控制；合理的连接/读取超时；以及 kotlinx.serialization 转换器（json.asConverterFactory("application/json".toMediaType())）。对于负载格式不严格的 API，请配置：

Json { ignoreUnknownKeys = true; coerceInputValues = true; isLenient = true }

身份验证：拦截器，以及抛出还是继续的决策

通过 Interceptor 附加令牌，而不是为每个端点使用 @Header——只要漏掉一个 @Header 参数，就会产生运行时才失败的未认证请求，而非编译时错误。最常见的错误是令牌缺失时该如何处理：

class AuthInterceptor @Inject constructor(
    private val tokenProvider: TokenProvider,
) : Interceptor {
    override fun intercept(chain: Interceptor.Chain): Response {
        val token = tokenProvider.getToken()
            ?: throw IOException("Auth token unavailable") // fail fast — see note below
        val request = chain.request().newBuilder()
            .header("Authorization", "Bearer $token")
            .build()
        return chain.proceed(request)
    }
}

抛出还是继续：如果所有端点都需要身份验证，就抛出——令牌缺失时应立即显现，而不是悄无声息地导致令人困惑的 401。仅当同一个 OkHttpClient 同时用于需要身份验证和公开访问的端点时，才在没有请求头的情况下继续：?: return chain.proceed(chain.request())。所有调用都需要身份验证时仍悄无声息地继续，是一种常见错误。

错误处理

存储库是错误边界：在其中捕获 HttpException/IOException，并将其映射为领域错误类型——绝不要让 Retrofit/OkHttp 异常类型传到 ViewModel，也不要向其暴露 Retrofit DTO。这里不要重新定义错误层次结构；存储库模式和共享的 DataError 分类请参阅 android-skills:android-data-layer。

检查清单

  • 所有服务函数都是 suspend
  • 只有在需要状态码、响应头或错误正文时才使用 Response<T>
  • OkHttpClient 日志记录受 BuildConfig.DEBUG 控制；已设置合理的超时
  • 通过 Interceptor 应用身份验证，并已选择令牌缺失时的策略（抛出还是继续）
  • 在存储库中将网络异常映射为领域类型；DTO 不会传到 ViewModel

评论

支持 Markdown