深入解析 Macro 的 invite_email:Askama 邀请邮件元数据、限流键与模板工程实践
深入解析 Macro 的 invite_email:Askama 邀请邮件元数据、限流键与模板工程实践
invite_email 是 Macro 中专门承载“邀请类邮件”通知元数据与 HTML 模板的 crate:它既不负责发送,也不负责决定谁被邀请,而是定义“这封邀请邮件长什么样、标题怎么写、多久能发一次”。本文以该 crate 的设计说明为主线,逐一拆解五种邀请邮件的字段契约、限流键设计、环境感知链接、团队邀请的权益承诺一致性,以及模板预览与新增邮件的完整工程流程。
一、crate 定位:只做“元数据 + 模板”,不做“发送”
按 crates/invite_email/CLAUDE.md 的界定,这个 crate 属于通知体系的一部分,职责非常收敛:
- Owns(负责):邀请 / 推荐 / 同事加入三类邮件的通知元数据与模板。
- Not here(不负责):通知的发送与排队属于
crates/notification;谁触发一次邀请属于crates/call、crates/referral、crates/model_notifications。 - Depends on(依赖):
notification(提供Notification、NotificationExtEmail等类型)、macro_env、macro_user_id、model-entity。 - Used by(被谁使用):
model_notifications、call、referral。
这种“元数据在业务 crate、投递在通知服务”的切分,在 Cargo.toml 中也有直接体现:notification 以 default-features = false 引入,说明本 crate 只需要通知的领域模型(trait、限流模型、EmailContent),不需要通知服务完整的运行时能力;依赖清单里没有 SMTP、SQS、数据库客户端之类的东西。
从源码结构看,这是一个典型的“纯数据 + 派生宏”型 crate:
| 文件 | 作用 |
|---|---|
| src/lib.rs | InviteToMacro、ReferralCode、ChannelInviteMetadata、InviteToTeamMetadata、InviteePlan 及共用 URL 构造函数 |
| src/call_invite.rs | CallInvite,一个类型一个文件 |
| src/colleague_joined.rs | ColleagueJoinedMacro,同事加入提醒 |
| templates/*.html | 实际的邮件 HTML(Askama 语法,与 Jinja2 高度兼容) |
| preview_invite.py | 用 Jinja2 渲染 invite.html 并在浏览器打开的预览脚本 |
| src/test.rs | 全部单元测试(34 个 #[test]) |
模块顶部还有 #![deny(missing_docs)],配合每个字段上的文档注释,等于用编译器强制保证“字段语义必须写清楚”——这也是本 crate 能被当作契约阅读的原因。
二、统一的抽象:Notification 三元组
所有邀请类型都实现同一套 trait 组合。核心定义在 crates/notification/src/domain/models.rs:
pub trait Notification: Serialize + DeserializeOwned + Send + Sync + 'static {
const TYPE_NAME: &'static str;
}
pub trait NotificationExtEmail: Notification {
fn format_email(&self) -> EmailContent;
fn rate_limit_config() -> RateLimitConfig;
fn rate_limit_key(&self) -> RateLimitKey;
}
invite_email 里每个类型都遵循这个三段式:
- 用
const TYPE_NAME声明通知类型名(如"invite_to_team"),它同时进入序列化标签与限流键的首段; - 用
format_email()返回EmailContent { subject, body },其中body来自self.render()(AskamaTemplate派生); - 用
rate_limit_config()+rate_limit_key()声明“同一个桶里多久只能发一封”。
EmailContent 的定义在 crates/notification/src/domain/models/queue_message.rs,只有 subject 与 body 两个字符串,没有收件人字段——收件人由上层 SendNotificationRequestBuilder 的 recipient_ids 决定。这意味着同一份元数据可以被复制成多封邮件发往不同收件人,正如频道邀请所做的事。
三、五种邮件类型逐个拆解
3.1 InviteToMacro:推荐注册邀请
定义与实现见 src/lib.rs#L42-L130:
#[derive(Debug, Serialize, Deserialize, Clone, Template)]
#[template(path = "invite.html")]
pub struct InviteToMacro {
pub recipient_email: EmailStr<'static>,
pub referral_code: ReferralCode,
pub sender_profile_picture_url: Option<Url>,
pub sender_name: Option<String>,
#[serde(default)]
pub sender_email: Option<String>,
}
字段契约要点:
recipient_email用EmailStr<'static>而非裸String,构造即校验;它同时进入限流键,保证“同一收件人”维度的去重。referral_code是#<a href="https://link.gitcode.com/i/5cb035983bfea3cb0af7fabfff3f4aa9" target="_blank">serde(transparent)]的 newtype([#L37-L40),序列化后就是字符串,避免在 JSON 里多套一层对象。sender_profile_picture_url是Option<Url>,模板里用{% if let Some(url) = ... %}决定是否渲染头像块。仓库中referral侧的构造点会先把字符串url::Url::parse一次再传入(crates/referral/src/domain/service.rs),解析失败就退化为None,即“没有头像”。sender_email带#<a href="https://link.gitcode.com/i/77b28af942ce1c110bab2ecc899d04b3" target="_blank">serde(default)],这正是文档 Gotchas 里强调的向后兼容手段:字段后加,旧队列负载反序列化不会失败。测试 [deserialization_without_sender_email_uses_none 就覆盖了这条。
format_email() 的兜底逻辑是一个三级降级链,任何一级可用就停止:
sender_name → sender_email → "A Macro user"
于是标题会出现 Test User has invited you to join Macro、sender@example.com has invited you to join Macro、A Macro user has invited you to join Macro 三种形态,测试 src/test.rs#L346-L382 逐一断言。模板正文里则进一步拼成 Name <email> 的形式(templates/invite.html#L163-L168)。
3.2 ChannelInviteMetadata:“频道邀请”与“DM 消息通知”共用一套元数据
这是本 crate 中最复杂的一类,因为它同时承担两种语义:频道邀请与私信消息通知。字段定义见 src/lib.rs#L132-L162。
关键设计点有三个:
(1)序列化的双写兼容。 结构体标注了 #<a href="https://link.gitcode.com/i/4190a3b4ba0aed66dd4b692592e6a99b" target="_blank">serde(rename_all = "camelCase")],于是线上格式是 invitedBy、channelName;同时每个字段又挂了 #[serde(alias = "invited_by")]、#[serde(alias = "channel_name")],让历史 snake_case 负载仍可解析。测试 [legacy_channel_invites_default_to_channel_wording 用两种 JSON 形状验证同一结果。
(2)is_direct_message 决定文案骨架。 该字段带 #[serde(default)],所以旧负载默认 false,仍然渲染“频道邀请”措辞——注释里明确写了这一点。文案分叉集中在 format_title() 与 format_email():
| 场景 | 邮件标题 | 推送标题 | 按钮 |
|---|---|---|---|
| 频道邀请 | {sender} has invited you to join #{channel} |
{sender} invited you to join #{channel} |
Join channel |
| 私信消息 | {sender} sent you a message on Macro |
{sender} sent you a message |
View message |
对应实现在 #L178-L216 与 templates/invite_to_channel.html#L171-L253。
(3)两个 #[serde(skip)] 字段只服务限流。 message_id 与 email_recipient 不参与序列化,只在构造限流键时使用:
if self.is_direct_message && let Some(message_id) = self.message_id {
return RateLimitKey::builder(&Self::TYPE_NAME)
.append(&message_id)
.append(&self.email_recipient)
.finish();
}
这就是文档“Recipes”里那句浓缩的规则:DM 邮件把稳定的 message ID 放进限流键,因此重试会被抑制,但后续消息不会被丢弃;普通频道邀请仍保留 sender/channel 维度。测试 dm_emails_deduplicate_retries_without_suppressing_later_messages 用“同一个 message_id 两次 → 键相同”“换 message_id → 键不同”“换 email_recipient → 键不同”“频道邀请换 message_id → 键仍相同”四组断言把这个语义钉死。
调用侧可以印证这个设计意图:crates/channels/src/outbound/notification_sender.rs 先对已注册用户走 APNS + conn gateway,再对未注册收件人逐个复制元数据、设置 email_recipient,然后 .with_email() 单独投递;不变量是“每个收件人一个独立的重试键”。
此外该类还实现了 NotificationExtIos,用 sender_profile_picture_url 是否存在来决定 mutable_content(#L249-L279),并为推送构造 NotifCollapseKey,让同一实体的多条推送可折叠。
3.3 InviteToTeamMetadata 与 InviteePlan:承诺必须等于实际授予
团队邀请的字段见 src/lib.rs#L282-L315:
pub struct InviteToTeamMetadata {
pub team_name: String,
pub team_id: Uuid,
pub team_invite_id: Uuid,
pub invited_by: MacroUserIdStr<'static>,
pub role: Option<String>,
pub sender_profile_picture_url: Option<Url>,
#[serde(default, alias = "invitee_plan")]
pub invitee_plan: InviteePlan,
#[serde(default)]
pub reminder: bool,
}
InviteePlan 是一个两态枚举,默认 Free:
Free:Macro 的免费计划。注释明确说明“计划被记录之前发出的邀请按 Free 读取,而这一读取始终为真:加入团队永远不会让被邀请人付钱”。Premium:由付费、试用或企业团队承担的 Pro 席位。
这份枚举不是营销文案开关,而是一条业务不变量。文档 Gotchas 写得很直白:发送方 teams 的 invite_users_to_team 必须按 join_team 授予权益的方式来推导它——“Pro 只来自企业团队或带订阅的团队”,邮件文案的承诺绝不能超过实际加入时授予的东西。
源码完全对得上 crates/teams/src/domain/team_service.rs#L1495-L1534:先取企业状态,企业即 Premium;否则读支付状态与订阅 ID,(true, Some(_)) → Premium、(true, None) → Free、(false, Some(_)) → 返回 TeamNotPaying、(false, None) → 尝试回填历史订阅,成功才 Premium。这个推导结果还会被 tracing::Span::current().record("invitee_plan", ...) 记录,便于线上核查“邮件说了什么”。
模板侧用 Askama 的 {% match %} 直接分叉(templates/invite_to_team.html#L205-L252):
Premium→ “Pro is included /{team}covers your seat, so you get every AI model and agent at no cost to you.”Free→ “Free to join / There's nothing to pay. Accept the invite to start working with{team}in Macro.”
测试 team_invite_promises_pro_only_when_the_team_covers_the_seat 双向断言:Premium 正文必须包含“Pro is included”且不得出现“Free to join”;Free 正文必须包含“Free to join”且不得出现“covers your seat”。这就是把文案一致性变成了可回归的测试。
其他细节同样值得注意:
invite_url()生成/app/team-invite?id={team_invite_id}(#L332-L343)。模板里这个 URL 被用三次:按钮href、兜底链接href、兜底链接可见文本,测试 team_invite_links_the_button_and_a_pasteable_fallback 断言body.matches(&url).count() == 3——保证“邮件客户端屏蔽按钮”时用户仍能复制链接。join_label()用MAX_BUTTON_TEAM_NAME_CHARS = 24(#L329-L356)控制按钮文字:短队名渲染Join {team},超长则退化为Join team,避免按钮被撑破。注意它按chars().count()计,不是字节数,所以中文队名不会被误判。role为Some时模板追加一行“Your role will be {role}”,为None时整段不渲染。
3.4 CallInvite:免注册的会议邀请
CallInvite 是唯一一个“收件人不需要 Macro 账号”的邀请,定义见 src/call_invite.rs:
pub struct CallInvite {
pub title: String,
pub share_token: String,
pub invited_by: MacroUserIdStr<'static>,
pub recipient_email: String,
}
- 链接形如
/app/meet/join/{share_token},share_token被注释为“已校验、由服务端签发的会议凭证”。 - 模板极简(templates/invite_to_call.html),但包含两句必要声明:“No Macro account needed. Enter your name to join.” 与录音/转写告知。
- 测试 call_invitation_links_directly_to_guest_join_and_escapes_titles 同时验证:正文出现
/app/meet/join/...、出现“No Macro account needed”、不出现/signup(说明这是访客通道而不是注册漏斗)、标题里的<script>被转义、主题包含邀请人邮箱。 - 调用侧的权限约束在 crates/call/src/domain/service/meetings.rs#L60-L75:只有会议 owner 能发;且
meeting.channel_id.is_some()时直接拒绝,理由是“Channel calls cannot be shared with people outside Macro”——免注册链接不会成为绕过成员边界的通道。
3.5 ColleagueJoinedMacro:把“不可信名字”渲染成一行的示范
定义见 src/colleague_joined.rs,字段 team_name、joined_by、joined_name: Option<String>、recipient_email。其中 joined_name 被明确标注为“来自不可信来源,只显示一行、长度截断、并转义”。
实现用一个 display_name() 做规范化(#L20-L35):
let words: Vec<&str> = self.joined_name.as_deref()?
.split(|c: char| c.is_whitespace() || c.is_control())
.filter(|word| !word.is_empty())
.collect();
// 用空格重连 → 取前 DISPLAY_NAME_MAX_CHARS(64) 个 char → trim_end
这处理了三类风险:换行/制表符导致的头部注入类排版问题(按空白与控制字符切分后重连)、超长名字撑爆版式(64 字符上限)、纯空白名字导致的空显示((!name.is_empty()).then(...) 返回 None,回退到邮箱)。
对应测试覆盖非常细:
- 无名字或名字全是空白/控制字符 → 主题回退为
alice@acme.com joined Macro(#L52-L64); " Alice\r\nExample\t\u{0}{100 个 x}"→ 主题变成Alice Example {50 个 x} joined Macro(#L66-L77);- 名字为
<b>x</b>→ 主题保留原文(纯文本),正文里被转义为<b>x</b>(#L79-L93)。
最后一条值得单独强调:主题与正文的转义边界不同。邮件主题是纯文本,不需要 HTML 转义;正文由 Askama 按 .html 后缀做 HTML 自动转义。频道邀请的用户内容(channel_name、message_content)同理,测试 invite_email_escapes_message_content_and_channel_names 对 DM/频道两种模式都断言 <script> 不会原样出现。
四、限流:键的构成就是业务语义
限流模型来自 rate_limit crate,notification 只是 re-export(crates/notification/src/domain/models/rate_limit.rs)。实现细节在 crates/rate_limit/src/domain/models.rs:RateLimitKey 本质是 XxHash64 的 8 字节哈希,builder(seed).append(x).finish() 逐段喂入 Hash 实现——顺序敏感、内容敏感,所以“先 append sender 再 append channel”和反过来的键不同。
投递时的判定在 crates/notification/src/domain/service/egress.rs#L320-L372:先 check_rate_limit(key, config),超限直接返回 DeliveryFailure::RateLimit;发送失败则 rollback_ticket,把配额还回去,避免“发失败也算一次”。这一点对邀请邮件尤其重要:SMTP 抖动不该消耗掉用户一周一次的推荐邀请额度。
本 crate 四类邮件的限流配置汇总如下(均可从源码逐条核对):
| 类型 | max_count |
window |
键组成 | 设计意图 |
|---|---|---|---|---|
InviteToMacro |
1 | 1 周(60*24*7 分钟,见 MINUTES_PER_WEEK) |
类型名 + recipient_email |
同一收件人每周最多被推荐邀请一次 |
ChannelInviteMetadata(频道) |
1 | 7 天(24*7 小时) |
类型名 + invited_by + channel_name |
同一人对同一频道不重复骚扰 |
ChannelInviteMetadata(DM) |
1 | 同上 | 类型名 + message_id + email_recipient |
单条消息的重试去重,但新消息仍可触达 |
InviteToTeamMetadata |
1 | 1 小时 | 类型名 + team_id + team_invite_id |
一个邀请一个桶:批量邀请多人时每人各得一封 |
CallInvite |
1 | 1 分钟 | 类型名 + share_token + recipient_email |
允许快速重发,但仍防抖 |
ColleagueJoinedMacro |
1 | 1 年(24*365 小时) |
类型名 + joined_by + recipient_email |
一场加入事件对同一收件人只播报一次 |
团队邀请的键选择有一个容易被忽略的收益,文档和源码注释都点明了:因为键是 (team_id, team_invite_id) 而不是 (sender, team),一次邀请十个同事会发出十封邮件;而“重发”复用同一个 team_invite_id,所以天然与首次发送共享配额。
五、提醒邮件:与 1 小时窗口强耦合的调度
InviteToTeamMetadata.reminder 只做一件事——在主题前加 "Reminder: "(#L364-L376)。测试 team_invite_reminder_says_so_in_the_subject 对照了加与不加两种主题。
但它带来一个跨 crate 的约束链:
- 提醒与首次邀请共用同一个限流桶(同一个
team_invite_id),窗口 1 小时; - 因此两次提醒必须间隔 超过 1 小时,否则后一封会被限流直接丢弃;
- 手动“重发”也必须等过同一窗口。
这条约束在三个地方各有一份“同一事实的镜像”,这是本 crate 最值得学习的工程实践之一:
- 服务端判定:crates/teams/src/domain/team_service.rs#L66-L72 的
invite_resend_interval()直接读取InviteToTeamMetadata::rate_limit_config().window,而不是写死常量——单一事实来源就在本 crate。 - SQL 侧过滤:crates/teams/src/outbound/team_repo.rs#L447-L460 用
make_interval(secs => $3)传入同一函数的值,只重发last_sent_at早于该窗口的邀请,避免“键被丢弃但last_sent_at已前移”的错位。 - 前端按钮:apps/web/src/features/settings/teamInviteResend.ts 用
INVITE_RESEND_INTERVAL_MINUTES = 60复刻,注释写明“Mirrorsinvite_resend_intervalin the teams crate”。
提醒的实际节奏由 sweeper 决定:模块注释写明“每个邀请最多两封提醒,最后一封邮件后 3 天一次、再 4 天一次”,SQL 里对应 reminders_sent = 0 AND last_sent_at <= NOW() - INTERVAL '3 days'(crates/teams/src/outbound/team_repo.rs#L555-L575)。两封提醒各自用 reminder_number 派生确定的通知 ID(Uuid::new_v5),所以同一封提醒重复投递只会产生一条通知。
另一个细节:提醒路径的 invitee_plan 采用更保守的推导(crates/teams/src/domain/team_service/invite_reminders.rs#L60-L72),只认 enterprise || (paying && has_subscription),不做订阅回填——后台 sweep 不应该触发副作用,“读成 free”永远不会承诺得比实际更多。
六、模板工程:Askama 写、Jinja2 预览、邮件客户端兼容
6.1 模板结构与兼容性处理
五个模板共用同一套“邮件安全 HTML”骨架,可在 templates/invite.html 中看到全部要素:
role="presentation"的布局表格 +cellpadding/cellspacing="0",避免 Outlook 表格渲染差异;<!--[if mso]>条件注释包裹固定宽度 560 的表格与PixelsPerInch设置,处理 Windows Outlook;<meta name="x-apple-disable-message-reformatting">、format-detection关闭电话/日期自动识别;<meta name="color-scheme" content="light">锁定浅色方案;- 隐藏的 preheader
<div>(display:none; max-height:0; mso-hide:all)用于列表页摘要; @media screen and (max-width: 600px)内联样式覆写padding、font-size,invite_to_team.html还额外把按钮display:block; width:100%;- 所有关键元素用内联 style(邮件客户端普遍不支持
<style>选择器)。
一个容易被忽视的一致性守护:四封邀请邮件的 logo 图片都带固定 width="54" height="36",测试 invitation_logos_keep_the_png_aspect_ratio 会对 InviteToMacro、ChannelInviteMetadata、InviteToTeamMetadata、ColleagueJoinedMacro 四封渲染结果做空白归一化后逐一断言这串属性存在。这类“渲染产物断言”比肉眼检查可靠得多。
6.2 预览脚本如何把 Askama 喂给 Jinja2
preview_invite.py 的思路是“轻量语法转换 + Jinja2 渲染 + 临时文件 + 浏览器打开”:
def askama_to_jinja2(src: str) -> str:
# {{ referral_url() }} → 直接替换为假 URL
src = re.sub(r"\{\{\s*referral_url\(\)\s*\}\}", DUMMY_REFERRAL_URL, src)
# {% if let Some(var) = expr %} → {% if expr %}{% set var = expr %}
src = re.sub(
r"\{%-?\s*if let Some\((\w+)\)\s*=\s*(\w+)\s*-?%\}",
r"{% if \2 %}{% set \1 = \2 %}",
src,
)
return src
转换只覆盖两件事:方法调用 referral_url()(Jinja2 无法调用 Rust 的 self 方法)与 if let Some(...) 绑定(Jinja2 没有 if-let,用 {% if %} + {% set %} 等价实现)。其余语法({{ }}、{% if %}、{% endif %})两边通用。
使用方式与注意事项:
pip3 install jinja2
python3 crates/invite_email/preview_invite.py
脚本会把渲染结果写入 tempfile(delete=False)并 webbrowser.open("file://..."),同时打印路径。三个实操要点:
- 改模板路径:
TEMPLATE_PATH硬编码为templates/invite.html,预览其他模板需先改这一行; - 改假数据:
tmpl.render(...)的sender_profile_picture_url/sender_name/sender_email就是文档所说的 dummy data,把前两者置为None即可验证“邮件地址回退”路径(脚本内注释亦如此提示); - 预览不做转义:
Environment(autoescape=False)是有意为之(否则 RHS 的None与Some判断会更麻烦),代价是预览看不出转义问题。转义正确性必须靠cargo test -p invite_email里的断言兜底,而不是靠浏览器观感。
对于新增的其他模板(如 invite_to_team.html),除了改路径,还需补上脚本无法自动转换的表达式:{{ inviter() }}、{{ invite_url() }}、{{ join_label() }}、{{ match invitee_plan }}...{% endmatch %}。这是“预览脚本覆盖范围有限”的真实边界,文档用“edit its dummy data / template path first”一句带过,实际动手时正好会撞上。
6.3 与 packages/email-renderer 的区别
文档 Related 提到:如果要在独立渲染器里渲染,而不是走这里的邮件模板管线,去看 packages/email-renderer/README.md。后者处理的是用户来信正文的确定性 HTML/CSS 准备、引用折叠、主题色适配、Shadow DOM 挂载等前端渲染职责,与本 crate 的“服务端 Askama 生成整封邀请邮件”是两条完全不同的路径,不要混用。
七、新增一种邀请邮件:完整配方
文档 Recipes 给出的三步是主干,结合源码可以展开成可执行的检查清单。
第 1 步:新建元数据类型。 在 src/<name>.rs 里定义结构体并派生:
#[derive(Debug, Clone, Serialize, Deserialize, Template)]
#[template(path = "<name>.html")]
pub struct MyInvite {
pub invited_by: MacroUserIdStr<'static>,
pub recipient_email: String,
}
CallInvite 与 ColleagueJoinedMacro 就是照此写的,且都用 use super::*; 复用 lib.rs 中的 frontend_host、signup_url 等私有构造函数——所以新文件必须 mod 到 lib.rs 里(或像这两个文件一样被 mod + pub use)。
第 2 步:实现三个 trait 方法。
impl Notification for MyInvite {
const TYPE_NAME: &'static str = "my_invite";
}
impl NotificationExtEmail for MyInvite {
fn format_email(&self) -> EmailContent { /* subject + self.render() */ }
fn rate_limit_config() -> RateLimitConfig { /* max_count + window */ }
fn rate_limit_key(&self) -> RateLimitKey { /* 业务语义 */ }
}
注意 TYPE_NAME 必须是全局唯一的字符串:它既作为序列化标签,也是限流键首段。
第 3 步:写模板 templates/<name>.html。 最省事的做法是复制 templates/invite.html 改文案——骨架(MSO 条件注释、preheader、响应式媒体查询、logo 尺寸)已经被测试守护,不要重写。
第 4 步:在 lib.rs 中导出。 与其他类型保持一致:
mod my_invite;
pub use my_invite::MyInvite;
若该类型需要出现在推送/摘要/前端契约里,还要同步下游(这是文档 Boundaries 与 Gotchas 共同指向的“扩散面”):
- 在 crates/model_notifications/src/metadata.rs 的
pub use invite_email::{...}中 re-export; - 若属于“不应进入摘要邮件”的类型,加到 crates/model_notifications/src/digest_state.rs 的
digest_email_block_list()(现有的InviteToMacro、CallInvite、ColleagueJoinedMacro、InviteToTeamMetadata都在其中); - 若需要出现在通知服务的 OpenAPI 里,请派生
utoipa::ToSchema(当前只有ChannelInviteMetadata、InviteToTeamMetadata、InviteePlan派生了它)。
第 5 步:处理 serde 演进。 文档把这条列为 Gotcha,值得原样重申:元数据是排队并以 JSON 存储的,所以
- 新字段一律加
#[serde(default)],否则部署前入队的负载会反序列化失败; - 需要与旧命名兼容时加
#[serde(alias = "...")](频道/团队两类邮件就是这么做的); - 线上字段形状要稳定,测试里用
serde_json::json!({...})固化 wire shape 是有效手段(参见 colleague_joined_serde_round_trip_keeps_the_wire_shape 与 team_invite_plan_keeps_its_wire_shape); - 若该类型暴露给前端,需要重新生成客户端:在
apps/web下执行bun run gen-api notification-service。
第 6 步:加测试。 现有 34 个测试基本给出了模板:主题降级链、限流键区分度、HTML 转义、历史 payload 兼容、按钮兜底链接次数。照抄最接近的那个再改断言即可。
八、验证与排错速查
# 单元测试:34 个用例,覆盖渲染、转义、限流键、serde 兼容
cargo test -p invite_email
# 模板视觉预览(需 jinja2)
pip3 install jinja2 && python3 crates/invite_email/preview_invite.py
常见现象与根因对照:
| 现象 | 可能根因 | 定位点 |
|---|---|---|
本地邮件里的链接指向 macro.com 而不是 localhost |
环境变量未设置,Environment::new_or_prod() 回退到 Production |
crates/macro_env/src/lib.rs#L51-L53、src/lib.rs#L73-L85 |
| 本地链接端口不是期望值 | FRONTEND_PORT 未设,默认 3000 |
同上 |
| 重发邀请失败/静默丢失 | 1 小时窗口未过,或 last_sent_at 已被前移 |
invite_resend_interval() 与 SQL 过滤 |
| 批量邀请只到了一封 | 限流键误用 (sender, team) 而非 (team_id, team_invite_id) |
src/lib.rs#L387-L394 |
| 同一 DM 反复发多封 | 键里缺少稳定 message_id |
src/lib.rs#L225-L238 |
| 部署后旧通知反序列化失败 | 新字段漏加 #[serde(default)] |
各结构体字段属性 |
| 邮件承诺 Pro 但用户加入后没有 | InviteePlan 派生与 join_team 不一致 |
crates/teams/src/domain/team_service.rs#L1495-L1534 |
九、小结
invite_email 的价值不在于“五个 HTML 文件”,而在于它把邀请邮件的三件难事都变成了可编译、可测试的代码:
- 契约——
Notification/NotificationExtEmail把“标题怎么降级、键怎么算、多久发一次”固化为类型系统的一部分; - 一致性——
InviteePlan让邮件文案与团队实际授予权益同源,invite_resend_interval()让后端判定、SQL 过滤、前端按钮共享同一个窗口数值; - 安全——不可信名字按空白/控制字符规范化并截断到 64 字符,用户内容统一走 Askama 自动转义,并用断言把转义结果写进回归测试。
当你需要新增一封邀请邮件时,真正的成本不在写模板,而在想清楚三件事:限流键代表哪个业务维度、文案是否超额承诺、新字段如何与已排队的 JSON 负载共存。这三点想清楚了,剩下的就是照着 crates/invite_email/src/test.rs 的既有模式补齐断言。