这次我们来看一个发布在 Hacker News 的 PostgreSQL 生态新项目Interlock。它想做的一件事很聚焦在 PostgreSQL 上用 TypeScript 写出“原子化”的领域状态迁移规则。如果你正在做领域驱动设计DDD或者经常处理订单状态、审批流程、任务状态这类需要严格状态流转的业务这个项目值得关注。先快速给结论。Interlock 的核心卖点不是又一个 ORM也不是简单的状态机库而是把“状态迁移逻辑”下沉到 PostgreSQL 事务里用 TypeScript 的类型系统约束迁移规则靠数据库事务保证原子性。也就是说状态变更要么全部生效要么全部回滚不会出现中间态。同时迁移规则是用 TypeScript 写的能拿到类型检查和 IDE 提示而不是散落在 SQL 里的复杂 CASE WHEN。本文不会只是介绍概念。后面会按“项目定位 - 设计思路 - 环境准备 - 安装启动 - 功能验证 - API 与批量任务 - 性能观察 - 排错 - 最佳实践”的顺序走一遍最后给出一套可以直接落地的验证流程。适合这几类读者正在用 TypeScript PostgreSQL 做后端开发的团队、受够了状态机状态散落各处的同学、以及想在数据库事务层面保证领域一致性的架构师。1. 核心能力速览能力项说明项目定位在 PostgreSQL 上执行 TypeScript 编写的原子化领域状态迁移库核心机制通过数据库事务保证状态迁移原子性通过 TypeScript 类型保证迁移规则可检查编程语言TypeScript / Node.js 环境目标数据库为 PostgreSQL状态迁移方式声明式定义领域状态、事件、转移规则原子性保障基于 PostgreSQL 事务出错自动回滚是否支持接口 API从项目形态看更偏向库集成可封装为 REST/gRPC 服务具体 API 需按实际实现确认是否支持批量任务可以通过循环或批量接口对多个领域对象执行迁移需要自行设计批处理边界是否依赖特定 PostgreSQL 版本一般建议 PostgreSQL 12具体以项目 README 为准适合场景订单状态机、审批流、任务调度、文档生命周期管理、审计追踪不适合场景简单 CRUD、不需要状态约束的纯数据存储、需要跨数据库迁移的业务注意一点由于项目本身信息有限上面表格里的“推荐 PostgreSQL 版本”“是否支持 API”属于保守判断。真正落地前请以你拉下来的项目 README 和源码为准。下面展开讲设计思路和落地步骤。2. 为什么需要 Atomic Domain Transitions在传统业务系统里状态流转最常见的写法是这样某个字段存储当前状态比如 order 表的 status。接口层判断当前状态是否允许迁移到目标状态。更新数据库中的状态字段。表面看没问题但真实业务里会有几个隐患。第一个隐患是“状态判断和状态更新不是原子的”。两个并发请求同时读到订单是pending一个要改成paid一个要改成canceled如果代码没有行锁或乐观锁后写的人会把别人改好的状态覆盖掉。更麻烦的是从pending到paid可能需要同时更新库存表、写流水表、发消息这些操作必须绑定在同一个事务里否则就会出现“订单已支付但库存没扣”这种对不上的数据。第二个隐患是“状态迁移规则散落”。今天在接口里写一个if (order.status pending)明天在后台任务里又写一个类似的判断。状态一多迁移路径越来越多根本看不出一个领域对象从创建到终止到底经历了哪些合法路径。第三个隐患是“类型不可检查”。用字符串代表状态pendng和pending在编译器眼里没区别直到线上才炸。Interlock 想解决的正是这个问题。它把状态机和迁移逻辑提升为代码中的一等公民并且让每一步迁移最终落到 PostgreSQL 事务里执行。这样状态流转路径是显式的、类型安全的、并且是原子的。用数据库事务去做状态迁移并不是新鲜事但 Interlock 的价值在于把“状态迁移”这个领域概念和“事务”这个基础设施概念黏合起来再通过 TypeScript 类型系统让非法迁移在编译期就被拦下来。这个思路比在业务代码里到处写 if/else 要更工程化。3. 核心设计思路从项目名称Interlock可以得到一个很强的画面像机械联锁装置一样只有当当前状态满足特定条件时才能切换到下一个状态。每个状态转换都需要“解锁条件”并且这些条件在数据库事务中被校验和提交。大致可以拆成四层。3.1 领域模型层用 TypeScript 定义领域状态典型写法可能是枚举或字面量联合类型// 通用示例实际接口名需要按项目 README 调整 export type OrderStatus | created | pending_payment | paid | shipped | completed | canceled;3.2 迁移规则层定义从哪个状态可以迁移到哪个状态。这里最容易联想到类似Fsm.define的 API// 通用示例Interlock 的具体 API 以源码为准 import { defineTransitions } from interlock; export const orderTransitions defineTransitionsOrderStatus() .from(created).to(pending_payment) .from(pending_payment).to(paid) .from(pending_payment).to(canceled) .from(paid).to(shipped) .from(shipped).to(completed) .build();类型系统会保证你写了一个不存在的状态名编译直接报错你写了一条非法迁移路径也有机会在编译期提示。3.3 事务执行层迁移不是直接 UPDATE 一个字段而是通过一个带事务的函数执行。大致逻辑如下开启事务。根据主键锁定目标行SELECT ... FOR UPDATE或者使用乐观锁版本号。读取当前状态。检查当前状态是否允许迁移到目标状态。执行领域事件副作用写审计表、更新关联表、发消息。更新状态。提交事务。任何一步抛错就回滚。这层最终拼接到 PostgreSQL通常会用pg或类似驱动再配合 SQL 事务语句。3.4 审计与可追溯层状态变更往往需要审计。Interlock 类的设计一般会在同一事务里插入一条 transition log记录领域对象 ID。原状态。目标状态。操作人/系统。迁移时间。业务上下文 JSON。这样每次状态变化都能回溯且与状态更新共用事务不会出现“状态改了但审计日志丢了”的问题。4. 环境准备与前置条件无论 Interlock 具体怎么安装你都至少需要准备以下环境依赖版本建议说明Node.js18 或 20 LTSTypeScript 项目的常用运行时TypeScript5.x确保类型系统完整PostgreSQL12事务、行锁、审计表支持npm / pnpm / yarn任意包管理工具Docker可选用于快速启动 PostgreSQL 测试实例如果你本地还没有 PostgreSQL最省事的方式是用 Docker 拉一个测试实例# 快速启动一个 PostgreSQL 测试实例密码和端口按实际需要修改 docker run --name interlock-pg \ -e POSTGRES_PASSWORDpostgres \ -e POSTGRES_DBinterlock \ -p 5432:5432 \ -d postgres:16等容器启动后可以先用psql验证连接是否正常psql -h 127.0.0.1 -p 5432 -U postgres -d interlock连接成功后再看项目要求。如果项目使用pg驱动连接字符串一般在环境变量里配置。常见做法是创建一个.env文件DATABASE_URLpostgres://postgres:postgres127.0.0.1:5432/interlock端口占用时记得把宿主机端口改成 5433、5434 之类的空闲端口避免和本地已有 PostgreSQL 冲突。5. 安装部署与启动方式Interlock 是库还是完整应用目前只能从项目名 “Show HN” 推断是一个开源库。安装方式大概率是 npm 依赖。如果它已经发布到 npm安装命令应该是npm install interlock # 或者 pnpm add interlock如果没有发布到 npm而是需要从源码构建一般流程是git clone 项目仓库地址 cd interlock npm install npm run build这一步要先看项目根目录的package.json和README。常见的启动或测试脚本是# 运行测试验证核心迁移逻辑 npm test # 开发模式执行示例 npm run dev这里需要特别说明如果材料里没有给出确切的命令请以实际 README 为准。我上面给的是通用模板不是 Interlock 官方命令。更稳妥的判断是先cat package.json看 scripts 字段再决定执行哪个命令。项目跑起来后一般会提供两种使用方式在你的业务项目里引入 Interlock作为状态迁移库。运行项目自带示例代码观察数据库里的状态变化和审计日志。如果你希望把 Interlock 封装成一个 HTTP 服务可以自己写一个 Express/Fastify 路由对外暴露 POST /transitions 接口具体见第 6 节。6. 功能测试与效果验证这一节我们走一遍“定义状态 - 定义迁移 - 执行迁移 - 验证回滚”的完整流程。因为 Interlock 的具体 API 未公开下面代码是概念演示重点看逻辑不是复制就能跑。6.1 定义领域状态和迁移规则// domain/order.ts export type OrderStatus | created | pending_payment | paid | shipped | completed | canceled; export const transitions { created: [pending_payment], pending_payment: [paid, canceled], paid: [shipped], shipped: [completed], completed: [], canceled: [], } as const;这个表达足够直观。接下来的重点是如何在事务中执行而不是单纯写一个查表函数。6.2 执行一次状态迁移假设你拿到了一个连接池并封装了一个transitionOrder函数// 伪代码用于演示 Interlock 类项目的执行逻辑 import { Pool } from pg; const pool new Pool({ connectionString: process.env.DATABASE_URL }); export async function transitionOrder(orderId: string, toStatus: string, actor: string) { const client await pool.connect(); try { await client.query(BEGIN); // 锁定目标行防止并发迁移 const { rows } await client.query( SELECT id, status FROM orders WHERE id $1 FOR UPDATE, [orderId] ); const order rows[0]; if (!order) { throw new Error(order not found); } // 校验迁移路径 const allowed transitions[order.status as keyof typeof transitions]; if (!allowed.includes(toStatus as any)) { throw new Error(Illegal transition from ${order.status} to ${toStatus}); } // 写入审计日志与状态更新同一事务 await client.query( INSERT INTO order_transitions (order_id, from_status, to_status, actor) VALUES ($1, $2, $3, $4), [orderId, order.status, toStatus, actor] ); // 更新状态 await client.query( UPDATE orders SET status $1, updated_at now() WHERE id $2, [toStatus, orderId] ); await client.query(COMMIT); return { ok: true, from: order.status, to: toStatus }; } catch (err) { await client.query(ROLLBACK); throw err; } finally { client.release(); } }这段代码就是 Interlock 想自动化和类型化的东西。它包含三个关键点迁移前用FOR UPDATE锁行避免并发覆盖。校验逻辑放在应用层但仍然在事务里。审计日志和状态更新必须同生共死。Interlock 如果落地它内部应该就是把这段模板封装好并且把transitions表驱动和 TypeScript 类型绑定在一起。6.3 测试原子性故意构造失败验证这个项目是否靠谱最直接的办法是造一个必然失败的迁移。比如创建订单状态为created。尝试从created直接迁移到paid。预期行为迁移失败数据库回滚订单状态仍然是created。再测试一批并发迁移同时发起两条迁移请求pending_payment - paid和pending_payment - canceled。预期行为只有一条成功另一条要么阻塞后失败要么因状态已变化而失败。成功的那条会写入一条 transition log失败的那条不会留下状态残留。如果项目自带了测试套件先运行npm test如果没有用上面的思路写一个集成测试。6.4 判断成功标准状态字段符合预期。每次合法迁移都能查到对应的审计日志。非法迁移不会改变任何数据。并发迁移不会产生脏状态。事务回滚后关联业务表例如扣库存、积分变更也不会残留脏数据。7. 接口 API 与批量任务Interlock 如果只作为库使用它不一定自带 HTTP 接口。但从工程化角度看你大概率会把它封装成一个内部服务或者直接在现有后端中调用。7.1 把状态迁移封装成 API如果你用 Express 或 Fastify可以这样封装import express from express; import { transitionOrder } from ./domain/order; const app express(); app.use(express.json()); app.post(/orders/:id/transition, async (req, res) { const { toStatus } req.body; const actor req.headers[x-user-id] ?? system; try { const result await transitionOrder(req.params.id, toStatus, actor); res.json(result); } catch (err) { res.status(400).json({ error: (err as Error).message }); } }); app.listen(3001, () { console.log(api listening on :3001); });用 curl 验证curl -X POST http://127.0.0.1:3001/orders/123/transition \ -H Content-Type: application/json \ -H x-user-id: system \ -d {toStatus: paid}注意toStatus在真实项目中应该也用 TypeScript 类型校验防止任意字符串传入。7.2 批量状态迁移批量任务比单条迁移更容易踩坑。常见的需求是某个活动结束后把所有pending_payment的订单统一标记为canceled。如果直接用一条UPDATE ... SET status canceled WHERE status pending_payment确实快但会丢失审计日志而且没有按对象维度校验迁移合法性。更合理的方式是分批处理// 伪代码批量迁移需要设计好边界不要一次性处理过多数据 async function batchTransition(orderIds: string[], toStatus: string, actor: string) { const results []; for (const id of orderIds) { try { const result await transitionOrder(id, toStatus, actor); results.push({ id, ok: true, ...result }); } catch (err) { results.push({ id, ok: false, error: (err as Error).message }); } } return results; }如果要追求高吞吐可以把单条事务改成一次事务里处理多行但复杂度会上升。建议第一次实现时先一条一个事务确认逻辑正确后再考虑批量优化。批量任务要额外写入日志记录每一条失败原因。如果中途崩溃至少能知道已经处理到哪一批。8. 资源占用与性能观察Interlock 这类基于事务的状态迁移项目性能瓶颈通常不在代码而在数据库。8.1 显存、内存、CPU这个项目不涉及 GPU也没有显存占用问题。要观察的是Node.js 进程的内存占用。PostgreSQL 的连接数。PostgreSQL 在锁等待时的连接状态。8.2 事务吞吐量每次迁移至少包含SELECT 锁行、INSERT 审计、UPDATE 状态、COMMIT。如果每单都串行执行吞吐量会有上限。观察方法-- 查看当前数据库活动会话 SELECT pid, state, wait_event_type, wait_event, query FROM pg_stat_activity WHERE datname interlock;如果大量 session 处于Lock等待状态说明并发迁移同一行时产生了锁竞争。锁竞争不一定是坏事反而说明原子性在起作用。8.3 如何降低锁冲突减少单行锁持有时间把事务里的无关操作移出去。使用短事务不要在一个迁移事务里做外部 HTTP 调用。如果业务允许把同一类对象的迁移串行化避免争抢。批量任务避免多个 worker 同时处理同一批订单。8.4 观察连接池Node.js 的pg连接池默认max是 10。一旦并发超过连接数后续请求会排队。观察方式// 连接池事件日志仅在调试时使用 pool.on(acquire, () { console.log(client acquired, total count:, pool.totalCount); });实际生产环境要根据 PostgreSQLmax_connections和业务并发量调整连接池大小一般建议连接数不要超过数据库连接总数的 20%。9. 常见问题与排查方法问题现象可能原因排查方式解决方案安装依赖时报 TypeScript 类型错误本地 TypeScript 版本过低或过高查看报错栈中的类型定义文件将 TypeScript 版本对齐到项目peerDependencies要求连接 PostgreSQL 超时数据库未启动、端口不对、连接串错误psql测试连接检查.env修正DATABASE_URL确认容器或本地服务在运行迁移时报Illegal transition状态路径未定义或当前状态已变化打印迁移前状态和允许路径检查transitions定义事务回滚了但业务代码报错某个副作用抛错整体回滚查看服务端日志错误堆栈让副作用的错误在事务内抛出或调整副作用顺序并发迁移出现could not serialize access使用了可重复读/序列化隔离级别或唯一约束冲突查看 PostgreSQL 日志加锁重试或改用 READ COMMITTED批量任务突然卡住某个事务长时间持有行锁查询pg_stat_activity的wait_event终止长时间事务优化批量粒度审计日志突然变多每次迁移都记录查看日志表总量定期归档或联表查询时加索引发布新迁移规则后旧的非法迁移还能通过配置缓存未刷新确认规则是构建时生成还是运行时读取更新后重启进程或刷新配置如果遇到cache lookup failed for type这类 PostgreSQL 报错通常不是 Interlock 本身的问题而更可能是迁移数据库时类型定义不一致。可以先检查 PostgreSQL 的类型缓存重建涉及的对象或者重启 PostgreSQL 连接后重新执行。10. 最佳实践与使用建议10.1 第一次使用先小范围验证不要一上来就把所有业务状态机迁到 Interlock 上。选一个核心且简单的状态机比如“订单支付状态”先跑通。验证原子性、审计、类型检查三个能力后再横向推广。10.2 状态定义和迁移规则集中管理把领域状态和迁移规则全部放在domain目录下不要分散到多个 service 里。这样团队里每个人查状态机只需要看一个文件。10.3 事务里不要做外部 I/O事务内调用短信、邮件、外部 HTTP 接口一旦接口慢整个事务就会长时间持锁。正确做法是事务内只写数据库和发送内部消息或者先改状态再通过 outbox 模式发异步通知。10.4 建立审计表索引审计日志会越积越多。常用查询条件是order_id和created_at要给这两个字段建组合索引避免全表扫描。CREATE INDEX idx_order_transitions_order_created ON order_transitions (order_id, created_at);10.5 权限与授权边界状态迁移往往意味着业务权限变化。如果 Interlock 支持传入 actor 或 operator 字段务必在接口层做鉴权不要让调用方任意指定操作人。涉及用户数据、人脸、声音等敏感信息时必须遵守隐私保护要求确保授权链路清晰。10.6 保留一套最小可运行配置在项目目录下放一个docker-compose.yml让新成员能一条命令启动 PostgreSQLversion: 3 services: postgres: image: postgres:16 container_name: interlock-pg environment: POSTGRES_PASSWORD: postgres POSTGRES_DB: interlock ports: - 5432:5432 volumes: - pgdata:/var/lib/postgresql/data volumes: pgdata:这个配置只用于本地开发测试。生产环境务必设置强密码、开启 TLS、限制访问来源不要暴露到公网。11. 总结与下一步Interlock 这个项目最值得尝试的点是它把领域状态迁移从“业务代码里的散装 if/else”提升到了“数据库事务 TypeScript 类型”的工程化层面。如果它能顺利跑通你至少能得到三样东西非法迁移的编译期检查、状态变更的原子性、可审计的迁移轨迹。第一次上手时最先验证的应该是原子回滚造一个必然失败的迁移看数据库状态是否真的没有变化。最容易踩的坑有两个一个是把事务写得太长导致锁竞争另一个是迁移规则和实际代码不同步。如果你平时已经在用 TypeScript PostgreSQL并且手头正好有一个状态机需求可以把这个项目拉下来对照 README 里的示例跑一遍。也可以基于它的设计思路自己实现一个只覆盖核心场景的版本毕竟状态迁移的核心逻辑并不复杂。后续可以继续扩展的方向包括把迁移规则可视化导出、接入消息队列处理事务后的领域事件、增加乐观锁版本控制、生成状态机文档、对接 Apollo/GraphQL。希望这个项目能给你的领域建模带来一点新的思路。建议收藏备用等你有状态流转需求的时候再拿出来对照验证。
Interlock：用TypeScript在PostgreSQL事务中实现原子化状态迁移
这次我们来看一个发布在 Hacker News 的 PostgreSQL 生态新项目Interlock。它想做的一件事很聚焦在 PostgreSQL 上用 TypeScript 写出“原子化”的领域状态迁移规则。如果你正在做领域驱动设计DDD或者经常处理订单状态、审批流程、任务状态这类需要严格状态流转的业务这个项目值得关注。先快速给结论。Interlock 的核心卖点不是又一个 ORM也不是简单的状态机库而是把“状态迁移逻辑”下沉到 PostgreSQL 事务里用 TypeScript 的类型系统约束迁移规则靠数据库事务保证原子性。也就是说状态变更要么全部生效要么全部回滚不会出现中间态。同时迁移规则是用 TypeScript 写的能拿到类型检查和 IDE 提示而不是散落在 SQL 里的复杂 CASE WHEN。本文不会只是介绍概念。后面会按“项目定位 - 设计思路 - 环境准备 - 安装启动 - 功能验证 - API 与批量任务 - 性能观察 - 排错 - 最佳实践”的顺序走一遍最后给出一套可以直接落地的验证流程。适合这几类读者正在用 TypeScript PostgreSQL 做后端开发的团队、受够了状态机状态散落各处的同学、以及想在数据库事务层面保证领域一致性的架构师。1. 核心能力速览能力项说明项目定位在 PostgreSQL 上执行 TypeScript 编写的原子化领域状态迁移库核心机制通过数据库事务保证状态迁移原子性通过 TypeScript 类型保证迁移规则可检查编程语言TypeScript / Node.js 环境目标数据库为 PostgreSQL状态迁移方式声明式定义领域状态、事件、转移规则原子性保障基于 PostgreSQL 事务出错自动回滚是否支持接口 API从项目形态看更偏向库集成可封装为 REST/gRPC 服务具体 API 需按实际实现确认是否支持批量任务可以通过循环或批量接口对多个领域对象执行迁移需要自行设计批处理边界是否依赖特定 PostgreSQL 版本一般建议 PostgreSQL 12具体以项目 README 为准适合场景订单状态机、审批流、任务调度、文档生命周期管理、审计追踪不适合场景简单 CRUD、不需要状态约束的纯数据存储、需要跨数据库迁移的业务注意一点由于项目本身信息有限上面表格里的“推荐 PostgreSQL 版本”“是否支持 API”属于保守判断。真正落地前请以你拉下来的项目 README 和源码为准。下面展开讲设计思路和落地步骤。2. 为什么需要 Atomic Domain Transitions在传统业务系统里状态流转最常见的写法是这样某个字段存储当前状态比如 order 表的 status。接口层判断当前状态是否允许迁移到目标状态。更新数据库中的状态字段。表面看没问题但真实业务里会有几个隐患。第一个隐患是“状态判断和状态更新不是原子的”。两个并发请求同时读到订单是pending一个要改成paid一个要改成canceled如果代码没有行锁或乐观锁后写的人会把别人改好的状态覆盖掉。更麻烦的是从pending到paid可能需要同时更新库存表、写流水表、发消息这些操作必须绑定在同一个事务里否则就会出现“订单已支付但库存没扣”这种对不上的数据。第二个隐患是“状态迁移规则散落”。今天在接口里写一个if (order.status pending)明天在后台任务里又写一个类似的判断。状态一多迁移路径越来越多根本看不出一个领域对象从创建到终止到底经历了哪些合法路径。第三个隐患是“类型不可检查”。用字符串代表状态pendng和pending在编译器眼里没区别直到线上才炸。Interlock 想解决的正是这个问题。它把状态机和迁移逻辑提升为代码中的一等公民并且让每一步迁移最终落到 PostgreSQL 事务里执行。这样状态流转路径是显式的、类型安全的、并且是原子的。用数据库事务去做状态迁移并不是新鲜事但 Interlock 的价值在于把“状态迁移”这个领域概念和“事务”这个基础设施概念黏合起来再通过 TypeScript 类型系统让非法迁移在编译期就被拦下来。这个思路比在业务代码里到处写 if/else 要更工程化。3. 核心设计思路从项目名称Interlock可以得到一个很强的画面像机械联锁装置一样只有当当前状态满足特定条件时才能切换到下一个状态。每个状态转换都需要“解锁条件”并且这些条件在数据库事务中被校验和提交。大致可以拆成四层。3.1 领域模型层用 TypeScript 定义领域状态典型写法可能是枚举或字面量联合类型// 通用示例实际接口名需要按项目 README 调整 export type OrderStatus | created | pending_payment | paid | shipped | completed | canceled;3.2 迁移规则层定义从哪个状态可以迁移到哪个状态。这里最容易联想到类似Fsm.define的 API// 通用示例Interlock 的具体 API 以源码为准 import { defineTransitions } from interlock; export const orderTransitions defineTransitionsOrderStatus() .from(created).to(pending_payment) .from(pending_payment).to(paid) .from(pending_payment).to(canceled) .from(paid).to(shipped) .from(shipped).to(completed) .build();类型系统会保证你写了一个不存在的状态名编译直接报错你写了一条非法迁移路径也有机会在编译期提示。3.3 事务执行层迁移不是直接 UPDATE 一个字段而是通过一个带事务的函数执行。大致逻辑如下开启事务。根据主键锁定目标行SELECT ... FOR UPDATE或者使用乐观锁版本号。读取当前状态。检查当前状态是否允许迁移到目标状态。执行领域事件副作用写审计表、更新关联表、发消息。更新状态。提交事务。任何一步抛错就回滚。这层最终拼接到 PostgreSQL通常会用pg或类似驱动再配合 SQL 事务语句。3.4 审计与可追溯层状态变更往往需要审计。Interlock 类的设计一般会在同一事务里插入一条 transition log记录领域对象 ID。原状态。目标状态。操作人/系统。迁移时间。业务上下文 JSON。这样每次状态变化都能回溯且与状态更新共用事务不会出现“状态改了但审计日志丢了”的问题。4. 环境准备与前置条件无论 Interlock 具体怎么安装你都至少需要准备以下环境依赖版本建议说明Node.js18 或 20 LTSTypeScript 项目的常用运行时TypeScript5.x确保类型系统完整PostgreSQL12事务、行锁、审计表支持npm / pnpm / yarn任意包管理工具Docker可选用于快速启动 PostgreSQL 测试实例如果你本地还没有 PostgreSQL最省事的方式是用 Docker 拉一个测试实例# 快速启动一个 PostgreSQL 测试实例密码和端口按实际需要修改 docker run --name interlock-pg \ -e POSTGRES_PASSWORDpostgres \ -e POSTGRES_DBinterlock \ -p 5432:5432 \ -d postgres:16等容器启动后可以先用psql验证连接是否正常psql -h 127.0.0.1 -p 5432 -U postgres -d interlock连接成功后再看项目要求。如果项目使用pg驱动连接字符串一般在环境变量里配置。常见做法是创建一个.env文件DATABASE_URLpostgres://postgres:postgres127.0.0.1:5432/interlock端口占用时记得把宿主机端口改成 5433、5434 之类的空闲端口避免和本地已有 PostgreSQL 冲突。5. 安装部署与启动方式Interlock 是库还是完整应用目前只能从项目名 “Show HN” 推断是一个开源库。安装方式大概率是 npm 依赖。如果它已经发布到 npm安装命令应该是npm install interlock # 或者 pnpm add interlock如果没有发布到 npm而是需要从源码构建一般流程是git clone 项目仓库地址 cd interlock npm install npm run build这一步要先看项目根目录的package.json和README。常见的启动或测试脚本是# 运行测试验证核心迁移逻辑 npm test # 开发模式执行示例 npm run dev这里需要特别说明如果材料里没有给出确切的命令请以实际 README 为准。我上面给的是通用模板不是 Interlock 官方命令。更稳妥的判断是先cat package.json看 scripts 字段再决定执行哪个命令。项目跑起来后一般会提供两种使用方式在你的业务项目里引入 Interlock作为状态迁移库。运行项目自带示例代码观察数据库里的状态变化和审计日志。如果你希望把 Interlock 封装成一个 HTTP 服务可以自己写一个 Express/Fastify 路由对外暴露 POST /transitions 接口具体见第 6 节。6. 功能测试与效果验证这一节我们走一遍“定义状态 - 定义迁移 - 执行迁移 - 验证回滚”的完整流程。因为 Interlock 的具体 API 未公开下面代码是概念演示重点看逻辑不是复制就能跑。6.1 定义领域状态和迁移规则// domain/order.ts export type OrderStatus | created | pending_payment | paid | shipped | completed | canceled; export const transitions { created: [pending_payment], pending_payment: [paid, canceled], paid: [shipped], shipped: [completed], completed: [], canceled: [], } as const;这个表达足够直观。接下来的重点是如何在事务中执行而不是单纯写一个查表函数。6.2 执行一次状态迁移假设你拿到了一个连接池并封装了一个transitionOrder函数// 伪代码用于演示 Interlock 类项目的执行逻辑 import { Pool } from pg; const pool new Pool({ connectionString: process.env.DATABASE_URL }); export async function transitionOrder(orderId: string, toStatus: string, actor: string) { const client await pool.connect(); try { await client.query(BEGIN); // 锁定目标行防止并发迁移 const { rows } await client.query( SELECT id, status FROM orders WHERE id $1 FOR UPDATE, [orderId] ); const order rows[0]; if (!order) { throw new Error(order not found); } // 校验迁移路径 const allowed transitions[order.status as keyof typeof transitions]; if (!allowed.includes(toStatus as any)) { throw new Error(Illegal transition from ${order.status} to ${toStatus}); } // 写入审计日志与状态更新同一事务 await client.query( INSERT INTO order_transitions (order_id, from_status, to_status, actor) VALUES ($1, $2, $3, $4), [orderId, order.status, toStatus, actor] ); // 更新状态 await client.query( UPDATE orders SET status $1, updated_at now() WHERE id $2, [toStatus, orderId] ); await client.query(COMMIT); return { ok: true, from: order.status, to: toStatus }; } catch (err) { await client.query(ROLLBACK); throw err; } finally { client.release(); } }这段代码就是 Interlock 想自动化和类型化的东西。它包含三个关键点迁移前用FOR UPDATE锁行避免并发覆盖。校验逻辑放在应用层但仍然在事务里。审计日志和状态更新必须同生共死。Interlock 如果落地它内部应该就是把这段模板封装好并且把transitions表驱动和 TypeScript 类型绑定在一起。6.3 测试原子性故意构造失败验证这个项目是否靠谱最直接的办法是造一个必然失败的迁移。比如创建订单状态为created。尝试从created直接迁移到paid。预期行为迁移失败数据库回滚订单状态仍然是created。再测试一批并发迁移同时发起两条迁移请求pending_payment - paid和pending_payment - canceled。预期行为只有一条成功另一条要么阻塞后失败要么因状态已变化而失败。成功的那条会写入一条 transition log失败的那条不会留下状态残留。如果项目自带了测试套件先运行npm test如果没有用上面的思路写一个集成测试。6.4 判断成功标准状态字段符合预期。每次合法迁移都能查到对应的审计日志。非法迁移不会改变任何数据。并发迁移不会产生脏状态。事务回滚后关联业务表例如扣库存、积分变更也不会残留脏数据。7. 接口 API 与批量任务Interlock 如果只作为库使用它不一定自带 HTTP 接口。但从工程化角度看你大概率会把它封装成一个内部服务或者直接在现有后端中调用。7.1 把状态迁移封装成 API如果你用 Express 或 Fastify可以这样封装import express from express; import { transitionOrder } from ./domain/order; const app express(); app.use(express.json()); app.post(/orders/:id/transition, async (req, res) { const { toStatus } req.body; const actor req.headers[x-user-id] ?? system; try { const result await transitionOrder(req.params.id, toStatus, actor); res.json(result); } catch (err) { res.status(400).json({ error: (err as Error).message }); } }); app.listen(3001, () { console.log(api listening on :3001); });用 curl 验证curl -X POST http://127.0.0.1:3001/orders/123/transition \ -H Content-Type: application/json \ -H x-user-id: system \ -d {toStatus: paid}注意toStatus在真实项目中应该也用 TypeScript 类型校验防止任意字符串传入。7.2 批量状态迁移批量任务比单条迁移更容易踩坑。常见的需求是某个活动结束后把所有pending_payment的订单统一标记为canceled。如果直接用一条UPDATE ... SET status canceled WHERE status pending_payment确实快但会丢失审计日志而且没有按对象维度校验迁移合法性。更合理的方式是分批处理// 伪代码批量迁移需要设计好边界不要一次性处理过多数据 async function batchTransition(orderIds: string[], toStatus: string, actor: string) { const results []; for (const id of orderIds) { try { const result await transitionOrder(id, toStatus, actor); results.push({ id, ok: true, ...result }); } catch (err) { results.push({ id, ok: false, error: (err as Error).message }); } } return results; }如果要追求高吞吐可以把单条事务改成一次事务里处理多行但复杂度会上升。建议第一次实现时先一条一个事务确认逻辑正确后再考虑批量优化。批量任务要额外写入日志记录每一条失败原因。如果中途崩溃至少能知道已经处理到哪一批。8. 资源占用与性能观察Interlock 这类基于事务的状态迁移项目性能瓶颈通常不在代码而在数据库。8.1 显存、内存、CPU这个项目不涉及 GPU也没有显存占用问题。要观察的是Node.js 进程的内存占用。PostgreSQL 的连接数。PostgreSQL 在锁等待时的连接状态。8.2 事务吞吐量每次迁移至少包含SELECT 锁行、INSERT 审计、UPDATE 状态、COMMIT。如果每单都串行执行吞吐量会有上限。观察方法-- 查看当前数据库活动会话 SELECT pid, state, wait_event_type, wait_event, query FROM pg_stat_activity WHERE datname interlock;如果大量 session 处于Lock等待状态说明并发迁移同一行时产生了锁竞争。锁竞争不一定是坏事反而说明原子性在起作用。8.3 如何降低锁冲突减少单行锁持有时间把事务里的无关操作移出去。使用短事务不要在一个迁移事务里做外部 HTTP 调用。如果业务允许把同一类对象的迁移串行化避免争抢。批量任务避免多个 worker 同时处理同一批订单。8.4 观察连接池Node.js 的pg连接池默认max是 10。一旦并发超过连接数后续请求会排队。观察方式// 连接池事件日志仅在调试时使用 pool.on(acquire, () { console.log(client acquired, total count:, pool.totalCount); });实际生产环境要根据 PostgreSQLmax_connections和业务并发量调整连接池大小一般建议连接数不要超过数据库连接总数的 20%。9. 常见问题与排查方法问题现象可能原因排查方式解决方案安装依赖时报 TypeScript 类型错误本地 TypeScript 版本过低或过高查看报错栈中的类型定义文件将 TypeScript 版本对齐到项目peerDependencies要求连接 PostgreSQL 超时数据库未启动、端口不对、连接串错误psql测试连接检查.env修正DATABASE_URL确认容器或本地服务在运行迁移时报Illegal transition状态路径未定义或当前状态已变化打印迁移前状态和允许路径检查transitions定义事务回滚了但业务代码报错某个副作用抛错整体回滚查看服务端日志错误堆栈让副作用的错误在事务内抛出或调整副作用顺序并发迁移出现could not serialize access使用了可重复读/序列化隔离级别或唯一约束冲突查看 PostgreSQL 日志加锁重试或改用 READ COMMITTED批量任务突然卡住某个事务长时间持有行锁查询pg_stat_activity的wait_event终止长时间事务优化批量粒度审计日志突然变多每次迁移都记录查看日志表总量定期归档或联表查询时加索引发布新迁移规则后旧的非法迁移还能通过配置缓存未刷新确认规则是构建时生成还是运行时读取更新后重启进程或刷新配置如果遇到cache lookup failed for type这类 PostgreSQL 报错通常不是 Interlock 本身的问题而更可能是迁移数据库时类型定义不一致。可以先检查 PostgreSQL 的类型缓存重建涉及的对象或者重启 PostgreSQL 连接后重新执行。10. 最佳实践与使用建议10.1 第一次使用先小范围验证不要一上来就把所有业务状态机迁到 Interlock 上。选一个核心且简单的状态机比如“订单支付状态”先跑通。验证原子性、审计、类型检查三个能力后再横向推广。10.2 状态定义和迁移规则集中管理把领域状态和迁移规则全部放在domain目录下不要分散到多个 service 里。这样团队里每个人查状态机只需要看一个文件。10.3 事务里不要做外部 I/O事务内调用短信、邮件、外部 HTTP 接口一旦接口慢整个事务就会长时间持锁。正确做法是事务内只写数据库和发送内部消息或者先改状态再通过 outbox 模式发异步通知。10.4 建立审计表索引审计日志会越积越多。常用查询条件是order_id和created_at要给这两个字段建组合索引避免全表扫描。CREATE INDEX idx_order_transitions_order_created ON order_transitions (order_id, created_at);10.5 权限与授权边界状态迁移往往意味着业务权限变化。如果 Interlock 支持传入 actor 或 operator 字段务必在接口层做鉴权不要让调用方任意指定操作人。涉及用户数据、人脸、声音等敏感信息时必须遵守隐私保护要求确保授权链路清晰。10.6 保留一套最小可运行配置在项目目录下放一个docker-compose.yml让新成员能一条命令启动 PostgreSQLversion: 3 services: postgres: image: postgres:16 container_name: interlock-pg environment: POSTGRES_PASSWORD: postgres POSTGRES_DB: interlock ports: - 5432:5432 volumes: - pgdata:/var/lib/postgresql/data volumes: pgdata:这个配置只用于本地开发测试。生产环境务必设置强密码、开启 TLS、限制访问来源不要暴露到公网。11. 总结与下一步Interlock 这个项目最值得尝试的点是它把领域状态迁移从“业务代码里的散装 if/else”提升到了“数据库事务 TypeScript 类型”的工程化层面。如果它能顺利跑通你至少能得到三样东西非法迁移的编译期检查、状态变更的原子性、可审计的迁移轨迹。第一次上手时最先验证的应该是原子回滚造一个必然失败的迁移看数据库状态是否真的没有变化。最容易踩的坑有两个一个是把事务写得太长导致锁竞争另一个是迁移规则和实际代码不同步。如果你平时已经在用 TypeScript PostgreSQL并且手头正好有一个状态机需求可以把这个项目拉下来对照 README 里的示例跑一遍。也可以基于它的设计思路自己实现一个只覆盖核心场景的版本毕竟状态迁移的核心逻辑并不复杂。后续可以继续扩展的方向包括把迁移规则可视化导出、接入消息队列处理事务后的领域事件、增加乐观锁版本控制、生成状态机文档、对接 Apollo/GraphQL。希望这个项目能给你的领域建模带来一点新的思路。建议收藏备用等你有状态流转需求的时候再拿出来对照验证。