moostjs

Moost

面向 TypeScript 的元数据驱动事件处理框架。通过装饰器 + 可组合项（基于 Wooks）处理 HTTP、CLI、WebSocket 和工作流事件。每种事件类型对应一个适配器。没有模块抽象——控制器直接注册到 Moost 上。所有适配器共享 DI、拦截器和管道。单个控制器可以同时公开 @Get、@Cli、@Message 方法；每个适配器只绑定自己的处理器类型。

由以下项目提供支持：@prostojs/mate（元数据）、@prostojs/infact（DI）、@wooksjs/event-core（异步事件上下文）、@prostojs/dye（编译时终端颜色）。

领域地图 — 仅加载所需内容

领域	文件	在以下情况下加载
核心概念、Moost 类、生命周期、注册、应用初始化/销毁	core.md	新项目、多适配器设置、app.init()、@MoostInit/@InjectMoost/app.addInitHook()、启动时设置、Moost 子类、app.dispose()/@MoostDispose、优雅关闭、disposeOnSignals()（SIGTERM/SIGINT 处理程序、开发重载时出现 MaxListenersExceededWarning、Ctrl-C 销毁了错误的应用）、热重载时资源泄漏、重载后定时器/任务重复
装饰器、元数据、自定义装饰器、Mate	decorators.md	创建/使用装饰器、读取元数据、控制器子类化 / @Inherit / 父级路由返回 404 / diagnostics.inheritance
DI 作用域、@Injectable、@Inject、@Provide、@Circular	di.md	服务、作用域、提供者、替换项；以另一个控制器身份运行代码（withControllerContext、forkEventContext）
拦截器：优先级、@Intercept、守卫、基于类的拦截器	interceptors.md	身份验证/日志记录/错误处理等横切关注点
管道：@Pipe、@Resolve、TRANSFORM/VALIDATE	pipes.md	验证、转换、自定义参数装饰器
自定义适配器：TMoostAdapter、defineMoostEventHandler	custom-adapters.md	为新的事件源构建适配器
HTTP 设置/路由	event-http.md	MoostHttp、路由装饰器、处理程序返回值、fetch/SSR、invoke（当前请求中的路由）、withHttpContext、forwardHeaders/DEFAULT_FORWARD_HEADERS、匿名 127.0.0.1 自调用
HTTP 请求数据	http-request.md	@Query/@Header/@Cookie/@Body/@Req/@Res/@Ip
HTTP 响应控制	http-response.md	@SetStatus/@SetHeader/@SetCookie、引用、正文大小限制、HttpError
HTTP 身份验证守卫	http-auth.md	defineAuthGuard、AuthGuard、@Authenticate
CLI	event-cli.md	CliApp、@Cli/@CliOption、帮助、CLI 拦截器
工作流	event-wf.md	@Step/@Workflow/@WorkflowSchema、暂停/恢复、输出端、状态策略
WebSocket 核心	event-ws.md	MoostWs/WsApp、@Message/@Connect/@Disconnect、线路协议
WebSocket 房间	ws-rooms.md	useWsRooms、广播、WsBroadcastTransport
WebSocket 测试	ws-testing.md	prepareTestWsMessageContext / prepareTestWsConnectionContext
Vite 插件：开发/构建、中间件、SSR/SPA、部署	vite.md	moostVite、vite.config.ts、createSSRServer、ssrEntry/serverEntry、ssr.noExternal/ssr.external、ssrExternalCheck、开发服务器拆分警告 / “开发环境中由 Node 原生加载” / instantiate(MoostHttp) 仅在 vite serve 下失败、dist/server、HMR、“生产环境中 useRequest() 未定义”、“Cannot read properties of undefined (reading 'headers')”、外部化依赖调用 wooks 组合式函数、开发服务器提供了未完全启动的应用 / 编辑后某些 API 路由返回 index.html / 开发环境中不显示 app.init() 错误 / “502 Moost app failed to load” / 插件是否等待 init()、SSR 渲染约定 / 每页 head-SEO / 状态 / ssrHead / TSSRRenderResult / TSSRRenderContext / ssrFetchForwarding（SSR 查看者身份）
Swagger/OpenAPI	swagger.md	SwaggerController、Swagger* 装饰器、OpenAPI 规范生成、提供 spec.json/UI、securitySchemes
OpenTelemetry	otel.md	enableOtelForMoost、跨度/追踪、@OtelIgnoreSpan/@OtelIgnoreMeter、跨度处理器、useOtelContext/useSpan/withSpan、moost.event.duration 指标
RBAC/ABAC 访问控制	@aooth/arbac-moost (aooth 文档)	身份验证、角色/范围、授权守卫——不属于此仓库；@moostjs/arbac 已弃用，现由 aooth 取代

