Lightweight automatic routing and URI-matching: annotation-defined routes, compile-time registration and injection, exact/prefix matching, global interceptors and fallbacks, zero-dependency URI utilities.
VirtualMatch 是一个专为 Kotlin Multiplatform (KMP) 设计的轻量级、全自动路由与 URI 匹配框架。它通过 KSP 自动收集路由元数据，并利用 KCP (Kotlin Compiler Plugin) 实现零配置的代码注入。
@Urls 注解定义，编译时自动生成注册代码。@InitTarget 的函数中自动注入初始化逻辑。:shared, :feature）中定义路由，并在 App 模块自动聚合。VirtualUri 工具，零外部依赖，封装各平台原生 API（Android, iOS, JVM, JS, WasmJs）。在任何模块的函数上使用 @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.virtual Gradle 插件。VirtualMatch 是一个专为 Kotlin Multiplatform (KMP) 设计的轻量级、全自动路由与 URI 匹配框架。它通过 KSP 自动收集路由元数据，并利用 KCP (Kotlin Compiler Plugin) 实现零配置的代码注入。
@Urls 注解定义，编译时自动生成注册代码。@InitTarget 的函数中自动注入初始化逻辑。:shared, :feature）中定义路由，并在 App 模块自动聚合。VirtualUri 工具，零外部依赖，封装各平台原生 API（Android, iOS, JVM, JS, WasmJs）。在任何模块的函数上使用 @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.virtual Gradle 插件。