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 和環境變數產生，不應直接編輯。