WMRouter：美團外賣Android開源路由架構

WMRouter是一款Android路由架構，基於組件化的設計思路，功能靈活，使用也比較簡單。

WMRouter最初用於解決美團外賣C端App在業務演化過程中的實際問題，之後逐步推廣到了美團其他App，因此我們決定將其開源，希望更多技術同行一起開發，應用到更廣泛的情境裡去。Github項目地址與使用文檔詳見 github.com/meituan/WMRouter。

本文先簡單介紹WMRouter的功能和適用情境，然後詳細介紹WMRouter的發展背景和過程。

功能簡介

WMRouter主要提供URI分發、ServiceLoader兩大功能。

URI分發功能可用於多工程之間的頁面跳轉、動態下發URI連結的跳轉等情境，特點如下：

1. 支援多scheme、host、path
2. 支援URI正則匹配
3. 頁面配置支援Java代碼動態註冊，或註解配置自動註冊
4. 支援配置全域和局部攔截器，可在跳轉前執行同步/非同步作業，例如定位、登入等
5. 支援單次跳轉特殊操作：Intent設定Extra/Flags、設定跳轉動畫、自訂StartActivity操作等
6. 支援頁面Exported控制，特定頁面不允許外部跳轉
7. 支援配置全域和局部降級策略
8. 支援配置單次和全域跳轉監聽
9. 完全組件化設計，核心組件均可擴充、按需組合，實現靈活強大的功能

基於SPI (Service Provider Interfaces) 的設計思想，WMRouter提供了ServiceLoader模組，類似Java中的java.util.ServiceLoader，但功能更加完善。通過ServiceLoader可以在一個App的多個模組之間通過介面調用代碼，實現模組解耦，便於實現組件化、模組間通訊，以及和依賴注入類似的功能等。其特點如下：

1. 使用註解自動設定
2. 支援擷取介面的所有實現，或根據Key擷取特定實現
3. 支援擷取Class或擷取執行個體
4. 支援無參構造、Context構造，或自訂Factory、Provider構造
5. 支援單例管理
6. 支援方法調用

其他特性：

1. 最佳化的Gradle外掛程式，對編譯耗時影響很小
2. 編譯期和運行時配置檢查，避免配置衝突和錯誤
3. 編譯期自動添加Proguard混淆規則，免去手動設定的繁瑣
4. 完善的調試功能，協助及時發現問題

適用情境

WMRouter適用但不限於以下情境：

1. Native+H5混合開發模式，需要進行頁面之間的互相跳轉，或進行靈活的運營跳轉連結下發。可以利用WMRouter統一頁面跳轉邏輯，根據不同的協議（HTTP、HTTPS、用於Native頁面的自訂協議）跳轉對應頁面，且在跳轉過程中可以使用UriInterceptor對跳轉連結進行修改，例如跳轉H5頁面時在URL中加參數。

2. 統一管理來自App外部的URI跳轉。來自App外部的URI跳轉，如果使用Android原生的Manifest配置，會直接啟動匹配的Activity，而很多時候希望先正常啟動App開啟首頁，完成常規初始化流程（例如登入、定位等）後再跳轉目標頁面。此時可以使用統一的Activity接收所有外部URI跳轉，到首頁時再用WMRouter啟動目標頁面。

3. 頁面跳轉有複雜判斷邏輯的情境。例如多個頁面都需要先登入、先定位後才允許開啟，如果使用常規方案，這些頁面都需要處理相同的商務邏輯；而利用WMRouter，只需要開發好UriInterceptor並配置到各個頁面即可。

4. 多工程、組件化、平台化開發。多工程開發要求各個工程之間能互相通訊，也可能遇到和外賣App類似的代碼複用、依賴注入、編譯等問題，這些問題都可以利用WMRouter的URI分發和ServiceLoader模組解決。

5. 對業務埋點需求較強的情境。頁面跳轉作為最常見的商務邏輯之一，常常需要埋點。給每個頁面配置好URI，使用WMRouter統一進行頁面跳轉，並在全域的OnCompleteListener中埋點即可。

