Macro GTM 邀请链接模块 gtm_invite 架构解析与实战指南
Macro GTM 邀请链接模块 gtm_invite 架构解析与实战指南
gtm_invite 是 Macro 仓库中承载增长(GTM)能力的 Rust crate:Macro 员工为潜在客户生成个性化、有时效的注册链接,对方通过链接注册后,账号归因到创建链接的员工,并在结账时自动获得首月 Premium 促销。本文以该 crate 的模块说明为骨架,结合 crates/gtm_invite 的源码、数据库迁移文件与 authentication_service 的集成点,完整拆解其六边形架构、领域不变量、HTTP 契约、并发正确性设计以及配置与扩展方式。
模块定位:它拥有什么,不拥有什么
按照 crates/gtm_invite/AGENTS.md 的界定,这个 crate 的职责边界非常清晰:
- Owns(负责):GTM 邀请链接的创建(create)、兑换(redeem)、撤销(revoke),以及面向员工看板(staff dashboard)的 API。
- Not here(不负责):checkout 对促销抵扣的具体应用、以及账号创建本身。
这意味着一件事:gtm_invite 只负责"链接从生成到归因到转化"这条状态链路,它把"钱"和"账号"两件事留给上游。真正的结账逻辑在 services/authentication_service/src/outbound/subscription_checkout.rs 中,它只向本 crate 询问"这个用户手上还有没有可用的促销",其余交给 Stripe。
依赖关系上,该 crate 依赖 macro_authorization(axum 鉴权)与 rate_limit(axum 限流);它被 services/authentication_service 使用——后者在 src/api.rs 中以 /gtm-invite 前缀挂载路由,并在 src/api/swagger.rs 中登记全部 6 个 handler 以生成 OpenAPI 文档。
六边形架构:分层与目录映射
lib.rs 的文档注释直接给出了分层声明(见 crates/gtm_invite/src/lib.rs):domain 放模型、端口(trait)与服务实现;outbound 放外部依赖适配器(PostgreSQL);inbound 放入站请求适配器(Axum handler)。这与仓库的 cloud-storage-hexagonal-architecture 规范一致。
目录与职责对应如下:
| 路径 | 职责 |
|---|---|
| src/domain/service.rs | 创建/兑换/撤销/列表的链接生命周期编排 |
| src/domain/ports.rs | GtmInviteRepo 仓储端口与 GtmInviteService 服务端口 |
| src/domain/models.rs | 链接模型、值对象、错误枚举、状态机 |
| src/inbound/axum_router.rs | 路由装配、状态结构、错误到 HTTP 的映射 |
| src/inbound/axum_router/ | 每个路由一个文件:create_link、get_offer、redeem_link、resolve_link、revoke_link、list_links |
| src/inbound/axum_router/gtm_macro_staff.rs | 仅放行 Macro 员工的提取器 |
| src/outbound/pg_gtm_invite_repo.rs | Postgres 适配器,SQL 直接写在此处 |
Cargo 特性(feature)把这套分层做成了可选编译单元,见 crates/gtm_invite/Cargo.toml:
[features]
axum = ["dep:axum", "dep:axum-extra", "dep:ip_extractor", "dep:macro_authorization",
"dep:model-error-response", "dep:tower", "dep:utoipa"]
default = ["axum", "inbound", "outbound", "ports"]
inbound = ["axum", "ports"]
outbound = ["dep:sqlx", "ports"]
ports = []
ports 是空特性,只用来开关 trait 定义;inbound 需要 axum;outbound 才引入 sqlx。好处是:如果某个服务只需要领域模型(例如上游只想读 GtmInviteConfig 与 PromoCode),可以关掉默认特性、不把 Axum 与 SQLx 拖进依赖树。lib.rs 中对应的条件编译也是这么写的(#[cfg(feature = "inbound")]、#[cfg(feature = "outbound")])。
领域模型:值对象与不变量
邀请令牌 InviteToken
令牌是链接里唯一的秘密。长度常量为 INVITE_TOKEN_LENGTH = 32,生成时使用 rand 的字母数字分布(见 models.rs 与 InviteToken::generate):
pub const INVITE_TOKEN_LENGTH: usize = 32;
const MIN_INVITE_TOKEN_LENGTH: usize = 16;
const MAX_INVITE_TOKEN_LENGTH: usize = 64;
pub fn generate() -> Self {
let token: String = rand::rng()
.sample_iter(Alphanumeric)
.take(INVITE_TOKEN_LENGTH)
.map(char::from)
.collect();
Self(token)
}
解析(FromStr)时做两道校验:长度必须落在 16~64 之间,字符必须是 ASCII 字母数字或 -、_。任何不满足的都返回 GtmInviteError::InvalidToken,最终映射为 400。这就是为什么 /public/short 这种明显不是生成出来的令牌会被直接拒绝——路由层甚至不会去查库,服务层测试 tokens_must_look_generated 与路由层测试 resolving_a_malformed_token_is_a_bad_request 分别覆盖了这两层。
促销码 PromoCode
PromoCode 对应 Stripe 的推广码(默认 1MF,即首月 100% 折扣)。解析规则:先 trim,长度 1~64,字符集与令牌相同,失败返回 InvalidPromoCode,错误文案是固定的"promo code must be 1-64 characters of letters, digits, '-' or '_'"。注意它是一个独立的值对象而不是裸 String,因此"非法促销码"不可能出现在 InviteLink 里。
链接聚合与状态机
InviteLink 是聚合根,字段覆盖归因、时效、埋点和转化四类信息:id(UUID v7)、token、first_name、recipient_email、note、promo_code、created_by、created_at、expires_at、revoked_at、open_count、first_opened_at、redemption。
状态不是存储字段,而是读时派生的(InviteLinkStatus:Active / Expired / Revoked / Redeemed / Converted)。派生逻辑在 InviteLink::status(&self, now) 中,顺序至关重要:
pub fn status(&self, now: DateTime<Utc>) -> InviteLinkStatus {
match &self.redemption {
Some(redemption) if redemption.conversion.is_some() => InviteLinkStatus::Converted,
Some(_) => InviteLinkStatus::Redeemed,
None if self.revoked_at.is_some() => InviteLinkStatus::Revoked,
None if now >= self.expires_at => InviteLinkStatus::Expired,
None => InviteLinkStatus::Active,
}
}
源码注释说明了设计意图:兑换优先于过期与撤销——已经注册的人即使窗口关闭,归因关系依然保留。反过来,未兑换的链接先看是否被撤销,再看是否过期。这条"优先级"被单测 status_prefers_redemption_over_expiry_and_revocation 明确固化,是不变量而非实现细节。
GtmInviteConfig 则是"每条链接携带的同一份 offer"的静态配置,三个字段分别是 promo_code、link_ttl、free_months。
服务层:七个用例的完整语义
GtmInviteServiceImpl<R> 由仓储 repo 与 config 组合而成(service.rs),实现 GtmInviteService 端口。所有方法都带 #[tracing::instrument],并把关键字段(creator、caller、user、link_id)打进 span,便于在分布式追踪里定位。
create_link:员工校验 + 输入归一化 + 铸码
require_staff(creator)?;
let request = normalize_create_request(request)?;
let now = Utc::now();
let link = InviteLink {
id: macro_uuid::generate_uuid_v7(),
token: InviteToken::generate(),
...
promo_code: self.config.promo_code.clone(),
created_by: creator.clone().into_owned(),
created_at: now,
expires_at: now + self.config.link_ttl,
revoked_at: None,
open_count: 0,
first_opened_at: None,
redemption: None,
};
self.repo.insert_link(&link).await.map_err(internal)?;
require_staff 判断的是 MacroUserIdStr::is_macro_staff(),其实现对邮箱域名做大小写无关比较,等于 macro.com(见 crates/macro_user_id/src/user_id.rs),并注明 name+tag@macro.com 这类 plus 别名同样命中。因此"是不是员工"是纯域名规则,不依赖数据库中的权限表。
normalize_create_request 是纯函数,规则可枚举:
| 字段 | 规则 | 违反时 |
|---|---|---|
first_name |
非空、char 计数 ≤ MAX_FIRST_NAME_LENGTH(80) |
400 BadRequest |
recipient_email |
空串视作 None;否则小写化并用 Email::parse_from_str 校验 |
400 "recipient email is not a valid email address" |
note |
空串视作 None;char 计数 ≤ MAX_NOTE_LENGTH(500) |
400 |
注意长度用 chars().count() 而不是字节长度,避免中文姓名被误判超限;邮箱统一小写化,使后续按邮箱归因与 Stripe webhook 的匹配保持一致。
list_links:员工看板
list_links(caller, only_mine) 先做员工校验,再构造 ListInviteLinks { created_by, limit }。only_mine 为真时把调用者自身作为过滤条件,否则为 None(全公司可见)。单次返回条数被硬编码为 DASHBOARD_LIST_LIMIT = 500:
const DASHBOARD_LIST_LIMIT: i64 = 500;
let filter = ListInviteLinks {
created_by: only_mine.then(|| caller.clone().into_owned()),
limit: DASHBOARD_LIST_LIMIT,
};
也就是说这个接口没有分页参数,靠上限兜底;如果将来链接量级超过该值,需要在端口层引入游标,而不是简单放大常量。
revoke_link:只撤销"还没人能用的"链接
撤销是唯一带竞态语义的管理操作,代码里的注释写得很直接:更新以"行仍未兑换"为条件,因此并发的注册会赢,并保住它的归因。
if link.redemption.is_some() {
return Err(already_used());
}
if link.revoked_at.is_none() {
let revoked = self.repo.revoke_link(id, Utc::now()).await.map_err(internal)?;
if !revoked {
return Err(already_used());
}
}
先读后写只是"快速失败",真正的正确性在 SQL 的 WHERE ... AND revoked_at IS NULL AND redeemed_by_user_id IS NULL 上。已撤销的链接重复撤销不报错(幂等),因为它们本来就不能用;只有"有人已注册"才返回 400,文案是"a link someone already signed up through cannot be revoked"。撤销成功后重新读取并返回,保证响应里的 revoked_at 是最新值。
resolve_link:公开欢迎页 + 埋点不阻塞
这是唯一无鉴权的用例。它按令牌查库,然后记录一次打开:
// Tracking only — never fail the welcome page over it.
let _ = self.repo
.record_open(link.id, Utc::now())
.await
.inspect_err(|e| tracing::warn!(error=?e, "failed to record invite link open"));
这里刻意吞掉错误并降级为 warn! 日志:埋点失败不应该让潜在客户看到错误页。单测 resolve_link_survives_a_failed_open_count 就是守护这条契约的。另外注意 resolve_link 不检查链接是否过期——它把状态原样交给上层,由前端根据 status 展示"已失效"的欢迎页,而不是返回 404/410。
redeem_link:幂等、单链接、原子
兑换是逻辑密度最高的方法,按顺序做四次判断:
- 同一用户重复兑换:
if link.is_redeemed_by(user) { return Ok(link); }—— 完全幂等,直接返回原链接。 - 用户已有别的兑换链接:查询
get_redeemed_link_for_user,若命中则打一条info!并返回原来那条。注释写明"A user holds one offer: whichever link they redeemed first stays",这对应数据库上redeemed_by_user_id的部分唯一索引。 - 状态机校验:
Active放行;Expired→ 410;Revoked→ 410;Redeemed | Converted→ 409。 - 原子写入:调用
repo.redeem_link(id, user, now),返回None意味着"并发注册、撤销或到期抢先了",统一映射为AlreadyRedeemed(409)。
self.repo
.redeem_link(link.id, user, now)
.await
.map_err(internal)?
.ok_or(GtmInviteError::AlreadyRedeemed)
第 3 步的检查与第 4 步的写库看似重复,其实是"读时给用户友好错误、写时保证竞态安全"的双层设计:前者避免无意义的写,后者才是真相。
active_offer_for_user 与 mark_converted:与计费系统的两个接口
active_offer_for_user 返回用户已兑换、但尚未转化的链接:
Ok(link.filter(|link| {
link.redemption
.as_ref()
.is_some_and(|redemption| redemption.conversion.is_none())
}))
这就是 checkout 侧的调用点:StripeCheckoutGateway::invite_promotion 把它映射成促销码字符串(subscription_checkout.rs),随后 promotion() 用 code + active = true + limit = 1 去 Stripe 查实际的 promotion code id。也就是说「用户是否享有邀请优惠」由本 crate 决定,「优惠在 Stripe 里是否真实存在且有效」由 Stripe 决定——两边都是必要条件。
mark_converted(user, stripe_subscription_id) 由 Stripe 订阅 webhook 触发。authentication_service 中的 mark_gtm_invite_converted 先把 customer email 转成 MacroUserIdStr,再调用服务(stripe_webhook.rs),失败只记录 error! 而不会让 webhook 整体失败。返回 bool 表示"确实有一行被更新",因此重复收到同一事件是安全的。
HTTP 契约:6 个端点、状态码与访问控制
路由在 axum_router.rs 中装配,最终被 authentication_service 挂在 /gtm-invite 之下,所以对外完整路径是 /gtm-invite/...:
| 方法 | 路径 | 权限 | 说明 |
|---|---|---|---|
POST |
/gtm-invite/links |
Macro 员工 | 创建链接 |
GET |
/gtm-invite/links?mine=true |
Macro 员工 | 列出链接(默认全部,mine 仅自己) |
DELETE |
/gtm-invite/links/{id} |
Macro 员工 | 撤销未被使用的链接 |
GET |
/gtm-invite/public/{token} |
匿名 | 欢迎页解析链接并计数打开 |
POST |
/gtm-invite/redeem |
已登录用户 | 将账号归因到链接 |
GET |
/gtm-invite/offer |
已登录用户 | 查询账号当前持有的优惠 |
员工路由的双重门禁
路由本身不做鉴权,鉴权由提取器完成,分两层:
GtmMacroStaffExtractor<Auth>:先用MacroAuthorizationExtractor<Auth, UserOrInternal>完成认证(失败返回其自身的 401 响应),再检查macro_user_id.is_macro_staff(),不是员工则返回GtmInviteError::Forbidden(403)。- 服务层
require_staff:再过一遍。看起来冗余,但这让服务在脱离 HTTP 层被调用(例如内部脚本、其他服务直接依赖 crate)时依然守住权限边界,单测create_link_rejects_non_staff_without_touching_the_repo验证了非员工连仓储都不会被触碰。
用户路由(/redeem、/offer)只用认证,不要求员工身份;公开路由完全匿名。
错误到状态码的映射
GtmInviteError 实现了 IntoResponse,映射集中在 axum_router.rs:
| 错误 | HTTP 状态 | 典型场景 |
|---|---|---|
RateLimitExceeded |
429 | 公开解析被限流 |
NotFound |
404 | 令牌或 id 不存在 |
Forbidden |
403 | 非 @macro.com 账号访问员工接口 |
Expired / Revoked |
410 Gone | 兑换窗口已关或被撤销 |
AlreadyRedeemed |
409 Conflict | 已被其他账号使用 |
InvalidToken / BadRequest |
400 | 令牌格式、姓名/邮箱/备注不合法 |
Internal |
500 | 数据库等内部错误 |
一个安全细节:所有 5xx 响应都会先打 tracing::error!,然后把消息覆盖为固定的 "internal server error",避免把 SQL 错误、连接串等泄露给客户端。响应体统一是 model_error_response::ErrorResponse,前端只需读 message 一个字段。
公开端点的按 IP 限流
只有 /public/{token} 被套上限流中间件,且限流参数由类型参数 PerIpResolveRateLimit 声明(resolve_link.rs):
fn config() -> RateLimitConfig {
RateLimitConfig {
max_count: 120,
window: Duration::from_mins(60),
}
}
fn key(&self) -> RateLimitKey {
RateLimitKey::builder(&"per-ip-gtm-invite-resolve")
.append(&self.0.origin_ip())
.finish()
}
即每 IP 每小时 120 次,key 前缀 per-ip-gtm-invite-resolve 与客户端源 IP 拼接。源码注释给出的取舍是:对"真人刷新欢迎页"足够宽松,对"扫描令牌"毫无意义——令牌空间是 62^32 级别。单测 the_rate_limit_does_not_cover_authenticated_routes 明确断言限流不覆盖已鉴权路由,因为中间件只挂在公开路由上。
DTO 层:域模型不直接出网
dto.rs 定义了全部线上类型,并由 utoipa 生成 OpenAPI:
GtmInviteLink:员工看板视图,camelCase序列化,把redemption与conversion摊平成redeemedBy、redeemedAt、convertedAt、stripeSubscriptionId,并附带status与freeMonths。from_link(link, free_months, now)负责转换,now由 handler 传入,保证一次列表里所有链接的状态判定基于同一时刻。PublicGtmInviteLink:只暴露firstName、status、freeMonths。这是有意的信息裁剪——匿名用户拿不到token、createdBy、备注等内部字段。路由测试anyone_can_resolve_a_link_and_only_sees_public_fields直接断言响应里没有createdBy和token。GtmInviteOffer/GtmInviteOfferStatus:给前端展示"你有一份首月免费",包含linkId、firstName、promoCode、freeMonths、redeemedAt;未持有时offer为null而非 404。CreateGtmInviteLinkRequest、RedeemGtmInviteLinkRequest、ListGtmInviteLinksQuery:入参类型,可选项均加#[serde(default)],因此{ "firstName": "Grace" }这样最简请求即可创建链接。
数据库:约束即不变量
持久化表定义在 crates/macro_db_client/migrations/20260917130509_gtm_invite_link.sql。用户引用统一用 Macro user id(macro|email 形式),注释说明这样鉴权服务可以直接从请求主体归因,无需额外查表。
关键约束有三条:
CONSTRAINT gtm_invite_link_pkey PRIMARY KEY (id),
CONSTRAINT gtm_invite_link_token_key UNIQUE (token),
CONSTRAINT gtm_invite_link_redemption_consistent
CHECK ((redeemed_by_user_id IS NULL) = (redeemed_at IS NULL)),
CONSTRAINT gtm_invite_link_conversion_requires_redemption
CHECK (converted_at IS NULL OR redeemed_by_user_id IS NOT NULL)
token唯一:令牌即外键,重复会导致查库歧义。- 兑换两列必须同生同死:避免出现"有兑换人没有兑换时间"的半状态。
- 转化必须有兑换:
converted_at不能先于兑换出现。
索引则直接服务于查询模式:
CREATE INDEX idx_gtm_invite_link_created_by_created_at
ON public.gtm_invite_link (created_by_user_id, created_at DESC);
CREATE INDEX idx_gtm_invite_link_created_at
ON public.gtm_invite_link (created_at DESC);
CREATE UNIQUE INDEX idx_gtm_invite_link_redeemed_by_user_id
ON public.gtm_invite_link (redeemed_by_user_id)
WHERE redeemed_by_user_id IS NOT NULL;
前两个索引分别匹配"按创建人过滤 + 倒序"与"全量倒序",对应 list_links 的 ORDER BY created_at DESC, id DESC;第三个是部分唯一索引,把"一个用户最多持有一条已兑换链接"从服务层逻辑升级为数据库硬约束——即使服务层判断被绕过,并发插入也会在库层失败。
三条 SQL 的并发语义
Postgres 适配器 pg_gtm_invite_repo.rs 把状态判断下推为单条语句的条件,从而消除读-改-写窗口。
兑换用 UPDATE ... RETURNING 一次完成判断与写入:
UPDATE gtm_invite_link
SET redeemed_by_user_id = $2,
redeemed_at = COALESCE(redeemed_at, $3)
WHERE id = $1
AND revoked_at IS NULL
AND ((redeemed_by_user_id IS NULL AND expires_at > $3)
OR redeemed_by_user_id = $2)
RETURNING id, token, first_name, ...;
COALESCE(redeemed_at, $3) 保证同一用户重复兑换时保留首次时间;OR redeemed_by_user_id = $2 让本人的重复请求也能命中;fetch_optional 为空即"抢输了"。源码注释点明这是为了"两个账号抢同一链接,或注册与撤销竞态,都在数据库里裁决"。
撤销同样是条件更新:
UPDATE gtm_invite_link
SET revoked_at = $2
WHERE id = $1
AND revoked_at IS NULL
AND redeemed_by_user_id IS NULL
转化标记用 converted_at IS NULL 保证只记一次:
UPDATE gtm_invite_link
SET converted_at = $3, stripe_subscription_id = $2
WHERE redeemed_by_user_id = $1
AND converted_at IS NULL
open_count 的累加也是原子表达式 open_count = open_count + 1,配合 first_opened_at = COALESCE(first_opened_at, $2) 保留首次打开时间。
行到聚合的转换由 TryFrom<InviteLinkRow> 承担,并做防御式校验:redeemed_by_user_id 与 redeemed_at 一有一无会返回 sqlx::Error::Decode("redemption columns are inconsistent");存储的 token、promo code、user id 若无法解析也会就地报错。这让"数据库被外部改写"的故障在读取时立即暴露,而不是渗透进业务逻辑。
接入 authentication_service:配置项与环境变量
服务启动时在 server.rs 解析配置,在 config.rs 中做校验:
fn resolve_gtm_invite_config(
promo_code: &GtmInvitePromoCode,
link_ttl_hours: &GtmInviteLinkTtlHours,
) -> anyhow::Result<GtmInviteConfig> {
let promo_code: PromoCode = nonblank_value(promo_code.value())
.unwrap_or(DEFAULT_GTM_INVITE_PROMO_CODE)
.parse()
.context("GTM_INVITE_PROMO_CODE is invalid")?;
let link_ttl_hours: i64 = match nonblank_value(link_ttl_hours.value()) {
Some(hours) => hours.trim().parse()
.context("GTM_INVITE_LINK_TTL_HOURS must be a whole number of hours")?,
None => DEFAULT_GTM_INVITE_LINK_TTL_HOURS,
};
if link_ttl_hours <= 0 {
anyhow::bail!("GTM_INVITE_LINK_TTL_HOURS must be positive");
}
Ok(GtmInviteConfig {
promo_code,
link_ttl: chrono::Duration::hours(link_ttl_hours),
free_months: GTM_INVITE_FREE_MONTHS,
})
}
两个环境变量都是可选(Doppler 项目 authentication-service),未设置或为空时回落默认值:
| 变量 | 默认值 | 含义 | 校验 |
|---|---|---|---|
GTM_INVITE_PROMO_CODE |
1MF |
结账时下发给 Stripe 的客户可见促销码 | 必须是合法 PromoCode;且需在 Stripe 中真实存在并处于激活状态 |
GTM_INVITE_LINK_TTL_HOURS |
48 |
链接创建后可打开、可兑换的时长 | 必须是正整数小时,否则启动失败 |
free_months 在服务层是常量 GTM_INVITE_FREE_MONTHS = 1,不从环境变量读取——它只用于面向用户的文案(欢迎页与优惠卡显示的"免费 N 个月")。若促销码在 Stripe 侧配置的时长与此不一致,就会出现"文案说 1 个月、实际按 Stripe 规则计费"的偏差,因此修改促销策略时要同时改这两处。
GtmInviteConfig 的解析在一次启动中只做一次,之后所有链接创建时拷贝同一份 promo_code 与 TTL——这意味着已在库中的链接不会因配置变更而改变过期时间或促销码,它们是写入时快照。要调整存量链接,只能重建。
配置就绪后,服务实例在 server.rs 组装为 GtmInviteServiceImpl { repo, config } 并包进 Arc,随后注入 GtmInviteRouterState(service + rate_limiter + authorization_state 三件套)供路由使用。
端到端链路
把上述模块串起来,一次完整的 GTM 邀请经历如下阶段(与 services/authentication_service/README.md 的描述一致):
- 员工在
/app/internal/invite-links看板调用POST /gtm-invite/links,得到 32 字符令牌。 - 潜在客户打开
/app/invite?token=…,前端调用GET /gtm-invite/public/{token}拿到名字、状态与免费月数,open_count自增。 - 客户完成注册后,前端调用
POST /gtm-invite/redeem,账号与链接绑定。 - 进入套餐选择步骤时调用
GET /gtm-invite/offer,有优惠则跳过套餐选择器直接展示免费月。 - 结账时后端调用
active_offer_for_user取促销码,转成 Stripe promotion code 应用到 checkout session。 - Stripe 订阅成功后的 webhook 调用
mark_converted,链接进入converted状态。
注意第 3 步与第 4 步之间的时序:redeem 必须在登录之后发生,因为归因需要 macro_user_id;而 resolve 必须能匿名访问,因为客户此时还没有账号——路由的鉴权粒度正是按这条时间线划分的。
开发实践:扩展与验证
AGENTS.md 给出了两条明确的改动路径,配合源码可以还原成可执行的开发流程。
新增一个路由
顺序是自内向外,避免中间层空转:
src/domain/ports.rs:如果是新的仓储行为,先在GtmInviteRepo加方法(返回impl Future<Output = Result<T, Self::Err>> + Send),并在GtmInviteService加对应用例。src/domain/service.rs:在GtmInviteServiceImpl实现用例,注意先做require_staff之类的准入判断,再碰仓储;纯校验逻辑抽成normalize_*函数以便单测。src/inbound/axum_router/<name>.rs:新建 handler 文件,写#[utoipa::path]注解、定义拒绝类型、复用既有 DTO 风格。src/inbound/axum_router.rs:pub mod声明 +.route(...)注册;如果涉及新错误码,同步扩展IntoResponse的 match 分支。- 若接口要出现在对外文档,还需在
authentication_service的swagger.rs注册 handler 泛型实例。
仓储 trait 用了 #[cfg_attr(test, mockall::automock(type Err = anyhow::Error;))],因此服务层单测可以直接 MockGtmInviteRepo::new() + expect_insert_link(),无需数据库。
修改持久化
改 src/outbound/pg_gtm_invite_repo.rs 后必须同步 src/outbound/pg_gtm_invite_repo/test.rs。这些测试用 #[sqlx::test(migrator = "MACRO_DB_MIGRATIONS")] 启动临时库并跑全部迁移,覆盖了:按 token/id 往返读写、未知 token 返回 None、token 唯一性、列表倒序与创建人过滤、open_count 累加与首次打开时间、撤销只影响未使用链接、兑换的先到先得与赢家幂等、拒绝过期与撤销链接、一个用户只能持有一条已兑换链接、转化只记录一次。任何 SQL 语义变化都应该在这里留下新用例。
检查命令
# crate 单测;SQLX_OFFLINE 必须未设置,否则 sqlx 宏走离线缓存
cargo test -p gtm_invite
# 改过 schema 后,在仓库根目录准备本地数据库
nix develop --command just prepare_db
# 全特性编译检查(crate 自带 justfile 的 check 目标)
cargo check --all-features
just prepare_db 在 crates/gtm_invite/justfile 中定义为 just sqlx::prepare_db {{ DATABASE_URL }},它会为 sqlx::query! 宏准备离线元数据;忘记执行会在编译期报"查询与数据库不匹配"之类的错误,这是最常见的新手卡点。
安全与设计取舍小结
把源码里的注释与测试汇总,这个模块有几条值得记住的工程决策:
- 令牌是唯一的秘密,且必须有形状:32 字符随机字母数字,解析时限制 16~64 长度与字符集,让明显伪造的请求在触库前被拒。
- 公开接口只暴露三个字段:
firstName、status、freeMonths。归因人、备注、兑换人全部留在员工看板接口里。 - 限流只保护匿名端点:120 次/小时/IP,键含源 IP 与前缀;已鉴权路由不受此限制,避免正常用户被误伤。
- 状态读时派生而非存储:避免出现"存了
expired但时间还没到"的不一致;同时明确"兑换优先于过期/撤销"。 - 正确性下沉到数据库:条件
UPDATE、部分唯一索引、CHECK 约束共同保证并发下的归因唯一性与一次性转化。 - 埋点失败不影响主流程:
record_open的错误只降级为warn。 - 内部错误不外泄:5xx 统一返回
internal server error。
理解了这套划分,就能明白为什么 gtm_invite 在仓库里既小又"干净":它把账号、支付、邮件这些副作用全部推给上游,自己只维护一条从"链接"到"归因"再到"转化"的状态线,并用数据库约束把这条线的关键不变量钉死。需要继续深入时,建议从 服务实现、Postgres 适配器 与 迁移文件 三处对照阅读。