Attribute Macro application 

#[application]

业务作用：把业务异步 main 转换为统一生命周期进程入口。

支持的组件字符串

attr 可以为空；非空时只接受下面 17 个区分大小写的精确字符串，不支持别名：

• "log"：启用两阶段日志。Bootstrap 先建立早期控制台日志，最终配置就绪后再安装文件日志， 并支持运行期日志级别热更新；需要 nasa 的 log feature。
• "nacos-config"：启用 Nacos 配置中心。启动时拉取远端配置 overlay，运行期监听配置变化并按 last-known-good 规则热刷新；需要 nacos-config feature，真实连接 Nacos 还需要 nacos-sdk。
• "telemetry"：启用有界 OpenTelemetry span 管道与受管停机 flush；需要 telemetry feature。
• "partition"：启用保序分 lane 执行器。容量计划可由 YAML partition 提供，或在 UserHook 提交；容器在 Prepare 创建执行器、发布强类型句柄并监督动态健康与停机排空；需要 partition feature。
• "grpc"：启用受管 gRPC service registry 与 listener。业务在 UserHook 登记 generated server， 容器在 Ready 自动装配、绑定端口、监督 serve 所有权并在停机时排空；需要 grpc feature。
• "db"：启用 MySQL/PostgreSQL 数据源。启动时按 driver 校验并探测地址、鉴权和数据库，创建连接池、 注册应用资源，同时注入对应的事务与 Mapper 运行时；需要 tx 或 tx-pgsql feature。
• "redis"：启用 Redis 客户端。启动时校验配置、探测 standalone/cluster 拓扑并建立受管客户端， 停机时由容器显式关闭；需要 redis feature。
• "redis-job"：启用多 source RedisJob 长生命周期运行时，并隐式加入 Redis；需要 redis-job feature。
• "cache"：启用由容器拥有的两级缓存运行时与可选跨节点失效广播；需要 cache feature。
• "saga"：启用 Saga Ready 门禁、只读能力发布与 durable timer 监督，并隐式加入 DB 与 Outbox。业务在 UserHook 通过 configure_saga 提交 Orchestrator 或参与方计划；需要 saga-runtime 或 saga-runtime-pgsql feature。
• "kafka"：启用受管 Kafka producer/consumer。负责 broker 探测、consumer 收集与启动、动态 readiness、运行期健康监控、停止消费和 producer flush；需要 kafka feature。
• "outbox"：启用事务型 Outbox dispatcher。业务在 UserHook 提交发布计划，组件负责持续投递、 readiness、退避与停机；需要 outbox feature。该组件隐式加入 DB；声明 "saga" 时也会自动 纳入 Outbox，无需重复书写。

隐式加入只负责补齐缺失依赖，不构成互斥约束。("saga")、("saga", "db") 与 ("saga", "db", "outbox") 会生成相同的组件图；只有同一个字符串在属性中重复出现才会拒绝。

• "auth"：启用 OAuth Resource Server/JWKS warmup、刷新和 readiness；必须同时声明 "web"， 需要 Web/OAuth 能力。
• "web"：启用 HTTP MVC 服务。自动收集 mapping 端点，安装 /healthz、/readyz 和请求观测， 绑定监听器并在停机时停止接流、排空在途请求；需要 web feature。
• "ws"：启用 TCP/WebSocket 长连接服务。业务在启动 Hook 中配置鉴权和 endpoint，容器负责监听、 会话服务、集群数据面接入与优雅排空；需要 ws feature，Redis/Kafka 集群子能力另开对应 feature。
• "nacos-discovery"：启用服务发现和注册。创建带负载均衡的出站 REST runtime，在服务 Ready 后 注册本实例，停机时先从注册中心摘流再关闭客户端；需要 nacos-discovery feature，真实 Nacos provider 还需要 nacos-sdk。
• "scheduling"：启用定时任务。收集 #[scheduled] 任务，在 Application Ready 后统一启动并在 停机时停止；需要 scheduling feature，Redis 选主的集群调度使用 scheduling-cluster。

