FastAPI + PostgreSQL 实战：做一个重启后还能继续的审批流程

FastAPI PostgreSQL 实战做一个重启后还能继续的审批流程《企业级 Workflow 实战从审批流到 AI Agent》第 03 篇 / 共 24 篇本篇成果提交客户服务申请、创建运营待办、完成审批、查询流程历史并实测应用进程重启后数据仍在 PostgreSQL。环境Python 3.12、FastAPI、PostgreSQL 16依赖与启动命令见配套code/README.md。教学边界固定演示租户没有身份认证本篇只实现运营审核切片签署、收款、ERP 与权益开通仍由后续文章扩展。第 01 篇的内存实验可以判断“仅审批不等于开通”但退出 Python 进程后所有申请、待办和事实一起消失。假设一位运营人员上午打开审批页服务在午间重新部署下午点击批准时却找不到原任务。开发者可能回答“我们把status写进数据库就好了”。这个回答只解决了一部分一条状态记录仍不能说明申请对应哪一次流程、当前任务是谁的、审批针对哪版材料也无法恢复一条清楚的处理时间线。本篇把最小审批流程真正放进 PostgreSQL。销售提交申请时系统在同一个数据库事务中创建申请、流程实例、运营待办和第一条迁移历史。运营针对待办发出批准或驳回命令系统在另一个事务里检查任务和资料版本更新任务及实例并追加历史。读者可以通过 HTTP 查询当前状态也可以在关闭、重启 FastAPI 进程后再次查询同一申请。我们这次验证的是应用进程重启后的数据库持久性。数据库容器在实验中一直运行。它不能证明数据库节点故障恢复、备份还原、跨机高可用也不能证明已经完成企业身份鉴别。把验收边界说清楚才能判断下一篇真正还缺什么能力。图 1申请 ID 是业务对象标识实例 ID 是一次流程执行标识任务和历史按实例关联。一、把上一章的业务语言变成持久记录第 01 篇用APP-001作为便于阅读的教学编号。第 03 篇的可运行服务改用完整 UUID 作为application_id另用business_key保存销售系统能识别的业务键。两份代码不是把同一个 Python 对象直接接到 API它们共享业务语义但持久化契约从这里正式开始。后续文章要复用本篇的申请 ID、实例 ID、资料版本、状态名和任务结构不再每篇重新发明一个编号系统。我们约定一个固定的教学租户xinghe-demo。这是为了让数据库唯一约束有明确范围不代表已经实现真正的多租户隔离。生产服务不能相信请求体里随意填写的租户或审批人身份应从认证后的上下文确定租户按权限读取和修改数据。本篇的actor_id只是演示谁提交了决定的输入字段任何调用者都能填写它不能充当授权证据。applications保存客户与套餐、业务键和material_version。同一租户下(tenant_id, business_key)唯一防止销售因为页面重复提交创建两条相同业务申请。这里的冲突行为是返回 HTTP 409它并不等于完整的幂等接口。若第一次请求已提交但响应丢失第二次相同请求会收到冲突需要客户查询业务键或依靠后续第 06 篇设计的重试契约。直接把“唯一约束”写成“已经实现网络幂等”会隐藏调用方最关心的结果查询问题。workflow_instances保存与申请一对一的流程实例、本篇阶段状态、规则版本与修订号。状态只允许SUBMITTED、APPROVED、REJECTED因为本篇尚未实现签署与到账的事实入口。把READY、ACTIVE提前加进数据库枚举却没有相应命令和证据容易让人误以为可以手工把状态跳过去。到后续章节结构会通过显式迁移扩展不靠重新建库掩盖旧数据。tasks保存本次运营审核责任。它关联流程实例并记录被审核的application_version。一张任务有OPEN与COMPLETED两种状态完成时记录APPROVE或REJECT、教学操作者 ID 与时间。申请状态与任务状态不是重复申请SUBMITTED告诉我们流程在哪里任务OPEN告诉我们还有哪项具体人工工作没有完成。未来出现转派、领取、会签时这种区分会更加重要。transition_history保存每一次已接受的状态迁移从什么状态到什么状态、由哪个命令触发、操作者字段和资料版本。提交申请时也插入一条从空到SUBMITTED的记录因此时间线从起点开始。历史是解释业务变化的最小记录但目前它还不是防篡改审计系统没有身份鉴别和权限限制时actor_id的可信度非常有限。第 16 篇会把运行观测和业务审计分别处理。上述四类记录来自上一章的概念模型但“业务事实”表尚未出现因为本篇没有接入合同和财务回执。签署与到账不能凭空从审批结果推导。后续增加事实记录时它要带来源编号、申请关联及必要的对象版本已有APPROVED只能说明当前资料在这一审核切片里通过了运营审核。二、数据库约束替我们守住哪些底线完整建表语句在code/schema.sql。申请、实例和任务使用 UUID 主键实例的application_id同时带外键和唯一约束表达本季课程中“一张申请对应一个有效流程实例”的规则。material_version、rule_version和revision都要求为正整数。状态字段用CHECK限制允许值而不是让任意拼写混进持久数据。任务表的组合检查约束也有用OPEN任务的决定、完成者和完成时间应为空COMPLETED任务则必须有这三项。这不是把所有业务规则都塞进 SQL而是让数据库拒绝明显自相矛盾的记录。举例来说一条任务既标记为开放又带着REJECT决定会让界面和后台对“还能否审批”产生分歧。数据库检查可以及早暴露这种写入错误。迁移历史通过外键关联流程实例并按history_id排序查询。时间戳使用TIMESTAMPTZ让跨时区显示在将来可以由界面决定本文不根据服务器本地字符串排序历史。历史行只在事务成功时写入。若审批任务更新了但追加历史失败整笔事务应回滚避免出现“状态已变、无法解释何时改变”的结果。图 2申请、实例、待办和初始历史要共同提交其中任何一步失败事务回滚。图中的事务不包含未来的 ERP HTTP 调用。这里要区分事务保证的边界。PostgreSQL 可以保证本库同一事务里的这些写入共同提交或回滚它不能把未来的合同系统、ERP 和权益平台自动并入同一个本地事务。PostgreSQL 事务教程解释了数据库事务的原子提交语义。第 06 篇会面对“本库提交成功但通知外部系统失败”的双写问题此处先把最基本的本库一致性建好。实际教学项目不采用自动create_all每次开机改结构而提供一份明确可读的初始 SQL 和init_db.py。数据库初始化与服务启动分开方便读者检查结构、比较版本也提醒大家正式环境中的结构变更需要迁移脚本和回滚方案。本篇 SQL 用IF NOT EXISTS让第一次安装可以重复运行这并不意味着未来任何字段变化都能靠重新执行它自动完成。三、三个 API 对应三种不同的业务动作code/app.py提供三个主要端点。POST /applications接收business_key、customer_name、package_code返回新的申请 ID、实例 ID、待办 ID、SUBMITTED状态和材料版本。POST /tasks/{task_id}/decision接收APPROVE或REJECT与教学操作者字段返回新的实例状态和修订号。GET /applications/{application_id}返回申请、实例、任务列表及迁移历史。另有GET /healthz用于实验脚本等待数据库连接可用。FastAPI 的请求模型在边界上检查字符串是否为空、长度是否超限并把决定限定为枚举。它可处理参数解析和响应序列化但不会自动知道“这位运营是否真的有权批准 v1 材料”。业务检查仍在处理函数里数据库约束负责最后一道结构性保护。FastAPI 官方文档也说明其数据库层没有强制绑定某一种 ORM 或数据库本例直接使用 PostgreSQL 驱动与 SQL以便读者看清事务包含的每一步。FastAPI SQL 数据库教程提交端点会为申请、实例和待办生成独立 UUID。四条INSERT被放在同一连接的事务作用域内成功才提交同租户业务键冲突由 PostgreSQL 唯一约束产生再被 API 转换为 409。我们没有在发生冲突后偷偷新建另一个业务键也没有自动把重复输入解释为“用户想要一份新申请”。如果业务确实允许同一客户多次开通调用方应提供能区分不同申请的业务键。查询端点按申请 UUID 与固定教学租户读取资料和流程再从任务表、历史表读取关联记录。页面因此可以同时展示“当前状态”和“到达这个状态的路径”。只读接口对未知 UUID 返回 404这个错误与未授权用户应看到什么还没有关系因为本篇没有身份体系。正式系统还需避免通过不同错误码泄露其他租户申请是否存在。图 3三个 API 共同形成可复验的审批切片actor_id仍只是教学输入不能证明真实身份。四、审批事务先锁定责任再写入决定运营提交决定时API 不直接执行UPDATE workflow_instances SET stateAPPROVED。它先按任务 ID 查询任务、实例与申请使用SELECT ... FOR UPDATE OF t, i锁定任务和流程实例记录随后检查任务仍为OPEN、实例仍为SUBMITTED并且任务绑定的资料版本等于申请的当前版本。通过后才在同一事务中关闭任务、更新实例状态与修订号并追加迁移历史。PostgreSQL 的行锁使同一任务上同时到来的两笔决定请求先后处理。后到的一笔在前一笔提交后重新看到已完成的任务得到 409而不是覆盖第一笔结论。这是本篇针对同一任务重复决定的最小保护它还不是完整的并发设计。资料编辑、权限变更、不同任务关联同一申请等竞态都需要更细的约束与测试第 05 篇会专门展开。PostgreSQL 官方文档对SELECT FOR UPDATE的等待与行锁行为有详细说明。PostgreSQL 显式锁文档请注意“锁”的位置任务和实例在数据库事务里被锁住检查与写入在同一事务完成。若先查询OPEN释放连接再另开连接写入两位审批人仍有机会同时基于旧结果做决定。另一方面长时间持锁会拖慢其他请求本篇事务只处理数据库内的必要写入没有在锁内调用 ERP 或等待人工。之后接入外部系统时不应把远端 HTTP 请求放进持锁事务试图用本地行锁覆盖跨系统业务结果。代码片段保留了最关键的结构异常处理、查询语句和响应字段请看完整文件withconnection()asconn,conn:withconn.cursor()ascur:cur.execute(SELECT ... FOR UPDATE OF t, i,(task_id,))# 检查 OPEN、SUBMITTED、版本一致# 更新任务更新实例追加 transition_history这里的SELECT ...是为解释事务边界而省略列名的示意片段不可直接运行。完整可执行 SQL 位于code/app.py。当检查失败函数抛出 HTTP 409事务不会提交半套修改。数据库驱动连接用closing显式关闭避免请求结束后连接长期占用。教学项目每个请求新建连接易于看清生命周期高并发生产服务需要连接池、超时与容量配置但这些优化不应掩盖本篇的业务约束。图 4第二次决定看到任务已经完成后返回 409它不会产生第二条有效审批历史。有一个容易被误读的细节409 只表示这次命令没有被执行。如果第一次批准已经成功但浏览器没有收到响应用户再次点击得到 409调用方仍需要通过查询端点确认当前事实而不能根据 409 猜测第一次是成功还是失败。为了支持可靠重试第 06 篇会设计更明确的命令幂等键与结果查询语义。本篇先确保重复决定不会覆盖既有结论并把“不确定时查状态”纳入验收。五、从零运行项目先建库再启动 API完整目录含compose.yaml、schema.sql、init_db.py、app.py、smoke_test.py和依赖文件。若已有本地 PostgreSQL可设置DATABASE_URL指向自己的教学数据库下列命令默认使用隔离的 Docker Compose 数据库。密码acmeflow_demo_only只服务于本地样例不能复制到真实环境。cdcodedockercompose up-dpython-mpipinstall-rrequirements.txt python init_db.py python-muvicorn app:app--host127.0.0.1--port8000Windows PowerShell、macOS 与 Linux 的虚拟环境激活方式不同。为了不让一段正文变成平台命令百科code/README.md分别写出工作目录、环境变量和运行步骤。请使用隔离环境安装固定版本依赖运行结束后按 README 停止教学容器不要把示例密码或数据库端口暴露到公网。打开http://127.0.0.1:8000/docs可以看到 FastAPI 自动生成的 API 文档。先提交一条业务申请记下返回的application_id和task_id。用申请 ID 查询时应看到stateSUBMITTED、一项OPEN审核任务以及SUBMIT初始历史。再对任务发出APPROVE查询应变成stateAPPROVED、任务COMPLETED、revision2历史追加一条SUBMITTED → APPROVED。尝试对同一任务再发REJECT应得到 409原结论不变。你也可以直接运行python smoke_test.py。脚本会自行启动 Uvicorn、通过 HTTP 完成提交与审批、结束应用进程再重新启动并读取同一申请。它在每一步使用断言检查响应与持久状态最后停止它自己启动的进程。数据库仍由 Compose 或测试容器管理。脚本不是压测也没有验证多个机器同时审批它专门回答“应用重启以后任务和历史还在不在”。本次在本机运行时init_db.py读取到 PostgreSQL16.15 (Debian 16.15-1.pgdg132)。成功的 HTTP 实验创建了一份申请返回application_id5e2bf8b3-bd8b-415a-be71-0a844b7c2100。审批返回 200重复审批与重复业务键均返回 409。Uvicorn 进程停止、再次启动之后用同一 UUID 查询仍得到APPROVED、修订号 2、已完成的任务以及两条迁移记录。实际原始输出存于code/actual-output.txtUUID 是本次运行产生的样例值读者重新运行会获得不同编号。图 5图内申请 UUID 和结果来自本次真实smoke_test.py输出。数据库容器保持运行只有 Uvicorn 进程重启。这次实验说明当前设计至少跨过了第一道持久化门槛应用进程退出不会清空 PostgreSQL 里的申请、任务和历史。实验没有重启数据库容器也没有断电模拟、主从切换或磁盘损坏演练。持久化只是把状态存下来能否在复杂故障后正确继续还取决于下一步动作、外部副作用和恢复策略。后面的第 11 篇才系统讨论长期执行与重放。六、故障实验重复请求与“响应已经丢了”第一个故障实验是重复审批。先对一项开放任务提交APPROVE再对同一任务提交REJECT。第二次得到 409是因为数据库中的任务已完成实例已不在SUBMITTED。再次查询历史应仍然只有提交和批准两条而不是“先批准、后驳回”两项有效决定。对于用户界面409 不应只弹一个抽象错误它可以触发重新读取任务告知当前决定已经由哪个已记录的请求完成。不过本篇的完成者字段仍不具有真实身份可信度不能展示成合规审计结论。第二个故障实验是重复提交相同业务键。数据库的唯一约束让它返回 409。这个实验证明同一教学租户下不会因为简单重复提交产生第二张同业务键申请它没有证明所有重试语义都清楚。特别是第一次请求可能在数据库提交后丢失 HTTP 响应客户端并不知道申请 UUID。真实接口可以采用稳定请求键并返回同一结果或者提供按业务键查询已提交申请的授权接口。第 06 篇会把这一步做成明确的网络契约。第三个故障实验是应用重启。脚本在审批成功后先停止 Uvicorn再启动全新进程按原 UUID 查询。返回的任务完成状态与历史来自数据库读取而非 Python 内存列表因此可以证明这项结果跨过了应用进程边界。要更严格地检查你可以在两次启动之间用 PostgreSQL 客户端查询四张表的记录核对同一instance_id本篇的自动脚本已通过 API 查询并断言对应关系数据库只存一份事实来源。一个没有测试的情况同样值得写在验收里如果应用在数据库事务提交之后、HTTP 响应发出之前崩溃客户端重试会看到业务键冲突。系统没有丢数据但客户端暂时无法直接从这次 409 知道原申请 UUID。把这个窗口诚实标出来比宣称“用了 PostgreSQL 就完全可靠”更有价值。下一篇处理并发第 06 篇处理可靠投递和命令去重时都会回到它。1. 申请创建到一半失败会留下什么假设开发者在创建申请记录后构造待办时程序抛出异常。如果四次写入分别在四个自动提交连接上执行数据库里就可能存在一份没有流程实例、也没有处理人的孤儿申请。销售查询时会看到“已提交”运营待办列表却没有它。我们的提交处理把四条写入放进同一个事务异常使整笔事务回滚相同业务键随后可以重新提交。这里的判断依据不是应用日志中出现“rollback”字样而是再次查询数据库时申请、实例、待办、历史要么都存在要么都不存在。这种原子性并不意味着所有字段一定从一开始就完美。客户名称可能输入错误套餐编码也可能需要业务字典校验。数据库可以保证记录之间结构一致业务规则仍要逐项补充。因此本篇把套餐当作固定样例字符串不声称已经接入产品目录真实系统在提交边界还要确认套餐可售、客户有资格申请以及业务键来自可信上游。2. 审批成功但页面显示超时怎么办网络超时不告诉浏览器数据库有没有提交。运营看到转圈后再点一次按钮第二次可能得到 409。如果前端把所有 409 都显示成“你没有权限”会误导处理人如果前端自动改用另一个任务 ID 重试又可能制造更大混乱。合理的第一步是按任务或申请 ID 重新查询确认当前状态和历史。若历史显示该任务已由原请求完成就把这个结果展示出来若任务仍开放再允许一次明确的重试。要做到跨设备、跨进程追踪同一次命令还需要请求标识与幂等结果记录这是后续章节的任务。3. 数据库里有状态为什么仍不是持久工作流引擎当前 API 能在重启后回答“审批到了哪一步”因为状态与历史保存在数据库。但它还没有自动调度下一步也没有等待合同消息的订阅、失败任务的重试计划、超时计时器或运行中版本升级机制。把状态存入数据库是可靠流程的必要基础却不足以让所有长期动作自动继续。第 11 篇会用执行历史和恢复实验介绍专门的持久执行机制在那之前我们先把每种失败窗口通过普通数据库结构讲透。这也是为什么第 03 篇没有急着接 ERP。若把一个远端调用塞到当前审批事务的结尾读者可能误以为本地事务提交与远端创建服务记录可以共同回滚。实际上远端系统已经创建后本地事务仍可能失败。等到第 06 篇把投递与去重、以及第 10 篇把补偿与对账的边界建立起来再扩展跨系统动作读者才能清楚理解每一步究竟由哪种机制保证。七、验收标准与后续扩展位置本篇的验收不以“页面显示绿色成功”为准而以可以反复查询的数据库记录和 HTTP 结果为准。提交一次申请要同时能读到一张申请、一个实例、一项开放待办和起始历史完成审批后任务与实例须一致重复决定必须被拒绝重启 API 后原申请状态与历史仍可读。这四条检查了最小路径及两个常见故障窗口。图 6每行同时检查请求响应和业务状态。这里未把未来的签署、到账、ERP 与权益开通算入已实现能力。代码中的几个字段为后续章节留下稳定边界。material_version让审批绑定资料版本revision支持第 05 篇的并发控制实验business_key用于第 06 篇讨论重复提交instance_id让后续事件与人工任务能关联一次流程执行rule_version记录实例采用的规则。但“存在字段”不等于对应能力已经实现。我们现在仍没有修改资料的 API、没有签署或付款事实表、没有外部调用也没有真正的规则迁移策略。后续扩展应使用数据库迁移而不是要求读者删除本篇已有申请重新开始。新增事实、Outbox、Inbox、截止时间或任务领取字段都应说明旧实例该如何读取与继续。尤其不能在第 05 篇为了演示更复杂的锁把第 03 篇的状态意义全部换掉系列项目只有保持共同契约读者才能看见一个小系统如何逐步承受更真实的业务压力。还有一个检查比“接口返回 200”更接近真实运维拿一份申请询问另一位没有参与开发的同事请他只看查询响应复述当前是谁的责任、资料第几版、上一个决定是什么、下一步为何还不能执行。若他只能看到APPROVED却无法知道任务是否已关闭说明 API 的查询模型不够完整若他能看到任务和历史却不能解释签署与到账是否完成说明系统还缺外部事实记录。一个阶段的教学切片可以有未实现范围但必须能指出缺口在哪里。在数据库维护上也要分清“现在的数据”与“发生过的动作”。实例行适合列表查询和条件判断历史行适合时间线与争议复盘。不要仅凭历史最后一行推断全部当前业务事实也不要用覆盖实例状态的方式抹去过去的处理。若将来因修复错误需要更正决定应设计有授权、有原因、有新历史的修复命令而不是让管理员在数据库里把两张表改到看似一致。第 16 篇会把这种受控实例修复放进故障处置手册。对于阅读代码的读者建议顺着一份申请执行一次数据库查询先找applications的 UUID 与业务键再用外键找到workflow_instances接着按实例 ID 查看任务与历史。尝试只删除或篡改其中一项会发现有些错误受到外键和检查约束阻止有些逻辑错误仍需要应用规则发现。这正是数据库约束的实际位置它替所有写入路径守住基础结构却不能理解“这位审核员是否看过正确的合同”。把基础结构与业务判断都说清楚后面的并发和事件实验才有可靠起点。如果你准备把这份教程改造成自己的项目还要先回答数据保留时间。客户申请、审批历史与外部回执可能有不同的保留要求不能简单地在 API 中增加DELETE /applications/{id}就让级联删除把流程解释依据一并抹去。此处我们没有开放删除端点原因是当前课程尚未定义撤回、归档和依法删除的业务语义。后续真正需要处理资料清除时应同时考虑实例是否仍在运行、审计需要保留什么、外部系统已经产生什么效果。Workflow Thinking为什么一开始要存迁移历史而不等上线以后再补因为审批争议发生时事后补写的“历史”无法可靠还原当时的命令、版本和决定。初始流程很短记录历史只增加一张表和每次事务中的一次写入却让后续调试、用户说明与故障复盘有了共同时间线。它不是完整审计方案但比只存当前状态更容易解释业务发生过什么。下一篇将用同一份客户开通案例对照状态机与 BPMN。那时会出现签署和到账两条并行等待路径并明确说明图上的并行汇合只是模型语义先于等待节点到达的外部事实仍需由事件入口保存和正确关联。