5.1 DataStream API：发动机舱里的完全控制权

5.1 DataStream API：发动机舱里的完全控制权

本节摘要：DataStream API 是 Flink 的底层通用表达层：无界数据集上的转换算子，加上带状态钩子的进程函数。本节梳理它的算子体系、进程函数这对"状态加定时器"的组合拳，以及什么时候值得为控制权付出样板代码的代价。它是理解 SQL 在底下生成什么代码的最佳教材。

从最高的一层往下看

第 3、4 两章的概念（时间、窗口、状态、检查点）都还是图纸，本章开始它们变成代码。第一站先下到发动机舱：DataStream API。它之所以值得先学，不只是因为它是 SQL 的底座，更因为它把引擎的全部能力摊开在你面前——每一份状态都由你亲手声明，每一个定时器都由你亲手设定。读懂了它，5.2 节里 SQL 的执行计划在你眼里就不再黑盒。

算子体系：从转换到分区

DataStream 的主体是一组熟悉的函数式算子，作用在"无限的数据集"上：map 一对一转换，filter 过滤，flatMap 一对多展开，union 简单合并多流，connect 把两条不同类型的流"接在一起"供后续按流分别处理（做双流 join 的前置动作）。这些算子是无状态的：进一条出一条，不记忆。

真正让 DataStream 有资格承载复杂业务的，是 keyBy 之后的进程函数（ProcessFunction）家族。KeyedProcessFunction 给你三样此前章节反复铺垫的东西：键控状态的读写（第 4 章）、事件时间定时器（第 3 章的时间语义落地）、对所有输入数据的完全处理权。定时器的语义值得强调：注册"当水位线推进到 T 时回调我"，引擎在时间到达时把回调投递回来——乱序世界的"等一等再决定"，全靠它实现。

// 业务：支付成功后 30 分钟内出现退款，则标记"秒退"订单（简化示意）
public class RefundWatch extends KeyedProcessFunction<String, OrderEvent, String> {
    private ValueState<OrderEvent> pendingPay;

    @Override
    public void processElement(OrderEvent e, Context ctx, Collector<String> out) throws Exception {
        if ("pay".equals(e.getType())) {
            pendingPay.update(e);                       // 记下这笔支付
            long deadline = e.getTs() + 30L * 60 * 1000;
            ctx.timerService().registerEventTimeTimer(deadline);  // 30 分钟后闹铃
        } else if ("refund".equals(e.getType())) {
            OrderEvent pay = pendingPay.value();
            if (pay != null) {                          // 等待期内的退款：秒退
                out.collect("秒退订单: " + e.getOrderId());
                pendingPay.clear();
            }
        }
    }

    @Override
    public void onTimer(long ts, OnTimerContext ctx, Collector<String> out) {
        pendingPay.clear();                             // 30 分钟平安无事：清状态放行
    }
}
​

这十几行代码浓缩了 DataStream 的全部气质：状态、时间、逻辑揉在一个函数里，你说了算。代价也摆在明面上——状态生命周期、清理时机、定时器粒度全是你的责任，样板代码随业务复杂度线性膨胀。

图 5-1 API 分层栈：表达力与控制力的交换

什么时候值得下到这一层

按值班室的实战经验，DataStream 的进程函数在四种场景里不可替代。场景一：精细的状态生命周期——SQL 的状态 TTL 是键级的粗粒度，而"按业务事件主动清理"（比如订单支付后清理等待状态，如上面代码的 onTimer）只有进程函数做得到。场景二：跨流的有状态关联——双流 join 的"等待与超时"语义复杂时，connect 加进程函数比 SQL interval join 更可控。场景三：逐条决策的复杂规则——风控规则带十几个条件与外部特征查询时，SQL 的表达力会捉襟见肘。场景四：性能敏感的热路径——绕开 SQL 生成的通用序列化路径，手写更紧凑的类型与状态，热键场景常能省出可观资源。

相应的忠告也直白：聚合报表类需求不要来这层凑热闹。手写窗口的状态布局、序列化与清理，多半不如 SQL 优化器的产出，还搭上成倍的维护代码。

⚠️ 常见坑：进程函数里注册了定时器却忘了在合适的时机删（deleteEventTimeTimer），或在状态里堆积了永不清理的中间对象——两者都是"状态慢性肿胀"的惯犯，第 4.4 节的解剖报告里都有它们的影子。

一段进程函数的评审实录

进程函数写起来自由，评审起来也就格外要紧。拿一段真实评审记录做教材。提交的代码：按用户做点击去重，ValueState 记录三十秒内的访问指纹，processElement 里注册三十秒的定时器做清理。评审提出三个问题。问题一：状态清理靠定时器，定时器挂了怎么办？——提交人补上了 TTL 兜底：定时器是主动清理，TTL 是被动保险，两者成对才算完整（8.2 的成对原则在编码层的映照）。问题二：热点用户的指纹状态多大？——高活跃用户三十秒内可能产生上百条访问，ValueState 里存列表会随活跃度膨胀；改成"只存一条最新指纹加计数"的紧凑结构，单键状态上限恒定。问题三：定时器数量多少？——每条数据注册一个定时器，峰值下百万级定时器同时挂起，定时器本身也是要快照的状态；改用"同键复用定时器"（已有未触发的定时器就不再注册），定时器量级降到键数量级。三个问题改完，函数的状态画像从"不可控"变成"有上界"。

这段实录是本节方法论的浓缩：进程函数的评审，本质是给状态、定时器、外部调用三样东西逐一定价。定价清楚的函数才能进生产——自由的对价，就是这份审慎。

本节要点

• DataStream 是"完全控制权"的表达层：算子负责无状态转换，进程函数补上状态、定时器与逐条决策。
• KeyedProcessFunction 的组合拳是"键控状态加事件时间定时器"，乱序世界的延迟决策全靠这对搭档。
• 四个不可替代场景：精细状态清理、复杂双流关联、逐条规则决策、热路径性能手艺活。
• 聚合报表默认上 SQL；下到 DataStream 的每一行样板代码，都要有明确的理由买单。

下一站上一级台阶：同样的聚合，用 SQL 写出来是什么样、引擎在底下替你做了什么、执行计划又该怎么看。