架构总览

灵珑的架构可以按四层看：

层级	模块	作用
API 契约	lingframe-api	Ling、LingContext、注解、权限、事件、异常
核心运行时	lingframe-core	类加载器、生命周期、状态机、Pipeline、治理、路由、资源回收
运行时适配	lingframe-runtime	Spring Boot 2/3 Starter 和 Native 启动器
基础设施与控制面	lingframe-infrastructure、lingframe-dashboard	SQL/缓存治理代理和可视化管理面板

宿主启动路径

Spring Boot Starter 会自动装配：

1. EventBus
2. RuntimeCoordinator
3. LocalGovernanceRegistry
4. PermissionService
5. LingRepository
6. LingServiceRegistry
7. FilterRegistry
8. InvocationPipelineEngine
9. LingLifecycleEngine
10. LingDiscoveryService
11. Web 路由和治理 Filter

Native 运行时由 NativeLingFrame.start() 手动启动，装配同一批核心组件，但容器适配换成 NativeContainerFactory。

灵元部署路径

ling.yml
  -> LingManifestLoader
  -> DefaultLingLifecycleEngine.deploy
  -> LingClassLoader
  -> LingContainer
  -> LingInstance
  -> InstancePool
  -> RuntimeCoordinator

关键事实：

• ling.yml 只在目录根或 JAR 根识别。
• id 和 version 必须非空。
• 同一灵元可多版本并存。
• 非热重载部署不允许重复版本。
• properties.canary == true 的自动扫描结果会作为非默认版本部署。

请求调用路径

Web / @LingReference / LingContext.invoke
  -> InvocationContext
  -> InvocationPipelineEngine
  -> FilterRegistry ordered filters
  -> TerminalInvokerFilter

Web 入口在 Boot 2/3 中由 Servlet Filter 做治理。灵元 Controller 的实际路由由宿主代理 handler 转发，不把灵元 Controller 类直接长期暴露给宿主 HandlerMapping 缓存。

可观测路径

事件和指标来自三个方向：

• EventBus：生命周期、状态变更、监控和告警事件。
• MetricsCollector：调用成功率、失败、延迟、超时。
• GovernanceMetricsCollector：限流、熔断、恢复和治理状态指标。

Dashboard 读取这些运行时对象，提供列表、详情、健康、治理、时间线和诊断接口。