中英文術語表

依主題查閱 Saavo 文件中的中英文術語、程式碼名稱和容易混淆的概念。

本表統一前面各章的常用名稱,也可用來查閱英文程式碼、記錄和平台主控台中的概念。中文採用本文慣例,檔名、型別、設定欄位、指令和協定識別碼則保留原始碼寫法。

表中說明以目前範本和文件的語境為準,不代表專案已實作列出的每一種技術或恢復機制。精確欄位和預設值請查閱參考手冊,個別問題請查閱疑難排解。

使用與寫作慣例

  • 首次介紹不熟悉的概念時,可以寫成「中文名稱(English Name)」,後文保持一致。
  • Cloudflare、Stripe、OAuth、Webhook、API、URL、JSON、SQL 等名稱保留英文,不必強行直譯。
  • 識別碼、路徑、指令和字面值使用反引號,例如 DB、SAAS_SECRET、payment_succeeded。
  • 中文句子優先使用逗號和句號。分號用於確實需要區分層次的並列句,不作為清單和一般句子的預設結尾。
  • 同一英文詞在不同領域有不同含義時,請寫明語境。例如,資料庫交易和付款交易都可能對應 transaction。
  • 「範本預設設定」指範本原始檔中的值,「初始化後的設定」可能已由 CLI 改寫,「目前生效的設定」還取決於執行環境和已部署版本。
  • 「支援」應有實際實作和呼叫入口。出現型別、錯誤碼或註解範例,不代表對應業務已開放。
  • 使用「讀取、寫入、傳送、比對、授予、撤銷」等動作說明行為,避免只寫「處理完成」,卻未說明完成到哪一步。

專案、版本與開發流程

English / 程式碼中文名稱含義與用法
SaavoSaavo產品名稱,保留原文
Saavo CLISaavo 命令列工具用於登入、選擇範本和建立專案等,不等於應用程式執行環境
template範本用來建立專案的基礎原始碼與設定
project / application專案 / 應用程式「專案」著重原始碼和開發,「應用程式」著重執行後的產品
initialization初始化準備專案或資源的初始狀態,必須說明是本機還是遠端
template version範本版本取得範本時的來源版本,與應用程式版本分別記錄
application version應用程式版本自己的產品版本,不能據此反推範本來源
dependency相依套件專案安裝並使用的第三方套件或模組
lockfile相依套件鎖定檔記錄解析後的相依套件版本,例如 package-lock.json
build建置將原始碼轉換為建置檔案,不等於部署或資料庫遷移
type checking型別檢查TypeScript 靜態檢查,不等於 Vite 建置
lint程式碼規範檢查檢查已設定的程式碼規則,不能取代業務測試
test測試透過輸入、操作和斷言驗證預期行為
branch分支Git 中用來組織獨立開發工作的參照
commit提交Git 中的程式碼快照,也指提交操作
tag標籤標記一個 Git 狀態,不代表已部署
diff差異兩個程式碼或設定狀態之間的變更
merge conflict合併衝突兩邊修改無法直接自動合併,需要理解後處理
source archive原始碼套件某個明確原始碼狀態的封存檔,不包含執行資料或 Secret
changelog / release notes變更紀錄 / 更新說明內部紀錄說明實作細節,公開說明則描述使用者可見的變更

程式碼結構與介面慣例