"hystrix"、"grafana"、"mapper" 等是门面 feature 或函数级能力，不是组件字符串。

YAML 创建受管单源与多源

MySQL、PostgreSQL、Redis 与 Kafka 的 endpoint、凭据、池和客户端参数必须来自最终 YAML；Application 在启动期 创建并冻结完整命名表，业务 main 只取得受管句柄，不自行建池或连接。三类资源的配置形态如下：

资源	单源	多源	默认入口
MySQL	database	datasources.<name>	app.default_datasource().await
PostgreSQL	database	datasources.<name>	app.default_pg_datasource().await
Redis	扁平 redis	redis.properties.<qualifier>	app.default_redis().await
Kafka	kafka	kafkas.<client>	app.default_kafka()

单源根与多源根互斥。数据库单源固定发布为 default；Redis 单源的持久身份是 primary，查询边界 同时接受 default；Kafka 单 client 省略 client_name 时默认为 default。多源示例：

datasources:
  default:
    url: ${APP_PRIMARY_DB_URL}
  reporting:
    url: ${APP_REPORTING_DB_URL}
outbox:
  datasource_ref: reporting
saga:
  role: orchestrator
  plan_mode: custom
  database_bootstrap: application
  datasource_ref: reporting

redis:
  properties:
    primary:
      url: ${APP_PRIMARY_REDIS_URL}
      namespace: orders
      profile: RustV2
    sessions:
      url: ${APP_SESSION_REDIS_URL}
      namespace: sessions
      profile: RustV2

kafkas:
  default:
    bootstrap_servers: ${APP_PRIMARY_KAFKA_BOOTSTRAP_SERVERS}
  audit:
    bootstrap_servers: ${APP_AUDIT_KAFKA_BOOTSTRAP_SERVERS}

outbox.datasource_ref 选择 Outbox 数据源；managed Saga 使用角色作用域内的 datasource_ref，custom Saga 使用顶层 saga.datasource_ref。Cache、缓存失效广播和 Scheduling 使用各自的 redis_ref 选择 redis.properties。Kafka consumer/producer 通过 client name 选择 kafkas。这些引用在首次网络握手前复验，不存在时不会回退到默认或唯一实例。UserHook 中的 configure_saga、configure_kafka、configure_redis_jobs 等入口只提交业务定义和处理逻辑， 不负责建立基础设施 source。完整字段与单源示例见 napp README。

保序执行器的通用容量也可完全由 YAML 提供，不需要在 main 构造计划：

partition:
  partitions: 16
  queue_capacity: 1024
  global_inflight: 16384
  max_lanes: 4096
  shutdown_timeout_ms: 5000

声明顺序：与业务书写顺序无关

业务侧不需要按启动顺序书写组件字符串：宏接受任意顺序,内部按唯一的规范启动顺序 （CANONICAL_COMPONENT_ORDER：log → nacos-config → telemetry → db → redis → cache → partition → saga → kafka → outbox → redis-job → grpc → auth → web → ws → nacos-discovery → scheduling）自动规范化后再生成组件列表。因此 #[application("web", "log", "kafka")] 与 #[application("log", "kafka", "web")] 完全等价, 都按 log → kafka → web 启动、严格反序停机。宏仍会拒绝未知组件名和重复声明。

示例（任意顺序均可，等价于规范顺序）：

#[nasa::application(
    "log",
    "nacos-config",
    "telemetry",
    "partition",
    "grpc",
    "redis",
    "cache",
    "saga",
    "kafka",
    "auth",
    "web",
    "ws",
    "nacos-discovery",
    "scheduling"
)]
async fn main(app: nasa::Application) -> anyhow::Result<()> {
    // 声明 Saga 后 DB 与 Outbox 已纳入生命周期，这里只提交业务计划和其它组件定制。
    Ok(())
}

参数说明：

• attr：按任意书写顺序声明的零个或多个受支持组件字符串。
• item：零参数或接收一个 Application 的异步主函数。

返回：入口合法时生成同步进程入口、规范组件描述和业务启动 Hook；合同非法时生成定位到调用处的 编译错误。