做物联网对接时,经常会遇到这种情况:设备数据已经通过 Kafka 流转起来了,第三方平台却只提供 HTTP 接口。写一个消费者,把 JSON 换个格式再 POST 过去,第一版似乎很快就能完成。 真正麻烦的是后面的事:对方超时了怎么办?请求已经成功,本地还没来得及记账就重启了怎么办?早高峰突然堆进来一批消息,又该让它们等在哪里?
ps: 本文的目的是记录一个项目设计过程,便于日后复盘,但暂不提供实际压测指标(如吞吐量、延迟、资源消耗)
本文由AI润色。
一、业务背景与核心需求
1.1 智慧停车中的数据对接
路边停车的摄像头会持续向 IOT 平台上报数据。最初需要对接的主要有两类:
- 车辆出入事件:车辆驶入或驶出泊位时,设备上报车牌、出入时间、识别可信度,以及全景图、车牌图、特写图等图片信息。
- 心跳抓拍图:摄像头按业务约定每 5 分钟拍摄一次泊位照片,用来确认设备在线状态和泊位情况。
后续又接入了过车记录、地磁事件和地磁设备信息。它们的字段和接口各不相同,但都需要经过“接收消息、转换格式、调用第三方接口”这条处理链路。
IOT 平台已经通过 Kafka 分发这些消息,第三方停车管理平台提供的却是 HTTP REST 接口。因此,需要一个独立的转发服务,在两边完成协议与数据格式转换。把对接逻辑放在这里,也能让第三方接口变慢时,设备数据接收仍沿着原有链路进行。
1.2 核心需求
需求一:可靠接收,失败可恢复。
车辆出入事件直接影响停车计费。少了一条驶入记录,可能少收一次费用;少了一条驶出记录,订单就可能迟迟无法结束。我希望每条已接收的消息都能查到处理状态,服务重启之后能继续处理尚未完成的工作。
这意味着要明确 Kafka offset 的提交条件,并把待办消息和处理进度持久化。对方已经处理成功、本地还没记下结果时发生中断,也需要通过幂等机制处理再次投递。
需求二:完成字段映射后再转发。
Kafka 消息和第三方接口的格式差异不少。例如,上游用 0/1 表示出场和进场,平台要求 2/1;可信度需要从小数转换为百分比整数;图片类型和路径也需要适配。转换逻辑要集中管理,方便对照接口文档和真实消息排查。
需求三:承受高峰期的 I/O 并发。
早晚高峰有大量车辆集中进出,而转发任务的大部分时间花在等待 HTTP 响应上。系统需要容纳这些等待,同时控制下游请求数量,让积压有地方存放,避免堆满进程内存。
需求四:按规则重试,并保留失败原因。
第三方接口会超时、返回 5xx,也会在 HTTP 200 中返回业务错误。服务需要区分成功、可重试和停止处理,并记录尝试次数、错误原因与下次执行时间,方便自动恢复和人工补发。
需求五:便于多实例运行和日常排障。
多个实例可能接到重复消息,也可能同时发现一条待重试记录。入库和领取任务都需要有明确的并发控制;运行后还要能看到积压量、失败记录和请求结果,回答“这条车牌对应的事件为什么没有送达”。
二、方案对比
确定需求之后,首先考虑的是:消费者提交 offset 时,尚未完成的工作由谁保管? 这决定了重启后的恢复方式,也决定了下游变慢时压力会积在哪里。
2.1 方案 A:内存队列转发
| |
这个方案结构简单,少了一次数据库写入,消息进入进程后就可以排队发送。
关键在于 ACK 时机。如果消息进入内存队列就提交 offset,进程异常退出会丢掉还没发出的待办。如果等 HTTP 完成再提交,未确认的消息可以交给 Kafka 重投,但批次确认、并发完成顺序和队列容量都需要一起设计。
它适合处理链路较短、主要依靠 Kafka 回放恢复的场景。对于这个项目,逐条查询处理状态、延迟重试和人工补发还需要另外建设。
2.2 方案 B:先转发,再记录结果
| |
这个方案把“第三方收到消息”作为消费完成的重要条件,正常路径直观,数据库也能保留转发结果。
代价是消费进度与下游响应时间紧密关联:一次超时就会拖长本批处理时间。如果第三方已经处理成功,结果落库前服务退出,Kafka 重投后会再次发起 HTTP 请求,仍然需要下游幂等配合。
在请求量较低、接口稳定时,这种做法容易实现。面对集中到来的事件和不稳定的下游,更希望先把消息接住,再独立安排发送。
2.3 方案 C:先持久化,再异步转发
| |
这个方案把数据库作为待办工作的保存位置。消息入库之后,即使首次任务没有拿到并发许可,也能留在数据库中等待后续处理。服务重启后,调度器根据状态和时间继续执行。
与此同时,接收与发送可以分别优化:接收侧做批量写入,发送侧用虚拟线程承载 HTTP 等待,重试侧按到期时间领取任务。
它增加了数据库写入和维护成本。下游持续变慢时,积压会表现为数据库中的待办记录增长,因此还要配置并发上限、重试窗口和数据归档。
2.4 为什么选择方案 C
把三种方案放在一起看:
| 方案 | 待办与恢复方式 | 状态查询和补发 | 主要成本 |
|---|---|---|---|
| A:内存队列转发 | 未 ACK 的消息由 Kafka 重投;提前 ACK 的待办依赖进程内存 | 需要补充记录与管理机制 | 队列容量、并发完成与 offset 协调 |
| B:HTTP 后记录结果 | 在 HTTP 和结果落库完成后 ACK,异常时重投 | 有结果记录,恢复仍需处理不确定结果 | 下游延迟影响消费进度 |
| C:DB 后异步转发 | 数据库保存消息、状态和重试时间 | 可以围绕同一条记录查询、重试和归档 | 数据库写入、积压存储与维护 |
这个停车场景既需要实时转发,也需要事后查清每条事件的去向,所以我选择了方案 C。它让可靠接收、并发发送和故障恢复有了各自清晰的处理位置,后续扩展地磁和 IOT 回调时,也可以沿用这套思路。
三、总体技术架构
服务围绕两条路径运行:新消息从 Kafka 进入,持久化后提交 HTTP 任务;待处理记录从数据库进入,经过调度再次提交任务。 两条路径共用转发执行器、请求映射和结果处理。

