Saavo

类型定义

默认模板中的请求上下文、Worker 上下文、通用结果和领域类型。

默认模板的公共类型主要放在 src/types.ts 和 src/ctx/。各业务模块的输入、输出和数据模型留在本模块内，不会全部集中到一个全局类型文件中。

Variables

Variables 定义 Hono 请求期间可通过 c.get()、c.set() 和 c.var 访问的上下文变量，源码位于 src/types.ts。

Prop

Type

Ctx

type Ctx = Context<{
    Bindings: CloudflareBindings;
    Variables: Variables;
}>;

Ctx 是默认模板统一使用的 Hono Context 类型。Cloudflare 资源和运行时变量通过 c.env 读取，请求上下文变量通过 c.var 或 c.get() 读取。

WorkerCtx

WorkerCtx 位于 src/ctx/create.ts，是 HTTP、Queue、Cron 和 Durable Object Alarm 共用的运行上下文。

Prop

Type

createWorkerCtx

根据 Hono Context 或非 HTTP 入口提供的字段创建 WorkerCtx。fetch 入口传入 Hono Context；queue、scheduled 和 alarm 入口传入 env、logger、locale、tr 和 i18nCtx。

resolveFetchWorkerCtx

接收 Context | WorkerCtx。参数已经是 WorkerCtx 时直接返回，否则按 fetch 入口创建新的 WorkerCtx。

getWorkerCtx

getWorkerCtx 位于 src/ctx/get.ts，供 Queue、Cron 和 Alarm 入口创建完整上下文。未传 locale 时使用 config/i18n.ts 的默认语言；未传 runtime 时按 queue 处理。

WorkerCtx 只能在本次调用中使用

不要把 getWorkerCtx() 的返回值缓存在模块作用域。一个 Worker isolate 可能连续处理多次调用，每次调用都必须使用自己的日志、语言和运行信息。

通用结果类型

这些类型都定义在 src/types.ts。

SuccessResult<T>

Prop

Type

FailureResult

Prop

Type

FnResult<T>

SuccessResult<T> | FailureResult，供 Service 和其他内部函数统一返回成功或失败结果。

APIResponse<T>

API 返回类型。成功时与 SuccessResult<T> 相同；失败时必须提供 error，客户端据此读取相应语言的错误文案。

isSuccessResult

根据 success === true 把 APIResponse<T> 收窄为 SuccessResult<T>。

类型所在位置

类型范围位置
配置输入和校验规则src/libs/config/schemas/
Cloudflare Bindingworker-configuration.d.ts
API 请求参数对应的 src/api/**/schema.ts 或路由文件
账号、认证和会话src/core/services/auth/types.ts、src/core/services/session/types.ts
角色、权益、能力和 Subjectsrc/core/services/access/**/types.ts
支付src/core/modules/payment-v1/types.ts 及其子模块
联盟推广src/core/services/affiliate/**/types.ts
Reactionsrc/core/reaction/types.ts 及各 Event、Command 定义文件
原始数据库记录和 SQL 查询结果src/core/db/ 下的类型或 DAO 文件
仓储操作的输入、结果和数据转换src/core/repositories/ 下的对应模块
业务领域类型拥有该业务概念的领域模块
API 请求和响应 DTOsrc/api/ 下的对应接口模块

worker-configuration.d.ts 由 npm run cf-typegen 根据 wrangler.jsonc 和环境变量生成，不应直接编辑。