Master Android Modular Routing with TheRouter: Features, Usage, and Migration

TheRouter Overview

TheRouter is a Kotlin‑written framework that offers a complete solution for Android modular development. Its source code and documentation are available on GitHub.

Core Capabilities

Navigator : Page navigation for Activity and Fragment, support for path regex, JSON route export, dynamic JSON route updates, object passing without serialization, interceptors, custom parameter parsing, and third‑party SDK navigation.

ServiceProvider : Cross‑module dependency injection with customizable creation rules, mock debugging, and object caching.

FlowTaskExecutor : Single‑module automatic initialization, lazy loading, compile‑time circular dependency detection, and customizable initialization timing for privacy compliance.

ActionManager : Global callbacks for actions such as pop‑ups, logging, or cache cleaning, with traceable interceptor chains.

One‑click AAR/source switching script.

Why Use TheRouter

Routing decouples the strong Intent dependency between pages, which is essential for large enterprise apps that adopt modular architecture. TheRouter not only handles page jumps but also solves common modular problems such as accessing Application lifecycle across components.

Navigator Details

Supports Activity and Fragment navigation.

Path can be a URL and may contain regular expressions (must include escaped backslashes).

Exportable JSON route tables and dynamic JSON updates allow fallback to H5 pages.

Custom actions and parameter parsing can be defined per route.

ServiceProvider Details

Cross‑module injection with customizable creation rules.

Supports mock implementations for testing.

Object caching ensures a single instance per injection.

FlowTaskExecutor Details

Methods annotated with @FlowTask and declared public static are collected at compile time.

Tasks have a unique taskName, optional dependsOn (comma‑separated), and an async flag.

Built‑in tasks TheRouterFlowTask.APP_ONCREATE and TheRouterFlowTask.APP_ONSPLASH handle initialization after Application.onCreate() and the first Activity.onCreate() respectively.

ActionManager Details

Define actions with a unique URI (e.g., therouter://action/xxx).

Register ActionInterceptor implementations that handle the action, return a boolean to continue or stop the chain, and have a numeric priority (higher means earlier).

Useful for prioritized pop‑ups, logging, or remote commands.

Routing Process

During development, annotate target pages with @Route, specifying path, optional action, description, and params. The compiler generates classes prefixed with RouteMap__. The top‑level app module aggregates all RouteMap__ classes via a Gradle plugin into TheRouterServiceProvideInjecter. At runtime, the router loads the combined route map without any reflection.

Dynamic Route Table

The router generates a full route map JSON file under /assets/therouter/routeMap.json after each build. This file can be remotely overridden, allowing hot‑fixes such as replacing a crashed page with an H5 fallback. Two remote update strategies are provided: automatic upload after each build or manual upload via a configuration system.

Service Injection (SOA Design)

TheRouter’s ServiceProvider follows a service‑oriented architecture. Service providers expose interfaces without exposing implementation details, while consumers retrieve services via TheRouter.get(IRecordService::class.java). Providers can be written in Java (public static) or Kotlin (top‑level functions).

One‑Click Source/AAR Switching

A Gradle script ( moduleApi) reads a local.properties file to decide which modules are compiled from source and which are used as AARs. It iterates over all projects, adds either a project dependency or a Maven dependency accordingly, and prints the chosen mode.

Migration Tools

TheRouter offers a graphical migration tool to convert ARouter configurations to TheRouter annotations. Downloads are available for macOS and Windows. After migration, developers may need to adjust manual initialization calls such as IProvider.init().

Feature Comparison (summary)

Fragment routing, dependency injection, and path regex support.

No runtime dex scanning or reflection – compile‑time generated route maps.

Supports multiple paths for the same page, remote route table updates, and per‑activity interceptors.

Incremental compilation for both annotation processor and Gradle plugin.

Built‑in single‑module initialization and dynamic action handling.

Conclusion

TheRouter is more than a lightweight router; it is a comprehensive Android modular solution that addresses navigation, dependency injection, initialization, dynamic routing, and migration. It provides tools for smooth migration from ARouter and encourages community contributions via GitHub.