3.1 模块职责
| 模块 | 主要职责 | 核心机制 |
|---|---|---|
| Kafka 接收 | 批量消费,解析消息标识,保留 payload 与来源信息,完成批次 ACK | 批量监听、手动确认 |
| 持久化接收 | 在同一事务中处理幂等键、车辆事件去重和批量入库 | 数据库唯一约束、独立事务 |
| 任务分发 | 获取并发许可,提交虚拟线程;首次任务提交失败时释放领取状态 | Semaphore、虚拟线程执行器 |
| HTTP 转发 | 构建平台请求,执行调用,解析 HTTP 与业务响应 | 字段映射、同步 HTTP 调用 |
| 状态与重试 | 短事务更新结果,扫描到期记录,恢复处理中断的任务 | 原子领取、持久化状态、指数退避 |
新消息的关键顺序是:整批入库事务提交 → 尝试提交虚拟线程任务 → 分发返回 → ACK。HTTP 任务提交后独立执行,其结果通过短事务写回数据库。
因此,Kafka offset 反映消息接收进度,数据库状态反映第三方转发进度。运行时需要同时观察 Kafka lag 和数据库积压。
3.2 管理、维护和业务扩展
主链路之外,还有三组配套能力:
- 管理与监控:管理页面查询消息、响应和失败日志,并提供人工重试;Actuator 与 Micrometer 暴露记录状态和并发许可指标。
- 数据维护:Flyway 管理表结构,维护任务预建分区、清理幂等键,并将历史热数据转入归档表。
- 业务扩展:地磁通过独立的 Mapper、平台地址与 token 接入主链路;过车响应中的
img_flag=1会触发独立的 IOT 回调流程。
有了这张整体图,后面的实现可以围绕几个交接点展开:什么时候算接收完成,谁取得了执行资格,结果如何写回,失败后从哪里继续。
四、技术栈选型
4.1 组件与职责
| 组件 | 项目选型 | 选择理由 |
|---|---|---|
| Java | Java 21 编译目标 | 使用正式的虚拟线程 API 承载 I/O 等待 |
| 应用框架 | Spring Boot 3.3.4 | 复用配置、事务、管理接口和监控生态 |
| Kafka 客户端 | Spring Kafka 批量监听 | 便于批量持久化,并显式控制 ACK 时机 |
| HTTP 客户端 | JDK HttpClient | 内置 HTTP/2 支持、超时控制和连接复用 |
| 并发模型 | 虚拟线程 + Semaphore | 保持同步调用写法,并限制同时执行的转发任务 |
| 数据访问 | PostgreSQL + JDBC + Spring Data JPA | JDBC 批量写入,JPA 查询和状态管理,数据库约束协调并发 |
| 主键 | 雪花 ID | 入库前在应用侧分配 ID,关联幂等键与主记录 |
| 数据维护 | Flyway + 时间分区与归档 | 管理结构变更,控制热数据规模 |
| 管理与监控 | React、Actuator、Micrometer、Prometheus/Grafana | 查询处理过程、人工补发、观察积压与失败 |
4.2 为什么选择虚拟线程
这个服务的主要工作是等待数据库和第三方 HTTP,业务代码本身相对直接。使用虚拟线程后,每次转发仍可以按照“构建请求、发送、解析、记录”的顺序编写,异常处理也能沿着普通调用栈展开。
Reactor/WebFlux 同样适合处理高并发 I/O。对这个已经使用 JDBC/JPA 的项目,选择继续采用同步调用方式,让并发机制尽量少侵入业务逻辑。虚拟线程负责承载任务,Semaphore 则单独表达下游可以承受的并发数量。
4.3 为什么使用 JDK HttpClient
项目主要向固定平台发送 JSON POST 请求,需要的能力集中在超时、请求头、HTTPS 和响应读取上。JDK HttpClient 已经覆盖这些需求,可以共享客户端并复用连接,也减少了一个外部客户端依赖。
客户端配置为优先使用 HTTP/2,实际协议由服务端协商;业务侧采用同步 send(),在虚拟线程中等待结果。重试交给数据库状态和调度器统一管理,便于查清每一次失败的原因。
4.4 为什么在应用侧生成 ID
批量入库之前,服务就需要把“消息幂等键”和“将要创建的主记录”关联起来。雪花 ID 可以在这个阶段生成,使两类数据在同一事务中写入。
它还提供了包含时间信息、整体趋势递增的整数 ID,便于日志定位和批量处理。多个实例通过不同的 worker-id、datacenter-id 组合区分;如果采用数据库序列,也可以实现唯一 ID,选择取决于 ID 生成时机和部署方式。
五、消息流程
以一条获得转发资格的新消息为例,看看它从 Kafka 到第三方平台经过哪些步骤。

