Android Retrofit

new-silvermoon/awesome-android-agent-skills/.github/skills/concurrency_and_networking/android-retrofit

作者 new-silvermoon82900eacc8dbe13de93c6310af27b9df4b2bd2f6无许可证收录于 2026年10月9日更新于 2026年10月9日

Expert guidance on setting up and using Retrofit for type-safe HTTP networking in Android. Covers service definitions, coroutines, OkHttp configuration, and Hilt integration.

仅含说明Software Development

AI 生成的概览

提供在 Android 中搭建 Retrofit 类型安全 HTTP 网络层的指导，涵盖服务定义、协程、OkHttp 与 Hilt。

功能: 该技能为使用 Retrofit 构建 Android 网络层提供参考指导和代码示例。内容涵盖动态 URL 路径与查询参数、请求体、表单编码与 multipart 请求、静态与动态请求头、suspend 函数与 Response 返回类型、Hilt 模块配置，以及仓库层的错误处理。它产出的是说明性指令和 Kotlin 代码片段，而非可运行脚本。
适用场景: 适用于使用 Retrofit 实现或审查 Android 应用 HTTP 网络层的场景。适合解答关于服务接口、OkHttp 客户端配置、使用 Hilt 进行依赖注入，或处理网络响应与错误的问题。
运行要求: 不包含脚本或工具，仅为说明性指令。应用其中的示例需要具备使用 Kotlin、Retrofit、OkHttp 和 Hilt 的 Android 项目，并在运行时需要网络访问。

Android Networking with Retrofit

Instructions

When implementing network layers using Retrofit, follow these modern Android best practices (2025).

1. URL Manipulation

Retrofit allows dynamic URL updates through replacement blocks and query parameters.

Dynamic Paths: Use {name} in the relative URL and @Path("name") in parameters.
Query Parameters: Use @Query("key") for individual parameters.
Complex Queries: Use @QueryMap Map<String, String> for dynamic sets of parameters.

kotlin

interface SearchService {    @GET("group/{id}/users")    suspend fun groupList(        @Path("id") groupId: Int,        @Query("sort") sort: String?,        @QueryMap options: Map<String, String> = emptyMap()    ): List<User>}

interface SearchService {    @GET("group/{id}/users")    suspend fun groupList(        @Path("id") groupId: Int,        @Query("sort") sort: String?,        @QueryMap options: Map<String, String> = emptyMap()    ): List<User>}

2. Request Body & Form Data

You can send objects as JSON bodies or use form-encoded/multipart formats.

@Body: Serializes an object using the configured converter (JSON).
@FormUrlEncoded: Sends data as application/x-www-form-urlencoded. Use @Field.
@Multipart: Sends data as multipart/form-data. Use @Part.

kotlin

interface UserService {    @POST("users/new")    suspend fun createUser(@Body user: User): User
    @FormUrlEncoded    @POST("user/edit")    suspend fun updateUser(        @Field("first_name") first: String,        @Field("last_name") last: String    ): User
    @Multipart    @PUT("user/photo")    suspend fun uploadPhoto(        @Part("description") description: RequestBody,        @Part photo: MultipartBody.Part    ): User}

interface UserService {    @POST("users/new")    suspend fun createUser(@Body user: User): User
    @FormUrlEncoded    @POST("user/edit")    suspend fun updateUser(        @Field("first_name") first: String,        @Field("last_name") last: String    ): User
    @Multipart    @PUT("user/photo")    suspend fun uploadPhoto(        @Part("description") description: RequestBody,        @Part photo: MultipartBody.Part    ): User}

3. Header Manipulation

Headers can be set statically for a method or dynamically via parameters.

Static Headers: Use @Headers.
Dynamic Headers: Use @Header.
Header Maps: Use @HeaderMap.
Global Headers: Use an OkHttp Interceptor.

kotlin

interface WidgetService {    @Headers("Cache-Control: max-age=640000")    @GET("widget/list")    suspend fun widgetList(): List<Widget>
    @GET("user")    suspend fun getUser(@Header("Authorization") token: String): User}

interface WidgetService {    @Headers("Cache-Control: max-age=640000")    @GET("widget/list")    suspend fun widgetList(): List<Widget>
    @GET("user")    suspend fun getUser(@Header("Authorization") token: String): User}

