Fallback

Kitex 自定义 Fallback 使用指南。

支持版本：>= v0.5.0 （go.mod依赖 github/cloudwego/kitex)

Protobuf 生成代码版本：>=v0.5.0（版本见生成代码文件头部与版本注释）

Thrift 对生成代码版本无要求

1. Kitex Fallback 功能说明

业务在 RPC 请求失败后通常会有一些降级措施保证有效返回（比如请求超时、熔断后，构造默认返回），Kitex 的 Fallback 支持对所有异常请求进行处理。同时，因为业务异常通常会通过 Resp（BaseResp）返回，所以也支持对 Resp 进行处理。

1.1 支持 Fallback 的结果类型

RPC Error：RPC 请求异常，如超时、熔断、限流、协议等 RPC 层面的异常
业务 Error：业务自定义的异常，区别于 RPC 异常，具体是 Kitex - 业务异常处理使用文档
Resp：在没有使用业务异常的情况下，用户会在 Resp（BaseResp）中定义错误返回，所以也支持对 Resp 判断做 fallback

1.2 监控上报

Fallback 后可能直接返回成功的 Resp，对用户而言是一次成功请求，但 RPC 层面还是失败请求，所以监控默认以原来的结果上报，但支持配置化调整为以 Fallback 结果上报。

2. 使用方式

因为 Fallback 涉及业务逻辑，只支持代码配置。

2.1 Client 维度配置

import (
    "github.com/cloudwego/kitex/client"
)

var opts []client.Option
opts = append(opts, client.WithFallback(yourFallbackPolicy))

xxxCli := xxxservice.NewClient("target_service", opts...)

2.2 Call 维度配置

import (
    "github.com/cloudwego/kitex/client/callopt"
)

xxxCli.XXXMethod(ctx, req, callopt.WithFallback(yourFallbackPolicy))

2.3 如何配置 Fallback Policy

2.3.1 Fallback Func 定义

Kitex 提供两种 Fallback Func 定义：

以 XXXArgs/XXXResult 作为 req/resp 参数，与 Middleware 相同
以真实的 RPC Req/Resp 作为参数，与 Handler 的参数类型相同

后者符合使用直觉，对用户更加友好，但不兼容有多个请求参数的 API，因此框架默认使用前一种方法。

XXXArgs/XXXResult 作为 req/resp 参数

注意：必须通过 result.SetSuccess(yourFallbackResult) 替换原返回值。

// Func is the definition for fallback func, which can do fallback both for error and resp.
// Notice !! The args and result are not the real rpc req and resp, are respectively XXArgs and XXXResult of generated code.
// setup eg: client.WithFallback(fallback.NewFallbackPolicy(yourFunc))
type Func func(ctx context.Context, args utils.KitexArgs, result utils.KitexResult, err error) (fbErr error)

// use demo
client.WithFallback(
fallback.NewFallbackPolicy(
func(ctx context.Context, args utils.KitexArgs,
result utils.KitexResult, err error) (fbErr error) {
// your fallback logic...
result.SetSuccess(yourFallbackResult)
return
}))

真实的 RPC Req/Resp 作为参数

通过使用 Kitex 提供的 fallback.UnwrapHelper，可以定义签名为 RealReqRespFunc 的 Fallback Func，参数类型和 Handler 的 req、resp 一致。

注意：如果需要返回 resp，这里需要构造真实的 RPC resp 作为返回值，Helper 会调用 SetSuccess 方法替换原返回值。

// RealReqRespFunc is the definition for fallback func with real rpc req as param, and must return the real rpc resp.
// setup eg: client.WithFallback(fallback.NewFallbackPolicy(fallback.UnwrapHelper(yourRealReqRespFunc)))
type RealReqRespFunc func(ctx context.Context, req, resp interface{}, err error) (fbResp interface{}, fbErr error)

