Client Option

用法

在创建客户端时，带上 Option 参数即可：

client, err := echo.NewClient("targetService", client.WithXXXX...)

基础 Option

基本信息 - WithClientBasicInfo

func WithClientBasicInfo(ebi *rpcinfo.EndpointBasicInfo) Option

设置 Client 侧的 Service 信息，包括 ServiceName 和自定义的 Tags，自定义 Tag 如 Cluster、IDC、Env，无需设置 EndpointBasicInfo 的 Method 字段。强烈建议配置该 Option。

IP 端口 - WithHostPorts

func WithHostPorts(hostports ...string) Option

手动指定一个或者多个目标端，会覆盖掉服务发现的结果，直接直连访问。

传输协议 - WithTransportProtocol

func WithTransportProtocol(tp transport.Protocol) Option

设置传输协议，在消息协议上配置传输协议。Thrift/KitexProtobuf 可以配置 TTHeader、TTHeaderFramed、Framed，另外，Framed 严格意义上并不算传输协议，为区分用于 PurePayload 将其也作为传输协议配置，PurePayload 表示没有传输协议；如果配置为 GRPC 表示使用 GRPC 协议，GRPC 的传输协议是 HTTP2，但为便于用户理解，直接作为传输协议的配置，注意配置 GRPC 需要用 Protobuf 定义 Service，如果没有配置 GRPC，默认使用的是 KitexProtobuf 协议。

未设置 WithTransportProtocol 时，默认协议为 PurePayload。

短连接 - WithShortConnection

func WithShortConnection() Option

是否启用短连接，详见连接类型-短连接。

长连接 - WithLongConnection

func WithLongConnection(cfg connpool.IdleConfig) Option

是否启用长连接，详见连接类型-长连接。

多路复用 - WithMuxConnection

func WithMuxConnection(connNum int) Option

是否启用连接多路复用，需要同时在服务端也开启设置，详见连接类型-连接多路复用。

中间件扩展 - WithMiddleware

func WithMiddleware(mw endpoint.Middleware) Option

添加一个中间件，在 Service 熔断和超时中间件之后执行。用法参考 Middleware 扩展。

中间件扩展 - WithInstanceMW

func WithInstanceMW(mw endpoint.Middleware) Option

用于添加一个中间件，在服务发现和负载均衡之后执行，如果有实例熔断器，会在实例熔断器后执行（如果使用了 Proxy 则不会调用到，如 Mesh 模式下）。用法参考 Middleware 扩展。

中间件扩展 - WithMiddlewareBuilder

func WithMiddlewareBuilder(mwb endpoint.MiddlewareBuilder) Option

用于创建并添加中间件，可以根据 ctx 判断场景并创建中间件。 ctx 是框架传入的包含运行时配置信息的上下文（非 RPC 调用的上下文），以便中间件初始化时能利用框架的信息。

熔断器 - WithCircuitBreaker

func WithCircuitBreaker(s *circuitbreak.CBSuite) Option

设置熔断，默认包含 service 熔断和 instance 熔断，使用示例：

var opts []client.Option

cbs := circuitbreak.NewCBSuite(circuitbreak.RPCInfo2Key)
opts = append(opts, client.WithCloseCallbacks(func() error {
   // 熔断器的 Close 方法注入到 CloseCallbacks，用于在client销毁时，释放熔断相关资源
   return cs.cbs.Close()
}))
opts = append(opts, client.WithCircuitBreaker(cbs))


// 动态更新熔断配置
cbs.UpdateServiceCBConfig(key, config)
cbs.UpdateInstanceCBConfig(key, config)

关于熔断说明，详见熔断器。

超时重试 - WithFailureRetry

func WithFailureRetry(p *retry.FailurePolicy) Option

设置超时重试规则，可以配置最大重试次数，累计最大耗时，重试熔断错误率阈值，DDL 中止和退避策略等，详见请求重试。

备份请求 - WithBackupRequest

func WithBackupRequest(p *retry.BackupPolicy) Option

设置 Backup Request 的策略，可以配置请求次数、熔断中止、链路中止等，详见请求重试。

超时设置 - WithRPCTimeout

func WithRPCTimeout(d time.Duration) Option

进行 RPC 超时设置，详见超时控制。

超时设置 - WithConnectTimeout

func WithConnectTimeout(d time.Duration) Option

设置连接超时，详见超时控制。

超时设置 - WithTimeoutProvider

func WithTimeoutProvider(p rpcinfo.TimeoutProvider) Option

添加一个 TimeoutProvider 来整体设置 RPC 超时，连接超时等策略。若同时使用了 WithRPCTimeout 或 WithConnectTimeout，那么这里的设置会被覆盖。

