docs(kdoc): 重写信箱生命周期相关 KDoc,改为直白说明并去掉内部编号
原有注释大量引用 §5.1/§5.2/Q2/US-01 这类文档编号和内部简称,跳过了"这段代码在做什么、 为什么这么做",没有读过设计文档的人基本读不懂。本次统一改成先讲清这件事本身、 再说为什么要这样做,编号只在末尾留一处指路。 覆盖本次改动涉及的 24 个 Kotlin 文件(生产 16 个 + 测试 8 个): - 领域与端口:ProcState(补齐全量字段说明与状态/错误分类逐项注释)、 ProcStateRepository / InboxCursorRepository / CminmsgInboxRepository 及 MailboxRow / BackfillDue / Backlog; - 收报:InboxPoller(把"水位连续、遇缺口停下、缺口老化"用大白话讲透)、 InboxService、JdbcCminmsgInboxRepository; - 处理:Pump / MessageProcessor、ScheduleProcessor、DynamicProcessors、 ProcFailure、JdbcProcStateRepository 与游标实现; - 回填与观测:BackfillService、InboxLifecycleHealthIndicator、JobRunner; - 配置与 stub:PipelineProps(三个新增参数说清取值理由)、MailboxProps、 StubRepositories; - 测试:8 个测试类改为"这些用例在守哪几条规矩",并保留 H2 不覆盖 ON CONFLICT 的说明。 术语统一按第一次出现就地解释:水位、处理标记、回填、死信、队头、终态。 纯注释改动;除拆分枚举时按仓库风格补的两个行尾逗号外无代码变更 (已用剥离注释后比对 HEAD 的方式逐文件核对)。测试仍为 78 passed / 1 skipped。
This commit is contained in:
@@ -4,9 +4,10 @@ import io.micronaut.context.annotation.ConfigurationProperties
|
||||
import java.time.Duration
|
||||
|
||||
/**
|
||||
* ACMA-8 参数表(v4)初值;阶段 0 现网基线校准。
|
||||
* U03(N02):Micronaut 要求嵌套配置类同样标注 @ConfigurationProperties,否则
|
||||
* msgx.pipeline/schd/identity.* 全部静默回落 Kotlin 默认值。
|
||||
* 管道运行参数,对应配置文件里的 `msgx.*`。
|
||||
*
|
||||
* 注意:嵌套的配置类也必须标 `@ConfigurationProperties`,否则 Micronaut 不会绑定
|
||||
* 里面的键,配置会静默失效、悄悄用回代码里的默认值。
|
||||
*/
|
||||
@ConfigurationProperties("msgx")
|
||||
class PipelineProps {
|
||||
@@ -26,19 +27,24 @@ class PipelineProps {
|
||||
var headDeadline: Duration = Duration.ofMinutes(10) // 最坏 HOL 上界(毒丸升级)
|
||||
|
||||
/**
|
||||
* message-lifecycle §5.1 空洞老化:水位 W+1 处的空洞持续超过该时延即判定为永久并放行。
|
||||
* 取值口径 = 库方承诺的最大提交时延(Q2);太小会把迟到消息判成永久空洞(FIFO 越序风险)。
|
||||
* 缺口等待时长:水位后面缺了一个 ID 时,等这么久还没出现就认定它永远不会来了,
|
||||
* 跳过缺口继续推进水位。
|
||||
*
|
||||
* 取值应该等于库方承诺的"上游提交到消息可见的最长时间"。设太小,可能把一条
|
||||
* 迟到的消息误判成永久缺失,导致它排到后面的消息之后;设太大,收报会在缺口上白等。
|
||||
*/
|
||||
var maxCommitDelay: Duration = Duration.ofMinutes(5)
|
||||
|
||||
/**
|
||||
* message-lifecycle §5.2 超期补写期限 R:终态后仍无处理标记的行到达该期限即强制补写,
|
||||
* 保证库方清除前提「边界内无未标记行」在有限时间内成立。
|
||||
* R ≥ 人工重放期限 + 人工处置期限(Q6);确认前不得下调。
|
||||
* 超期补写期限:一条消息处理完之后,如果过了这么久还是没能把处理标记写回信箱
|
||||
* (比如回填一直失败),就直接强制补写一次,不再等退避。
|
||||
*
|
||||
* 这是保证库方能清理信箱的兜底期限,必须覆盖人工重放所需的保留期,
|
||||
* 确认之前不要调小,否则还在重放窗口内的消息会先被库方清掉。
|
||||
*/
|
||||
var overdueBackfill: Duration = Duration.ofDays(30)
|
||||
|
||||
/** 回填扫描单批条数。 */
|
||||
/** 每次回填扫描最多处理多少条。 */
|
||||
var backfillBatch: Int = 100
|
||||
|
||||
/** U07:启动即拉起 Pump/Dispatcher 循环(默认关——需要真实仓储或 msgx.stubs=true 才可安全开启)。 */
|
||||
|
||||
Reference in New Issue
Block a user