wooksjs

wooksjs

面向 Node.js 的类型化可组合框架。所有请求／事件数据均通过可组合函数访问——无需 req／res 参数，也无需中间件链。适配器：HTTP、CLI、WebSocket、工作流。此外还提供独立的 WebSocket 客户端。

安装

包	安装	对等依赖说明
@wooksjs/event-http	npm i wooks @wooksjs/event-http	—
@wooksjs/event-cli	npm i wooks @wooksjs/event-cli	—
@wooksjs/event-ws	npm i wooks @wooksjs/event-ws ws	需要 ws ^8.0.0
@wooksjs/event-wf	npm i wooks @wooksjs/event-wf	可选对等依赖 @wooksjs/event-http + @wooksjs/http-body（HTTP 输出端）
@wooksjs/http-body	npm i @wooksjs/http-body	对等依赖 @wooksjs/event-core、@wooksjs/event-http
@wooksjs/http-static	npm i @wooksjs/http-static	对等依赖 @wooksjs/event-http
@wooksjs/http-proxy	npm i @wooksjs/http-proxy	对等依赖 @wooksjs/event-http
@wooksjs/ws-client	npm i @wooksjs/ws-client	ws 可选——仅限 Node；浏览器使用原生 WebSocket

依赖关系图

event-core  <-  wooks  <-  adapters: event-http, event-cli, event-ws, event-wf
                           event-http  <-  utilities: http-body, http-static, http-proxy

ws-client: standalone (no event-core dependency)

• 工具的对等依赖特定为 event-http（http-body 还依赖 event-core）。
• event-wf 的可选对等依赖为 @wooksjs/event-http + @wooksjs/http-body——使用 HTTP 输出端时请同时安装两者。

架构

所有公共 API 都是由 defineWook 创建的可组合函数，并按 EventContext 缓存。EventContext 是一个类型化槽位容器（key／cached／cachedBy／slot），通过 AsyncLocalStorage 传播；调用 current() 即可在任何位置获取它，无需传递参数。父级上下文链使嵌套事件（HTTP → 工作流、HTTP → WS 升级）能够读取父级槽位。详情：event-core.md。

快速开始

import { createHttpApp, useRouteParams } from '@wooksjs/event-http'

const app = createHttpApp()
app.get('/hello/:name', () => `Hello, ${useRouteParams().get('name')}!`)
app.listen(3000)

大多数参考文件末尾都有一张 Rules & Gotchas 表——编写代码前请先阅读。

关键导入

// event-core — context engine, custom adapters
import { key, cached, cachedBy, slot, defineEventKind, defineWook,
  EventContext, run, current, tryGetCurrent, createEventContext,
  useRouteParams, useEventId, useLogger, routeParamsKey, eventTypeKey,
  ContextInjector, getContextInjector, replaceContextInjector, resetContextInjector } from '@wooksjs/event-core'

// event-http — HTTP server + request/response composables
import { createHttpApp, useRequest, useResponse, useHeaders, useCookies,
  useUrlParams, useAuthorization, useAccept, HttpError,
  prepareTestHttpContext, DEFAULT_FORWARD_HEADERS } from '@wooksjs/event-http'

// http-body — parsed request bodies (JSON, form-data, urlencoded)
import { useBody } from '@wooksjs/http-body'

// http-static — file serving
import { serveFile } from '@wooksjs/http-static'

// http-proxy — reverse proxy
import { useProxy } from '@wooksjs/http-proxy'

// event-cli — command-line apps
import { createCliApp, useCliOptions, useCliOption,
  useCliHelp, useAutoHelp, useCommandLookupHelp } from '@wooksjs/event-cli'

// event-ws — WebSocket server
import { createWsApp, useWsConnection, useWsMessage, useWsRooms, useWsServer,
  currentConnection, prepareTestWsConnectionContext, prepareTestWsMessageContext } from '@wooksjs/event-ws'

// event-wf — workflows
import { createWfApp, useWfState, StepRetriableError } from '@wooksjs/event-wf'

// ws-client — standalone WS client (browser + Node)
import { createWsClient } from '@wooksjs/ws-client'

参考资料

阅读与任务匹配的参考文件。不要加载所有文件，只加载所需文件。

领域	文件	在以下情况下加载
路由	router.md	路由模式、参数、通配符、正则表达式、路径构建器、配置
上下文引擎	event-core.md	使用槽位、组合式函数、EventContext、自定义适配器
HTTP 核心／路由	event-http.md	创建 HTTP 应用、路由、服务生命周期、安全标头
HTTP 请求	http-request.md	读取标头、Cookie、查询参数、原始请求体、授权
HTTP 响应	http-response.md	状态码、标头、Cookie、缓存、错误、流式传输、测试
请求体解析	http-body.md	解析请求体（useBody）：JSON、form-data、urlencoded 类型
静态文件	http-static.md	提供文件／目录（serveFile）、范围请求、缓存标头
HTTP 代理	http-proxy.md	代理／转发请求、筛选标头／Cookie、allowedHosts
CLI 应用	event-cli.md	构建 CLI 工具、命令路由、选项、帮助系统
WebSocket 服务端	event-ws.md	WS 服务端、房间、广播、消息路由、通信协议
工作流核心	event-wf.md	步骤、流程、架构语法、暂停／恢复、useWfState
工作流出口	wf-outlets.md	HTTP／电子邮件投递、状态策略、令牌、触发器处理程序
工作流高级功能	wf-advanced.md	父上下文、侦听器、错误处理、测试
WS 客户端	ws-client.md	浏览器／Node WS 客户端、RPC、订阅、重新连接

跨领域参考

• 父上下文链（HTTP → 工作流、HTTP → WS）：wf-advanced.md
• 跨适配器共享路由器（createCliApp({}, http) 等）：router.md
• 性能——每个处理程序只解析一次上下文：event-http.md
• 自动状态码推断（方法 × 请求体 → 状态码）：event-http.md
• WS 通信协议（3 种消息结构）：event-ws.md
• Express／Fastify／H3 集成属于独立软件包——@wooksjs/express-adapter、@wooksjs/fastify-adapter、@wooksjs/h3-adapter；文档：https://wooks.moost.org/webapp/integrations/

另请参阅

• 文档站点：https://wooks.moost.org
• 源代码：https://github.com/wooksjs/wooksjs