脚手架

npm create moost@latest [name] -- [--http|--cli|--ws|--ssr] [--wf] [--oxc] [--force]

最多传入一个项目类型标志（--http --ws 除外：它表示 HTTP 应用 + WebSocket 插件）。标志会预先选择插件，并跳过相应的交互式切换项。详情请参阅：core.md。

快速开始

import { Moost } from 'moost'
import { MoostHttp } from '@moostjs/event-http'

const app = new Moost()
app.adapter(new MoostHttp()).listen(3000)
app.registerControllers(AppController)
await app.init()

其他入口：

• CLI：new CliApp().controllers(AppController).useHelp({ name: 'my-cli' }).start() — 基于 Moost + MoostCli 的便捷封装（event-cli.md）
• 独立 WS：await new WsApp().controllers(ChatController).start(3000)（event-ws.md）
• 多个适配器共用一个 HTTP 服务：先捕获适配器 — const http = app.adapter(new MoostHttp())，然后调用 http.listen(3000) 和 app.adapter(new MoostWs({ httpApp: http.getHttpApp() }))（event-ws.md）
• Moost 子类本身就是一个控制器 — 直接装饰其方法（core.md）

通用要点

DI 作用域 — @Injectable() / @Injectable(true) / @Injectable('SINGLETON') = 应用生命周期内使用同一个实例。@Injectable('FOR_EVENT') = 每个事件使用一个新实例。@Controller() 会隐式设置 @Injectable(true)（SINGLETON）。当类属性保存每个请求的状态，或使用属性级 ref/resolver 装饰器时，请使用 'FOR_EVENT'。FOR_EVENT 需要活动的事件上下文（组合式函数在 SINGLETON 构造函数中不可用）。作用域生命周期（HTTP 响应 + 处理器、工作流运行和 WS 消息的每事件所有权、0.6.42 之前的 scope isn't registered 错误）：di.md#scopes。

Wooks 组合式函数可在处理器中使用 — 所有 @wooksjs/* 组合式函数（例如 useRequest、useResponse、useHeaders）都可直接在 Moost 处理器中使用；它们运行在同一个事件上下文中。

日志记录 — 组合式函数：useLogger('topic')（来自 moost，由 @wooksjs/event-core 重新导出）。属性：@InjectEventLogger()（每个事件）/ @InjectMoostLogger('topic')（应用级；回退到 @LoggerTopic，然后是类 @Id）。独立使用：createLogger({ transports: [loggerConsoleTransport] }) — loggerConsoleTransport 是一个已构造的传输器常量；直接传入，不要调用它。

重新导出 — moost 从 @wooksjs/event-core 重新导出 current、useLogger、key、cached、eventTypeKey、createEventContext、run，以及从 @prostojs/infact 重新导出 createProvideRegistry/createReplaceRegistry。moost 还导出自己的 globalKey(name) — 一个可安全避免重复的上下文键工厂（通过 globalThis 按名称缓存槽位）；对于任何由 moost 管理的上下文键，请用它代替 key，以免 moost 被多次加载时（双 ESM/CJS，或重复安装）set/get 不同步。@moostjs/event-http 重新导出 httpKind、HttpError、useHttpContext、prerenderJson（+ 类型 TPrerenderJsonOptions）。@moostjs/event-cli 重新导出 cliKind，以及从 moost 重新导出的 Param/Controller/Intercept/Description/Optional/defineBeforeInterceptor/defineAfterInterceptor/defineInterceptor（注意：defineErrorInterceptor 不会重新导出 — 请从 moost 导入）。@moostjs/event-wf 重新导出 wfKind、useWfState、StepRetriableError、出口原语。@moostjs/event-ws 重新导出 wsConnectionKind/wsMessageKind、WsError、所有 useWs* 组合式函数、currentConnection、prepareTestWs*。

架构参考

• 装饰器系统 — 所有装饰器都通过 getMoostMate()（单例 Mate，'moost' 工作区）；元数据在绑定时读取：decorators.md
• 拦截器优先级与阶段 — interceptors.md
• 管道优先级顺序与作用域级别 — pipes.md
• 事件处理器生命周期（defineMoostEventHandler）— custom-adapters.md
• 适配器模式 — 每个适配器都实现 TMoostAdapter<H>，通过 app.adapter(a) 附加，并根据自身的 handler.type 筛选 opts.handlers：custom-adapters.md