6. 對App可用性要求較高的情境。一方面，可以對頁面跳轉失敗進行埋點監控上報，及時發現線上問題；另一方面，頁面跳轉時可以執行判斷邏輯，發現異常（例如服務端異常、用戶端崩潰等）則自動開啟降級後的頁面，保證關鍵功能的正常工作，或給方便使用的提示。

7. 頁面A/B測試、動態配置等情境。在WMRouter提供的介面基礎上進行少量開發配置，就可以實現：根據下發的A/B測試策略跳轉不同的頁面實現；根據不同的需要動態下發一組路由表，相同的URI跳轉到不同的一組頁面（實現方面可以自訂UriInterceptor，對匹配的URI返回301的UriResult使跳轉重新導向）。

基本概念解釋

下面開始介紹WMRouter的發展背景和過程。為了方便後文的理解，我們先簡單瞭解和回顧幾個基本概念。

路由

根據維基百科的解釋，路由（routing）可以理解成在互聯的網路通過特定的協議把資訊從源地址傳輸到目的地址的過程。一個典型的例子就是在互連網中，路由器可以根據IP協議將資料發送到特定的電腦。

URI

URI（Uniform Resource Identifier，統一資源識別項）是一個用於標識某一互連網資源名稱的字串。URI的組成如所示。

一些常見的URI舉例如下，包括平時經常用到的網址、IP地址、FTP地址、檔案、打電話、發郵件的協議等。

• http://www.meituan.com
• http://127.0.0.1:8080
• ftp://example.org/resource.txt
• file:///Users/
• tel:863-1234
• mailto:chris@example.com

在Android中也提供了android.net.Uri工具類用於處理URI，Android中URI常用的幾個部分主要是scheme、host、path和query。

Android中的Intent跳轉

在Android中的Intent跳轉，分為顯式跳轉和隱式跳轉兩種。

顯式跳轉即指定ComponentName（類名）的Intent跳轉，一般通過Bundle傳參，範例程式碼如下：

Intent intent = new Intent(context, TestActivity.class);intent.putExtra("param", "value")startActivity(intent);

隱式跳轉即不指定ComponentName的Intent跳轉，通過IntentFilter找到匹配的組件，IntentFilter支援action、category和data的匹配，其中data就是URI。例如下面的代碼，會啟動系統預設的瀏覽器開啟網頁：

Intent intent = new Intent(Intent.ACTION_VIEW);intent.setData(Uri.parse("http://www.meituan.com"))startActivity(intent);

Activity通過Manifest配置IntentFilter，例如下面的配置可以匹配所有形如demo_scheme://demo_host/***的URI。

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

URI跳轉

在美團外賣C端早期開發過程中，產品希望通過後台下發URI控制用戶端跳轉指定頁面，從而實現靈活的運營配置。外賣App採用了Native+H5的混合開發模式，Native頁面定義了專用的URI，而H5頁面則使用HTTP/HTTPS連結在專門的WebView容器中載入，兩種連結的跳轉邏輯不同，實現起來比較繁瑣。

Native頁面的URI跳轉最開始使用的是Android原生的IntentFilter，通過隱式跳轉啟動，但是這種方式存在靈活性差、功能缺失、Bug多等問題。例如：

1. 從外部（瀏覽器、等）跳轉外賣的URI時，系統會直接開啟相應的Activity，而沒有經過歡迎頁面的正常啟動流程，一些代碼邏輯可能沒有執行，例如定位邏輯。

2. 有很多頁面在開啟前需要確保使用者先登入或先定位，每個頁面都寫一遍判斷登入、定位的邏輯非常麻煩，提高了開發維護成本。

3. 運營人員可能會配錯URI，頁面跳轉失敗，有些跳轉的地方沒有做try-catch處理，會產生Crash；有些地方雖然加了try-catch，但跳轉失敗後沒有任何響應，使用者體驗差；跳轉失敗沒有監控，不能及時發現和解決線上業務異常。

