深入理解C++ Workflow源码（3）

第3篇 WFNetworkTask 源码解析

如果说SeriesWork解决的是“任务怎么串起来”，那么WFNetworkTask解决的就是“一个网络任务到底长什么样”。

HTTP、Redis、MySQL、DNS 这些看起来完全不同的协议任务，在 Workflow 里最后都被统一成了同一个模板基类：

template<classREQ,classRESP>classWFNetworkTask:publicCommRequest

这一篇我们就沿着这条线往下看，理解 Workflow 是怎样把“请求/响应对象、连接、超时、回调、客户端/服务端差异”统一塞进一个网络任务里的。

一、WFNetworkTask 的定位：面向协议，站在通信框架之上

先看它的继承关系：

WFNetworkTask<REQ,RESP>->CommRequest->SubTask+CommSession

这条继承链很重要：

• SubTask说明它能被 Workflow 的工作流调度
• CommSession说明它能被通信框架Communicator驱动
• CommRequest说明它具备“请求一个通信目标”的能力

这意味着WFNetworkTask正好卡在两个世界中间：

• 对上，暴露给业务的是协议化请求/响应
• 对下，接入的是连接、socket、poller、超时控制

所以可以把它理解成：

Workflow 的网络任务适配层。

二、REQ / RESP 模板参数到底解决了什么

以 HTTP 为例：

usingWFHttpTask=WFNetworkTask<protocol::HttpRequest,protocol::HttpResponse>;

以 MySQL 为例：

usingWFMySQLTask=WFNetworkTask<protocol::MySQLRequest,protocol::MySQLResponse>;

这样设计有两个直接好处：

1. 协议对象天然强类型

用户在 callback 里拿到的get_req()/get_resp()是明确的协议对象，不需要自己做类型转换。

2. 调度逻辑和协议逻辑解耦

网络任务的调度模型可以完全复用，而协议差异只体现在：

• message_out()
• message_in()
• 具体的REQ/RESP编解码

这就是 Workflow “协议丰富，但内核统一”的一个典型体现。

三、WFNetworkTask 持有了哪些语义

WFNetworkTask自身并不大，但语义非常全：

REQ req;RESP resp;std::function<void(WFNetworkTask<REQ,RESP>*)>prepare;std::function<void(WFNetworkTask<REQ,RESP>*)>callback;intsend_timeo;intreceive_timeo;intkeep_alive_timeo;intwatch_timeo;void*user_data;intstate;interror;inttimeout_reason;

从这些字段能看出，它同时承担了：

• 协议数据载体：req/resp
• 用户扩展入口：prepare/callback/user_data
• 传输策略：发送超时、接收超时、keep-alive、watch timeout
• 结果状态：state/error/timeout_reason

也就是说，一个WFNetworkTask本身就足以描述“一次网络交互”的完整语义。

四、为什么它的 start() 也要先进 Series

客户端任务的start()依旧是：

voidstart(){assert(!series_of(this));Workflow::start_series_work(this,nullptr);}

这说明网络任务在 Workflow 里没有特殊地位。
它和计算任务、定时器任务一样，依然只是工作流中的一个节点。

这种统一性非常重要，因为它意味着：

• 一个 HTTP 请求后面可以无缝接一个定时器
• 一个 MySQL 请求后面可以无缝接一个线程计算任务
• 所有任务共享同样的串并联语义

这就是 Workflow 名字里 “work flow” 的真正含义。

五、CommRequest：把网络任务变成可投递请求

WFNetworkTask的直接父类CommRequest非常关键：

virtualvoiddispatch(){if(this->scheduler->request(this,this->object,this->wait_timeout,&this->target)<0){this->handle(CS_STATE_ERROR,errno);}}

这里做的事其实很纯粹：

1. 向CommScheduler申请一个目标CommTarget
2. 让Communicator去建立/复用连接并驱动收发
3. 如果投递失败，立刻进入错误回调路径

这层设计非常巧妙，因为：

• WFNetworkTask不直接操作 socket
• 它也不关心连接是否复用
• 它只知道“我需要一个可通信目标，把我送进去”

这让网络任务保持了很高的抽象层级。

六、prepare 和 callback 分别是什么角色

很多人第一次看 Workflow 会注意到 callback，但忽略了prepare。

callback

这个大家熟悉，表示任务结束后执行业务逻辑：

if(this->callback)this->callback(this);

prepare

它在真正发送前调用：

if(this->prepare)this->prepare(this);return&this->req;

这意味着你可以在连接真正建立之后，再最后一次修正请求。

这在实际工程里非常有价值，比如：

• 根据最终连接信息补充 header
• 做 trace 注入
• 做签名
• 做按连接态决定的请求修正