// use demo
client.WithFallback(fallback.NewFallbackPolicy(fallback.UnwrapHelper(func(ctx context.Context, req, resp interface{}, err error) (fbResp interface{}, fbErr error) {
// your fallback logic...
return fbResp, fbErr
}))

2.3.2 构造 Fallback Policy

默认的构造方法 NewFallbackPolicy，框架会对 Error 和 Resp 均触发 Fallback 执行，为了方便业务使用，如果用户是希望对 Error 或者超时/熔断做 fallback，框架也提供了封装。

对 Error 和 Resp 均做判断执行 Fallback

// 方法1：XXXArgs/XXXResult as params
fallback.NewFallbackPolicy(func(ctx context.Context, args utils.KitexArgs, result utils.KitexResult, err error) (fbErr error) {
   // your fallback logic...
   result.SetSuccess(yourFallbackResult)
   return
})

// 方法2：real rpc req/resp as params
fallback.NewFallbackPolicy(fallback.UnwrapHelper(func(ctx context.Context, req, resp interface{}, err error) (fbResp interface{}, fbErr error) {
   // your fallback logic...
   return
})

只对 Error（包括业务 Error）进行 Fallback

非 Error 不会执行 Fallback

// 1: XXXArgs/XXXResult as params
fallback.ErrorFallback(func(ctx context.Context, args utils.KitexArgs, result utils.KitexResult, err error) (fbErr error) {
   // your fallback logic...
   result.SetSuccess(yourFallbackResult)
   return
})

// 2: real rpc req/resp as params
fallback.ErrorFallback(fallback.UnwrapHelper(func(ctx context.Context, req, resp interface{}, err error) (fbResp interface{}, fbErr error) {
   // your fallback logic...
   return
})

只对超时和熔断 Error 进行 Fallback

非超时和熔断 Error 不会执行 Fallback

// 1: XXXArgs/XXXResult as params
fallback.TimeoutAndCBFallback(func(ctx context.Context, args utils.KitexArgs, result utils.KitexResult, err error) (fbErr error) {
   // your fallback logic...
   result.SetSuccess(yourFallbackResult)
   return
})

// 2: real rpc req/resp as params
fallback.TimeoutAndCBFallback(fallback.UnwrapHelper(func(ctx context.Context, req, resp interface{}, err error) (fbResp interface{}, fbErr error) {
   // your fallback logic...
   return
})

2.3.3 如何以 Fallback 结果进行监控上报

框架默认以原来的 RPC 结果进行监控上报，fallback.Policy 提供了 EnableReportAsFallback() 方法可以选择以 Fallback 结果上报。

注意：如果原结果本来就不是 RPC 失败（业务 Error），但如果在 Fallback 里返回了 error，即使设置了 EnableReportAsFallback，框架也不会以 Fallback 结果上报。

原结果	是否使用 EnableReportAsFallback()	上报结果
RPC 失败	是	fallback 结果
RPC 失败	否	is_error=1 (rpcinfo.GetRPCInfo(ctx).Stats().Error() is not nil)
业务错误（Biz Err 或 BaseResp 非成功状态）	是/否	is_error=0 (rpcinfo.GetRPCInfo(ctx).Stats().Error() is nil)

2.4 配置示例

示例1：只对超时和熔断 error 做 fallback，且以 fallback 结果进行监控上报

yourFallbackPolicy := fallback.TimeoutAndCBFallback(func(ctx context.Context, args utils.KitexArgs, result utils.KitexResult, err error) (fbErr error) {
   methodName := rpcinfo.GetRPCInfo(ctx).To().Method()
   fbRPCResp := buildFallbackRPCResp(methodName, req)
   result.SetSuccess(fbRPCResp)
   return nil
}).EnableReportAsFallback()

var opts []client.Option
opts = append(opts, client.WithFallback(yourFallbackPolicy))

xxxCli := xxxservice.NewClient("target_service", opts...)

示例2：对 Error 和 Resp 都需要 fallback，使用真实的 RPC req/resp 类型作为参数

yourFallbackPolicy := fallback.NewFallbackPolicy(fallback.UnwrapHelper(func(ctx context.Context, req, resp interface{}, err error) (fbResp interface{}, fbErr error) {
   methodName := rpcinfo.GetRPCInfo(ctx).To().Method()
   fbResp = buildFallbackRPCResp(methodName, req, resp)
   return fbResp, nil
})).EnableReportAsFallback()

xxxCli.XXXMethod(ctx, req, callopt.WithFallback(yourFallbackPolicy))

3.注意事项

3.1 特殊返回值说明

若 Fallback 的 resp, err 均为 nil，框架将返回原来的 resp 和 error
若 Fallback 的 resp, err 均不为 nil，不会返回 resp 给用户
允许 fallback 返回 error

3.2 Kitex Protobuf / Kitex gRPC 使用

Kitex Protobuf 和 Kitex gRPC 的 Unary 请求均支持 fallback ，但需要用 >=v0.5.0 工具版本生成的代码（版本见生成代码文件头部与版本注释）
Kitex gRPC streaming 请求不支持 fallback

反馈

当前页面对你有帮助吗？

请告诉我们如何改进.

最后修改 April 18, 2024 : doc(kitex): update fallback.md zh version (#1058) (343c12d)