English / 程式碼中文名稱含義與用法
configuration / config設定應用程式的設定及規則,注意區分靜態設定與執行變數
source of truth權威來源 / 唯一依據某項資料或規則應以哪個定義為準
schemaSchema / 資料結構設定和輸入驗證常寫 Schema,資料庫語境則寫資料表結構或資料結構
domain業務領域描述業務概念,與網站的「網域」區分
service服務層 / Service負責業務規則與流程組織,具體程式碼名稱保持原樣
repository儲存庫層 / Repository呼叫資料庫存取層,將儲存值轉換為業務值,不是 Git 儲存庫
DB access / DAO資料庫存取層負責 SQL、原始資料列和資料庫操作,DB 單獨出現時也可能是 Binding
UI介面 / UI面向使用者時寫「介面」,說明分層時可保留 UI
DTO資料傳輸物件(DTO)API 邊界上的請求或回應結構,不等於資料庫原始資料列
contract約定 / 契約例如介面約定、資料約定,描述呼叫雙方需遵守的規則
route路由請求路徑、方法與處理入口之間的比對關係
endpoint端點 / Endpoint對外呼叫入口,平台主控台中的物件名稱可以保留英文
handler處理函式處理請求、訊息、事件或命令的函式
middleware中介軟體在請求處理過程中執行的共用邏輯
guard存取守衛(Guard)檢查存取條件,具體回傳或重新導向行為以呼叫處為準
provider服務供應商 / Provider商業語境指外部服務供應商,程式碼語境也指實作某項功能的配接器
runtime執行階段執行程式碼的環境或入口語境,例如 fetch、queue、scheduled
context執行脈絡目前執行所需的環境、語言和記錄等資訊,例如 Ctx、WorkerCtx
serialization序列化將資料轉換為可儲存或傳輸的形式,不等於加密
validation驗證檢查輸入格式、型別或約束,不應一概視為使用者身分驗證

Cloudflare、環境與儲存

English / 程式碼中文名稱含義與用法
Cloudflare WorkersCloudflare Workers平台名稱,單一部署應用程式可稱 Worker,不譯為工作執行緒
Binding資源繫結 / BindingWorker 存取資源的設定關係,名稱如 MAIN_KV
resource name / resource ID資源名稱 / 資源 ID平台資源的名稱和識別碼,不等於程式碼中的 Binding 名稱
environment variable環境變數隨執行或建置環境提供的設定,變數名稱保留原始碼寫法
SecretSecret / 敏感設定Worker 中敏感變數的儲存方式,其值可能是金鑰、權杖或密碼
SAAS_SECRET應用程式主金鑰專案長期用於加密、簽章等操作的金鑰,不是版本號碼
build-time variable建置時變數建置過程中讀取,且可能寫入建置檔案的值,修改後通常需重新建置
runtime variable執行階段變數應用程式執行時讀取的值,需核對實際 Worker 設定
D1D1 資料庫範本透過 DB 和 ANALYTICS_DB 存取兩套資料庫
DB業務資料庫 Binding儲存帳號、付款、權限等業務資料
ANALYTICS_DB統計資料庫 Binding儲存第一方造訪統計資料
KVKV 儲存索引鍵值儲存,範本用於內容、記錄、客服案件內文等,不只是快取
R2R2 物件儲存R2 是服務名稱,Bucket 才是個別儲存貯體
bucket儲存貯體物件儲存中的容器,例如 MAIN_R2 指向的 Bucket
object key物件 Key / 物件識別碼物件在儲存貯體中的名稱,不是加密金鑰
Durable Object / DODurable Object / DO提供可持久保存的狀態與協調能力的 Cloudflare 元件,保留名稱
local environment本機環境在本機執行,資源狀態與遠端環境分別管理
local preview本機預覽打包後在本機查看,不代表已設定獨立測試 Worker
staging environment預備環境用來獨立驗證接近正式環境行為的環境,範本不會自動提供完整的一套
production environment正式環境正式對外提供服務的環境
Origin來源 / Origin由通訊協定、主機和連接埠組成的來源,不包含 URL 路徑
hostname主機名稱例如 app.example.com,不包含通訊協定和路徑
custom domain自訂網域綁定至應用程式的自有網域

資料庫、遷移與資料狀態

