做物联网对接时,经常会遇到这种情况:设备数据已经通过 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:内存队列转发

1
Kafka → 内存队列 → HTTP

这个方案结构简单,少了一次数据库写入,消息进入进程后就可以排队发送。

关键在于 ACK 时机。如果消息进入内存队列就提交 offset,进程异常退出会丢掉还没发出的待办。如果等 HTTP 完成再提交,未确认的消息可以交给 Kafka 重投,但批次确认、并发完成顺序和队列容量都需要一起设计。

它适合处理链路较短、主要依靠 Kafka 回放恢复的场景。对于这个项目,逐条查询处理状态、延迟重试和人工补发还需要另外建设。

2.2 方案 B:先转发,再记录结果

1
Kafka → HTTP → DB 记录结果 → 提交 offset

这个方案把“第三方收到消息”作为消费完成的重要条件,正常路径直观,数据库也能保留转发结果。

代价是消费进度与下游响应时间紧密关联:一次超时就会拖长本批处理时间。如果第三方已经处理成功,结果落库前服务退出,Kafka 重投后会再次发起 HTTP 请求,仍然需要下游幂等配合。

在请求量较低、接口稳定时,这种做法容易实现。面对集中到来的事件和不稳定的下游,更希望先把消息接住,再独立安排发送。

2.3 方案 C:先持久化,再异步转发

1
2
Kafka → DB 保存消息与状态 → 提交异步转发任务
                            → 整批分发返回后 ACK

这个方案把数据库作为待办工作的保存位置。消息入库之后,即使首次任务没有拿到并发许可,也能留在数据库中等待后续处理。服务重启后,调度器根据状态和时间继续执行。

与此同时,接收与发送可以分别优化:接收侧做批量写入,发送侧用虚拟线程承载 HTTP 等待,重试侧按到期时间领取任务。

它增加了数据库写入和维护成本。下游持续变慢时,积压会表现为数据库中的待办记录增长,因此还要配置并发上限、重试窗口和数据归档。

2.4 为什么选择方案 C

把三种方案放在一起看:

方案待办与恢复方式状态查询和补发主要成本
A:内存队列转发未 ACK 的消息由 Kafka 重投;提前 ACK 的待办依赖进程内存需要补充记录与管理机制队列容量、并发完成与 offset 协调
B:HTTP 后记录结果在 HTTP 和结果落库完成后 ACK,异常时重投有结果记录,恢复仍需处理不确定结果下游延迟影响消费进度
C:DB 后异步转发数据库保存消息、状态和重试时间可以围绕同一条记录查询、重试和归档数据库写入、积压存储与维护

这个停车场景既需要实时转发,也需要事后查清每条事件的去向,所以我选择了方案 C。它让可靠接收、并发发送和故障恢复有了各自清晰的处理位置,后续扩展地磁和 IOT 回调时,也可以沿用这套思路。

三、总体技术架构

服务围绕两条路径运行:新消息从 Kafka 进入,持久化后提交 HTTP 任务;待处理记录从数据库进入,经过调度再次提交任务。 两条路径共用转发执行器、请求映射和结果处理。

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 组件与职责

组件项目选型选择理由
JavaJava 21 编译目标使用正式的虚拟线程 API 承载 I/O 等待
应用框架Spring Boot 3.3.4复用配置、事务、管理接口和监控生态
Kafka 客户端Spring Kafka 批量监听便于批量持久化,并显式控制 ACK 时机
HTTP 客户端JDK HttpClient内置 HTTP/2 支持、超时控制和连接复用
并发模型虚拟线程 + Semaphore保持同步调用写法,并限制同时执行的转发任务
数据访问PostgreSQL + JDBC + Spring Data JPAJDBC 批量写入,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 到第三方平台经过哪些步骤。

首次转发时序:数据库事务提交后提交虚拟线程任务,整批分发返回后 ACK;HTTP 与 ACK 可以交错

5.1 接收一批消息

接收端遍历这一批消息,提取 messageId 和车辆事件的 data.itemId,保留原始 payload 与 Kafka 来源信息,再执行持久化和任务分发。

把关键顺序展开,可以写成下面的伪代码:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
var records = parseBatch(kafkaRecords);

// 通过事务 Bean 调用,返回时独立事务已经提交。
var persisted = persistence.insertMessageKeysAndRecords(records);

// 根据入库和去重结果,尝试提交虚拟线程任务。
dispatchPersistedRecords(persisted);

