如何用TAF回调函数实现Oracle RAC故障转移自定义处理？

Oracle RAC的透明应用故障转移（Transparent Application Failover，简称TAF）并不是简单的物理重连动作。对OCI客户端来说，连接在切换到备份节点后，原来打开的游标、临时LOB、会话级参数都需要重新准备。TAF回调函数正是在这个过程中为应用提供了插入自定义处理逻辑的机会。它的接口由Oracle Call Interface定义，通常用C语言完成注册，但理解其中的事件模型对任何使用RAC的开发者都有价值。

在开始编写回调之前，需要先分清两个容易混淆的层次：Oracle Net配置负责“是否启用TAF、用哪一种模式切换”，而OCI回调负责“切换前后应用要额外做什么”。两者配合才能达到真正的业务连续性。下面从事件类型、注册方法、业务逻辑设计和常见问题四个角度展开。

一、TAF回调函数的工作机制与事件类型

TAF回调函数由OCI在故障转移的不同阶段主动调用。调用时机和切换模式直接相关。tnsnames.ora中的FAILOVER_MODE参数决定基础行为：TYPE=SESSION表示切换后只恢复用户会话，应用先前打开的游标会失效，必须重新执行查询；TYPE=SELECT表示OCI会尝试重新打开并定位到故障前的游标位置，对只读查询比较友好。METHOD=BASIC是默认方式，客户端平时只连接主节点，故障发生时才去连接备份节点；METHOD=PRECONNECT会预先在备份实例上建立连接，切换速度更快，但会消耗更多资源。

回调函数本身对应OCI中的OCICallbackFailover类型，函数签名固定为：sb4 callback(dvoid *svchp, dvoid *envhp, dvoid *fo_ctx, ub4 fo_type, ub4 fo_event)。其中fo_type表示故障转移类型，常见取值为OCI_FO_SESSION或OCI_FO_SELECT；fo_event表示当前处于哪个阶段。OCI定义了六个事件：OCI_FO_BEGIN在故障转移开始前触发，适合做失效游标清理；OCI_FO_END在成功切换到备份实例后触发，适合重建会话状态；OCI_FO_ABORT在无法完成切换时触发；OCI_FO_REAUTH在重新认证前触发；OCI_FO_ERROR在调用过程中遇到低层错误时触发；OCI_FO_RETRY在每次重试连接前触发，应用可以根据返回值和重试计数决定是否继续等待。

理解这些事件的关键在于不要把所有恢复逻辑都堆在OCI_FO_END里。例如一个需要重新设置NLS参数的场景，OCI_FO_END自然是合适的位置；但如果当前业务有一个长事务需要在切换前明确回滚，放在OCI_FO_BEGIN里更合理，因为此时旧连接可能还可以发送最后一条SQL。不过需要注意，OCI_FO_BEGIN阶段的旧连接状态并不稳定，除非能容忍可能出现的ORA错误，否则应尽量少做重度操作。

二、在OCI程序中注册TAF回调函数

注册TAF回调函数的位置是在服务器句柄上，而不是会话句柄上。具体做法是先用OCIServerAttach建立服务器上下文，然后通过OCIAttrSet把回调函数地址写入OCI_ATTR_FOCBK属性，把自定义上下文指针写入OCI_ATTR_FOCBK_CTX属性。上下文指针可以指向一个结构体，用来保存应用自己的连接标识、重试次数、日志句柄等信息。OCI在触发回调时会把该指针原样传回，避免依赖全局变量。

下面的代码展示了一个最小化的注册流程。为了突出核心步骤，省略了部分错误处理，但保留了环境句柄和错误句柄的创建过程。

#include <stdio.h>
#include <oci.h>

typedef struct {
    char conn_name[32];
    int failover_count;
} taf_ctx;

sb4 taf_callback(dvoid *svchp, dvoid *envhp, dvoid *fo_ctx, ub4 fo_type, ub4 fo_event)
{
    taf_ctx *ctx = (taf_ctx *)fo_ctx;
    switch (fo_event) {
        case OCI_FO_BEGIN:
            printf("Failover begin, type=%u, count=%d\n", fo_type, ctx->failover_count);
            ctx->failover_count++;
            break;
        case OCI_FO_END:
            printf("Failover end\n");
            break;
        case OCI_FO_ABORT:
            printf("Failover aborted\n");
            break;
        case OCI_FO_REAUTH:
            printf("Re-authenticating\n");
            break;
        case OCI_FO_ERROR:
            printf("Failover error event\n");
            break;
        case OCI_FO_RETRY:
            printf("Retry attempt\n");
            break;
        default:
            break;
    }
    return 0;
}