指定服务 - WithDestService

func WithDestService(svr string) Option

指定调用目标端的服务名称，在 NewClient 中，第一个 string 参数就封装了这个 Option ，服务发现等场景会用到该字段。

添加标签 - WithTag

func WithTag(key, val string) Option

为 Client 添加一些元信息，例如 idc，cluster 等，用于辅助服务发现等场景。

埋点粒度 - WithStatsLevel

func WithStatsLevel(level stats.Level) Optiong

为 Client 设置埋点粒度，详见埋点粒度。

gRPC 相关配置

这类设置只对传输协议使用 gRPC 的场景生效，对 gRPC 传输进行一些参数调整。

WithGRPCConnPoolSize

func WithGRPCConnPoolSize(s uint32) Option

设置 gRPC 的连接池大小。只对传输协议使用 gRPC 的场景生效。

WithGRPCWriteBufferSize

func WithGRPCWriteBufferSize(s uint32) Option

设置 gRPC 写缓冲大小，写缓冲决定了每次批量调用底层写发送数据的大小。默认值为32KB，如果设置为0，则相当于禁用缓冲区，每次写操作都直接调用底层连接进行发送。该设置只对传输协议使用 gRPC 的场景生效。

WithGRPCReadBufferSize

func WithGRPCReadBufferSize(s uint32) Option

设置 gRPC 的读缓冲大小，读缓冲决定了每次批量从底层读取多少数据。默认值为32KB，如果设置为0，则相当于禁用缓冲区，每次读操作都直接从底层连接进行读操作。该设置只对传输协议使用 gRPC 的场景生效。

WithGRPCInitialWindowSize

func WithGRPCInitialWindowSize(s uint32) Option

设置 gRPC 每个 Stream 的初始收发窗口大小，最低为64KB，若设置的值小于最低值，则会被忽略。该设置只对传输协议使用 gRPC 的场景生效。

WithGRPCInitialConnWindowSize

func WithGRPCInitialConnWindowSize(s uint32) Option

设置 gRPC 单条连接上的初始窗口大小，最低为64KB，若设置的值小于最低值，则会被忽略。该设置只对传输协议使用 gRPC 的场景生效。

WithGRPCMaxHeaderListSize

func WithGRPCMaxHeaderListSize(s uint32) Option

设置 gRPC MaxHeaderListSize 参数，该参数决定了每次调用允许发送的header的最大条数。该设置只对传输协议使用 gRPC 的场景生效。

WithGRPCKeepaliveParams

func WithGRPCKeepaliveParams(kp grpc.ClientKeepalive) Option

设置 gRPC 客户端 Keepalive 的各项参数。该设置只对传输协议使用 gRPC 的场景生效。

WithGRPCTLSConfig

func WithGRPCTLSConfig(tlsConfig *tls.Config) Option

设置 gRPC 客户端的 TLS 配置。 该设置只对传输协议使用 gRPC 的场景生效。

高级 Option

配套扩展 - WithSuite

func WithSuite(suite Suite) Option

设置一套特定配置，可根据场景进行定制，在 Suite 中配置多个 Option 和 Middleware 的组合和封装，详见 Suite 扩展。

代理 - WithProxy

func WithProxy(p proxy.ForwardProxy) Option

用于代理场景（如 Mesh Egress）做一些配置处理、返回代理地址，配置 proxy.ForwardProxy 后，框架不会执行服务发现、熔断、InstanceMWs。

重试 - WithRetryContainer

func WithRetryContainer(rc *retry.Container) Option

手动设置 RetryContainer。用于结合熔断器进行重试策略。目前提供了 NewRetryContainer，NewRetryContainerWithCB 与 NewRetryContainerWithCBStat 三个快速实现方案。

• NewRetryContainerWithCB（建议）

​ 若在已经配置熔断器的情况下，建议与 RetryContainer 复用熔断器，避免额外的统计，可以使用 NewRetryContainerWithCB ，例如下面的示例中，启用熔断器的场景，同时将熔断器透传给 RetryContainer：

   cbs := circuitbreak.NewCBSuite(circuitbreak.RPCInfo2Key)
   retryC := retry.NewRetryContainerWithCB(cbs.ServiceControl(), cbs.ServicePanel())
       var opts []client.Option
   opts = append(opts, client.WithRetryContainer(retryC))
    // enable service circuit breaker
   opts = append(opts, client.WithMiddleware(cbs.ServiceCBMW()))

• NewRetryContainer

  • 指定重试策略的默认 RetryContainer，其内置了一个熔断器

• NewRetryContainerWithCBStat

