WMRouter路由框架深度解析与最佳实践指南

2026-02-04 05:25:38作者：仰钰奇

前言

在现代Android应用开发中，模块化与组件化已成为主流架构模式。作为美团开源的轻量级路由框架，WMRouter凭借其灵活的设计和强大的功能，在美团内部多个大型App中得到了广泛应用。本文将全面解析WMRouter的核心设计思想，并提供详细的使用指南，帮助开发者快速掌握这一优秀的路由解决方案。

核心架构设计

1. 网络请求式设计理念

WMRouter创新性地借鉴了网络请求的处理机制，将每一次URI跳转视为一个请求（UriRequest），通过一系列处理器（UriHandler）和拦截器（UriInterceptor）的协同工作来完成路由过程。

这种设计带来了几个显著优势：

清晰的职责划分：每个组件只关注自己的处理逻辑
灵活的扩展性：可以自由组合各种处理器和拦截器
完善的错误处理：类似HTTP的状态码机制

2. 核心组件详解

UriRequest - 路由请求封装

作为路由过程中的核心数据载体，UriRequest包含三个关键部分：

Context：Android上下文
URI：目标路由地址
Fields：扩展字段（HashMap结构）

典型的扩展字段使用场景包括：

页面跳转动画配置
startActivityForResult的requestCode
跳转结果监听器
自定义业务参数

// 典型使用示例
new DefaultUriRequest(context, "/user/profile")
    .putField("transition_anim", new int[]{R.anim.slide_in, R.anim.slide_out})
    .activityRequestCode(1001)
    .start();

UriHandler - 路由处理器

作为路由处理的核心接口，UriHandler采用责任链模式设计，主要特点包括：

异步处理机制：通过回调通知处理结果
链式传递：未处理时调用onNext()继续传递
组合模式：支持处理器嵌套

public class CustomHandler extends UriHandler {
    @Override
    public void handle(UriRequest request, UriCallback callback) {
        if(shouldHandle(request)) {
            // 处理逻辑
            callback.onComplete(resultCode);
        } else {
            // 不处理，继续传递
            callback.onNext();
        }
    }
}

UriInterceptor - 路由拦截器

拦截器提供了强大的AOP能力，常见应用场景包括：

权限校验（如登录态检查）
参数预处理
埋点统计
降级策略

public class AuthInterceptor implements UriInterceptor {
    @Override
    public void intercept(UriRequest request, UriCallback callback) {
        if(!checkAuth()) {
            // 跳转登录页
            startLoginActivity(request.getContext());
            callback.onComplete(CODE_AUTH_FAILED);
        } else {
            callback.onNext();
        }
    }
}

项目集成指南

1. 基础配置

Gradle依赖配置

在模块级build.gradle中添加：

dependencies {
    implementation 'com.sankuai.waimai.router:router:最新版本'
    annotationProcessor 'com.sankuai.waimai.router:compiler:最新版本'
    // Kotlin项目使用kapt替代annotationProcessor
}

初始化代码

建议在Application中完成初始化：

public class MyApp extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        
        // 主线程初始化核心路由
        Router.init(new DefaultRootUriHandler(this));
        
        // 后台线程预加载
        Executors.newSingleThreadExecutor().execute(() -> {
            Router.lazyInit();
        });
    }
}

2. 路由表配置

WMRouter提供三种注解方式配置路由：

@RouterUri - 标准路由配置

@RouterUri(
    scheme = "app",
    host = "user",
    path = "/profile",
    interceptors = {AuthInterceptor.class, LogInterceptor.class}
)
public class UserProfileActivity extends Activity {
    // 通过getIntent().getData()获取路由参数
}

@RouterPage - 内部页面跳转

@RouterPage(path = "/internal/home")
public class HomeActivity extends Activity {
    // 固定使用wm_router://page前缀
}

@RouterRegex - 正则匹配路由

@RouterRegex(
    regex = "http(s)?://.*\\.example\\.com/.*",
    priority = 100
)
public class WebViewActivity extends Activity {
    // 匹配指定域名的所有网页
}

高级功能解析

1. ServiceLoader服务发现机制

WMRouter的服务发现机制解耦了接口与实现，支持：

基础服务注册

public interface IUserService {
    String getUserName();
}

@RouterService(
    interfaces = IUserService.class,
    key = "default",
    singleton = true
)
public class UserServiceImpl implements IUserService {
    @Override
    public String getUserName() {
        return "John Doe";
    }
}

服务获取方式

// 获取指定key的实现
IUserService service = Router.getService(IUserService.class, "default");

// 获取所有实现
List<IUserService> services = Router.getAllServices(IUserService.class);

方法调用封装

@RouterService(
    interfaces = Func2.class,
    key = "/math/add"
)
public class AddFunction implements Func2<Integer, Integer, Integer> {
    @Override
    public Integer call(Integer a, Integer b) {
        return a + b;
    }
}

// 调用方式
int result = Router.callMethod("/math/add", 1, 2);

2. 深度链接处理

对于外部链接跳转，建议统一入口：

<activity android:name=".router.DeepLinkActivity" android:exported="true">
    <intent-filter>
        <data android:scheme="app" android:host="open"/>
        <action android:name="android.intent.action.VIEW"/>
        <category android:name="android.intent.category.DEFAULT"/>
        <category android:name="android.intent.category.BROWSABLE"/>
    </intent-filter>
</activity>

处理逻辑：

public class DeepLinkActivity extends Activity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        
        Router.startUri(this, getIntent().getData())
            .onComplete(new OnCompleteListener() {
                @Override
                public void onSuccess(UriRequest request) {
                    finish();
                }
                
                @Override
                public void onError(UriRequest request, int resultCode) {
                    showErrorPage();
                    finish();
                }
            });
    }
}

性能优化建议

懒加载策略：对于非关键路径的路由配置，使用懒加载减少启动时间
预加载机制：在Splash页或后台线程预加载路由表
单例模式：频繁使用的Handler和Interceptor应设计为单例
Proguard配置：确保路由类不被混淆

-keep class com.sankuai.waimai.router.generated.** { *; }
-keep @interface com.sankuai.waimai.router.annotation.**
-keepclasseswithmembers class * {
    @com.sankuai.waimai.router.annotation.* <methods>;
}