English / 程式碼中文名稱含義與用法
database資料庫明確說明是業務、統計、本機還是遠端資料庫
baseline / initial schema初始資料表結構 / 資料庫基準本文件中的「基準」指初始化起點,不是備份或增量遷移
initialization script初始化指令碼準備初始結構,範本的 *-init.sql 包含刪除資料表的操作
migration資料庫遷移對既有結構或資料進行版本化變更,不只是複製資料
seed data初始化資料為新環境寫入的基礎或範例資料,不代表範本提供通用 seed 指令
record / row紀錄 / 資料列業務描述常寫紀錄,SQL 語境常寫資料列
raw row原始資料列資料庫直接傳回、尚未轉換為業務型別的資料
transaction資料庫交易資料庫操作的交易邊界,與付款交易區分
primary key主索引鍵用來識別資料表中紀錄的索引鍵
foreign key外部索引鍵約束紀錄之間的參照關係
unique constraint唯一約束限制指定欄位組合不能重複
index索引資料庫索引與搜尋索引,需寫明所屬情境
backfill資料補寫為歷史紀錄補上新規則需要的值
soft delete虛刪除保留紀錄並標記為已刪除,能否還原取決於業務實作
purge徹底清除 / 實體刪除實際移除紀錄,沒有一般復原操作,還原需依靠備份等方式
revoke撤銷取消授權、角色、權益或權杖效力,不等於刪除歷史紀錄
expire / expiration過期 / 到期有效期限結束,不代表紀錄已被實際清除
retention資料保留原則 / 保留期間「保留期間」是時間,「保留原則」也包含清理範圍和執行規則
Unix timestampUnix 時間戳記說明使用秒還是毫秒,範本大多數儲存的時間使用毫秒
UTC國際標準時間(UTC)時間基準,不能直接當作訪客所在時區

身分驗證、驗證與 OAuth

English / 程式碼中文名稱含義與用法
authentication身分驗證 / 使用者驗證確認訪客身分,內文可依語境簡稱驗證
verification驗證確認某項事實或提交值,例如電子郵件地址所有權、驗證碼
authorization授權 / 權限控制OAuth 語境寫授權,業務存取判定可寫權限控制
account使用者帳號使用者身分,不等於某一次工作階段
session工作階段登入工作階段、驗證工作階段、OAuth 工作階段應依用途區分
CookieCookie瀏覽器儲存並依規則傳送的資料,不等於伺服器端工作階段本身
sign up註冊建立帳號的流程
sign in / log in登入兩種英文統一使用「登入」
sign out / log out登出不與註銷帳號混用
account deletion註銷帳號結束帳號使用並依業務規則處理資料,不是登出目前工作階段
password reset重設密碼通常用於無法使用原密碼時的恢復流程,與變更密碼區分
email verification電子郵件驗證確認電子郵件地址所有權,需區分本站驗證與第三方供應商宣告
two-factor authentication / 2FA雙重驗證(2FA)使用第二種驗證因素,不等於重複輸入密碼
TOTP以時間為基礎的一次性密碼(TOTP)驗證器依時間產生的動態碼
recovery code復原碼2FA 的備用驗證方式,與電子郵件驗證碼區分
step-up authentication敏感操作再次驗證執行特定操作前重新確認身分,不一定使用新的驗證因素
rate limit / throttling流量限制 / 請求節流限制操作頻率,不等於永久停用帳號
TurnstileCloudflare Turnstile防止自動化操作的驗證服務,不是使用者身分驗證或角色授權
OAuth 2.0OAuth 2.0授權協定,名稱保留空格
OAuth ClientOAuth 用戶端發起授權並使用權杖的應用程式,不等於登入使用者
authorization server授權伺服器處理授權並核發權杖的一方
Redirect URI回呼網址 / 重新導向 URIOAuth 返回用戶端的網址,實際值必須依協定與設定核對
authorization code授權碼授權流程中用來交換權杖的代碼,不是電子郵件驗證碼
Access Token存取權杖存取受保護資源時使用的權杖
Refresh Token重新整理權杖用來取得新的權杖,不是重新下載專案原始碼
Client Secret用戶端 Secret用戶端驗證資訊,不等於使用者密碼或應用程式主金鑰
PKCEPKCE將授權請求與權杖交換請求關聯的驗證機制,參數名稱保留原文
Scope授權範圍(Scope)OAuth 權杖的存取範圍,也常稱為作用範圍,不是使用者角色
consent授權確認 / 同意OAuth 頁面寫授權確認,Cookie 偏好設定語境則寫同意

角色、能力與權益