5.1 接收一批消息
接收端遍历这一批消息,提取 messageId 和车辆事件的 data.itemId,保留原始 payload 与 Kafka 来源信息,再执行持久化和任务分发。
把关键顺序展开,可以写成下面的伪代码:
| |
批量入库使用 REQUIRES_NEW 独立事务,一起完成以下操作:
- 对批次内的
messageKey去重,批量插入消息幂等键。 - 查询幂等键的归属,确认哪些消息是本批次新接收的。
- 为符合条件的车辆事件抢占
itemId转发资格。 - 批量插入新消息的
forward_records。
幂等键和主记录一起提交,避免只占了一个“已经处理过”的位置,却没有留下真正的待办记录。
5.2 首次入库,已经是 IN_PROGRESS
通过去重的新消息以 IN_PROGRESS、attempt_count=1 入库,将首次领取合并到插入操作中。发送阶段直接使用这条已领取的记录,少做一次“先查再改为处理中”的数据库操作。
接下来还需要取得 Semaphore 许可并提交任务。如果获取许可失败,或执行器拒绝任务,分发模块会把记录释放回:
| |
因此,IN_PROGRESS 包括已领取、等待执行以及正在处理的任务;实际执行并发由 Semaphore 控制。
5.3 ACK 在哪里,决定了故障后的接力方式
整批落库 → 尝试异步分发 → ACK 是消费线程上的执行顺序。虚拟线程在任务提交后就可以运行,HTTP 发送与 ACK 的先后取决于调度。
批量监听时,无参数的 ack.acknowledge() 确认这一批记录,并按各分区推进消费位置,所以代码将它放在整批处理之后。若放进逐条处理的循环,第一次调用就会确认本批,留下尚未处理的消息。
如果分发方法抛出异常,正常路径不会执行 ACK;如果只是没有拿到并发许可,则可以返回,已落库的消息由后续扫描接手。
对于输入内容,代码会记录并跳过 null 或空白消息,随批次确认;非空的非法 JSON 会在提取标识失败后使用 offset 组合键入库,在后续构建请求时记录为 FAILED。
六、虚拟线程解决等待,Semaphore 控制数量
虚拟线程最吸引我的地方,是不用把业务代码拆成一串回调。
这个项目里的 HTTP 调用仍然是同步写法:
| |
调用它的虚拟线程会等待响应。对于适合虚拟线程的阻塞 I/O,JVM 可以在等待期间释放底层线程,让它执行其他任务,从而承载更多并发等待。
等待中的任务仍然会持有消息、请求体和响应处理所需的对象,也会占用网络资源,所以还需要限制在途任务数量。
6.1 两个 Bean,就是主链路的并发骨架
核心配置是一个虚拟线程执行器,以及一个控制并发数量的信号量:
| |
分发模块在消费线程上先调用带超时的 tryAcquire(),拿到许可才提交任务。例如,设置 200 个许可,最长等 100ms。
首次投递获得许可后的核心提交逻辑如下,forwardClaimed() 表示执行已领取记录的转发过程:
| |
对于首次投递,等待许可超时或被中断时,也要把已领取记录释放回 PENDING;任务成功提交后,则由执行线程在 finally 中归还许可。
许可覆盖构建请求、HTTP 调用和结果处理这一整个任务,统计单位是同时执行的任务数。部署三个实例、每个实例 200 个许可,总并发额度就是最多 600。
6.2 “排进数据库”也有成本
用一个例子估算:目标每秒处理 500 条,平均每次 HTTP 等待 0.2 秒,覆盖这段等待大约需要 500 × 0.2 = 100 个并发任务。实际配置还要计入映射、数据库操作和长尾延迟,并与第三方的容量、限流规则匹配。
同样,获取许可的等待时间会影响 Kafka 消费线程。极端情况下,一批 100 条全都逐条等满 100ms,光等许可就可能花掉约 10 秒,还没算数据库耗时。调整批次大小和等待时间时,需要一起看消费处理时间与 max.poll.interval.ms。
6.3 用短事务及时释放数据库连接
如果把“改状态 → 发 HTTP → 记结果”包进一个事务,下游慢 10 秒,数据库连接也可能跟着占用 10 秒。虚拟线程省下来的线程资源,并不能补救耗尽的连接池。
这里把转发过程拆成三个阶段:外层只负责流程编排,数据库操作放进独立的事务 Bean,HTTP 在事务之外执行。
| 阶段 | 首次投递 | 重试投递 | 数据库事务 |
|---|---|---|---|
| 领取任务 | 已在入库时写入 IN_PROGRESS/1 | 原子更新 PENDING → IN_PROGRESS 并增加次数 | 短事务 |
| 构建并发送 HTTP | 使用已领取记录发送 | 领取成功后发送 | HTTP 等待期间不持有主链路数据库事务 |
| 记录结果 | 成功、待重试或失败 | 同左 | 独立短事务 |
事务方法放在另一个 Spring Bean 中,也让调用经过事务代理,避免同类自调用时误以为 @Transactional 已经生效。
七、两层幂等:消息去重与业务去重
上游重复发一条 Kafka 消息,与上游换了一个消息 ID 再次报告同一次停车事件,是两类不同的重复。
当前代码分了两层处理:
| 去重对象 | 标识来源 | 存在哪里 | 命中后的行为 |
|---|---|---|---|
| 消息重复 | 顶层 messageId | forward_message_keys | 不新增主记录,按已有记录状态处理 |
| 车辆业务事件重复 | VEHICLE_EVENT 的 data.itemId | forward_vehicle_event_item_keys | 新消息仍入库,标记 DUPLICATE,不发 HTTP |
举个例子:
| |
这里的规则是保留期内先抢到转发资格的记录负责这次业务事件。如果 A 最后失败,应重试或处理 A;B 保留为业务重复记录。
消息重复时,已有记录为 SUCCESS、FAILED、IN_PROGRESS 或 DUPLICATE 就跳过;为 PENDING 则尝试提交任务,并在执行前参与原子领取。重复消费可触发提前投递,next_retry_at 的到期过滤用于调度器扫描。
7.1 为什么选 messageId
topic + partition + offset 能识别 Kafka 中的同一条记录,重置消费进度之后重读它,仍然可以去重。它的不足在于:同一个业务消息如果被重新生产,获得了新的 offset,就变成了另一个键。
所以项目优先使用上游 messageId;缺失或解析失败时,才降级为 topic#partition#offset。
当前实现直接把 messageId 作为全局键,没有再拼 ApiType 或 Topic 前缀。这要求上游在这些输入来源之间维护唯一性。如果两个不同业务来源碰巧给了相同 ID,也会发生冲突。
车辆 itemId 缺失、空白或超过 128 字符时,当前实现会记录警告并跳过这一层去重,保留原有转发行为。
7.2 用数据库唯一约束协调并发
消息键的核心 SQL 是:
| |
随后批量查询 message_key → record_id,只有归属于本次新分配 ID 的记录,才继续插入主表。itemId 则通过多值 INSERT ... ON CONFLICT DO NOTHING RETURNING first_record_id 确认抢占结果。
这样,多实例同时接到重复数据时,由数据库约束裁决。Java 里先查询“没有”,再插入,并不能阻止另一个实例在同一时间也查到“没有”。
7.3 幂等键的保留期
当前两个幂等键表都按键做 32 个 HASH 分区,配置的保留期是 3 天;转发主表按日期分区,热数据保留 30 天。
这是两个不同的生命周期。幂等键到期并被清理后,即使主记录还在,同一业务消息再来,也可能被当成新消息处理。 长期补数、回放历史消息之前,需要先考虑这个窗口。
如果命中了幂等键,却查不到对应的热表主记录,代码会写入 forward_duplicate_anomalies,保留消息来源和原始内容供排查。
八、失败处理与持久化重试
8.1 消息状态
stateDiagram-v2
direction LR
[*] --> IN_PROGRESS: 新消息入库,首次尝试已领取
[*] --> DUPLICATE: 新 VEHICLE_EVENT 的有效 itemId 已被占用
IN_PROGRESS --> SUCCESS: HTTP 2xx 且 result=0 或 errcode=4
IN_PROGRESS --> PENDING: 可重试且次数未耗尽 / 首次任务未提交 / 处理中超时恢复
PENDING --> IN_PROGRESS: 原子更新领取成功
IN_PROGRESS --> FAILED: 次数耗尽 / 第三方平台异常 / 不可重试的构建异常
PENDING --> FAILED: 超出重试窗口,由已启用的归档维护任务处理
FAILED --> PENDING: 符合条件的人工重试
SUCCESS --> [*]
DUPLICATE --> [*]图 3:主链路状态机。首次未提交任务的释放会把尝试次数清零;失败后的等待和超时恢复则保留已有尝试次数。
| 状态 | 含义 | 后续动作 |
|---|---|---|
PENDING | 等待首次执行或再次尝试 | 到期后参与调度 |
IN_PROGRESS | 已领取任务,可能在执行,也可能中途异常退出 | 完成后记结果;超时后尝试恢复 |
SUCCESS | 本地已记录第三方成功响应,或平台表示重复上报 | 不再自动投递 |
FAILED | 当前处理已停止 | 排查原因,符合条件时人工重试 |
DUPLICATE | 车辆业务事件重复,仅留档 | 不转发,不参与普通失败重试 |
8.2 多实例通过原子更新领取任务
调度器先用普通查询获取候选记录。多个实例可以查到同一条 PENDING 记录,真正决定谁发送 HTTP 的,是后面的条件更新:
| |
领取操作检查受影响行数:更新成功,才继续读取记录并发送 HTTP;更新为 0,本次任务结束。
可以想象两个实例都拿到了记录 42。A 先把它从 PENDING 改成 IN_PROGRESS 并提交;B 再尝试同一个条件更新,已经匹配不到 PENDING,于是不会在这次竞争中继续发请求。
这个设计把“查候选”和“取得执行资格”分开,领取事务提交后即释放数据库连接和行锁,再执行 HTTP。
超时恢复阈值需要覆盖正常任务耗时。如果把仍在运行的任务重置为 PENDING,新任务会再次竞争领取;当前主链路没有尝试版本号隔离旧任务的结果写回,存在重复请求和旧结果覆盖的窗口。
8.3 同时判断 HTTP 状态和业务响应
对接平台通过 result 和 errcode 表达业务结果。转发时先检查 HTTP 状态,再按下面的规则处理响应:
| 结果 | 当前处理 |
|---|---|
2xx 且 result=0 | 成功 |
2xx 且业务错误码 4 | 平台表示重复上报,按成功处理 |
业务错误码 998 | 不可重试,进入 FAILED |
| 非 2xx、超时、发送异常、响应解析失败、其他业务失败 | 根据剩余次数,进入 PENDING 或 FAILED |
| 普通请求构建失败,例如字段映射或 JSON 问题 | 直接 FAILED |
RetryableRequestPreparationException,例如地磁 token 暂时获取失败 | 进入重试判定 |
8.4 重试次数的定义
主链路里 attempt_count 包含首次尝试,配置项 max-attempts 不包含首次。终止条件是:
| |
将 max-attempts 设为 0,首次处理失败后即停止追加常规失败重试;背压释放回 PENDING 的任务和符合条件的超时恢复任务,仍由调度器处理。
以 max-attempts: 5 为例,最多是 1 次首次尝试 + 5 次重试,对应的基础延迟如下:
| 第几次尝试失败 | 后续基础等待时间 |
|---|---|
| 1 | 5 秒 |
| 2 | 10 秒 |
| 3 | 20 秒 |
| 4 | 40 秒 |
| 5 | 80 秒 |
| 6 | 次数耗尽,标记 FAILED |
基础公式是 min(5 × 2^(attemptCount - 1), 300),代码还加入 ±20% 的随机抖动,并将最终结果限制在 1~300 秒。这样,一批同时失败的消息不必总在同一时刻挤回来。
next_retry_at 指定可以重试的最早时间,实际执行还取决于调度周期和并发许可。
8.5 调度周期与恢复窗口
调度器在上一次执行结束后等 5 秒再开始下一轮,每次先处理超过 5 分钟未更新的 IN_PROGRESS,再查询到期 PENDING;候选上限是 5000 条。
自动扫描还受 window-days: 1 限制,窗口依据是主记录的 created_at。超出窗口的 PENDING 停止参与扫描,在后续归档维护任务运行时标为 FAILED;这一步随归档功能启用。排查滞留记录时,需要同时看创建时间、下次重试时间和状态。
九、故障恢复:沿交接点检查消息去向
有了事务、状态和重试,再把服务中断放进处理流程,就能看出恢复时应该由哪一环接手:
| 故障发生的位置 | 留下了什么 | 当前恢复方式或边界 |
|---|---|---|
| 入库事务提交前 | 本批新写入回滚,正常路径不会 ACK | 由容器级错误处理接手,见下一节 |
| 入库已提交,ACK 尚未完成 | 已有主记录和幂等键 | Kafka 可能重投,保留期内由幂等逻辑处理 |
| 已落库、已 ACK,任务还没真正执行就退出 | 可能留下 IN_PROGRESS | 超时恢复后转回 PENDING,仍受配置与扫描窗口约束 |
| 下游超时或返回失败 | 本地记录失败原因 | 按次数和窗口决定重试或停止 |
| 对方已处理成功,本地成功状态尚未落库就退出 | 对方成功,本地仍可能是 IN_PROGRESS | 恢复后可能再次发送,需要下游幂等配合 |
| 幂等键过期并清理后,回放旧数据 | 历史主记录可能还在,键已经不在 | 可能再次入库和投递,回放前要设计去重范围 |
9.1 数据库入库失败时的处理
Kafka 消费容器可以配置有限次数的异常重试:
| |
它会间隔 1 秒进行 3 次重试。持续入库失败时,消息还没有写入数据库,项目也尚未配置可靠转存这类消息的恢复器。要满足可靠接收的需求,这条异常路径需要补齐:保留重投,或先可靠转存失败消息再推进消费进度。
已落库的转发失败由 FAILED 记录和管理入口处理。
9.2 并发转发与事件顺序
虚拟线程并发执行时,较晚消费的消息可以先完成 HTTP;失败重试也会改变到达顺序。若同一泊位的计费处理依赖事件顺序,需要按业务键串行投递,或由第三方根据事件时间处理乱序。
十、字段映射与后续扩展:主流程之外也有业务细节
请求构建时,根据消息类型选择字段映射和目标接口。这里有五类消息:
| 消息类型 | 第三方接口 | 主要内容 |
|---|---|---|
VEHICLE_EVENT | /mch/business | 车辆出入事件、图片、可信度 |
HEARTBEAT | /mch/heartbeat | 摄像头定时抓拍图 |
PASS_CAR_RECORD | /mch/passingVehicle | 过车记录 |
GEOMAGNETIC_EVENT | /dgApi/evt | 地磁事件 |
GEOMAGNETIC_DEVICE_INFO | /dgApi/uploadDevice | 地磁设备信息 |
车辆与摄像头消息、地磁消息分别设置监听入口,再交给统一的批处理流程。
10.1 车辆事件的字段映射
字段映射看起来多是字段搬运,但如果出入方向映射反了,请求照样可能返回成功,业务结果却完全错误。
挑几个当前实现中的例子:
| 上游字段或值 | 发给第三方的结果 |
|---|---|
inoutType=0,出场 | enter_state="2" |
inoutType=1,进场 | enter_state="1" |
可信度 0.854 | 四舍五入并限制到 0~100 后,得到 "85" |
| 图片类型 1 / 2 / 3 / 4 | 分别映射成 "1" / "2" / "0" / "2" |
当前映射中,缺失或未知的出入类型默认按驶入处理。这类默认值会影响计费事件的含义,对接时应和真实消息样例一起核对。
10.2 地磁接入复用可靠性处理,单独适配协议
地磁事件和设备信息使用独立的平台地址、凭证、token 和 Mapper。接入层按来源 Topic 选择映射方式,映射完成后继续走已有的转发记录、HTTP 结果处理与重试流程。
地磁业务响应提示 token 失效时,服务清除 token 缓存;后续请求重新获取凭证,失败记录按主链路的重试配置处理。
10.3 img_flag=1 又带来了一条 IOT 回调链路
过车记录转发成功,且响应的 data.img_flag=1 时,服务会尝试向 IOT 平台发起设备功能调用。
这条链路有独立的持久化记录、执行器、Semaphore、超时和调度器。当前配置为并发 50、最多尝试 4 次(包含首次)、60 秒有效窗口。
已经持久化的回调由独立调度器补偿,回调失败不改变第三方转发成功的状态。两条链路分别提交事务:若回调入库本身失败,异常会被捕获,主记录仍可记为成功,此时需要通过触发失败日志定位未创建的回调。
十一、数据库分区/分表
数据按处理状态、失败诊断、幂等判断和历史归档分别存放:
| 表或表组 | 保存什么 | 当前组织方式 |
|---|---|---|
forward_records | 原始消息、最新状态、次数、错误、可选响应体 | 按 created_at 日分区,主键为 (created_at, id) |
forward_retry_logs | 失败尝试与请求构建失败的诊断信息 | 按 attempted_at 日分区 |
forward_message_keys | 消息 ID 到主记录 ID 的归属 | 按消息键 HASH 分区 |
forward_vehicle_event_item_keys | 车辆事件的首次转发资格 | 按 itemId HASH 分区 |
archive.* | 从热表搬出的历史记录与日志 | 按月分区 |
消息唯一性由独立幂等键表承担,主表的 message_key 使用普通索引。这样,幂等键可以按键分区,转发记录则按时间分区,各自服务于不同的访问方式。
成功路径通过原生 UPDATE 写入状态,减少数据库查询和日志写入。forward_retry_logs 保存转发失败与请求构建失败的诊断过程,成功尝试只更新主记录。
响应体在解析业务结果之后,按接口白名单决定是否保存。例如,可以保留车辆事件、过车记录和地磁接口的响应,把高频心跳响应排除在外,减少存储开销。
归档方面,当前热数据配置保留 30 天。维护任务预建分区、分批复制历史数据,核对行数后删除对应热分区。冷归档达到配置的 3 年保留期后发出告警,删除由人工处理。
十二、监控与日常排障
监控围绕 5 个记录状态 Gauge,以及一个 Semaphore 剩余许可 Gauge 展开:
| Prometheus 指标 | 实际含义 |
|---|---|
forwarder_records_pending | 最近 1 天创建、当前处于 PENDING 的记录数 |
forwarder_records_in_progress | 最近 1 天创建、当前处于 IN_PROGRESS 的记录数 |
forwarder_records_success | 最近 1 天创建、当前处于 SUCCESS 的记录数 |
forwarder_records_failed | 最近 1 天创建、当前处于 FAILED 的记录数 |
forwarder_records_duplicate | 最近 1 天创建、当前处于 DUPLICATE 的记录数 |
forwarder_semaphore_available_permits | 当前实例的主链路剩余许可数 |
这里按记录创建时间过滤最近 1 天的数据。随着旧记录滑出窗口,各状态数量会下降,因此这些值使用 Gauge 表示。观察待办存量趋势,可以写:
| |
当前指标适合观察存量和积压趋势。若需要成功吞吐量,可在成功处理事件上增加 Counter 或 Timer,再按时间计算处理速率。
多实例共用数据库时,记录数量是同一份全库统计,看板应按数据库维度去重展示;Semaphore 是实例本地状态,按实例观察或汇总。
每次抓取的 5 个状态 Gauge 都会访问数据库,采集频率需要计入查询负载。排查积压时,可以按顺序查看 Kafka lag、数据库 PENDING、并发许可、连接池等待和下游错误;超过一天的滞留记录则通过管理查询定位。
管理页面支持查询记录、响应和失败日志,也支持对热表 FAILED 记录发起手动重试:重置状态并立即尝试分发,再通过记录状态确认结果。超过自动重试窗口的旧记录若即时分发遇到背压,会留在 PENDING,调度器不再扫描它。
十三、关键参数
调参时,我更关心参数之间的关系。下面用一组示例值说明它们分别影响哪一段处理:
| 参数 | 示例值 | 调整时关注什么 |
|---|---|---|
| 单批消息上限 | 100 条 | 批量写入效率、单批处理时间、消费间隔 |
| 每个监听容器的并发数 | 3 | Topic 分区数、实例数和接收侧数据库负载 |
| 单实例转发任务并发 | 200 | 下游容量,以及所有实例的总并发额度 |
| 获取并发许可的最长等待 | 100ms | 消费线程的等待时间与批次处理时间 |
| HTTP 请求超时 | 10 秒 | 下游正常响应耗时和任务占用许可的时长 |
| 失败重试次数 | 5 次,不含首次 | 业务允许的恢复时间与失败请求总量 |
| 自动重试窗口 | 1 天 | 消息的业务有效期和自动补发范围 |
| 幂等键保留期 | 3 天 | 上游重复投递、历史补数和回放的时间跨度 |
例如,单批消息数和许可等待时间一起决定消费线程会等待多久;HTTP 超时和任务并发一起影响资源占用;重试窗口与幂等保留期则决定失败恢复、历史回放时如何识别重复事件。
扩容实例时,也要一起核算下游总并发、数据库连接数,并为雪花 ID 分配不同的节点组合。
写在最后
回头看,这个项目里我最想留下的经验是:每次把工作交给下一环,都要知道交接完成的标志,以及中断以后从哪里继续。
Kafka 交给数据库,以事务提交为界;数据库交给执行任务,需要领取状态;HTTP 交给第三方,还需要对方的业务确认。而最后这一段只要存在“对方已经成功、本地还不知道”的窗口,就得认真对待重复请求。
虚拟线程让同步写法可以承载更多 I/O 等待,批量入库减少接收侧的数据库往返,短事务让连接及时归还。这些优化最终都落在同一件事上:让一条停车事件从被接收、被处理到留下结果。