// 整批分发返回后,确认 Kafka 消费进度。
ack.acknowledge();

批量入库使用 REQUIRES_NEW 独立事务,一起完成以下操作:

  1. 对批次内的 messageKey 去重,批量插入消息幂等键。
  2. 查询幂等键的归属,确认哪些消息是本批次新接收的。
  3. 为符合条件的车辆事件抢占 itemId 转发资格。
  4. 批量插入新消息的 forward_records。

幂等键和主记录一起提交,避免只占了一个“已经处理过”的位置,却没有留下真正的待办记录。

5.2 首次入库,已经是 IN_PROGRESS

通过去重的新消息以 IN_PROGRESS、attempt_count=1 入库,将首次领取合并到插入操作中。发送阶段直接使用这条已领取的记录,少做一次“先查再改为处理中”的数据库操作。

接下来还需要取得 Semaphore 许可并提交任务。如果获取许可失败,或执行器拒绝任务,分发模块会把记录释放回:

1
2
3
status = PENDING
attempt_count = 0
next_retry_at = NULL

因此,IN_PROGRESS 包括已领取、等待执行以及正在处理的任务;实际执行并发由 Semaphore 控制。

5.3 ACK 在哪里,决定了故障后的接力方式

整批落库 → 尝试异步分发 → ACK 是消费线程上的执行顺序。虚拟线程在任务提交后就可以运行,HTTP 发送与 ACK 的先后取决于调度。

批量监听时,无参数的 ack.acknowledge() 确认这一批记录,并按各分区推进消费位置,所以代码将它放在整批处理之后。若放进逐条处理的循环,第一次调用就会确认本批,留下尚未处理的消息。

如果分发方法抛出异常,正常路径不会执行 ACK;如果只是没有拿到并发许可,则可以返回,已落库的消息由后续扫描接手。

对于输入内容,代码会记录并跳过 null 或空白消息,随批次确认;非空的非法 JSON 会在提取标识失败后使用 offset 组合键入库,在后续构建请求时记录为 FAILED。

六、虚拟线程解决等待,Semaphore 控制数量

虚拟线程最吸引我的地方,是不用把业务代码拆成一串回调。

这个项目里的 HTTP 调用仍然是同步写法:

1
2
3
HttpResponse<String> response = httpClient.send(
        httpRequest,
        HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));

调用它的虚拟线程会等待响应。对于适合虚拟线程的阻塞 I/O,JVM 可以在等待期间释放底层线程,让它执行其他任务,从而承载更多并发等待。

等待中的任务仍然会持有消息、请求体和响应处理所需的对象,也会占用网络资源,所以还需要限制在途任务数量。

6.1 两个 Bean,就是主链路的并发骨架

核心配置是一个虚拟线程执行器,以及一个控制并发数量的信号量:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
@Bean(destroyMethod = "close")
@Primary
public ExecutorService virtualThreadExecutor() {
    return Executors.newVirtualThreadPerTaskExecutor();
}

@Bean
@Primary
public Semaphore httpConcurrencySemaphore(
        @Value("${forwarder.executor.max-concurrency:200}") int maxConcurrency) {
    return new Semaphore(maxConcurrency, true);
}

分发模块在消费线程上先调用带超时的 tryAcquire(),拿到许可才提交任务。例如,设置 200 个许可,最长等 100ms。

首次投递获得许可后的核心提交逻辑如下,forwardClaimed() 表示执行已领取记录的转发过程:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
try {
    virtualThreadExecutor.submit(() -> {
        try {
            forwardClaimed(record);
        } finally {
            httpConcurrencySemaphore.release();
        }
    });
} catch (RejectedExecutionException ex) {
    // 任务尚未执行,由提交方归还许可并释放首次领取状态。
    httpConcurrencySemaphore.release();
    transactionService.releaseInProgressToPending(record.getId());
    return false;
}

对于首次投递,等待许可超时或被中断时,也要把已领取记录释放回 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 再次报告同一次停车事件,是两类不同的重复。

当前代码分了两层处理:

去重对象标识来源存在哪里命中后的行为
消息重复顶层 messageIdforward_message_keys不新增主记录,按已有记录状态处理
车辆业务事件重复VEHICLE_EVENT 的 data.itemIdforward_vehicle_event_item_keys新消息仍入库,标记 DUPLICATE,不发 HTTP

举个例子:

1
2
3
4
5
消息 A:messageId=m-101,itemId=parking-event-7
消息 B:messageId=m-102,itemId=parking-event-7