English / 程式碼中文名稱含義與用法
access control存取控制頁面、API 和業務操作的整體存取規則
Subject授權主體(Subject)角色與權益的授予對象,具體型別以專案定義為準
role角色一組身分或職責對應的靜態能力定義,例如 admin
capability能力角色和權益包含的基礎授權單位,不限於靜態權限
static capability靜態能力對應 CapabilityType.Static,由角色設定提供
boolean capability布林能力對應 CapabilityType.Boolean,表達功能是否可用
numeric capability數值能力對應 CapabilityType.Numeric,表達可計量的資源或額度
entitlement權益授予主體的產品使用資格或資源規則,可包含動態能力
grant授予為主體新增角色或權益,並保留來源關係
grant source授予來源說明權限來自哪次購買、訂閱或系統操作
quota額度 / 配額資源可使用的數量或限額,具體含義由業務定義
credits點數產品定義的可消耗數值資源,不自動等於貨幣餘額
entitlement cycle權益週期週期權益的處理節奏,需與付款扣款週期分別描述

例如,角色可以提供管理使用者的靜態能力,下載權益可以提供是否允許下載的布林能力,也可以包含下載次數的數值能力。角色或權益的名稱不是能力檢查結果,購買某個方案也不自動等於擁有所有付費功能。

產品、付款與商業功能

English / 程式碼中文名稱含義與用法
product產品應用程式自己的產品設定,與 Stripe Product 物件分別說明
Plan方案產品下的購買選項,不交替寫成計畫、套餐或訂閱級別
Stripe ProductStripe ProductStripe 中的產品物件
Stripe Price / Price IDStripe Price / Price IDStripe 的價格物件及識別碼,實際值如 price_...
connection ID付款連線 ID專案用來辨識付款連線的穩定識別碼,例如 STRIPE_CONNECTION_ID
billing計費描述收費方式和週期,不將整個模組一概稱為帳單
subscription訂閱週期性計費關係,不等於某一次扣款交易
one-time purchase一次性購買一次性付款,不自動表示永久權益或終身服務
CheckoutCheckout / 結帳頁面付款結帳流程或頁面
Checkout SessionCheckout 工作階段一次結帳流程的物件,不是使用者登入工作階段
payment customer付款客戶付款服務供應商端的客戶關聯,不等於應用程式使用者紀錄
transaction交易付款語境中的業務交易,與資料庫交易區分
line item明細項目交易、訂閱等物件中的一筆產品或費用明細
Billing Portal帳單入口使用者管理付款與訂閱資訊的入口
Invoice帳單 / Stripe Invoice技術說明保留物件名稱,不應預設理解為中國稅務發票
trial period試用期依方案或訂閱規則提供的試用時間
Coupon優惠券(Coupon)Stripe 中儲存折扣規則的物件
Promotion Code促銷代碼使用者可輸入,且與 Coupon 關聯的代碼
Coupon Offer動態優惠活動範本透過連結選擇優惠的功能,章節中也稱動態優惠碼
refund退款區分申請、處理中、成功與失敗,不等於自動撤銷權益
affiliate聯盟行銷推廣者透過推薦取得收益的功能
referral推薦 / 推廣來源聯盟語境寫推廣連結或推廣來源,避免與付款回呼混用
commission佣金聯盟行銷產生的收益紀錄
payout佣金付款 / 收益付款將可結算收益支付給推廣者,不是退款給購買者

顯示價格、Stripe Price、購買交易和存取權益,是四個不同概念。頁面顯示的金額不會修改 Stripe 收費,付款完成後,也不能單憑成功頁面就證明權益已授予。

API、Webhook 與錯誤處理

English / 程式碼中文名稱含義與用法
APIAPI / 介面路徑、方法和參數保留實際定義
request / response請求 / 回應HTTP 或明確呼叫邊界中的輸入和回傳
request body / payload請求本文 / 承載資料請求本文屬於 HTTP,承載資料也可能是訊息或事件資料
callback回呼泛指完成某一步後呼叫另一入口,需說明是 OAuth 還是業務回呼
WebhookWebhook / 伺服器端回呼外部服務主動向應用程式投遞事件,不是瀏覽器返回成功頁面
signature verification簽章驗證驗證來源與完整性,不等於解密內容
raw body原始請求本文未重新解析和序列化的請求內容,Webhook 簽章驗證需保留
HTTP status codeHTTP 狀態碼例如 200、401、403、500,不等於業務錯誤碼
result code / error code結果碼 / 錯誤碼供程式判斷結果,需區分專案數值碼與第三方字串錯誤碼
APIResponse<T>API 回應型別約定範本提供的型別,並非每個實際端點都傳回相同的完整結構
retryable可重試允許在對應條件下再次嘗試,不保證下次成功
non-retryable不可重試目前的失敗不應自動重試,可能需要先修正輸入或核對副作用
fallback備用值 / 備用處理說明具體使用哪個備用值或路徑,不與版本回復混用
side effect副作用 / 外部效果資料寫入、郵件寄送、付款等實際效果,可能無法隨程式碼版本回復而撤銷

