# 地层核心框架 Stratal 是一个模块化的 Cloudflare Workers 框架，具有依赖注入 (tsyringe)、带有 OpenAPI 生成的基于 Hono 的路由、队列使用者、cron 作业、i18n、缓存、存储和电子邮件。完整文档位于 [stratal.dev]()。 ## 主要限制 * 仅 ESM（`“类型”：“模块”`） * 仅使用 `tsc` 构建 — **从不** esbuild/tsup (tsyringe 需要 `emitDecoratorMetadata`) * 必须在 tsconfig 中启用 `experimentalDecorators` 和 `emitDecoratorMetadata` * 始终从 `stratal/validation` 导入 Zod，而不是直接从 `zod` 导入 * 服务类可以直接用作 DI 令牌（`@inject(MyService)`）。仅当服务需要可替换或属于可重用库的一部分时才创建符号令牌 * 使用带有`@inject()`装饰器的构造函数注入 ## 项目设置文档：[安装]() · [您的第一个工人]() // src/index.ts — Worker 入口点从“地层”导入{地层}；从'./app.module'导入{AppModule}； const app = new Stratal({ 模块: AppModule }); 导出默认应用程序； ## 模块文档：[模块]() · [生命周期挂钩]() @模块({ 导入：[其他模块]，提供者：[MyService]，控制器：[MyController]，消费者：[我的消费者]，工作：[MyCronJob]， }) 导出类 AppModule 实现 OnInitialize { onInitialize(ctx: ModuleContext) { /* 设置逻辑 */ } } 动态模块使用“forRoot()”（同步）或“forRootAsync()”（异步工厂）。生命周期挂钩：`OnInitialize`、`OnShutdown`。 ## 控制器和路由文档：[控制器和路由]() · [OpenAPI]() @Controller('/api/v1/users', { 标签: ['用户'] }) 导出类 UsersController 实现 IController { 构造函数（@inject（UsersService）私有userService：UsersService）{} @Route({ body: CreateUserSchema, 响应: UserSchema }) 异步创建（ctx：RouterContext）{ const data = wait ctx.body(); 返回 ctx.json(等待 this.usersService.create(data)); } } **方法 → HTTP 映射：** `index` → GET、`show` → GET /:id、`create` → POST (201)、`update` → PUT /:id、`patch` → PATCH /:id、`destroy` → DELETE /:id。使用 `await ctx.body()` 来获取经过验证的正文 — **不是** `ctx.req.valid('json')`。 ## 依赖注入文档：[DI]() · [提供者]() // 简单：直接使用类作为 token @瞬态（）导出类 UsersService { /* ... */ } // 注入：@inject(UsersService) // 符号标记——仅适用于可替换的抽象 const USER_REPO = Symbol.for('UserRepository'); @模块({ 提供者：[ { 提供：USER_REPO，useClass：PgUserRepository，范围：Scope.Request }， ], }) 范围 |行为 ---|--- `范围.瞬态` |每个分辨率的新实例（默认） `范围.Singleton` |全局单实例 `范围.请求` |每个 HTTP 请求新实例 **提供程序类型：** `useClass`、`useValue`、`useFactory`（带有 `inject` 数组）、`useExisting`。 ## StratalEnv 增强文档：[环境类型]() // 1.生成牧马人类型：npx牧马人类型 // 2. 使用 Cloudflare.Env 扩展 StratalEnv：导出{}；声明模块“stratal”{ 接口 StratalEnv 扩展 Cloudflare.Env {} } 运行“npx wrangler types”以从“wrangler.jsonc”绑定生成“Cloudflare.Env”。 ## 守卫和中间件文档：[Guards]() · [中间件]() // Guard — 实现 CanActivate @瞬态（）导出类 ApiKeyGuard 实现 CanActivate { 构造函数（@inject（DI_TOKENS.CloudflareEnv）私有环境：StratalEnv）{} canActivate(ctx: RouterContext): 布尔值 { return ctx.header('x-api-key') === this.env.API_KEY; } } // 在控制器或方法上使用 @UseGuards(ApiKeyGuard) 进行应用 // 中间件类 — 实现中间件 @瞬态（）导出类 LoggingMiddleware 实现中间件 { 异步句柄(ctx: RouterContext, next: () => Promise) { console.log(`--> ${ctx.c.req.method} ${ctx.c.req.path}`); 等待下一个（）； } } // 中间件注册——模块实现 MiddlewareConfigurable 导出类 AppModule 实现 MiddlewareConfigurable { 配置（消费者：MiddlewareConsumer）{ Consumer.apply(LoggingMiddleware).forRoutes('*'); Consumer.apply(CorsMiddleware).exclude('/health').forRoutes(ApiController); } } ## 配置文档：[配置]() const databaseConfig = registerAs('数据库', (env: StratalEnv) => ({ url: env.DATABASE_URL, 池大小：10， })); @Module({ 提供者: [databaseConfig.asProvider()] }) 导出类 AppModule {} // 注入：@inject(databaseConfig.KEY) config: { url: string;池大小：数字 } ## 活动文档：[事件]() @监听器() 导出类 UserCreatedListener { @On('after.User.create') 异步 sendWelcomeEmail(context: EventContext<'after.User.create'>) { // 处理事件 } } 增强类型安全自定义事件的“CustomEventRegistry”。选项：“优先级”（数字）、“阻塞”（布尔值）。 ## 错误处理文档：[错误处理]() 从 'stratal/errors' 导入 { ApplicationError, ERROR_CODES }; 导出类 UserNotFoundError 扩展 ApplicationError { 构造函数（用户ID：字符串）{ super('errors.userNotFound', ERROR_CODES.RESOURCE.NOT_FOUND, { userId }); } } “ApplicationError”提供结构化 JSON 响应，其中包含 i18n 消息键、数字错误代码（来自“ERROR_CODES”）和元数据。 ## 队列消费者文档：[队列]() @瞬态（）导出类 EmailConsumer 实现 IQueueConsumer { 只读 messageTypes = ['email.send']; 异步句柄（消息：QueueMessage ）{ // 处理message.payload } } 在模块“consumers”数组中注册。消息具有“id”、“type”、“payload”和可选的“metadata”。 ## 计划任务文档：[Cron 作业]() @瞬态（）导出类 CleanupJob 实现 CronJob { 只读时间表='0 2 * * *'; 异步执行（控制器：ScheduledController）{ // 每天凌晨 2 点（世界标准时间）运行 } } 在模块“jobs”数组中注册。计划必须与“wrangler.jsonc”中的触发器匹配。 ## 工人文档：[持久对象]()·[服务绑定]()·[工作流程]() Stratal 为 Cloudflare Workers 原语（持久对象、服务绑定/RPC、工作流）提供基类，并具有内置 DI 支持。每个类都公开一个“runInScope()”方法，该方法从静态 Stratal 单例创建请求范围的 DI 容器。 // src/index.ts — 必须将 Stratal 导出为默认 + 将工作类导出为命名导出从 './counter' 导出 { Counter } ；从 './auth-rpc' 导出 { AuthRpc }；从 './my-workflow' 导出 { MyWorkflow }；导出默认新 Stratal({ module: AppModule }); ### StratalDurableObject 扩展“DurableObject”。 `runInScope` 自动注册 `DI_TOKENS.DurableObjectState` 和 `DI_TOKENS.DurableObjectId`。导出类 Counter 扩展 StratalDurableObject { 异步增量() { 返回 this.runInScope(async (container) => { const counterService = container.resolve(CounterService) counterService.increment(); }); } } ### StratalWorkerEntrypoint 扩展 RPC/服务绑定的“WorkerEntrypoint”。导出类 AuthRpc 扩展 StratalWorkerEntrypoint { 异步 verifyToken（令牌：字符串）{ 返回 this.runInScope(async (container) => { const auth = container.resolve(AuthService); 返回 auth.verify(token); }); } } ### StratalWorkflow 使用通用的“Env”和“Params”类型扩展“WorkflowEntrypoint”。导出类 MyWorkflow 扩展 StratalWorkflow { 异步运行(事件: WorkflowEvent<{ orderId: string }>, 步骤: WorkflowStep) { 等待步骤.do('进程', () => this.runInScope(异步（容器）=> { const svc = 容器.resolve(OrderService); 返回 svc.validate(event.payload.orderId); }) ）； } } ## 内置模块快速参考模块|进口|文档 ---|---|--- `缓存模块` | `分层/缓存` | [缓存]() `电子邮件模块` | `地层/电子邮件` | [电子邮件]() `存储模块` | `地层/存储` | [存储]() `I18n模块` | `stratal/i18n` | [i18n]() `OpenAPIModule` | `stratal/openapi` | [OpenAPI]() `LoggerService` | `地层/记录器` | [日志记录]() `配置模块` | `地层/配置` | [配置]() `队列模块` | `层/队列` | [队列]() ## 子路径导入路径|主要出口产品 ---|--- `地层` | `Stratal`、`应用程序`、`@Module`、`StratalEnv` `地层/di` | `容器`、`DI_TOKENS`、`范围`、`注入`、`瞬态` `地层/路由器` | `@Controller`、`@Route`、`RouterContext`、`UseGuards`、`IController` `地层/验证` | `z` (Zod)、`ZodType`、验证实用程序 `地层/错误` | `ApplicationError`、`ERROR_CODES`、内置错误类 `地层/事件` | `@Listener`、`@On`、`EventRegistry` `stratal/i18n` | `I18nModule`, `I18nService` `分层/缓存` | `缓存模块`、`缓存服务` `地层/电子邮件` | `电子邮件模块`、`电子邮件服务` `地层/存储` | `存储模块`、`存储服务` `层/队列` | `QueueModule`、`QueueService`、`IQueueConsumer` `地层/记录器` | `LoggerService`、`LOGGER_TOKENS` `地层/配置` | `ConfigModule`、`registerAs` `stratal/openapi` | `开放 API 模块` `地层/工人` | `StratalDurableObject`、`StratalWorkerEntrypoint`、`StratalWorkflow`、`runInScope` ## 该做和不该做的事情 * **Do** 使用类引用作为简单服务的 DI 令牌（`@inject(MyService)`） * **不要** 仅将符号标记用于可替换的抽象或可重用的库 * **Do** 使用 `await ctx.body()` 来验证请求主体 * **执行** 从 `stratal/validation` 导入 Zod * **Do** 使用带有`@inject()`的构造函数注入 * **Do** 将 `@Transient()` 添加到消费者、作业、守卫、中间件和侦听器 * **Do** 在 `consumers` 中注册消费者，在 `jobs` 数组中注册作业 * **不要**使用 esbuild 或 tsup — 仅使用 `tsc` * **不要**使用 `ctx.req.valid('json')` — 使用 `await ctx.body()` * **不要**直接从 `zod` 导入 Zod * **Do** 将 `Stratal` 实例导出为默认导出（工作线程类使用的静态单例需要） * **Do** 对每个需要 DI 的方法/工作流程步骤使用 `runInScope` — 每个调用都会获得一个新的请求范围容器 * **不要**跨 `runInScope` 调用缓存容器引用 - 容器仅在回调中有效 * **不要** 在 tsconfig 中禁用 `emitDecoratorMetadata`

地层

包含技能