涉及多表操作的动作类API编写最佳实践与数据完整性方案

单API塞全量逻辑是否符合最佳实践？ #

完全不符合，这是典型的大接口反模式，实际落地会踩非常多坑：

• 超时概率极高：单接口要连续做5次数据库写入，还要调用邮件服务发通知，邮件属于外部依赖，网络抖动、服务限流都可能把整个请求拖到超时，前端等半天拿不到响应，用户根本没法判断邀请到底发没发出去。
• 故障连带影响太大：任何一步出错都会搞崩整个流程——比如邮件服务临时挂了，就算前面的企业、账号、邀请记录都已经写进库了，整个接口还是会返回失败，要是事务没兜住就会留一堆脏数据，就算事务回滚了，本来和发邮件无关的核心邀请逻辑也被连带搞失败，完全没必要。
• 维护成本极高：所有逻辑揉在一个接口里，后续要改邀请附言规则、改员工权限默认配置、换邮件模板的时候，改一处就得测整个流程，很容易改出线上bug。
• 问题排查困难：整个流程是黑盒，出了问题没法快速定位是写哪张表失败了、还是发邮件卡了，也没法单独对失败的步骤做重试。

可落地的替代方案 #

根据业务复杂度选即可，不用上来就搭过重的架构：

方案1：核心逻辑同步+非核心逻辑异步（改造成本最低，优先选） #

把流程按一致性要求拆分：

• 同步执行部分：把强绑定的核心操作——也就是Company table创建被邀请企业、User table创建被邀请人账号、Staff table绑定账号和企业的权限关系、Invitation table写入邀请记录这4步，全部包在同一个数据库事务里，这部分执行成功就直接给前端返回「邀请发起成功」的响应，用户侧不需要等后面的步骤跑完。
• 异步执行部分：核心事务提交成功后，触发两个异步任务：
  • 写入Connection table建立企业关联（如果业务要求关联必须等被邀请人接受才生效，这步直接挪到被邀请人点「接受邀请」的接口里就行，根本不用放在发起邀请的流程里）
  • 调用邮件服务发送邀请通知，这部分加失败重试策略，比如间隔1分钟、5分钟、30分钟重试3次，重试都失败就打告警让运营手动补发，完全不影响核心邀请流程。

方案2：状态机驱动的多阶段编排（适合后续要扩展复杂流程的场景） #

如果后续邀请流程还要加企业资质审核、管理员审批、多渠道通知之类的逻辑，就用状态机模式拆分：

• 先给整个邀请流程定义明确的状态：初始化、企业创建完成、账号创建完成、权限配置完成、关联建立完成、通知发送完成、流程失败
• 第一次调用接口只做参数校验，生成一条初始状态的邀请记录就返回成功
• 后续每个步骤由独立的任务执行器按状态顺序推进，每跑完一步就更新对应状态，某一步失败就把状态标记为对应节点的失败状态，支持自动重试或者后台手动触发重试
• 前端可以通过轮询或者websocket获取邀请的实时进度，给用户展示当前卡在哪一步

拆分流程后的数据完整性保障手段 #

不管用上面哪个方案，做好这几点就不会出脏数据：

• 强一致操作必须包本地事务：创建企业、创建账号、绑定员工权限、写入邀请记录这几个强绑定的操作，必须放在同一个数据库事务里提交，要么全成要么全回滚，绝对不能出现企业建了但账号没生成、账号有了但没对应企业权限的情况。
• 所有跨步骤操作必须做幂等：给每个邀请生成全局唯一的邀请ID，后续建关联、发邮件的所有操作都拿这个ID当幂等键，不管任务重试多少次，同一个邀请只会建一条关联记录、发一封邀请邮件，不会产生重复数据。
• 用本地消息表兜底异步任务可靠性：不要在核心事务还没提交的时候就投递异步消息，怕消息丢的话就加一张本地消息表，和核心业务数据在同一个事务里写入待执行的任务记录，后台定时任务扫表把没执行的任务重新投递，确保异步任务不会因为消息中间件故障丢失。
• 加定期对账补偿逻辑：每天业务低峰期跑定时任务，校验最近7天的邀请记录，把卡在中间状态、数据缺漏的记录捞出来，自动触发补偿——比如邀请记录存在但没建关联的就补建关联、没发邮件的就补发邮件，自动修不了的打告警给人工处理。
• 留好运维操作入口：做个简单的后台页面，支持手动补发邀请邮件、手动补建企业关联、手动修正流程状态，真出问题的时候不用直接查数据库改数据，能快速恢复业务。

内容的提问来源于stack exchange，提问作者Sankaran Namboodiri