Macro GTM 邀请链接模块 gtm_invite 架构解析与实战指南

原创2026-10-29 22:39:231,416 阅读
文章标签:企业应用协同办公后端前端即时通讯AI Agent人工智能CRM桌面应用MCP Clients

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:幂等、单链接、原子

兑换是逻辑密度最高的方法,按顺序做四次判断:

  1. 同一用户重复兑换:if link.is_redeemed_by(user) { return Ok(link); } —— 完全幂等,直接返回原链接。
  2. 用户已有别的兑换链接:查询 get_redeemed_link_for_user,若命中则打一条 info! 并返回原来那条。注释写明"A user holds one offer: whichever link they redeemed first stays",这对应数据库上 redeemed_by_user_id 的部分唯一索引。
  3. 状态机校验:Active 放行;Expired → 410;Revoked → 410;Redeemed | Converted → 409。
  4. 原子写入:调用 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 的描述一致):

  1. 员工在 /app/internal/invite-links 看板调用 POST /gtm-invite/links,得到 32 字符令牌。
  2. 潜在客户打开 /app/invite?token=…,前端调用 GET /gtm-invite/public/{token} 拿到名字、状态与免费月数,open_count 自增。
  3. 客户完成注册后,前端调用 POST /gtm-invite/redeem,账号与链接绑定。
  4. 进入套餐选择步骤时调用 GET /gtm-invite/offer,有优惠则跳过套餐选择器直接展示免费月。
  5. 结账时后端调用 active_offer_for_user 取促销码,转成 Stripe promotion code 应用到 checkout session。
  6. Stripe 订阅成功后的 webhook 调用 mark_converted,链接进入 converted 状态。

注意第 3 步与第 4 步之间的时序:redeem 必须在登录之后发生,因为归因需要 macro_user_id;而 resolve 必须能匿名访问,因为客户此时还没有账号——路由的鉴权粒度正是按这条时间线划分的。

开发实践:扩展与验证

AGENTS.md 给出了两条明确的改动路径,配合源码可以还原成可执行的开发流程。

新增一个路由

顺序是自内向外,避免中间层空转:

  1. src/domain/ports.rs:如果是新的仓储行为,先在 GtmInviteRepo 加方法(返回 impl Future<Output = Result<T, Self::Err>> + Send),并在 GtmInviteService 加对应用例。
  2. src/domain/service.rs:在 GtmInviteServiceImpl 实现用例,注意先做 require_staff 之类的准入判断,再碰仓储;纯校验逻辑抽成 normalize_* 函数以便单测。
  3. src/inbound/axum_router/<name>.rs:新建 handler 文件,写 #[utoipa::path] 注解、定义拒绝类型、复用既有 DTO 风格。
  4. src/inbound/axum_router.rs:pub mod 声明 + .route(...) 注册;如果涉及新错误码,同步扩展 IntoResponse 的 match 分支。
  5. 若接口要出现在对外文档,还需在 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 适配器 与 迁移文件 三处对照阅读。

登录后查看全文
macro