VirtualMatch 是一个专为 Kotlin Multiplatform (KMP) 设计的轻量级、全自动路由与 URI 匹配框架。它通过 KSP 自动收集路由元数据，并利用 KCP (Kotlin Compiler Plugin) 实现零配置的代码注入。
- 全自动注册：无需手动维护路由表，通过
@Urls注解定义，编译时自动生成注册代码。 - 零代码注入：利用 KCP 插件，在带有
@InitTarget的函数中自动注入初始化逻辑。 - 跨模块支持：支持在多个 KMP 模块（如
:shared,:feature）中定义路由，并在 App 模块自动聚合。 - 轻量级 URI 解析：内置
VirtualUri工具，零外部依赖，封装各平台原生 API（Android, iOS, JVM, JS, WasmJs）。 - 灵活匹配策略：支持 精确匹配 (EXACT) 和 最长前缀匹配 (PREFIX)，且规则由定义端管控。
- 强大的扩展性：支持全局 拦截器 (Interceptors) 和 兜底处理 (Fallbacks)。
在任何模块的函数上使用 @Urls 注解。函数必须有且仅有一个 VirtualParams 参数。
// 默认使用精确匹配 (EXACT)
@Urls(urls = ["qzd://virtual/home", "qzd://virtual/main"])
fun openHome(params: VirtualParams) {
// 访问原始 URL 或解析后的参数
val id = params.uri.getQueryParameter("id")
println("跳转到主页，ID: $id")
}
// 也可以指定为前缀匹配 (PREFIX)
@Urls(
urls = ["qzd://virtual/user"],
matchType = VirtualMatchType.PREFIX
)
fun onUserPath(params: VirtualParams) {
// 匹配 qzd://virtual/user/profile, qzd://virtual/user/settings 等
}在你的 App 入口（如 Application 或 MainActivity）定义一个带 @InitTarget 的空函数。VirtualMatch 会在编译时自动把所有路由注册逻辑注入进去。
class MyApp : Application() {
override fun onCreate() {
super.onCreate()
// 只需要调用这个标记了注解的函数
initVirtual()
}
}
@InitTarget
fun initVirtual() {
// 编译器会自动在这里插入: VirtualRegistry.register(...)
}使用 String 的扩展函数轻松触发跳转。调用方无需关心匹配模式，系统会自动根据注册规则寻找最优匹配。
"qzd://virtual/home?id=123".virtualCall()
// 或者传递自定义上下文和数据
"qzd://virtual/home".virtualCall(context = this, data = somePayload)
// 也可以监听匹配结果。如果提供了 matched 回调，则全局兜底 (Fallback) 将不会触发。
"qzd://virtual/home".virtualCall { matched ->
if (matched) {
println("匹配成功")
} else {
println("匹配失败，执行自定义逻辑")
}
}可以在跳转前进行权限校验、日志记录或参数修改：
VirtualMatch.addInterceptor { params ->
if (params.url.contains("secret")) {
// 返回 false 拦截跳转
false
} else {
true
}
}处理未定义的路由跳转：
VirtualMatch.setDefaultFallback { params ->
println("无法识别的路径: ${params.url}")
// 跳转到 404 页面
}系统在匹配时遵循以下优先级：
- 精确优先：优先寻找
EXACT匹配的路由。 - 最长匹配：如果没有精确匹配，寻找符合
PREFIX规则且匹配路径最长的路由（最具体匹配原则）。
:virtual：核心运行时库，包含VirtualUri和VirtualRegistry。:process：KSP 处理器，负责扫描注解和收集元数据。:process-kcp：Kotlin 编译器插件，负责自动注入init代码。:process-gradle-plugin：Gradle 插件，用于简化上述工具的配置。
@Urls标记的方法必须是全项目唯一的（针对baseUri）。- 确保项目应用了
top.brightk.virtualGradle 插件。