A 抢到 itemId:正常转发
B 的 messageId 虽然不同,但 itemId 已存在:留档为 DUPLICATE

这里的规则是保留期内先抢到转发资格的记录负责这次业务事件。如果 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 是:

1
2
3
INSERT INTO forward_message_keys (message_key, record_id, created_at)
VALUES (?, ?, NOW())
ON CONFLICT (message_key) DO NOTHING;

随后批量查询 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 的,是后面的条件更新:

1
2
3
4
5
6
UPDATE forward_records
SET status = 'IN_PROGRESS',
    attempt_count = attempt_count + 1,
    updated_at = NOW()
WHERE id = :id
  AND status = 'PENDING';

领取操作检查受影响行数:更新成功,才继续读取记录并发送 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 不包含首次。终止条件是:

1
2
3
4
int maxTotalAttempts = retryCfg.getMaxAttempts() + 1;
if (attemptCount >= maxTotalAttempts) {
    record.setStatus(ForwardStatus.FAILED);
}

将 max-attempts 设为 0,首次处理失败后即停止追加常规失败重试;背压释放回 PENDING 的任务和符合条件的超时恢复任务,仍由调度器处理。

以 max-attempts: 5 为例,最多是 1 次首次尝试 + 5 次重试,对应的基础延迟如下:

第几次尝试失败后续基础等待时间
15 秒
210 秒
320 秒
440 秒
580 秒
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
new DefaultErrorHandler(new FixedBackOff(1000L, 3L))

它会间隔 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 表示。观察待办存量趋势,可以写:

1
2
3
4
5
6
7
8
# 当前滚动窗口内的待办记录数
forwarder_records_pending

# 最近 5 分钟 Gauge 的变化趋势
deriv(forwarder_records_pending[5m])

# 仅适用于当前单实例许可数为 200 的配置
100 * (1 - forwarder_semaphore_available_permits / 200)

当前指标适合观察存量和积压趋势。若需要成功吞吐量,可在成功处理事件上增加 Counter 或 Timer,再按时间计算处理速率。

多实例共用数据库时,记录数量是同一份全库统计,看板应按数据库维度去重展示;Semaphore 是实例本地状态,按实例观察或汇总。

每次抓取的 5 个状态 Gauge 都会访问数据库,采集频率需要计入查询负载。排查积压时,可以按顺序查看 Kafka lag、数据库 PENDING、并发许可、连接池等待和下游错误;超过一天的滞留记录则通过管理查询定位。

管理页面支持查询记录、响应和失败日志,也支持对热表 FAILED 记录发起手动重试:重置状态并立即尝试分发,再通过记录状态确认结果。超过自动重试窗口的旧记录若即时分发遇到背压,会留在 PENDING,调度器不再扫描它。

十三、关键参数

调参时,我更关心参数之间的关系。下面用一组示例值说明它们分别影响哪一段处理:

参数示例值调整时关注什么
单批消息上限100 条批量写入效率、单批处理时间、消费间隔
每个监听容器的并发数3Topic 分区数、实例数和接收侧数据库负载
单实例转发任务并发200下游容量,以及所有实例的总并发额度
获取并发许可的最长等待100ms消费线程的等待时间与批次处理时间
HTTP 请求超时10 秒下游正常响应耗时和任务占用许可的时长
失败重试次数5 次,不含首次业务允许的恢复时间与失败请求总量
自动重试窗口1 天消息的业务有效期和自动补发范围
幂等键保留期3 天上游重复投递、历史补数和回放的时间跨度

例如,单批消息数和许可等待时间一起决定消费线程会等待多久;HTTP 超时和任务并发一起影响资源占用;重试窗口与幂等保留期则决定失败恢复、历史回放时如何识别重复事件。

扩容实例时,也要一起核算下游总并发、数据库连接数,并为雪花 ID 分配不同的节点组合。

写在最后

回头看,这个项目里我最想留下的经验是:每次把工作交给下一环,都要知道交接完成的标志,以及中断以后从哪里继续。

Kafka 交给数据库,以事务提交为界;数据库交给执行任务,需要领取状态;HTTP 交给第三方,还需要对方的业务确认。而最后这一段只要存在“对方已经成功、本地还不知道”的窗口,就得认真对待重复请求。

虚拟线程让同步写法可以承载更多 I/O 等待,批量入库减少接收侧的数据库往返,短事务让连接及时归还。这些优化最终都落在同一件事上:让一条停车事件从被接收、被处理到留下结果。