int main(void)
{
    OCIEnv *envhp;
    OCIError *errhp;
    OCIServer *srvhp;
    OCISession *usrhp;
    OCISvcCtx *svchp;
    taf_ctx ctx;

    OCIEnvCreate(&envhp, OCI_DEFAULT, NULL, NULL, NULL, NULL, 0, NULL);
    OCIHandleAlloc((dvoid *)envhp, (dvoid **)&errhp, OCI_HTYPE_ERROR, 0, NULL);
    OCIHandleAlloc((dvoid *)envhp, (dvoid **)&srvhp, OCI_HTYPE_SERVER, 0, NULL);
    OCIServerAttach(srvhp, errhp, (text *)"racdb_svc", strlen("racdb_svc"), OCI_DEFAULT);

    OCIAttrSet((dvoid *)srvhp, OCI_HTYPE_SERVER, (dvoid *)taf_callback, 0, OCI_ATTR_FOCBK, errhp);
    OCIAttrSet((dvoid *)srvhp, OCI_HTYPE_SERVER, (dvoid *)&ctx, 0, OCI_ATTR_FOCBK_CTX, errhp);

    OCIHandleAlloc((dvoid *)envhp, (dvoid **)&svchp, OCI_HTYPE_SVCCTX, 0, NULL);
    OCIHandleAlloc((dvoid *)envhp, (dvoid **)&usrhp, OCI_HTYPE_SESSION, 0, NULL);
    OCIAttrSet((dvoid *)svchp, OCI_HTYPE_SVCCTX, (dvoid *)srvhp, 0, OCI_ATTR_SERVER, errhp);
    OCIAttrSet((dvoid *)usrhp, OCI_HTYPE_SESSION, (dvoid *)"scott", strlen("scott"), OCI_ATTR_USERNAME, errhp);
    OCIAttrSet((dvoid *)usrhp, OCI_HTYPE_SESSION, (dvoid *)"tiger", strlen("tiger"), OCI_ATTR_PASSWORD, errhp);
    OCISessionBegin(svchp, errhp, usrhp, OCI_CRED_RDBMS, OCI_DEFAULT);

    printf("Connected, waiting for failover test...\n");
    /* 模拟长连接，真实环境可替换为业务逻辑 */
    sleep(300);

    OCISessionEnd(svchp, errhp, usrhp, OCI_DEFAULT);
    OCIServerDetach(srvhp, errhp, OCI_DEFAULT);
    return 0;
}

在编译时需要链接Oracle客户端库，Linux下一般使用-L$ORACLE_HOME/lib -lclntsh。需要注意属性名称的大小写：OCI_ATTR_FOCBK和OCI_ATTR_FOCBK_CTX是在<oci.h>中定义的宏，某些老版本客户端可能只提供OCI_ATTR_FOCBK，这时需要查阅对应版本的文档确认。服务器句柄一旦注册回调，即使后续有多个会话，同一个回调函数和上下文也会被复用，因此上下文结构体必须保证整个连接生命周期内有效。

网络服务名对应的tnsnames.ora配置也需要同步启用TAF。下面给出一个RAC两节点的简化示例。

RACDB =
  (DESCRIPTION =
    (ADDRESS_LIST =
      (ADDRESS = (PROTOCOL = TCP)(HOST = node1-vip)(PORT = 1521))
      (ADDRESS = (PROTOCOL = TCP)(HOST = node2-vip)(PORT = 1521))
    )
    (CONNECT_DATA =
      (SERVICE_NAME = racdb_svc)
      (FAILOVER_MODE =
        (TYPE = SELECT)
        (METHOD = BASIC)
        (RETRIES = 30)
        (DELAY = 3)
      )
    )
  )

实际生产环境中，FAILOVER_MODE里的RETRIES乘以DELAY决定了客户端最长阻塞时间。例如这里配置为30次、每次间隔3秒，意味着最多等待约90秒。如果配合回调函数中的OCI_FO_RETRY事件，应用还可以根据业务时限主动提前结束重试，避免线程被长时间卡住。

三、回调函数中的业务逻辑设计

回调函数不是万能的恢复器，它更像一个受控的钩子。最典型的用法包括三类：清理无效资源、重建会话状态、记录切换事件。清理动作通常放在OCI_FO_BEGIN或OCI_FO_ABORT里，例如把应用层缓存中与当前连接关联的游标ID置为无效，或调用本地资源释放函数。重建动作放在OCI_FO_END里，例如重新执行一批ALTER SESSION语句，重新准备常用游标。记录日志则可以在所有事件中统一处理，方便事后分析RAC节点切换是否正常。