​ 若想对内置的熔断器进行自定义 ServiceCBKeyFunc 设置，则可以使用 NewRetryContainerWithCBStat 方法：

   cbs := circuitbreak.NewCBSuite(YourGenServiceCBKeyFunc)
   retry.NewRetryContainerWithCBStat(cbs.ServiceControl(), cbs.ServicePanel())

预热 - WithWarmingUp

func WithWarmingUp(wuo *warmup.ClientOption) Option

设置预热。Kitex 支持了客户端预热，可以在创建客户端的时候预先初始化服务发现和连接池的相关组件，避免在首次请求时产生较大的延迟。

预热服务发现：

cli, err := myservice.NewClient(psm, client.WithWarmingUp(&warmup.ClientOption{
    ResolverOption: &warmup.ResolverOption{
        Dests: []*rpcinfo.EndpointBasicInfo{
            &rpcinfo.EndpointBasicInfo{
                ServiceName: psm,
                Method: method,
                Tags: map[string]string{
                    "cluster": "default",
                },
            },
        },
    },
}))

预热连接池：

cli, err := myservice.NewClient(psm, client.WithWarmingUp(&warmup.ClientOption{
    PoolOption: &warmup.PoolOption{
        ConnNum: 2,
    },
}))

设置关闭时回调 - WithCloseCallbacks

func WithCloseCallbacks(callback func() error) Option

设置客户端 Close 时的回调函数。

异常处理器 - WithErrorHandler

func WithErrorHandler(f func(error) error) Option

设置异常处理函数，该函数会在远程调用结束，中间件执行前被执行。

泛化调用 - WithGeneric

func WithGeneric(g generic.Generic) Option

指定泛化调用类型，泛化需要结合泛化 Client/Server 使用。详见 Kitex 泛化调用使用指南。

权限控制 - WithACLRules

func WithACLRules(rules ...acl.RejectFunc) Option

设置 ACL 权限访问控制，该模块会在服务发现之前执行，具体用法详见自定义访问控制。

连接池监控 - WithConnReporterEnabled

func WithConnReporterEnabled() Option

设置连接池状态监控，详见连接类型-状态监控。

启用 HTTP 连接 - WithHTTPConnection

func WithHTTPConnection() Option

指定客户端使用 netpoll 提供的 http 连接进行 RPC 交互。

扩展 Option

链路监控 - WithTracer

func WithTracer(c stats.Tracer) Option

额外添加一个 Tracer 进行链路监控，详见链路跟踪-自定义 tracer。

服务发现 - WithResolver

func WithResolver(r discovery.Resolver) Option

指定一个 Resolver 进行服务发现，用法详见服务发现。

HTTP 解析器 - WithHTTPResolver

func WithHTTPResolver(r http.Resolver) Option

指定HTTP Resolver，详见直连访问-自定义 DNS resolver。

负载均衡 - WithLoadBalancer

func WithLoadBalancer(lb loadbalance.Loadbalancer, opts ...*lbcache.Options) Option

设置负载均衡器，详见负载均衡。

IO Bound 处理器 - WithBoundHandler

func WithBoundHandler(h remote.BoundHandler) Option

自定义 IO Bound，详见 Transport Pipeline-Bound 扩展。

编解码 - WithCodec

func WithCodec(c remote.Codec) Option

指定 Codec，详见编解码协议扩展

Payload 编解码 - WithPayloadCodec

func WithPayloadCodec(c remote.PayloadCodec) Option

指定 PayloadCodec，详见编解码协议扩展

元信息处理 - WithMetaHandler

func WithMetaHandler(h remote.MetaHandler) Option

添加一个元信息处理器，用法详见元信息传递扩展。

元信息处理 - WithFirstMetaHandler

func WithFirstMetaHandler(h remote.MetaHandler) Option

在 MetaHandler 链的最前面添加一个元信息处理器，功能同 WithMetaHandler 类似。

传输设置 - WithTransHandlerFactory

func WithTransHandlerFactory(f remote.ClientTransHandlerFactory) Option

自定义传输模块，详见传输模块扩展。

诊断扩展 - WithDiagnosisService

func WithDiagnosisService(ds diagnosis.Service) Option

添加一个自定义的 Diagnosis Service，用来获取更多的诊断信息，详见诊断模块扩展。

Dialer 扩展 - WithDialer

func WithDialer(d remote.Dialer) Option

手动指定 Dialer。通常情况下 Dialer 在其他配置中已经进行了配套实现，一般情况下不建议使用。

连接池扩展 - WithConnPool

func WithConnPool(pool remote.ConnPool) Option

手动设置连接池。通常情况下 ConnPool 在其他配置中已经进行了配套实现，一般情况下不建议使用。