终极RetrofitUrlManager教程：3种模式快速实现Android多环境API管理
项目地址: https://gitcode.com/gh_mirrors/re/RetrofitUrlManager RetrofitUrlManager是一个专为Android开发者设计的轻量级框架，它以最简洁的API让Retrofit同时支持多个BaseUrl以及动态改变BaseUrl，完美解决多环境切换、第三方API集成等开发痛点。本文将带你从基础到进阶，掌握这个强大工具的全部使用技巧。
📌 为什么需要RetrofitUrlManager？
在Android开发中，我们经常面临这些API管理难题：
- 开发/测试/生产环境的BaseUrl切换
- 同时集成多个第三方API服务
- 运行时动态切换服务器地址
- 部分接口需要特殊BaseUrl
传统解决方案要么需要创建多个Retrofit实例，要么通过拦截器手动处理，不仅代码冗余还容易出错。RetrofitUrlManager通过拦截器机制，仅需几行代码就能优雅解决这些问题。
图：RetrofitUrlManager演示界面，展示了如何在运行时切换不同API的BaseUrl
🚀 快速开始：3步集成RetrofitUrlManager
1. 引入依赖
首先在项目中添加RetrofitUrlManager依赖（具体版本请参考最新发布）。
2. 初始化配置
在OkHttpClient构建时添加RetrofitUrlManager拦截器：
OkHttpClient client = new OkHttpClient.Builder()
.addInterceptor(RetrofitUrlManager.getInstance().with())
.build();
3. 基本使用示例
// 设置全局BaseUrl
RetrofitUrlManager.getInstance().setGlobalDomain("https://api.example.com");
// 为特定API设置单独BaseUrl
@Headers({"Domain-Name: douban"})
@GET("v2/book/{id}")
Observable<ResponseBody> getBook(@Path("id") int id);
// 在代码中配置对应域名
RetrofitUrlManager.getInstance().putDomain("douban", "https://api.douban.com");
💡 三种工作模式全解析
RetrofitUrlManager提供三种灵活的BaseUrl管理模式，满足不同场景需求：
普通模式（默认）
适用场景：仅需要替换域名的简单场景
普通模式只能替换域名部分，例如将https://www.google.com/api中的https://www.google.com替换为其他域名，但保留/api路径。这种模式无需额外配置，直接使用putDomain方法即可。
核心实现类：DomainUrlParser
高级模式
适用场景：需要替换包含多个路径段的BaseUrl
高级模式可以替换包含多个pathSegments的BaseUrl，例如https://www.github.com/wiki/part。启用方法：
// 传入Retrofit原始BaseUrl
RetrofitUrlManager.getInstance().startAdvancedModel("https://www.github.com/wiki/part");
核心实现类：AdvancedUrlParser
超级模式
适用场景：每个Url需要不同PathSize的复杂场景
超级模式允许为每个Url单独指定PathSize，通过在Url中添加特殊标识实现：
// 在Url中加入#baseurl_path_size=2标识
@GET("users#baseurl_path_size=2")
Observable<ResponseBody> getUsers();
这种模式适合项目中存在多种不同结构BaseUrl的情况。
核心实现类：SuperUrlParser
🔧 实用功能与最佳实践
忽略特定Url的BaseUrl替换
某些第三方API可能不需要切换BaseUrl，可以使用忽略标识：
// 添加#url_ignore标识
String ignoreUrl = RetrofitUrlManager.getInstance().setUrlNotChange("https://thirdpartyapi.com/data");
监听Url变化
通过注册监听器可以跟踪BaseUrl的切换过程：
RetrofitUrlManager.getInstance().registerUrlChangeListener(new onUrlChangeListener() {
@Override
public void onUrlChangeBefore(HttpUrl oldUrl, String domainName) {
// 切换前回调
}
@Override
public void onUrlChanged(HttpUrl newUrl, HttpUrl oldUrl) {
// 切换后回调
}
});
调试模式
开启调试模式可以打印Url切换日志：
RetrofitUrlManager.getInstance().setDebug(true);
📝 完整使用示例
以下是一个综合示例，展示如何在实际项目中使用RetrofitUrlManager管理多个API：
// 1. 初始化Retrofit
OkHttpClient client = new OkHttpClient.Builder()
.addInterceptor(RetrofitUrlManager.getInstance().with())
.build();
Retrofit retrofit = new Retrofit.Builder()
.baseUrl("https://api.github.com")
.client(client)
.addCallAdapterFactory(RxJava2CallAdapterFactory.create())
.addConverterFactory(GsonConverterFactory.create())
.build();
// 2. 配置多域名
RetrofitUrlManager manager = RetrofitUrlManager.getInstance();
manager.setGlobalDomain("https://api.github.com"); // 全局默认域名
manager.putDomain("gank", "http://gank.io"); // Gank API
manager.putDomain("douban", "https://api.douban.com"); // 豆瓣API
// 3. 定义API接口
public interface ApiService {
// 使用全局域名
@GET("users")
Observable<ResponseBody> getUsers();
// 使用Gank域名
@Headers({"Domain-Name: gank"})
@GET("api/data/Android/10/1")
Observable<ResponseBody> getAndroidData();
// 使用豆瓣域名
@Headers({"Domain-Name: douban"})
@GET("v2/book/1220562")
Observable<ResponseBody> getBookInfo();
}
// 4. 动态切换域名
// 切换全局域名
manager.setGlobalDomain("https://api.github.com.cn");
// 移除某个域名
manager.removeDomain("gank");
📚 项目结构与核心文件
RetrofitUrlManager的核心代码集中在manager模块：
- 核心管理类：RetrofitUrlManager.java
- Url解析器：parser/
- 监听器接口：onUrlChangeListener.java
示例应用代码位于app模块，展示了如何在实际项目中集成和使用框架。
🔍 总结
RetrofitUrlManager通过三种灵活的工作模式，为Android开发者提供了简单高效的BaseUrl管理方案。无论是简单的多环境切换，还是复杂的多API集成，都能轻松应对。其核心优势包括：
- 无需创建多个Retrofit实例
- 运行时动态切换BaseUrl
- 支持全局、局部和单个请求级别的BaseUrl管理
- 轻量级设计，对原有代码侵入性小
如果你正在为Retrofit的多BaseUrl管理烦恼，不妨尝试RetrofitUrlManager，它可能正是你需要的解决方案！
要开始使用RetrofitUrlManager，请克隆项目仓库：
git clone https://gitcode.com/gh_mirrors/re/RetrofitUrlManager
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