4. Kotlin Support & Response Handling

When using suspend functions, you have two choices for return types:

Direct Body (User): Returns the deserialized body. Throws HttpException for non-2xx responses.
Response<User>: Provides access to the status code, headers, and error body. Does NOT throw on non-2xx results.

kotlin

@GET("users")suspend fun getUsers(): List<User> // Throws on error
@GET("users")suspend fun getUsersResponse(): Response<List<User>> // Manual check

@GET("users")suspend fun getUsers(): List<User> // Throws on error
@GET("users")suspend fun getUsersResponse(): Response<List<User>> // Manual check

5. Hilt & Serialization Configuration

Provide your Retrofit instances as singletons in a Hilt module.

kotlin

@Module@InstallIn(SingletonComponent::class)object NetworkModule {
    @Provides    @Singleton    fun provideJson(): Json = Json {        ignoreUnknownKeys = true        coerceInputValues = true    }
    @Provides    @Singleton    fun provideOkHttpClient(): OkHttpClient = OkHttpClient.Builder()        .addInterceptor(HttpLoggingInterceptor().apply { level = HttpLoggingInterceptor.Level.BODY })        .connectTimeout(30, TimeUnit.SECONDS)        .build()
    @Provides    @Singleton    fun provideRetrofit(okHttpClient: OkHttpClient, json: Json): Retrofit = Retrofit.Builder()        .baseUrl("https://api.github.com/")        .client(okHttpClient)        .addConverterFactory(json.asConverterFactory("application/json".toMediaType()))        .build()}

@Module@InstallIn(SingletonComponent::class)object NetworkModule {
    @Provides    @Singleton    fun provideJson(): Json = Json {        ignoreUnknownKeys = true        coerceInputValues = true    }
    @Provides    @Singleton    fun provideOkHttpClient(): OkHttpClient = OkHttpClient.Builder()        .addInterceptor(HttpLoggingInterceptor().apply { level = HttpLoggingInterceptor.Level.BODY })        .connectTimeout(30, TimeUnit.SECONDS)        .build()
    @Provides    @Singleton    fun provideRetrofit(okHttpClient: OkHttpClient, json: Json): Retrofit = Retrofit.Builder()        .baseUrl("https://api.github.com/")        .client(okHttpClient)        .addConverterFactory(json.asConverterFactory("application/json".toMediaType()))        .build()}

6. Error Handling in Repositories

Always handle network exceptions in the Repository layer to keep the UI state clean.

kotlin

class GitHubRepository @Inject constructor(private val service: GitHubService) {    suspend fun getRepos(username: String): Result<List<Repo>> = runCatching {        // Direct body call throws HttpException on 4xx/5xx        service.listRepos(username)    }.onFailure { exception ->        // Handle specific exceptions like UnknownHostException or SocketTimeoutException    }}

class GitHubRepository @Inject constructor(private val service: GitHubService) {    suspend fun getRepos(username: String): Result<List<Repo>> = runCatching {        // Direct body call throws HttpException on 4xx/5xx        service.listRepos(username)    }.onFailure { exception ->        // Handle specific exceptions like UnknownHostException or SocketTimeoutException    }}

7. Checklist

Use suspend functions for all network calls.
Prefer Response<T> if you need to handle specific status codes (e.g., 401 Unauthorized).
Use @Path and @Query instead of manual string concatenation for URLs.
Configure OkHttpClient with logging (for debug) and sensible timeouts.
Map API DTOs to Domain models to decouple layers.

来源与署名

来源：new-silvermoon/awesome-android-agent-skills位于.github/skills/concurrency_and_networking/android-retrofit提交82900ea

许可证：无许可证

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

Android Retrofit

Android Networking with Retrofit

Instructions

1. URL Manipulation

2. Request Body & Form Data

3. Header Manipulation

4. Kotlin Support & Response Handling

5. Hilt & Serialization Configuration

6. Error Handling in Repositories

7. Checklist

来源与署名

更多来自 new-silvermoon/awesome-android-agent-skills 的技能

Android Testing

Compose Ui

Kotlin Concurrency Expert

Android Viewmodel

Navigation3

Android Accessibility

更多Software Development技能

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices