Retrofit动态URL与Path参数处理

本文深度剖析Retrofit中动态URL与Path参数的处理机制，涵盖基础用法、源码解析、性能优化及工程实践，助你构建灵活高效的网络请求架构。

---

一、动态URL处理：@Url注解

当需要完全替换BaseUrl时，使用@Url注解传入完整URL：

interface ApiService {
    @GET
    suspend fun fetchData(@Url fullUrl: String): Response<Data>
}

// 使用示例
val dynamicUrl = "https://api.example.com/v3/data"
val response = retrofit.create(ApiService::class.java)
    .fetchData(dynamicUrl)

实现原理：

1. Retrofit通过RequestFactory解析注解
2. @Url参数会跳过BaseUrl拼接
3. 最终URL直接使用传入的完整路径

注意事项：

• URL必须包含协议（http/https）
• 适用于CDN切换、多域名等场景
• 性能优于拦截器方案（减少中间处理）

---

二、Path参数处理：@Path注解

1. 基础用法

@GET("users/{userId}/posts/{postId}")
suspend fun getPost(
    @Path("userId") userId: String,
    @Path("postId") postId: Int
): Post

2. 编码控制

// 自动编码特殊字符（默认）
@Path("folder") String path // "a/b" → "a%2Fb"

// 禁用编码（手动处理）
@Path(value = "folder", encoded = true) String rawPath

3. 动态路径段

@GET("{resource_type}/{id}")
suspend fun getResource(
    @Path("resource_type") type: String,
    @Path("id") id: String
): Resource

---

三、复合参数：Path + Query + Header

@GET("search/{category}")
suspend fun search(
    @Path("category") category: String,
    @Query("keyword") keyword: String,
    @Query("page") page: Int = 1,
    @Header("Cache-Control") cacheControl: String = "max-age=60"
): SearchResult

参数处理流程：

sequenceDiagram Client->>Retrofit: 调用search("books", "Kotlin", 2) Retrofit->>RequestFactory: 解析注解 RequestFactory->>HttpUrl: 构建URL：/search/books?keyword=Kotlin&page=2 Retrofit->>OkHttp: 创建Request OkHttp->>Server: 发送请求 Server-->>Client: 返回结果

---

四、动态BaseUrl工程方案

1. 拦截器实现（多环境切换）

class DynamicBaseUrlInterceptor : Interceptor {
    private var host: String = DEFAULT_HOST

    fun setHost(newHost: String) {
        host = newHost
    }

    override fun intercept(chain: Interceptor.Chain): Response {
        val original = chain.request()
        val newUrl = original.url.newBuilder()
            .host(host)
            .build()
        return chain.proceed(original.newBuilder().url(newUrl).build())
    }
}

// 初始化Retrofit
val retrofit = Retrofit.Builder()
    .baseUrl("http://placeholder.com/") // 伪baseUrl
    .client(OkHttpClient.Builder()
        .addInterceptor(DynamicBaseUrlInterceptor())
        .build()
    )
    .build()

2. 方案对比

方案	适用场景	性能影响	灵活性
@Url	完全替换URL	⭐⭐⭐⭐	⭐⭐
@Path	修改路径片段	⭐⭐⭐⭐⭐	⭐⭐⭐
拦截器	动态域名/全局路径修改	⭐⭐	⭐⭐⭐⭐

---

五、源码级优化技巧

1. 空值防御处理

@GET("users/{id}")
suspend fun getUser(
    @Path("id") id: String
): User {
    require(id.isNotBlank()) { "ID cannot be empty" }
    // ...
}

2. Path参数复用

const val USER_PATH = "users/{userId}"

interface UserService {
    @GET("$USER_PATH/profile")
    suspend fun getProfile(@Path("userId") userId: String)
    
    @GET("$USER_PATH/posts")
    suspend fun getPosts(@Path("userId") userId: String)
}

3. 自动URL编码控制

通过分析ParameterHandler.Path源码：

class ParameterHandler.Path extends ParameterHandler<String> {
  @Override void apply(...) {
    String value = values.get(relativeUrlPosition);
    if (value == null) throw new IllegalArgumentException(...);
    
    // 关键逻辑：根据encoded标志决定是否编码
    builder.addPathSegment(name, value, encoded);
  }
}

---

六、完整工程示例

模块化API设计

// core/NetworkModule.kt
object NetworkModule {
    fun provideRetrofit(): Retrofit = Retrofit.Builder()
        .baseUrl(BASE_URL)
        .addConverterFactory(GsonConverterFactory.create())
        .client(provideHttpClient())
        .build()
}

// feature/user/UserApi.kt
interface UserApi {
    @GET("users/{id}")
    suspend fun getUser(@Path("id") id: String): User
    
    @POST("users/{id}/update")
    suspend fun updateUser(
        @Path("id") id: String,
        @Body user: UserUpdate
    )
}

// feature/post/PostApi.kt
interface PostApi {
    @GET
    suspend fun getPostByUrl(@Url url: String): Post
    
    @GET("posts/{postId}")
    suspend fun getPostById(@Path("postId") id: String): Post
}

动态URL工厂

class DynamicUrlFactory(private val base: String) {
    fun createPostUrl(id: String) = "$base/posts/$id"
    fun createImageUrl(path: String) = "$base/images/${URLEncoder.encode(path, "UTF-8")}"
}

// 使用
val urlFactory = DynamicUrlFactory("https://cdn.example.com")
val imageUrl = urlFactory.createImageUrl("banner/main.png")

---

七、关键选择决策

黄金法则：

1. 路径级修改 → @Path
2. 完整URL替换 → @Url
3. 全局域名切换 → 拦截器
4. 高频动态路径 → URL工厂模式

---

八、前沿扩展：协程+Flow动态请求

class DataRepository(
    private val api: DynamicApi
) {
    fun fetchDynamicData(urlFlow: Flow<String>): Flow<Result<Data>> {
        return urlFlow.flatMapMerge { url ->
            flow { emit(api.fetchData(url)) }
                .catch { emit(Result.failure(it)) }
        }
    }
}

// 使用
val urls = flowOf("url1", "url2", "url3")
repository.fetchDynamicData(urls)
    .collect { result ->
        // 处理动态URL返回结果
    }

---

终极最佳实践：

1. 核心业务路径使用@Path保证类型安全
2. CDN资源加载使用@Url直接控制
3. 多环境切换采用拦截器实现
4. 高频动态路径抽象为URL工厂
5. 严格验证Path参数非空

通过合理组合这些技术方案，可构建出灵活高效、易于维护的网络请求架构。Retrofit的动态URL处理能力正是其区别于其他网络库的核心优势之一，掌握这些技巧将极大提升Android开发效率。