背景工作、訊息與執行紀錄

English / 程式碼中文名稱含義與用法
background job背景工作在背景完成的工作,不自動等於已排入 Queue
Cloudflare Queues / Queue佇列用來投遞訊息,佇列名稱和 Binding 保留原文
producer / consumer產生者 / 取用者傳送訊息的一方,以及接收並處理訊息的一方
enqueue排入佇列將訊息放入佇列,不表示業務已完成
acknowledgement / ack訊息確認表示不再要求這次訊息投遞繼續重試,不一定代表業務成功
redelivery重新投遞佇列或服務供應商再次投遞訊息或事件
retry重試必須說明是 Command 執行重試、HTTP 重試,還是 Queue 重新投遞
replay重播再次處理歷史事件或工作,應先核對等冪性與已發生的效果
idempotency等冪性 / 等冪處理重複處理同一業務操作時,不會重複產生約定範圍內的效果
idempotency key等冪鍵在對應範圍內識別同一業務操作,例如 idempotencyKey
lease租用在一定時間內取得的處理權,用來協調並行執行
dead-letter queue / DLQ死信佇列(DLQ)接收失敗訊息的佇列,不能暗示目前範本已為所有佇列設定
ReactionReaction專案內部組織業務事件與命令執行的系統
Event業務事件 / Reaction Event描述已發生的業務事實,型別名稱如 PaymentSucceededEvent
Command業務命令 / Reaction Command事件產生的執行步驟,型別名稱如 GrantRoleCommand
Event executionEvent 執行紀錄對應 event_execution,需與外部服務供應商的 Event ID 區分
Command executionCommand 執行紀錄對應 command_execution,儲存步驟狀態與執行資訊
synchronous / sync同步在目前執行流程中直接處理
asynchronous / async非同步與目前步驟分開安排,範本的非同步 Command 由佇列處理
Cron TriggerCron 排程觸發程序決定何時觸發工作,運算式稱為 Cron 運算式
scheduled handler排程工作入口Worker 中處理排程觸發的入口

狀態必須說明所屬物件

狀態本專案中的含義
Webhook processing事件處理紀錄持有租用,還需搭配更新時間判斷實際進展
Webhook succeeded這個事件的成功處理已記錄,不保證所有後續非同步效果都已完成
Webhook failed這個事件處理失敗,需要搭配錯誤紀錄排查
Command pending尚未結束,可能等待執行或重試
Command succeeded命令成功,且結果已儲存
Command failed命令以業務失敗結束
Command errored命令以例外結束
Event completed根據所屬 Command 計算的完成狀態
Event partial_failed允許失敗後繼續執行,全部步驟結束,且有業務失敗

Event 狀態由 Command 狀態計算,event_execution 中沒有另外儲存的 status 欄位。表格並未完整列舉所有狀態,詳細說明請見領域事件與命令。

同一個詞 Event 也可能指 Stripe 事件或統計事件。說明跨系統流程時,應寫出「Stripe Event ID」、「Reaction 執行 ID」或「統計事件」,不要只使用一個「事件 ID」貫穿所有系統。

內容、統計與國際化