為瞭解決上述問題，我們希望有一個Android的URI分發組件，可以根據URI中不同的scheme、host、path，進行不同的處理，同時能夠在頁面跳轉過程中進行更靈活的幹預。調研發現，現有的一些Android路由群組件主要都是在解決多工程之間解耦的問題，而URI往往只支援通過path分發，頁面跳轉的配置也不夠靈活，難以滿足實際需要。於是我們決定自行設計實現。

核心設計思路

展示了WMRouter中URI分發機制的核心設計思路。借鑒網路請求的機制，WMRouter中的每次URI跳轉視為發起一個UriRequest；URI跳轉請求被WMRouter逐層分發給一系列的UriHandler進行處理；每個UriHandler處理之前可以被UriInterceptor攔截，並插入一些特殊操作。

頁面跳轉來源

常見的頁面跳轉來源如下：

1. 來自App內部Native頁面的跳轉
2. 來自App內Web容器的跳轉，即H5頁面發起的跳轉
3. 從App外通過URI喚起App的跳轉，例如來自瀏覽器、等
4. 從通知中樞Push喚起App的跳轉

對於來自App內部和Web容器的跳轉，我們把所有跳轉代碼統一改成調用WMRouter處理，而來自外部和Push通知的跳轉則全部使用一個獨立的中轉Activity接收，再調用WMRouter處理。

UriRequest

UriRequest中包含Context、URI和Fields，其中Fields為HashMap<string, object="">，可以通過Key存放任意資料。簡單起見，UriRequest類同時承擔了Response的功能，跳轉請求的結果，也會被儲存到Fields中。Fields可以根據需要自訂，其中一些常見欄位舉例如下：

• Intent的Extra參數，Bundle類型
• 用於startActivityForResult的RequestCode，int類型
• 用於overridePendingTransition方法的頁面切換動畫資源，int[]類型
• 本次跳轉結果的監聽器，OnCompleteListener類型

每次URI跳轉請求會有一個ResultCode（類似HTTP請求的ResponseCode），表示跳轉結果，也存放在Fields中。常見Code如下，使用者也可以自訂Code：

• 200：跳轉成功
• 301：重新導向到其他URI，會再次跳轉
• 400：請求錯誤，通常是Context或URI為空白
• 403：禁止跳轉，例如跳轉白名單以外的HTTP連結、Activity的exported為false等
• 404：找不到目標(Activity或UriHandler)
• 500：發生錯誤

總結來說，UriRequest用於實現一次URI跳轉中所有組件之間的通訊功能。

UriHandler

UriHandler用於處理URI跳轉請求，可以嵌套從而逐層分發和處理請求。UriHandler是非同步結構，接收到UriRequest後處理（例如跳轉Activity等），如果處理完成，則調用callback.onComplete()並傳入ResultCode；如果沒有處理，則調用callback.onNext()繼續分發。下面的範例程式碼展示了一個只處理HTTP連結的UriHandler的實現：