所以prepare不是 callback 的替代品，而是网络任务发送前的最后一个可编程钩子。

七、客户端任务和服务端任务其实是两种不同生命形态

Workflow 在WFTask.inl里把网络任务拆成了两个分支：

• WFClientTask
• WFServerTask

它们都基于WFNetworkTask，但生命周期差异非常大。

1. 客户端任务：一次请求，一次回调，一次销毁

客户端done()非常直接：

if(this->callback)this->callback(this);deletethis;returnseries->pop();

这是典型的一次性交互模型。

2. 服务端任务：先处理请求，再决定是否回包

服务端任务更复杂，它内部甚至有一个Processor子任务：

classProcessor:publicSubTask{virtualvoiddispatch(){this->process(this->task);this->task=NULL;this->subtask_done();}};

服务端的处理流程不是“收到包立刻 done”，而是：

1. 收到请求
2. 构造一个专属 series
3. 执行用户 process
4. 再决定 reply / shutdown / noreply

这让服务端任务也能自然接入 Workflow 的任务流模型，而不是特判成另一套框架。

八、超时为什么分成这么多种

WFNetworkTask提供四类时间控制：

set_send_timeout(inttimeout);set_receive_timeout(inttimeout);set_keep_alive(inttimeout);set_watch_timeout(inttimeout);

这背后反映的是 Workflow 对网络过程的细粒度建模。

send timeout

发送阶段超时。

receive timeout

接收阶段超时。

keep alive timeout

连接在空闲池里可复用多久。

watch timeout

首次等待阶段超时，常用于更复杂的场景。

再配合timeout_reason：

TOR_WAIT_TIMEOUT TOR_CONNECT_TIMEOUT TOR_TRANSMIT_TIMEOUT

你会发现 Workflow 不满足于“超时了”这一级别，而是想告诉你：

它究竟是等资源超时、建连超时，还是传输超时。

这对于线上诊断非常有价值。

九、为什么 get_connection() 这么重要

WFNetworkTask提供：

virtualWFConnection*get_connection()const=0;

这不是装饰性接口，它非常重要，因为它把“请求语义”延伸到了“连接语义”。

有了它，用户或任务实现可以：

• 取连接上下文
• 做长连接事务
• 按连接状态做特殊逻辑

以 MySQL 为例，事务型任务就会利用固定连接语义来保证会话一致性。

所以，Workflow 里的任务不是只面对消息包，它也能感知连接这一层。

十、复杂客户端任务：真正的威力在WFComplexClientTask

真正有意思的不是WFClientTask，而是它上面的WFComplexClientTask。

这是 Workflow 客户端协议任务的通用骨架，它额外处理了：

• URI 初始化
• 默认端口补全
• RouteManager 路由
• DNS 解析
• 重定向
• 重试
• 固定地址 / 固定连接

比如这里的init_with_uri()，就已经把 URI 校验、端口补全和初始化逻辑串起来了。

更重要的是，复杂客户端任务通过覆写下面几个函数，就能拼出不同协议的行为：

virtualboolinit_success();virtualvoidinit_failed();virtualboolcheck_request();virtualWFRouterTask*route();virtualboolfinish_once();

这相当于给不同协议提供了一套统一的“扩展点模板”。

所以 HTTP、MySQL、Redis 等任务虽然行为差异很大，但它们的骨架极其相似。

十一、网络任务的完成，不只是“收到响应”

在 Workflow 里，一个网络任务完成，并不只是意味着“socket 收到数据”。

它至少包括这些阶段：

1. 选择目标
2. 建立或复用连接
3. 发送请求
4. 接收并解析响应
5. 处理错误/重试/重定向
6. 进入 callback
7. 回到 series 继续工作流

这也是为什么 Workflow 的网络任务值得被当成“一等公民”去设计，而不是一个简单的 future 或 callback wrapper。

十二、从 WFNetworkTask 里能看出的设计美感

我个人觉得，WFNetworkTask最漂亮的地方在于它完成了三件事的统一：

1. 协议统一

HTTP、MySQL、Redis、DNS 统一成REQ/RESP模板。

2. 调度统一

所有网络任务统一走CommRequest -> CommScheduler -> Communicator。

3. 工作流统一

所有网络任务最终还是SubTask，可以进入SeriesWork。

这让整个框架没有“协议库”和“工作流库”的断层，而是天然一体化。

十三、小结

读完WFNetworkTask之后，你应该建立这样一个心智模型：

• 它不是一个简单的“请求对象”
• 它是一个可被工作流调度的通信会话
• 它站在协议层与通信层之间
• 它把请求/响应、连接、超时、回调统一打包成了一个任务对象

用一句更凝练的话说：

WFNetworkTask是 Workflow 里“协议化异步通信”的统一载体。