Macro teams crate 团队事件生产者与 teammate-dm 消费者实战指南
Macro teams crate 团队事件生产者与 teammate-dm 消费者实战指南
Macro 的 teams crate 同时承担两件事:维护团队模型、持久化端口、服务策略与 HTTP 适配层,以及把成功的团队变更翻译成可被下游消费的 Kafka 事件。本文以该 crate 的说明文档为骨架,结合源码逐层拆解 macro.teams 主题的事件契约、投递语义、teammate-dms 消费者的实现细节与 backfill_teammate_dms 运维命令,帮助你在不破坏兼容性的前提下接入或排查这条事件链。
读完本文你将掌握:如何正确解读十种团队事件的载荷与字段含义;生产端为什么是"至多一次"而消费端是"至少一次";以及当 teammate DM 缺失时如何安全地做幂等回填。
crate 的职责边界与代码分层
teams crate 采用清晰的 domain / inbound / outbound 分层结构:
- crates/teams/src/domain/team_service.rs 是实现团队业务策略的主入口,
TeamServiceImpl聚合了团队仓储、客户(Stripe)仓储、频道服务、角色权限服务、通知、CRM 入队器、分析客户端、联系人入队器以及事件发布器等十多个协作方。 - crates/teams/src/domain/events.rs 定义发布到
macro.teams的全部事件模型。 - crates/teams/src/inbound/axum_router.rs 暴露 HTTP 路由(创建、PATCH、删除团队,邀请、接受、拒绝、撤销邀请,以及自动加入域开关等)。
- crates/teams/src/outbound/team_repo.rs 提供
TeamRepository的 Postgres 实现。
Cargo feature 划分了编译面:crates/teams/Cargo.toml 中 default = ["ai_tools", "axum", "inbound", "outbound", "ports"],而 backfill_binary 是一个独立 feature,它把 channels/outbound、database_env_vars、macro_entrypoint 等依赖引入,只为回填二进制服务:
[[bin]]
name = "backfill_teammate_dms"
path = "src/bin/backfill_teammate_dms.rs"
required-features = ["backfill_binary"]
这意味着普通的 cargo test 不会构建回填工具,避免把 channels 的写路径拖进团队 crate 的默认构建。
事件契约:主题、Key 与信封
所有事件发布到 macro.teams 主题。主题名在 crates/macro_event_topics/src/lib.rs 中集中声明:
/// Team lifecycle, invite, and membership events.
MacroTeamsTopic => "macro.teams",
该文件被注释说明"也被基础设施代码程序化抓取,以确保所有 Kafka topic 都被创建"——这正是后文上线顺序要求"先部署 Kafka-cluster 栈"的根源。
Key 是团队裸 UUID
每条记录的 Kafka key 是团队裸 UUID 字符串,不带任何前缀,例如 3f6f8b0a-6f9f-4a3f-9c3a-2b1e5d4c7a90。这一约定在构造器中被强制实现:
fn new(team_id: Uuid, event: TeamTopicEvent) -> Self {
Self::with_event(team_id.to_string(), Event::new(event))
}
Key 不属于 JSON 信封的一部分,只参与分区与压缩。因此同一团队的事件落在同一分区、按团队内顺序投递;不同团队之间的顺序未被定义。测试 constructors_use_teams_topic_bare_uuid_key_and_schema_version_one 同时断言了三件事:key 等于团队 UUID、key 不以 team| 开头、schema_version 恒为 1。
信封结构
信封由 crates/macro_event_broker/src/domain/models.rs 定义:
pub struct Event<E> {
pub event_id: Uuid,
pub schema_version: u8,
#[serde(flatten)]
pub event: E,
}
event_id 由 Uuid::now_v7() 生成(时间有序),schema_version 取自 TopicEvent::SCHEMA_VERSION,event 被 flatten 展开,最终线上形状是 event_id、schema_version、event_type、metadata 四个顶层字段。TeamTopicEvent 使用 #[serde(tag = "event_type", content = "metadata")] 完成这一展开:
pub enum TeamTopicEvent {
#[serde(rename = "team.created")]
Created(TeamCreatedMetadata),
// ...
}
impl TopicEvent for TeamTopicEvent 中 const SCHEMA_VERSION: u8 = 1;,即当前契约所有事件都用版本 1。
十种团队事件与触发时机
原文档给出的表格是这条契约的权威说明,下表在其基础上补充了对应的 Rust 元数据结构:
| 事件名 | 触发时机 | Metadata | 源码结构 |
|---|---|---|---|
team.created |
团队创建且所有可回滚的创建副作用成功 | team_id, name, slug, owner, enterprise, paid, auto_join_domain |
TeamCreatedMetadata |
team.updated |
含 name 或 slug 的团队 PATCH 已持久化 |
team_id, actor_user_id, 请求的 name, 请求的 slug |
TeamUpdatedMetadata |
team.deleted |
团队删除成功 | team_id, actor_user_id, member_user_ids(源码另含 bot_ids、owned_entities) |
TeamDeletedMetadata |
team.invite_created |
新邀请持久化;每个新受邀的小写邮箱产生一条事件 | team_id, invite_id, email, invited_by, team_name |
TeamInviteCreatedMetadata |
team.invite_rejected |
受邀人成功拒绝并删除邀请 | team_id, invite_id, email, actor_user_id |
TeamInviteRejectedMetadata |
team.invite_revoked |
管理员成功删除邀请 | team_id, invite_id, email, actor_user_id |
TeamInviteRevokedMetadata |
team.member_joined |
邀请加入、域名自动加入或邀请链接加入,且所有可回滚副作用成功 | team_id, member_id, teammate_ids, role, join_method |
TeamMemberJoinedMetadata |
team.member_removed |
成员移除且所有可回滚副作用成功 | team_id, member_id, removed_by, role |
TeamMemberRemovedMetadata |
team.member_role_changed |
每一次单独的成员角色更新成功 | team_id, actor_user_id, member_id, role, previous_role |
TeamMemberRoleChangedMetadata |
team.auto_join_domain_toggled |
显式切换自动加入域成功 | team_id, actor_user_id, auto_join_domain |
TeamAutoJoinDomainToggledMetadata |
注意 teams crate 的 README 表格是契约的稳定面,而源码近期为 team.deleted 扩了 bot_ids 与 owned_entities 两个字段(见 crates/teams/src/domain/events.rs 中 TeamDeletedMetadata 的注释与 #[serde(default)] 标注)。这属于增量字段,老消费者可以忽略。
角色取值与可空语义
role 一律小写,来自 TeamRole 的 #<a href="https://link.gitcode.com/i/1809d3549174c04b36049992f20687cf" target="_blank">serde(rename_all = "lowercase")],取值为 member、admin、owner,源码注释还说明其从"最少权限到最多权限"自上而下排序([crates/teams/src/domain/model.rs)。
可选 metadata 序列化为 null:
team.updated上的可变字段描述的是请求的 PATCH,null表示该字段被省略,而不是"值未变化"。team_name是尽力而为的邀请时查询结果,取不到即null。previous_role是已知的 PATCH 前快照中的角色。auto_join_domain是操作后的结果域,关闭时为null。
一个容易误读的点:团队删除只产生一条事件,member_user_ids 列出删除前存在的成员,不会为每个成员再补一条移除事件。而在成员自助退出场景中,removed_by 等于 member_id。
PATCH 的三种输出组合
patch_team 的实现决定了事件组合(crates/teams/src/domain/team_service.rs):
- 仅角色变更:逐个成员更新角色,每次成功立刻发布
team.member_role_changed;由于req.name与req.slug均为None,不发布team.updated。 - 仅名称/别名变更:不产生角色事件,发布一条
team.updated。 - 两者同时变更:先按请求顺序产生若干角色事件,再产生一条
team.updated。
角色更新按请求顺序提交:如果后续某个更新失败,之前已成功更新及其事件保持已提交状态,失败的那次不产生事件。发布点位于 patch_team_user_role 成功之后:
for update in user_role_updates {
let previous_role = team.members.iter()
.find(|member| member.user_id == update.team_user_id)
.map(|member| member.role);
self.team_repository
.patch_team_user_role(&team_id, &update.team_user_id, update.role)
.await?;
self.publish_team_event(&TeamMacroEvent::member_role_changed(...));
}
代码同时拒绝两类非法操作:分配 Owner 角色、降级团队所有者。这也是为什么 team.member_role_changed 实际只会出现 member/admin 两种新值。
创建事件中的 auto_join_domain 例外
团队创建时会尝试为公司域名默认开启自动加入:若所有者邮箱是通用邮箱域(is_generic_email_domain),则 auto_join_domain 为 None;否则调用 toggle_auto_join_domain 并取回结果。该步骤是尽力而为的——失败只记录日志,创建仍然成功。
关键区别在于:创建期间的自动开启只体现在 team.created 的 auto_join_domain 字段上,不额外产生 toggle 事件;只有显式的设置操作才产生 team.auto_join_domain_toggled。
join_method:带标签的联合类型
join_method 是 tagged union,由 #[serde(tag = "type", rename_all = "snake_case")] 决定线格式:
pub enum TeamJoinMethod {
InviteAccepted { invite_id: Uuid, invited_by: MacroUserIdStr<'static> },
DomainAutoJoin,
InviteLink,
}
三种形态分别对应:接受邀请(携带邀请 UUID 与邀请人)、邮箱域名自动加入(编码为 {"type":"domain_auto_join"})、通过团队可分享邀请链接加入({"type":"invite_link"})。源码中的调用点与之一一对应:域名加入在 try_join_team_by_domain 中传入 TeamJoinMethod::DomainAutoJoin,邀请链接加入在 crates/teams/src/domain/team_service/invite_link.rs 中传入 TeamJoinMethod::InviteLink。
消费者应当忽略不认识的 join method,以保证未来新增加入方式时不破坏解码。
完整的 member_joined 信封示例
{
"event_id": "01998a30-1a2b-7c3d-9e4f-5a6b7c8d9e0f",
"schema_version": 1,
"event_type": "team.member_joined",
"metadata": {
"team_id": "3f6f8b0a-6f9f-4a3f-9c3a-2b1e5d4c7a90",
"member_id": "macro|joiner@acme.com",
"teammate_ids": [
"macro|admin@acme.com",
"macro|owner@acme.com"
],
"role": "member",
"join_method": {
"type": "invite_accepted",
"invite_id": "0197f776-6e7b-7c69-a251-780ae754d3e4",
"invited_by": "macro|admin@acme.com"
}
}
}
teammate_ids 的定义值得单独说明:它是加入时刻其他现任队友的排序去重集合(所有者 + 成员,排除加入者本人)。当名单无法加载或团队没有其他成员时为空数组。该字段带 #[serde(default)],因此历史上未包含该字段的旧事件仍可解码为空数组。测试 member_joined_defaults_missing_teammate_ids 验证了这条兼容性路径。
生成逻辑在 teammate_ids_except:把 owner_id 与所有成员的 user_id 链接去重、过滤掉加入者、再按字符串排序。这份"排序去重"不是风格问题,而是让 DM 创建的请求集合稳定可比较,从而支持幂等重放。
脱敏与不产生事件的流程
事件载荷刻意排除 Stripe 订阅 ID、客户 ID、支付状态以及其他计费标识。唯一的计费派生值是创建事件上的 paid: bool——源码注释直接写道"不暴露计费标识的前提下说明团队是否为付费订阅"。
以下流程不发布团队事件:
- 计费流程,包括 Stripe webhook 驱动的订阅与支付状态变更、付费角色(premium)的撤销与恢复;
- CRM 设置变更与
patch_team_crm_settings; - 读/列表操作;
- 邀请重发及其
mark_invites_sent更新; - 通知结果。
此外,提交后进行的尽力而为的 CRM、联系人、通知工作不会抑制对应事件:这些后续步骤失败只记录日志(例如 enqueue_populate_crm_for_user 失败时的 tracing::error!),不会回滚已提交的变更,也不会吞掉事件。
一个实现细节印证了"每个新受邀邮箱一条事件":invite_to_team 只对 new_invite_emails 集合内的邀请发布事件,因此重复邀请同一邮箱不会重复产生 team.invite_created。
投递语义:生产至多一次,消费至少一次
生产侧:提交后 fire-and-forget
publish_team_event 的实现是整个契约的关键:
fn publish_team_event(&self, event: &TeamMacroEvent) {
drop(self.event_broker.send_event(event).inspect_err(|error| {
tracing::error!(error = ?error, "failed to schedule team event");
}));
}
send_event 只做序列化并把发布任务交给 spawner,返回 JoinHandle;调用方立即 drop 掉句柄,因此 API 不会等待 Kafka 投递,也不检查投递结果。发布任务内部有超时保护:macro_event_broker 的 PUBLISH_TIMEOUT 为 6 秒,超时返回 EventBrokerError::PublishTimeout 并记录错误日志。
由此产生的语义是:没有事务、没有 outbox、没有重试把数据库持久化与发布绑定在一起。相对于团队变更,投递是"至多一次"——一次已提交的变更可以完全没有对应事件。这也是为什么"事件缺失"在排查时不能直接判定为消费者 bug。
消费侧:提交 offset 前必须处理完
teammate DM 消费者是"至少一次"。它仅在处理成功或永久失败后才提交 offset,瞬时失败会在进程内重试;若重试仍失败,消费者直接退出且不提交 offset,由监管进程重启后重投该事件。
teammate-dms 消费者的实现解剖
消费者代码位于 channels crate:crates/channels/src/inbound/teammate_dms_consumer.rs。它不依赖 teams crate,而是定义了自己的通道视角视图,只解码 member_id 与 teammate_ids 两个字段:
pub(crate) struct TeammateDmsJoinedMetadata {
pub member_id: MacroUserIdStr<'static>,
#[serde(default)]
pub teammate_ids: Vec<MacroUserIdStr<'static>>,
}
TeamsTopicForDms 采用 #[serde(untagged)] 的双臂设计:MemberJoined(MemberJoinedEnvelope) 命中 event_type = "team.member_joined",其余一切落入 Other(IgnoredTeamEvent) 并被标记为成功、直接提交 offset。这样新增的团队事件类型不会卡住分区。
消费组名固定:
impl GroupName for TeammateDmsConsumerGroup {
const GROUP_NAME: &'static str = "teammate-dms";
}
处理逻辑由 handle_team_event 完成:join 事件调用 ensure_joined_member_dms,其他事件返回 Ok(())。重试策略为最多 5 次尝试,指数退避从 1 秒起每次翻倍:
const MAX_ATTEMPTS: u32 = 5;
const RETRY_BASE_DELAY: Duration = Duration::from_secs(1);
TeammateDmError::is_transient() 目前恒返回 true,即所有错误都按瞬时错误处理;handle_with_retry 中"非瞬时错误直接丢弃并提交"的分支是为将来分类错误预留的。批次出现部分失败时,TeammateDmError::Partial 会携带 created/existing/failed 计数,触发重试以保证最终一致。
无法解码的消息会被记录 topic、partition、offset 后跳过,不会卡住分区。
服务侧的接线方式
消费者由文档存储服务托管启动(services/document_storage_service/src/server.rs):它在 consumer_tracker 中循环调用 run_teammate_dms_consumer,正常退出或报错都以 tracing::error! 记录,并在 5 秒后重启,直到取消令牌触发。
生产端则接在认证服务上(services/authentication_service/src/server.rs):先构建 MacroEventBrokerService::new(KafkaEventPublisher::new(config.kafka_brokers.as_ref())?, ...),再通过 .with_event_broker(macro_event_broker.clone()) 注入 TeamServiceImpl。注意默认构造使用 NoopMacroEventBroker,如果忘记注入,事件会被静默丢弃而不会报错——这是排查"完全没有事件"时的第一个检查点。
DM 的构造方式
消费者最终调用 ensure_joined_member_dms,它把加入者与队友列表转成 EnsureDms 批次:
pub fn ensure_dms_for_joining_member(
joiner: MacroUserIdStr<'static>,
roster: impl IntoIterator<Item = MacroUserIdStr<'static>>,
) -> EnsureDms
DmPair::new 会规范化两端顺序(按字符串比较把小的放 lo),因此 (a, b) 与 (b, a) 是同一个 DM,重复事件重放不会产生重复频道;两端相同则返回 SelfDm 错误。这就是消费端能做到幂等的结构性原因。
回填:backfill_teammate_dms
一次漏掉的发布会让某个团队在一段时间内没有 DM,直到回填运行。命令由 crates/teams/justfile 提供:
just crates/teams/backfill_teammate_dms_local
just crates/teams/backfill_teammate_dms_dev
just crates/teams/backfill_teammate_dms_prod
三个入口的差异体现在数据库来源与确认方式:
local:直接使用DATABASE_URL环境变量,ENVIRONMENT=local,无二次确认。dev:rds_database_url.sh拼出 MacroDB URL,aws 导出临时凭证;运行前需输入y确认。prod:必须逐字输入prod backfill才会执行,否则打印Production backfill cancelled.并退出。
这个二进制(crates/teams/src/bin/backfill_teammate_dms.rs)的实现要点:
- 分页扫描全部团队,
PAGE_SIZE = 100,用list_team_ids_after(cursor, PAGE_SIZE)做游标分页;只有当整页取满时才推进游标,否则结束。 - 对每个团队加载完整名单,把所有者与成员合并进
HashSet,再用ensure_dms_for_roster构造完整队友 DM 团(clique)——这与消费端只建"加入者与队友之间"的边不同,回填会补齐团队内所有两两组合。 - 每处理完一个团队打印一行
team=... created=... existing=... failed=...,结束时打印汇总。 - 只要有任意失败,最终
anyhow::bail!以非零码退出,便于 CI/运维判定。
因为 ensure_dms 语义是"确保存在",整条链路幂等:重复运行只会增加 existing 计数,不会产生重复频道。
兼容性约束与上线顺序
面向未来演进,契约要求:
- 容忍未知
event_type:新事件变体不应导致消费者崩溃——TeamsTopicForDms的Other分支正是这一原则的实现。 - 容忍未知 metadata 字段:新增加性字段必须可被老消费者忽略。
- 缺字段要能解码:
teammate_ids、bot_ids、owned_entities都使用#[serde(default)],老事件仍可读出(空数组)。 - 按
schema_version解释已知事件:当前所有事件都是版本 1。
部署顺序上,必须先创建 macro.teams 主题,再上线生产者:
- 部署 Kafka-cluster 栈(主题集合由
macro_event_topics的声明驱动); - 在 Doppler 中为认证服务(生产者)和文档存储服务(teammate-DM 消费者)配置
KAFKA_BROKERS; - 最后部署这两个服务。
如果生产者先于主题上线,团队变更依然成功,但在"至多一次"契约下事件会丢失——只能靠回填补偿。
本地验证
teams crate 的 justfile 把常用校验命令固化下来,并开启了严格告警:
just crates/teams/check # cargo check
just crates/teams/test # cargo test
just crates/teams/clippy # cargo clippy(RUSTFLAGS=-Dwarnings)
just crates/teams/fmt-check # cargo fmt --check
与事件契约直接相关的测试集中在两处:crates/teams/src/domain/events/test.rs 覆盖每个变体的 JSON 线格式、key 与 schema version、以及缺失字段的默认值;crates/channels/src/inbound/teammate_dms_consumer/test.rs 覆盖信封解码与 join 事件处理。此外 crates/teams/src/domain/team_service/test.rs 中的 invite_join_does_not_create_teammate_dms_inline 与 domain_join_does_not_create_teammate_dms_inline 断言了"加入流程本身不内联创建 DM,只发布带 teammate_ids 的事件",防止两条路径被悄然合并而破坏异步语义。
当你需要判断某个字段是否属于稳定契约时,一个可靠的做法是:以 README 表格为基线,再对照 events.rs 中是否有 #[serde(default)]——带默认值的字段属于增量扩展,不带默认值的字段才是所有消费者必须处理的硬要求。