中英文术语表

按主题查阅 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 发布当前目录的代码,也不会下载新版模板。代码回退不会自动撤销数据库迁移、已付款交易或已经发送的邮件,详见升级与维护。

维护本表

只有在多篇文章会重复使用、译法容易混淆,或误解会影响配置与业务行为时,才需要新增术语。保持定义简明,详细流程链接到对应章节,不在术语表中再复制一套教程。

修改术语时先核对负责该概念的源码与现有文章。若只是补充英文别名或明确上下文,不必机械替换所有表述。若改变了已经使用的中文名称,应同步检查正文、标题和链接,避免本表与教程各用一套叫法。