使用Workflow框架实现同步API调用异步服务的最佳实践

2025-05-16 14:08:54作者：姚月梅Lane

在现代分布式系统中，经常会遇到需要将异步服务封装成同步API的场景。本文将详细介绍如何利用Workflow框架优雅地解决这一问题。

问题背景

在实际开发中，我们经常需要作为服务代理提供API，将接收到的HTTP请求转发给第三方服务。当第三方服务的API是异步设计时，如何将这种异步调用封装成同步API就成为一个技术挑战。

典型场景如下：

客户端发起HTTP请求到我们的服务
我们的服务将请求转发给第三方异步API
第三方服务处理完成后，通过HTTP回调通知我们的服务
我们的服务需要将最终结果返回给最初的客户端请求

核心解决方案

Workflow框架提供了多种机制来解决这类问题，其中最优雅的方式是使用WFMailboxTask和WFTimerTask的组合。

WFMailboxTask原理

WFMailboxTask是Workflow框架提供的一种特殊任务类型，它本质上是一个带有数据传递能力的计数器。主要特点包括：

可以阻塞任务序列的执行
支持通过名称或指针进行消息投递
收到消息后会继续执行后续任务

实现方案

接收客户端请求：当收到客户端HTTP请求时，创建并启动一个WFMailboxTask，将其加入到当前任务序列中。
转发请求：同时将请求转发给第三方异步API，并设置好回调地址。
设置超时：创建一个WFTimerTask作为超时控制，在指定时间后触发。
处理回调：当收到第三方服务的回调时，通过send_by_name向对应的WFMailboxTask发送消息。
结果返回：无论是正常回调还是超时，都通过WFMailboxTask的callback返回最终结果给客户端。

代码结构示例

// 处理客户端HTTP请求
void process_client_request(WFHttpTask* server_task) {
    // 创建mailbox任务
    auto* mailbox = WFTaskFactory::create_mailbox_task("request_id", nullptr);
    
    // 设置mailbox回调
    mailbox->set_callback([server_task](WFMailboxTask* task) {
        // 处理结果并返回给客户端
        // ...
    });
    
    // 将mailbox加入任务序列
    series_of(server_task)->push_back(mailbox);
    
    // 创建定时器任务
    auto* timer = WFTaskFactory::create_timer_task(10, nullptr);
    timer->set_callback([](WFTimerTask* task) {
        // 超时处理
        int ret = WFTaskFactory::send_by_name("request_id", nullptr);
        if (ret == 0) {
            // 已经收到回调，无需处理
        }
    });
    timer->start();
    
    // 转发请求给第三方服务
    // ...
}

// 处理第三方回调
void process_thirdparty_callback(WFHttpTask* task) {
    // 处理回调数据
    // ...
    
    // 通知mailbox任务
    int ret = WFTaskFactory::send_by_name("request_id", data_ptr);
    if (ret == 0) {
        // 已经超时，释放资源
        free(data_ptr);
    }
}