下面的代码片段展示了在OCI_FO_END阶段重新设置日期格式和当前schema的常见思路。需要注意的是，回调函数中执行的OCI调用应当使用故障转移后的新服务上下文，参数中的svchp就是OCI传递过来的有效句柄，不要使用全局保存的旧连接句柄。

sb4 taf_callback_with_setup(dvoid *svchp, dvoid *envhp, dvoid *fo_ctx, ub4 fo_type, ub4 fo_event)
{
    taf_ctx *ctx = (taf_ctx *)fo_ctx;
    OCIError *errhp = ctx->errhp;
    OCISvcCtx *new_svchp = (OCISvcCtx *)svchp;

    if (fo_event == OCI_FO_END) {
        char *sql = "ALTER SESSION SET NLS_DATE_FORMAT = 'YYYY-MM-DD HH24:MI:SS'";
        OCIStmt *stmthp;
        OCIHandleAlloc((dvoid *)envhp, (dvoid **)&stmthp, OCI_HTYPE_STMT, 0, NULL);
        OCIStmtPrepare(stmthp, errhp, (text *)sql, (ub4)strlen(sql), OCI_NTV_SYNTAX, OCI_DEFAULT);
        OCIStmtExecute(new_svchp, stmthp, errhp, (ub4)1, (ub4)0, NULL, NULL, OCI_DEFAULT);
        OCIHandleFree((dvoid *)stmthp, OCI_HTYPE_STMT);
        printf("Session state restored after failover\n");
    }
    return 0;
}

如果应用使用SELECT模式的TAF，OCI会在备份节点上重新执行查询并尝试定位到故障前的游标位置。但这种恢复对SQL有严格要求：查询必须是只读的，不能包含FOR UPDATE子句，客户端不能在切换前修改游标对应的结果集缓存。更重要的是，SELECT模式不会恢复事务，DML语句失败后仍需要应用手动处理。因此回调里即使看到OCI_FO_END成功，也不能假设业务上下文完整，最好在此时检查事务状态，必要时直接回滚并通知上层重试。

对于连接池场景，回调函数往往需要与池管理结合。例如Oracle UCP连接池中的连接被物理切换后，池内连接对象本身仍然是有效的，但会话状态丢失。此时可以在回调中重启池的自定义初始化SQL，或者让应用在借用连接时重新校验业务属性。不要试图在回调中归还或销毁连接池对象，因为回调执行线程与连接池管理线程通常不是同一个上下文，容易引发锁竞争和状态不一致。

四、TAF回调与Application Continuity的差异及常见调试方法

很多项目里TAF回调常被拿来和Application Continuity（AC）做比较。简单理解，TAF解决的是连接和游标层面的切换问题，AC则更侧重事务和结果的恢复。AC由Oracle数据库12c及以上版本支持，它通过客户端驱动记录事务上下文，在故障后自动重放事务并保证业务不会收到模棱两可的结果。TAF回调可以看作AC之前的基础可用性方案，也可以与AC配合，但两者并不能互相替代。

在实际使用TAF回调的工程中，最容易出现的几个问题：第一，回调函数不触发，通常是因为tnsnames.ora里没有配置FAILOVER_MODE，或者客户端使用了Easy Connect格式且没有指定TAF参数；第二，注册了回调但访问fo_ctx时崩溃，一般是上下文结构体被提前释放，必须保证其生命周期覆盖所有可能触发回调的阶段；第三，在回调函数里调用OCI函数导致阻塞或死锁，比如在OCI_FO_RETRY里又发起同步连接请求；第四，RETRIES和DELAY设置过小，导致回调只触发OCI_FO_BEGIN和OCI_FO_ABORT，看不到重试过程。

排查TAF问题时，可以依次检查三个方面。首先是客户端连接串，用Oracle Net配置工具或直接查看tnsnames.ora确认FAILOVER_MODE是否正确解析。其次是服务端RAC的监听和service状态，使用srvctl status service -d <db_unique_name>查看服务是否在多个节点上运行。最后是客户端跟踪，设置TRACE_LEVEL_CLIENT=16或启用OCI日志，可以观察到故障转移事件和回调调用顺序。回调函数本身打印的日志也很有用，但要控制好日志量，避免高并发故障时日志刷屏。

最后需要强调，TAF回调函数属于客户端侧的可用性机制，它无法解决RAC服务端节点故障的所有问题。设计业务层重试策略时，不要把回调中的逻辑当成完整的事务补偿方案，而应结合本地幂等性设计、服务端事务超时参数和连接池的失效检测能力，才能形成真正健壮的高可用架构。

Oracle RACTAF回调函数透明应用故障转移修改时间：2026-09-25 14:45:42