docs: review 未修项记录为已知语义(README/CLAUDE.md)

用户拍板:#5 批间不保序、#7 停机强刷无超时、#4 start 无回滚、#10 三处
快照样板重复,记录为已知语义/结构注意,不按缺陷修。

- README:批量坑段补两条业务方可感知的已知语义(批间不保序;停机会排队
  等业务批量方法、挂死会卡住优雅停机)。
- CLAUDE.md:dispatcher 段新增"已知语义/结构注意"条目(四条全记,含
  改快照样板须三处同步的提醒)。

全景手册(gitignored)已同步,不进本 commit。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
2026-07-15 03:40:07 +01:00
parent 9af2ef06e2
commit ffa30a7631
2 changed files with 3 additions and 0 deletions

View File

@@ -166,6 +166,8 @@ public class MyErrorHandler implements MqConsumeErrorHandler {
>
> ⚠️ **批量有几个坑**:参数必须写带具体元素类型的 `List<FrontData>`(裸 `List` 启动扫描直接抛 `IllegalStateException`);攒不满时最多等 `batchTimeoutMs`(缺省 60 秒,从本批第一条算起)会强制刷出,正常停机也会把没攒满的批刷出去(若停机瞬间恰有一批正在业务方法里跑,停机会等它跑完,上限 30 秒),但 kill -9 / 断电仍会丢内存里那批(最多一个超时窗口内的量);整批业务失败只回调 SINGLE 落库、不重投(所以批量务必配 `errorHandler`)。批量方法同样可以加第二参 `MqContext`(拿到的是该批最后一条的元数据)。
>
> 两条**已知语义**(设计如此,不按缺陷处理):**批与批之间不保证顺序**——超时刷出的批可能被恰好凑满的新批插队业务先收到新批再收到旧批MQ 重投本身也不保序,消费逻辑别依赖批间先后);**停机会排队等正在跑的业务批量方法**——等定时刷批那步有 30 秒上限,但停机强刷没有,业务方法若挂死(如数据库连接僵住),优雅停机会被一直卡住。
>
> 另外 `batchSize` 与首参是否 `List` **错配时不报错**:启动时打一条 WARN 日志、仍按首参决定走不走批量(`batchSize=50` 配单个 payload 退化为逐条;`List` 首参配 `batchSize` 缺省按 1 条一批)。见启动日志 `[mq] @MqListener batchSize=...`。
## 两个 driver 不太一样