English / 程式碼中文名稱含義與用法
MDXMDX支援元件內容的 Markdown 檔案形式,依專案元件慣例撰寫
FrontmatterFrontmatter / 文件中繼資料檔案開頭由 --- 包住的標題、描述等資訊
content collection內容集合從文件、部落格等原始檔產生的結構化內容
search index搜尋索引供搜尋查詢使用的建置檔案,不等於內文或資料庫索引
Slug路徑識別碼(Slug)內容 URL 中的路徑識別碼,實際路徑由路由規則決定
analytics造訪統計 / 統計本專案的流量和行為統計功能
first-party analytics第一方造訪統計本應用程式自行提供的統計資料收集與報表
third-party analytics第三方統計服務例如 Google Analytics、Clarity,需與第一方設定區分
tracking event統計事件 / 事件收集前者指紀錄,後者指收集動作,不等於業務 Event
page view / PV網頁瀏覽 / 網頁瀏覽量瀏覽行為或其計數,不等於不重複訪客人數
visitor / visit / session訪客 / 造訪 / 統計工作階段依統計實作區分身分與造訪過程,不等於登入工作階段
funnel轉換漏斗依一組步驟觀察完成與轉換情況
Do Not Track / DNT不要追蹤(DNT)瀏覽器的追蹤偏好訊號,不等於 Cookie 同意紀錄
Cookie consentCookie 同意管理管理同意偏好及相關指令碼的啟用條件
internationalization / i18n國際化讓應用程式具備支援多語言的結構與機制
localization / l10n在地化為某種語言或地區翻譯內容,並調整呈現方式
locale語言識別碼 / Locale本文件常指 en、zh-Hans 等識別碼,未必包含地區
language code語言代碼具體設定值保留原文,例如 zh-Hant
translation key文案索引鍵在標準語言資源中查找文字的路徑
LocalizedText可在地化文案設定設定中的 key 和 value 物件,不是一般字串
translation fallback文案備用值缺少翻譯時使用的內容,不代表翻譯已完成
Newsletter電子郵件訂閱網站更新郵件的訂閱功能,不是付費產品訂閱

統計資料用來觀察造訪行為,不能取代付款帳本或稽核紀錄。統計工作階段數也不能直接當作登入使用者人數。

發布、恢復與維護

English / 程式碼中文名稱含義與用法
deployment部署將應用程式和相關執行設定發布至目標環境
release發布 / 版本發布範圍可能包含程式碼、設定、資料和公開說明,需寫明實際操作
upgrade / update升級 / 更新明確說明對象是 CLI、範本、相依套件,還是線上應用程式
breaking change不相容變更使原有資料、設定或呼叫方式無法直接繼續使用的變更
backward compatibility回溯相容性新實作仍能處理約定範圍內的舊輸入或狀態,不代表永遠相容
health check健康狀態檢查檢查指定入口或條件,不等於完整業務驗收
backup備份為還原保留的副本,應說明包含哪些資源
restore還原從副本或還原點重建狀態,可能影響還原點之後的寫入
recovery point還原點可用於還原的明確歷史狀態
Time TravelD1 Time TravelD1 的時間點還原機制,不等於整個應用程式的自動回復
rollback回復舊版本 / 版本回復必須說明回復的是程式碼、設定還是資料,不能一概承諾全部撤銷
roll forward向前修正透過後續變更修正目前狀態,而非還原舊版本
log / audit log記錄 / 稽核記錄前者記錄執行資訊,後者追蹤需要稽核的操作
alert警示需要關注或處理的異常通知,不等於一般業務通知
observability可觀測性透過記錄、指標和執行紀錄,了解系統狀態的能力
incident / troubleshooting故障 / 疑難排解故障是問題,排查則是蒐集證據並定位原因的過程

升級 CLI 不會自動更新已建立的專案。deploy:update 發布目前目錄的程式碼,也不會下載新版範本。回復舊版程式碼,不會自動撤銷資料庫遷移、已付款交易或已寄送的郵件,詳細說明請見升級與維護。

維護本表

只有在多篇文章會重複使用、譯法容易混淆,或誤解會影響設定與業務行為時,才需要新增術語。請保持定義簡明,詳細流程連結至對應章節,不在術語表中再複製一套教學。

修改術語時,先核對負責該概念的原始碼與既有文章。如果只是補充英文別名或釐清語境,不必機械式替換所有表述。如果變更了已使用的中文名稱,應同步檢查內文、標題和連結,避免本表與教學各用一套名稱。