Kitex超时

学习目标

学完本章你应该能够：

1. 讲清 Kitex 客户端超时的两种控制方式：建立 Client 时统一配置（WithConnectTimeout / WithRPCTimeout）与单次请求时精细控制（callopt.WithConnectTimeout / callopt.WithRPCTimeout）。
2. 说清“统一超时”的局限——所有请求共用同一阈值，对快慢不一的服务不够精准，以及什么时候该改用单次请求控制。
3. 理解“冷启动超时”的成因：第一次请求要完成服务发现、建连、序列化器初始化，耗时会明显高于后续请求。
4. 讲清预热（Warming Up）做了哪两件事（服务发现预热、连接预热），以及它为什么能提升首次请求成功率、避免冷启动抖动。
5. 在面试里把“超时控制 + 预热”讲成一句话：用超时保护下游，用预热保护“第一次”。

前置知识：

• Go 基础语法与 context 包
• 微服务基本概念：客户端 / 服务端、服务发现、RPC
• Kitex 基本用法（定义 client、发起调用）

本章你会动手做的事：

1. 用 client.WithRPCTimeout 给 client 设一个统一超时，再故意调一个很慢的服务，观察超时报错。
2. 用 callopt.WithRPCTimeout 在单次请求上覆盖超时，对比同一 client 下不同请求的不同阈值。
3. 给 client 加上 WithWarmingUp，在真正发业务请求前先预热，观察首次请求耗时是否明显下降。

客户端

1、客户端统一超时控制

这个所有的本次连接都是一样的时间，但是有些服务就是快有些就是慢，这个控制很不精准

白话类比：统一超时像“全公司统一 8 点下班”——简单好管，但前台收快递 1 分钟能干完、后台跑报表要 2 小时，都用同一个钟点卡，要么前台被白白限制、要么后台拖垮大家。服务有快有慢时，就应该允许“按活儿定时间”。

client, err := math.NewClient(
    "dqq.math",
    client.WithResolver(resolver),
    // client.WithHostPorts("127.0.0.1:5678"),
    client.WithMiddleware(TimerMW),
    client.WithConnectTimeout(100*time.Millisecond),  // 连接超时
    client.WithRPCTimeout(200*time.Millisecond),   // RPC超时
)
if err != nil {
    klog.Fatalf("create rpc client fail: %s", err.Error())
}

统一超时与单次请求超时两种控制方式的区别：

flowchart TD
    A[NewClient 统一配置] -->|WithConnectTimeout / WithRPCTimeout| U[所有请求共用同一阈值
简单但不够精准]
    B[单次请求 callopt] -->|WithConnectTimeout / WithRPCTimeout| P[每次调用单独设阈值
快慢服务可差异化]
    U --> C[发请求]
    P --> C

2、客户端请求时控制超时

resquest := math_service.SubRequest{Left: 8, Right: 5}
response, err := client.Sub(context.Background(), &resquest,
    callopt.WithConnectTimeout(100*time.Millisecond),  // 连接超时
    callopt.WithRPCTimeout(200*time.Millisecond),      // RPC连接超时
)
if err != nil {
    klog.Error(err)
} else {
    klog.Info(response.Diff)
}

⚠️ 新手必踩的坑：统一超时“一刀切”。当 client 同时调多个快慢不同的方法时，统一阈值会让快方法被多余等待、慢方法又容易被误杀。对耗时差异大的接口，优先用 callopt 在单次请求上精细控制。

预热

在 Kitex 这类高性能 RPC 框架中，预热（Warming Up） 是指在客户端正式接收业务流量前，提前完成部分初始化操作，避免第一次请求时因耗时操作导致超时或性能抖动。

预热的核心目的

• 避免冷启动耗时：第一次请求需要做服务发现、建立连接、序列化器初始化等操作，耗时会明显高于后续请求，预热可以把这些耗时操作提前完成。
• 提升首次请求成功率：在服务刚上线或客户端刚启动时，提前建立连接、验证服务可用性，避免第一次请求就失败。

client.WithWarmingUp(&warmup.ClientOption{
    ResolverOption: &warmup.ResolverOption{
        Dests: []*rpcinfo.EndpointBasicInfo{
            {
                ServiceName: "dqq.math",
            },
        },
    },
}),

这段代码里的预热做了什么？

这段 WithWarmingUp 配置，是 Kitex 提供的客户端预热功能，具体做了两件事：

• 服务发现预热：提前向注册中心拉取 dqq.math 服务的实例列表，缓存到本地，避免第一次请求时才去解析地址。
• 连接预热（可选）：根据配置，提前和服务端建立长连接，避免第一次请求时才完成 TCP 三次握手、TLS 握手等连接过程。

白话类比：预热像“开业前的彩排”。餐厅正式营业前，先把菜单印好（服务发现）、把灶台点着（建连），客人一来直接点单上菜；否则第一位客人进门才现找菜单、现生火，等半天还容易把人等走（首次请求超时）。

冷启动 vs 预热后的首次请求时序对比：

sequenceDiagram
    participant App as 业务代码
    participant Client as Kitex Client
    participant Reg as 注册中心
    participant Svc as 服务端
    Note over App, Svc: 未预热（冷启动）
    App->>Client: 首次请求
    Client->>Reg: 服务发现（实时拉列表）
    Client->>Svc: TCP/TLS 握手建连
    Client->>Svc: 真正 RPC
    Note over App, Svc: 已预热
    App->>Client: 启动阶段 WithWarmingUp
    Client->>Reg: 提前拉实例列表缓存
    Client->>Svc: 提前建长连接
    App->>Client: 首次请求
    Client->>Svc: 直接 RPC（无需现发现/现建连）

自测题与动手练习

自测题（合上书能答出来，才算懂）：

1. Kitex 客户端超时有哪两种控制方式？分别用什么 API？
2. “统一超时”有什么局限？什么场景该改用单次请求控制？
3. 冷启动超时是怎么产生的？第一次请求比后续慢在哪几步？
4. Kitex 的预热（Warming Up）具体做了哪两件事？它为什么能提升首次请求成功率？
5. 连接超时（ConnectTimeout）和 RPC 超时（RPCTimeout）分别卡的是哪一段耗时？

动手练习（建议真做一遍）：

1. 用 client.WithRPCTimeout(200ms) 建一个 client，故意调一个 sleep 超过 200ms 的慢接口，观察返回的超时错误长什么样。
2. 同一 client 下，对快接口用 callopt.WithRPCTimeout(50ms)、对慢接口用 callopt.WithRPCTimeout(500ms)，验证单次请求能覆盖统一阈值。
3. 给 client 加 WithWarmingUp，在打点前后分别量两次“首次请求耗时”，确认预热后首次请求明显变快。

本章小结

• Kitex 超时控制有两档：建 client 时的统一配置（WithConnectTimeout / WithRPCTimeout），和单次请求时的精细覆盖（callopt.WithConnectTimeout / callopt.WithRPCTimeout）。
• 统一超时简单但“一刀切”，对快慢差异大的服务不精准；耗时差异大时应优先用 callopt 按请求单独设阈值。
• 冷启动超时源于首次请求要现场做服务发现、建连、序列化器初始化；预热把这些耗时提前到启动阶段完成。
• 预热做两件事：服务发现预热（提前拉实例列表缓存）+ 连接预热（提前建长连接），从而提升首次请求成功率、避免抖动。
• 下一篇我们接着看 Kitex 的限流、熔断与重试，把“保护下游”的几件套凑齐。