1.9 KiB
1.9 KiB
工程需求
技术基线
- MQ 固定为 RocketMQ 5.x，当前本机镜像版本为
apache/rocketmq:5.3.2。 - 业务模块只依赖
MessageBusAdapter与版本化事件，不直接引用客户端 SDK 类型。 - Scheduler 只发布任务，Worker 只消费执行；重复投递由幂等键和业务唯一约束处理。
配置契约
- Scheduler 使用
ROCKETMQ_ENABLED、ROCKETMQ_NAMESRV_ADDR、ROCKETMQ_ENDPOINT、ROCKETMQ_TOPIC_PREFIX和发送超时。RocketMQ 5.x Proxy 官方 Node Producer 不要求 Producer Group，禁止把旧 Remoting 参数混入配置。 - Worker 使用相同的基础连接字段，并增加
ROCKETMQ_CONSUMER_GROUP和客户端消费并发。 - 开发和生产模板的同一进程必须保持相同键集合；生产连接地址留空且不得提交真实值。
ROCKETMQ_ENABLED=false时不建立连接；启用后 Endpoint、Topic 和对应 Group 必须通过启动配置 Schema 校验。
消息语义
- 事件必须包含
eventId、eventType、schemaVersion、occurredAt、tradeDate、traceId和idempotencyKey。 - Topic 表达稳定业务域，Tag 表达事件类型，Consumer Group 表达独立消费进度。
- 需要顺序处理时必须声明消息组键；普通消息不保证全局顺序。
- 超过最大消费次数后进入死信，必须支持查询、告警和受控重放。
- 最大投递次数属于 RocketMQ 服务端 Consumer Group 重试策略，由运维配置并纳入部署验收，不作为官方 Node PushConsumer 的客户端环境变量。
本机验证
- 检查容器、镜像、端口映射和 NameServer 启动日志。
- 使用 TCP 探针验证
127.0.0.1:9876。 - 检查 Docker 容器和本机原生进程，避免把相同端口的其他监听者误判为目标容器。
- 通过
mqadmin clusterList、topicList、brokerStatus确认 Broker 注册、版本和管理链路；不擅自创建 Topic 或写入测试消息。