Flink各模块强耦合，flink-streaming-java与flink-clients版本不匹配会导致NoClassDefFoundError或JobManager未就绪等异常；须用flink-bom统一管理版本，避免patch差异引发序列化失败。
用 maven 引入 Flink 依赖时，为什么 flink-streaming-java 和 flink-clients 必须匹配版本？
因为 Flink 各模块之间强耦合，flink-clients 负责作业提交、配置解析，flink-streaming-java 提供 DataStream API；版本不一致会导致 NoClassDefFoundError 或 IllegalStateException: JobManager not ready 这类运行时异常。
实操建议：
立即学习“Java免费学习笔记（深入）”；
- 统一使用 Flink 官方推荐的 BOM（Bill of Materials）管理依赖版本，比如在
pom.xml中引入flink-bom并设为importscope - 避免手动指定子模块版本——哪怕只差一个 patch 版本（如
1.18.0vs1.18.1），也可能因序列化协议微调而失败 - 本地开发调试时，优先用
flink-runtime-web+flink-streaming-java+flink-clients三件套，别过早加flink-connector-kafka等扩展包
本地跑 StreamExecutionEnvironment 时，env.execute() 卡住或报 Job has been cancelled
这不是代码写错了，而是默认启动了 LocalStreamEnvironment，它会尝试绑定本地端口（如 8081）并启动 mini JobManager；一旦端口被占、JVM 退出过快、或没加日志输出，就表现为“卡住”或“莫名取消”。
实操建议：
立即学习“Java免费学习笔记（深入）”；
- 加一句
env.setParallelism(1)，避免多线程调度干扰调试 - 确保 main 方法末尾有阻塞逻辑，比如
System.in.read()，否则 JVM 直接退出，作业被强制 cancel - 想看 Web UI？改用
StreamExecutionEnvironment.createLocalEnvironmentWithWebUI(new Configuration())，但注意它会占用 8081 端口，冲突时要配rest.port - 生产环境不用这个模式——Local 模式只适合单机验证逻辑，不能测 checkpoint、state backend 行为
为什么 StateTtlConfig 设了却没生效？
因为 TTL 不是自动开启的：必须显式调用 StateDescriptor.enableTimeToLive()，且仅对 ValueState、MapState 等支持 TTL 的 state 类型有效；ListState 和 ReducingState 默认不支持。
实操建议：
立即学习“Java免费学习笔记（深入）”；
- 检查 state descriptor 创建后是否调用了
.enableTimeToLive(ttlConfig)，漏掉这步等于白配 - TTL 清理是惰性的：只在 state 访问时触发，不会后台定时扫描——所以空闲 key 可能长期残留
- 如果用 RocksDB backend，记得开
state.backend.rocksdb.ttl.compaction.filter.enabled: true配置，否则 compaction 阶段不清理过期数据 - 测试时用
MemoryStateBackend更容易观察 TTL 效果，但别在生产环境用它
用 FlinkKafkaConsumer 读 Kafka，为什么 offset 不提交或重复消费？
根本原因是 checkpoint 机制和 Kafka 提交策略没对齐。Flink 默认通过 checkpoint 保存 offset，不是靠 Kafka 自动提交；如果关了 checkpoint 或设置 enable.auto.commit=false（Kafka client 默认值），offset 就只存在内存里，重启就丢。
实操建议：
立即学习“Java免费学习笔记（深入）”；
- 必须启用 checkpoint：
env.enableCheckpointing(5000)，且setCheckpointingMode(CheckpointingMode.EXACTLY_ONCE) - Kafka consumer 构造时传入
props.put("group.id", "my-app")，但不要设enable.auto.commit——让 Flink 全权管理 offset - 如果要用 Kafka 的 earliest/latest 自动定位，得在 consumer 构造前设
setStartFromGroupOffsets()或setStartFromEarliest()，而不是靠 consumer config - 注意 Kafka broker 版本兼容性：
FlinkKafkaConsumer从 1.15 开始弃用旧版flink-connector-kafka，改用统一的flink-connector-kafka（无下划线），旧写法在 1.17+ 会编译失败
真正麻烦的从来不是搭环境，而是状态怎么存、offset 怎么管、checkpoint 失败后从哪恢复——这些细节藏在配置组合和运行时行为里，不跑起来压根看不出问题。