public interface UriCallback {    /**     * 處理完成，繼續後續流程。     */    void onNext();    /**     * 處理完成，終止分發流程。     *     * @param resultCode 結果     */    void onComplete(int resultCode);}public class DemoUriHandler extends UriHandler {    public void handle(@NonNull final UriRequest request, @NonNull final UriCallback callback) {        Uri uri = request.getUri();        // 處理HTTP連結        if ("http".equalsIgnoreCase(uri.getScheme())) {            try {                // 調用系統瀏覽器                Intent intent = new Intent();                intent.setAction(Intent.ACTION_VIEW);                intent.setData(uri);                request.getContext().startActivity(intent);                // 跳轉成功                callback.onComplete(UriResult.CODE_SUCCESS);            } catch (Exception e) {                // 跳轉失敗                callback.onComplete(UriResult.CODE_ERROR);            }        } else {            // 非HTTP連結不處理，繼續分發            callback.onNext();        }    }    // ...}

UriInterceptor

UriInterceptor為攔截器，不做最終的URI跳轉操作，但可以在最終的跳轉前進行各種同步/非同步作業，常見操作舉例如下：

• URI跳轉攔截，禁止特定的URI跳轉，直接返回403（例如禁止跳轉非meituan網域名稱的HTTP連結）
• URI參數修改（例如在HTTP連結末尾添加query參數）
• 各種中間處理（例如開啟登入頁登入、擷取定位、髮網絡請求）
• ……

每個UriHandler都可以添加若干UriInterceptor。在UriHandler基類中，handle()方法先調用抽象方法shouldHandle()判斷是否要處理UriRequest，如果需要處理，則逐個執行Interceptor，最後再調用handleInternal()方法進行跳轉操作。

public abstract class UriHandler {    // ChainedInterceptor將多個UriInterceptor合并成一個    protected ChainedInterceptor mInterceptor;    public UriHandler addInterceptor(@NonNull UriInterceptor interceptor) {        if (interceptor != null) {            if (mInterceptor == null) {                mInterceptor = new ChainedInterceptor();            }            mInterceptor.addInterceptor(interceptor);        }        return this;    }    public void handle(@NonNull final UriRequest request, @NonNull final UriCallback callback) {        if (shouldHandle(request)) {            if (mInterceptor != null) {                mInterceptor.intercept(request, new UriCallback() {                    @Override                    public void onNext() {                        handleInternal(request, callback);                    }                    @Override                    public void onComplete(int result) {                        callback.onComplete(result);                    }                });            } else {                handleInternal(request, callback);            }        } else {            callback.onNext();        }    }    /**     * 是否要處理給定的uri。在Interceptor之前調用。     */    protected abstract boolean shouldHandle(@NonNull UriRequest request);    /**     * 處理uri。在Interceptor之後調用。     */    protected abstract void handleInternal(@NonNull UriRequest request, @NonNull UriCallback callback);}

URI的分發與降級

在外賣C端App中的URI分發示意如。所有URI跳轉都會分發到RootUriHandler，然後根據不同的scheme分發到不同的子Handler。例如waimai協議分發到WmUriHandler，然後進一步根據不同的path分發到子Handler，從而啟動相應的Activity；HTTP/HTTPS協議分發到HttpHandler，啟動WebView容器；對於其他類型URI（tel、mailto等），前面的幾個Handler都無法處理，則會分發到StartUriHandler，嘗試使用Android原生的隱式跳轉啟動系統應用。

每個UriHandler都可以根據實際需要實現降級策略，也可以不作處理繼續分發給其他UriHandler。RootUriHandler中提供了一個全域的分發完成事件監聽器，當UriHandler處理失敗返回異常ResultCode或所有子UriHandler都沒有處理時，執行全域降級策略。

平台化與兩端複用

隨著外賣C端業務的演化，團隊成員擴充了數倍，商超生鮮等垂直品類的拆分，以及異地研發團隊的建立，用戶端的平台化被提上議程。關於外賣平台化更詳細的內容，可參考團隊之前已經發布的文章 美團外賣Android平台化架構演化實踐。

為了滿足實際開發需要，在長時間的探索後，逐步形成了的三層工程結構。

原有的單個工程拆分成多個工程，就不可避免的涉及到多工程之間的耦合問題，主要包括通訊問題、複用問題、依賴注入、編譯問題，下面詳細介紹。

通訊問題

當原先的一個工程拆分到各個業務庫後，業務庫之間的頁面需要進行通訊，最主要的情境就是頁面跳轉並通過Intent傳遞參數。

原先的頁面跳轉使用顯式跳轉，Activity之間存在強引用，當Activity被拆分到不同的業務庫，業務庫不能直接互相依賴，因此需要進行解耦。

利用WMRouter的URI分發機制，剛好可以很容易的解決這個問題。將將所有業務庫的Activity註冊到WMRouter，各個業務庫之間就可以進行頁面跳轉了。

此時WMRouter已經承載了兩項功能：

1. 後台下發的運營URI跳轉 (waimai://*)
2. 內部頁面跳轉，用於代替原有的顯式跳轉，實現工程解耦 (wm_router://page/*)

由於後台下發的URI是和產品、運營、H5、iOS等各端統一制定的協議，支援的頁面、格式、參數等都不能隨意改動，而內部頁面跳轉使用的URI，則需要根據實際開發需要進行配置，兩套URI協議不能相容，因此使用了不同的scheme。

複用問題與ServiceLoader模組

業務庫之間經常需要複用代碼。一些通用代碼邏輯可以下沉到平台層從而複用，例如業務無關的通用View組件；而有些代碼不適合下沉到平台層，例如業務庫A要使用業務庫B中的某個介面模組，而這個介面模組和業務庫B的耦合很緊密。具體到外賣實際業務情境中，商家頁在商家休息時會展示推薦商家列表，其樣式和首頁相同（），而兩個頁面不在一個工程中，商家頁希望能直接從首頁業務庫中擷取商家列表的實現。

為瞭解決上述問題，我們調研瞭解到Java中SPI (Service Provider Interfaces) 的設計思想與java.util.ServiceLoader工具類，還學習到美團平台為瞭解決類似問題而開發的ServiceLoader組件。

考慮到實際需求差異，我們重新開發了自己的ServiceLoader實現。相比Java中的實現，WMRouter的實現借鑒了美團平台的設計思路，不僅支援通過介面擷取所有實作類別，還支援通過介面和唯一的Key擷取特定的實作類別。另外WMRouter的實現還支援直接載入實作類別的Class、用Factory和Provider建立對象、單例管理、方法調用等功能。在Gradle外掛程式的實現思路上，借鑒了美團平台的ServiceLoader並做了效能最佳化，給平台提出了改進建議。

業務庫之間代碼複用的需求示意，業務庫A需要複用業務庫B中的ServiceImpl但又不能直接引用，因此通過WMRouter載入：

1. 抽取介面（或父類，後面不再重複說明）下沉到平台層，實作類別ServiceImpl實現該介面，並聲明一個Key（字串類型）。
2. 調用方通過介面和Key，由ServiceLoader載入實作類別，通過介面訪問實作類別。

URI跳轉和ServiceLoader看起來似乎沒有關聯，但通訊和複用需求的本質都可以理解成路由，頁面通過URI分發跳轉時的協議是Activity+URI，在這裡ServiceLoader的協議是Interface+Key。

依賴注入

為了相容外賣獨立App和美團App外賣頻道的兩端差異，平台層的一些介面要在兩個主工程分別實現，並注入到底層。常規Java代碼注入的方式寫起來很繁瑣，而使用WMRouter的ServiceLoader功能可以更簡單的實現和依賴注入類似的效果。

對於WMRouter來說，所有依賴它的工程（包括主工程、業務庫、平台庫）都是一樣的，任何一個庫想要調用其他庫中的代碼，都可以通過WMRouter路由轉寄。前面的通訊和複用問題，是同級的業務庫之間通過WMRouter調用，而依賴注入則是底層庫通過WMRouter調用上層庫，其本質和實現都是相同的。

ServiceLoader模組在載入實作類別時提供了單例管理功能，可用於管理一些全域的Service/Manager，例如使用者賬戶管理類UserManager。

編譯問題

由於曆史原因，主工程作為一個沒有商務邏輯的殼工程，對業務庫卻有較多依賴，特別是對業務庫的初始化配置繁瑣，和各業務庫耦合緊密。另一方面，WMRouter跳轉的頁面、載入的實作類別，需要在Application初始化時註冊到WMRouter中，也會增加主工程和業務庫的耦合。開發過程中各業務庫頻繁更新，經常出現無法編譯的問題，嚴重影響開發。

為瞭解決這個問題，一方面WMRouter增加了註解支援，在Activity類、ServiceLoader實作類別上配置註解，就可以在編譯期間自動產生代碼註冊到WMRouter中。

// 沒有註解時，需要在Application初始化時代碼註冊各個頁面，耦合嚴重register("/home", HomeActivity.class);register("/order", OrderListActivity.class);register("/shop", ShopActivity.class)register("/account", MyAccountActivity.class);register("/address", MyAddressActivity.class);// ...

// 增加註解後，只需要在各個Activity上通過註解配置即可@RouterUri(path = "/shop")public class ShopActivity extends BaseActivity {}

另一方面，ServiceLoader還支援指定介面載入所有實作類別，主工程可以通過統一介面，載入各個業務庫中所有實作類別並進行初始化，最終實現和業務庫的徹底隔離。

開發過程中，各個業務庫可以像外掛程式一樣按需整合到主工程，能大幅減少不能編譯的問題，同時由於編譯時間可以跳過不需要的業務庫，編譯速度也能得到提高。

WMRouter的推廣

在WMRouter解決了外賣C端App的各種問題後，發現公司內甚至公司外的其他App也遇到了相似的問題和需求，於是決定對WMRouter進行推廣和開源。

由於WMRouter是一個開放式組件化架構，UriRequest可以存放任意資料，UriHandler、UriInterceptor可以完全自訂，不同的UriHandler可以任意組合，具有很大的靈活性。但過於靈活容易導致易用性的下降，即使對於最常規最簡單的應用，也需要複雜的配置才能完成功能。

為了在靈活性與易用性之間平衡，一方面，WMRouter對包結構進行了合理的劃分，核心介面和實作類別提供基礎通用能力，儘可能保留最大的靈活性；另一方面，封裝了一系列通用實作類別，並組合成一套預設實現，從而滿足絕大多數常規使用情境，儘可能降低其他App的接入成本，方便推廣。

總結

目前業界已有的一些Android路由架構，不能滿足外賣C端App在開發過程中的實際需要，因此我們開發了WMRouter路由架構。借鑒網路請求的思想，設計了基於UriRequest、UriHandler、UriInterceptor的URI分發機制，在保證功能靈活強大的同時，又儘可能的降低了使用難度；另一方面，借鑒SPI的設計思想、Java和美團平台的ServiceLoader實現，開發了自己的ServiceLoader模組，解決外賣平台化過程中的四個問題（通訊問題、複用問題、依賴注入、編譯問題）。在經過了近一年的不斷迭代完善後，WMRouter已經成為美團多個App中的核心基礎組件之一。

參考資料

1. Routing - Wikipedia
2. 統一資源標誌符 - 維基百科
3. RFC 3966 - The tel URI for Telephone Numbers
4. RFC 6068 - The 'mailto' URI Scheme
5. Intent 和 Intent 過濾器
6. Introduction to the Service Provider Interfaces
7. 美團外賣Android平台化架構演化實踐

作者簡介

子健，美團進階工程師，2015年加入美團，先後負責外賣用戶端首頁、商家容器、評價等業務模組的開發維護，以及平台化、效能最佳化等技術工作。

淵博，美團進階工程師，2016年加入美團，目前作為外賣商家端Android App主力開發，主要負責商家端和蜜蜂端業務技術需求開發。

雲馳，美團進階工程師，2016年加入美團，目前負責外賣用戶端搜尋、IM等業務庫，及外賣多端統一工作。

招聘

美團外賣誠招Android、iOS、FE進階/資深工程師和技術專家，Base北京、上海、成都，歡迎有興趣的同學投遞簡曆到wukai05@meituan.com。

發現文章有錯誤、對內容有疑問，都可以關注美團技術團隊公眾號（meituantech），在後台給我們留言。我們每周會挑選出一位熱心小夥伴，送上一份精美的小禮品。快來掃碼關注我們吧！