feat: add reusable MySQL outbox and HTTP lifecycle example
This commit is contained in:
44
docs/reports/outbox-http-integration.md
Normal file
44
docs/reports/outbox-http-integration.md
Normal file
@@ -0,0 +1,44 @@
|
||||
# 可复用 Outbox 与 HTTP 生命周期验证
|
||||
|
||||
日期：2026-09-24。本报告仅覆盖本批接入适配与示例，不替代平台目标生产环境容量、高可用及数据库复制确认验收。
|
||||
|
||||
## 交付
|
||||
|
||||
- 独立模块 adapters/outbox/mysql，公开 EnqueueTx、可选受理关联回调、Run 和查询接口。无平台内部依赖，核心 SDK 无 SQL 驱动。
|
||||
- 旧 CLI 的发送核心及原有故障测试迁入公共模块；旧业务表、命令和固定提交身份兼容。
|
||||
- examples/http-service 提供完整装配、业务路由、数据库事务、Worker、持久 Inbox、后台错误传播及有界关闭。
|
||||
- 业务库与平台库分离；SQL沿用无外键表、中文字段注释。平台迁移及SDK协议未修改。
|
||||
|
||||
## 验收场景
|
||||
|
||||
1. 业务回滚同时撤销待发记录；未提交的记录不能领取；调用方负责 Commit。
|
||||
2. 8 个并发重复、同事务重复、RR 旧快照核对；内容/目标冲突拒绝；大整数保真。
|
||||
3. 接受钩子失败整笔确认回滚；无钩子也可确认，不依赖示例业务表；旧租约代次不能覆盖新确认。
|
||||
4. 原HTTP回执丢失、三个阶段的真实MySQL COMMIT成功包丢失、平台受理后发送器SIGKILL及自然租约接管。
|
||||
5. Run取消时等待在途发送完成确认，超时返回错误并保留持久恢复状态。
|
||||
6. HTTP请求未结束时后台依赖保持可用；后台致命错误触发宿主关闭；消费器在发送/执行组件之后结束。
|
||||
7. 完整进程：代理令Orbit不可用，HTTP仍提交本地事务；SIGKILL旧宿主并确认退出；新进程恢复原操作，实际Worker执行、Inbox入库、平台ACK；重复HTTP不新建业务行，改内容409，SIGTERM退出0。
|
||||
|
||||
## 验证状态
|
||||
|
||||
环境：macOS arm64、Go 1.27.1、Docker隔离MySQL 8.4、独立业务库与Orbit平台进程，回环地址；业务与平台使用同一隔离MySQL实例，不代表跨故障域部署。
|
||||
|
||||
- `make test`：六个模块的标准竞态测试通过（未配置数据库时Integration会跳过，真实数据库证据另列）。
|
||||
- `make vet build sdk-check`：通过；SDK 30个包、禁止依赖0项。适配器在GOWORK=off下使用已发布SDK v0.1.0，依赖图无平台内部包。
|
||||
- `make docs-check`：166份Markdown的本地链接检查通过。
|
||||
- `make adapters-check`：隔离MySQL/平台/业务模块定向回归退出0；公共Outbox 33.792s，完整HTTP进程场景9.52s，全部通过。恢复测试真实等待旧发送租约自然到期。
|
||||
- `make integration`：全量平台回归退出0；包含真实存储/升级、SDK、旧CLI、公共Outbox、HTTP宿主及Worker/Event/Workflow进程恢复。全量链路中Outbox 33.934s，HTTP进程场景9.64s，新增同事务重复与RR核对均通过。
|
||||
|
||||
复现：`make adapters-check`（定向隔离链路）和 `make integration`（平台全量隔离链路）。不操作现有开发数据库或运行容器。
|
||||
|
||||
## 本批发现与修正
|
||||
|
||||
新增发送器关闭测试的初版 HTTP 桩缺失协议必填 request_id，SDK正确拒绝无效响应，使测试未进入提交阶段。补齐符合正式协议的响应后重新执行。随后发现超时路径的测试桩仍持有未释放屏障，导致 httptest.Close 等待；已在清理中显式、幂等释放屏障并重跑。两次未通过运行均不计入通过证据。
|
||||
|
||||
## 边界
|
||||
|
||||
- 首版适配器仅支持 MySQL、SubmitTask；不会自动写业务表、删除历史或自动解除 REVIEW。
|
||||
- 外部副作用仍需业务幂等/核对；示例 Worker 仅做可重复纯计算。
|
||||
- 每条记录沿用24小时/100次总发送预算，重启不延长。ACCEPTED仅为平台受理。
|
||||
- HTTP示例只监听回环地址；接入真实服务复用业务自身鉴权、监控和部署生命周期。健康就绪不等于全局任务已经执行完毕。
|
||||
- Inbox是示例业务实现，不是本批新增的公共适配包；其他数据库/ORM专用集成不在本批交付内。
|
||||
@@ -7,13 +7,13 @@
|
||||
- [独立模块](../../examples/task-outbox/README.md)只依赖独立Orbit SDK与业务侧MySQL驱动，核心SDK没有新增依赖。
|
||||
- [模型](../../examples/task-outbox/internal/outbox/model.go)与[建表](../../examples/task-outbox/internal/outbox/schema.sql)：2个业务实体、22个Go/SQL中文注释字段，零外键；不改变平台35个实体和289个持久化字段。
|
||||
- [业务事务](../../examples/task-outbox/internal/outbox/store.go)：业务操作与待发命令原子创建，稳定操作/提交身份、冻结请求、摘要、有限次数、租约代次及原回执；确认与业务任务关联再次同事务。
|
||||
- [发送器](../../examples/task-outbox/internal/outbox/sender.go)：事务外HTTP、当前凭据核对目标、原键重报、背压退避、未知结果分类、过期接管与旧代次拒绝。
|
||||
- [发送器](../../adapters/outbox/mysql/sender.go)：事务外HTTP、当前凭据核对目标、原键重报、背压退避、未知结果分类、过期接管与旧代次拒绝。
|
||||
- [CLI](../../examples/task-outbox/cmd/sender/main.go)及[完整命令/方法/恢复手册](../examples/task-outbox.md)：init、enqueue、send、status和demo。
|
||||
- [Makefile](../../Makefile)和[隔离脚本](../../scripts/test-mysql.sh)纳入独立模块，使用单独业务数据库和专用平台凭据，不触碰现有开发数据库。
|
||||
|
||||
## 2. 定向数据库与故障证据
|
||||
|
||||
[数据库回归](../../examples/task-outbox/internal/outbox/store_integration_test.go)验证：
|
||||
[数据库回归](../../adapters/outbox/mysql/store_integration_test.go)验证：
|
||||
|
||||
1. 8个相同业务操作并发入库只有一条业务记录/Outbox，7次重复核对；修改正文、源引用或目标队列不能复用原操作。
|
||||
2. 实际业务INSERT失败时Outbox一起回滚；业务关联UPDATE失败时ACCEPTED一起回滚，恢复后可保存原回执。
|
||||
@@ -21,13 +21,13 @@
|
||||
4. 错误目标、损坏文档、权限拒绝、幂等冲突和无效回执停止自动发送；背压遵守Retry-After，次数耗尽和截止产生REVIEW，最后一次未知响应不能绕过上限。
|
||||
5. 实际Schema查询确认22个中文列注释、外键0，通过实际违规写入验证JSON、状态、次数和截止CHECK生效，领取查询使用ix_sender_due且无filesort；大整数9007199254740993在冻结请求与真实回执中保持精确。
|
||||
|
||||
[COMMIT故障代理](../../examples/task-outbox/internal/outbox/commit_loss_integration_test.go)在业务入库、领取和本地确认三处分别截获真实MySQL COMMIT OK包后丢弃。调用方得到ErrCommitUnconfirmed，新Store分别核对已存在业务记录、已提交租约和已确认关联，不假定COMMIT失败即回滚。
|
||||
[COMMIT故障代理](../../adapters/outbox/mysql/commit_loss_integration_test.go)在业务入库、领取和本地确认三处分别截获真实MySQL COMMIT OK包后丢弃。调用方得到ErrCommitUnconfirmed，新Store分别核对已存在业务记录、已提交租约和已确认关联，不假定COMMIT失败即回滚。
|
||||
|
||||
[HTTP回执丢失](../../examples/task-outbox/internal/outbox/http_integration_test.go)先取得真实平台受理结果，再向客户端发送不完整响应并断开；Outbox保持PENDING，原键重报后同一任务ACCEPTED、deduplicated=true、发送次数2，队列只有一项任务。错误持久化命名空间在提交前被拒绝。
|
||||
[HTTP回执丢失](../../adapters/outbox/mysql/http_integration_test.go)先取得真实平台受理结果，再向客户端发送不完整响应并断开；Outbox保持PENDING，原键重报后同一任务ACCEPTED、deduplicated=true、发送次数2，队列只有一项任务。错误持久化命名空间在提交前被拒绝。
|
||||
|
||||
[发送进程故障](../../examples/task-outbox/internal/outbox/process_integration_test.go)等待真实平台受理后、本地确认前的屏障，再SIGKILL并确认旧进程已退出。新进程等待数据库30秒租约自然到期，以原键取得原回执；最终只存在一个平台任务和一条本地业务记录。测试没有直接改时间来替代这项进程接管。
|
||||
[发送进程故障](../../adapters/outbox/mysql/process_integration_test.go)等待真实平台受理后、本地确认前的屏障，再SIGKILL并确认旧进程已退出。新进程等待数据库30秒租约自然到期，以原键取得原回执；最终只存在一个平台任务和一条本地业务记录。测试没有直接改时间来替代这项进程接管。
|
||||
|
||||
定向脚本第三轮正常退出，状态码0：Outbox集成33.009秒，其中发送进程故障31.19秒；init/demo均正常完成。随后增加的[真实CLI测试](../../examples/task-outbox/internal/outbox/cli_integration_test.go)进入本轮全量回归，验证编译后的enqueue重复、status、send及正常信号停止。
|
||||
定向脚本第三轮正常退出，状态码0：Outbox集成33.009秒，其中发送进程故障31.19秒；init/demo均正常完成。随后增加的[真实CLI测试](../../adapters/outbox/mysql/cli_integration_test.go)进入本轮全量回归，验证编译后的enqueue重复、status、send及正常信号停止。
|
||||
|
||||
## 3. 发现与修正
|
||||
|
||||
@@ -73,3 +73,5 @@ make integration
|
||||
- REVIEW保留原数据，由接入方带证据和审计的管理流程处置；本示例未实现通用业务审核系统或跨业务ORM适配。
|
||||
- 核心SDK、平台Schema和执行协议均未改变；新增业务示例不是已发布的兼容性SDK包。
|
||||
- 流程启动与信号Outbox类型需随Weave API实现；P6继续容量、数据库切换、备份恢复及运维验证。当前正确性与进程恢复证据不等同于生产高可用或百万规模容量结论。
|
||||
|
||||
2026-09-24 源码组织调整：发送核心及原故障回归迁至独立 adapters/outbox/mysql 模块，业务示例调用公共包；Outbox Record/SQL见[公共模型](../../adapters/outbox/mysql/model.go)与[表结构](../../adapters/outbox/mysql/schema.sql)，sender_jobs 保留在旧业务示例。上述历史验证日期不变，新增验证另见[接入适配报告](outbox-http-integration.md)。
|
||||
|
||||
Reference in New Issue
Block a user