Debezium 无官方 C# 客户端，C# 应通过 Kafka 客户端（如 Confluent.Kafka）消费其输出的 Avro 或 JSON 消息，需正确解析嵌套结构、处理幂等与乱序，并配置 SSL、topic 保留策略及优雅关闭消费者。
Debezium 本身不提供 C# 客户端库
Debezium 是基于 Java 的 CDC 工具，它把变更事件写入 Kafka Topic，不直接暴露 HTTP API 或 .NET SDK。你在 C# 里“使用 Debezium”，实际是消费它产出的 Kafka 消息——关键不在 Debezium，而在 Kafka 客户端。常见误区是搜 Debezium C# client，结果找不到官方包，因为根本不存在。
必须用 Kafka 客户端（如 Confluent.Kafka）订阅 Debezium 写入的 Topic，再手动解析 Avro/JSON 格式的消息体。默认 Debezium 输出的是 Avro（需 Schema Registry），但可配成 JSON（设 value.converter=org.apache.kafka.connect.json.JsonConverter 并关掉 schemas.enable=false），这对 C# 更友好。
- 若选 Avro：需引入
Confluent.SchemaRegistry.Serdes.Avro，并确保 C# 端能访问Schema Registry地址（如http://schema-registry:8081） - 若选 JSON：配置 Debezium Connector 时加
"value.converter.schemas.enable": "false"，消息体就是纯 JSON，C# 可直接用System.Text.Json反序列化 - Topic 名默认为
{database.server.name}.{schema}.{table}，例如inventory.public.products，注意大小写和下划线
解析 Debezium JSON 消息结构要小心字段嵌套
Debezium 的 JSON 消息不是扁平结构，payload 字段里才真正包含变更数据，且分 before/after/source 等子对象。直接反序列化整个消息会失败或丢字段。
推荐定义最小契约类，只覆盖你关心的字段。例如捕获 MySQL products 表更新：
public class DebeziumEnvelope
{
public Payload payload { get; set; }
}
<p>public class Payload
{
public ProductData before { get; set; }
public ProductData after { get; set; }
public Source source { get; set; }
public string op { get; set; } // "c"=create, "u"=update, "d"=delete, "r"=snapshot
}</p><p>public class ProductData
{
public int id { get; set; }
public string name { get; set; }
public decimal price { get; set; }
}</p><p>public class Source
{
public string table { get; set; }
public string ts_ms { get; set; }
}-
op字段决定业务逻辑分支：删除操作after为空，得用before；快照阶段op是r，此时before也为空 -
ts_ms是毫秒时间戳，需转DateTimeOffset.FromUnixTimeMilliseconds(...) - 字段名默认跟数据库一致，若用了
column.propagate.source.type=true，可能多出__debezium_source_ts_ms这类字段，但非必需
Kafka 消费端必须处理重复与乱序
Debezium + Kafka 不保证 exactly-once 到 C# 应用层。Kafka 自身只保证 partition 内有序、at-least-once 投递；网络重试、消费者重启都可能导致同一条消息被多次拉取。C# 侧不能假设“收到即处理成功”。
- 给每条消息加唯一 ID：用
payload.source.ts_ms + payload.source.snapshot + payload.source.table拼接，或直接取 Kafka 的offset+partition做幂等键 - 业务写库前先查是否存在该变更 ID（如存 Redis 或本地 LRU Cache），存在则跳过
- 避免依赖消息顺序做状态叠加（如“+10 → -5”必须严格先后），Debezium 的
transaction.id可用于跨表事务聚合，但需自行解析和缓存 -
Confluent.Kafka默认自动提交 offset，建议关掉（"enable.auto.commit": "false"），在业务处理成功后再显式consumer.Commit()
从开发到上线容易漏掉的三件事
本地跑通不代表生产可用。这些点常被忽略，但一出问题就难定位：
- Kafka 和 Schema Registry 的 SSL 配置：生产环境通常启用 SASL_SSL，C# 客户端要配
"sasl.mechanism": "PLAIN"、"security.protocol": "SASL_SSL"，且证书路径必须正确（"ssl.ca.location"） - Debezium Connector 的
database.history.kafka.topic必须提前建好，且保留策略设长些（如retention.ms=604800000），否则重启 Connector 时可能因找不到历史 DDL 而失败 - C# 进程退出前没调用
consumer.Close()，会导致 Kafka 认为消费者还活着，触发 rebalance，新实例启动慢甚至卡住
Debezium 的变更事件本质是日志解析结果，它不校验业务一致性。C# 消费端要自己兜底：字段缺失时给默认值、数值溢出时截断、遇到未知 op 类型就告警而非 crash。别把数据库日志当 API 合约来用。
