📚 课程目录第4章 Reconciler 基础

4. Reconciler 基础：接口定义、Request 与 Result、Reconcile 循环的生命周期

Reconciler（调谐器）是 Controller Runtime 中用户实现控制逻辑的核心接口。理解其定义、输入输出以及生命周期，是编写可靠控制面控制器的第一步。本章将深入剖析 Reconciler 的契约、数据结构与运行时循环。

4.1 Reconciler 接口定义

在 Controller Runtime 中，Reconciler 被定义为一个 Go 接口，位于 sigs.k8s.io/controller-runtime/pkg/reconcile 包下。该接口仅包含一个方法：Reconcile。

// Reconciler 接口定义
type Reconciler interface {
    Reconcile(ctx context.Context, req Request) (Result, error)
}

该接口的设计哲学是“单一职责”：用户只需实现一个方法，框架负责调度、缓存、事件触发与重试。接口的简洁性使得测试和模拟变得非常容易。

参数/返回值	类型	说明
`ctx`	`context.Context`	请求上下文，用于传递取消信号、超时和元数据。框架会在控制器停止或请求超时时取消该上下文。
`req`	`Request`	封装了触发调谐的对象的命名空间和名称。
`Result`	`Result`	告知框架调谐结果：是否需要重新入队、以及等待多久后重试。
`error`	`error`	如果返回非 nil 错误，框架会根据配置的重试策略重新入队该请求。

实战提示： 不要将 Reconcile 方法设计得过于冗长。推荐的做法是将其作为“调度器”，根据 req 中的对象类型或状态，将具体逻辑委托给子函数。这有助于单元测试和代码复用。

4.2 Request 与 Result 数据结构

Request 和 Result 是 Reconciler 与框架通信的两个核心数据结构。理解它们的字段含义，是控制调谐行为的关键。

4.2.1 Request：调谐的触发信号

// Request 包含一个对象的标识信息
type Request struct {
    types.NamespacedName
}

// NamespacedName 由 Namespace 和 Name 组成
type NamespacedName struct {
    Namespace string
    Name      string
}

Request 本质上是一个 NamespacedName，它不携带对象的完整状态。Reconciler 需要根据 Namespace 和 Name 从缓存或 API Server 中获取最新对象。这种设计使得事件队列轻量且高效。

4.2.2 Result：控制调谐的下一步

// Result 控制调谐后的行为
type Result struct {
    // RequeueAfter 指定在多少时间后重新入队该请求
    // 如果为 0，则不进行延迟重新入队
    RequeueAfter time.Duration

    // Requeue 为 true 时，立即将请求重新入队
    // 如果 RequeueAfter 非零，则优先使用 RequeueAfter
    Requeue bool
}

Result 组合	行为	典型场景
`Result{}, nil`	调谐成功，不重新入队。对象已达到期望状态。	资源创建完成、状态更新成功。
`Result{Requeue: true}, nil`	立即重新入队，再次触发调谐。	需要轮询外部系统、等待依赖资源就绪。
`Result{RequeueAfter: 5 * time.Second}, nil`	5 秒后重新入队。	速率限制、等待操作完成、定期同步。
`Result{}, err`	返回错误，框架根据重试策略（如指数退避）重新入队。	API Server 临时故障、网络错误。

常见陷阱： 当 RequeueAfter 和 Requeue 同时为 true 时，框架会优先使用 RequeueAfter 的延迟时间，忽略立即重试。不要依赖这种组合行为，应明确选择一种重试策略。

4.3 Reconcile 循环的生命周期

Reconcile 循环并非简单的“调用-返回”过程，而是一个由事件驱动、受速率限制、支持重试的闭环系统。下图展示了单个 Reconcile 请求从入队到完成的完整生命周期。

4.4 调谐循环的详细步骤

上图展示了宏观流程，下面从代码执行角度拆解每个步骤的职责与注意事项。

事件入队： 当 Informer 检测到资源变化（Add/Update/Delete）时，事件处理器将 Request 放入工作队列。框架会去重，确保同一时间队列中只有一个相同的 Request。
速率限制： 工作队列的 RateLimiter 决定何时将请求出队。默认使用基于失败次数的指数退避（base delay 5ms，max delay 16min）。
调用 Reconcile： 控制器 worker 从队列中取出 Request，调用用户实现的 Reconcile 方法。此时 ctx 已绑定超时和取消信号。
解析结果： 框架检查 Result 和 error：
- 如果 error != nil，框架将请求以错误状态重新入队，速率限制器会增加下次重试的延迟。
- 如果 Result.Requeue == true，请求立即重新入队（绕过速率限制？实际仍受队列内部机制影响，但语义上为“尽快”）。
- 如果 Result.RequeueAfter > 0，请求在指定延迟后重新入队，不增加失败计数。
- 如果 Result 为零值且 error == nil，请求被标记为成功，从队列中移除。
完成或重试： 根据上一步的结果，请求要么被丢弃（调谐完成），要么重新进入队列等待下一次处理。

4.5 控制器 Worker 与并发模型

Controller Runtime 使用固定数量的 worker goroutine 并发执行 Reconcile 循环。worker 数量通过 MaxConcurrentReconciles 选项配置。

// 创建控制器时设置并发数
ctrl, err := controller.New("my-controller", mgr, controller.Options{
    MaxConcurrentReconciles: 5, // 同时最多运行 5 个 Reconcile 协程
    Reconciler:              &MyReconciler{},
})

配置项	默认值	影响
`MaxConcurrentReconciles`	1	控制同一时刻最多有多少个 Reconcile 请求被并行处理。增大该值可提高吞吐量，但会增加 API Server 和缓存压力。
工作队列类型	RateLimitingQueue	提供速率限制和重试能力。可通过 `controller.Options.RateLimiter` 自定义。

    并发安全提示： 由于多个 worker 可能同时处理不同的 Request，你的 Reconciler 实现必须是并发安全的。避免在结构体字段中存储请求级别的状态；所有状态应通过 Request 从缓存或 API Server 重新获取。

4.6 典型 Reconcile 实现模板

以下是一个标准的 Reconciler 实现骨架，展示了如何安全地获取对象、处理删除事件以及返回正确的 Result。

type MyReconciler struct {
    client.Client
    Scheme *runtime.Scheme
}

func (r *MyReconciler) Reconcile(ctx context.Context, req reconcile.Request) (reconcile.Result, error) {
    // 1. 获取对象
    var myResource myapi.MyResource
    if err := r.Get(ctx, req.NamespacedName, &myResource); err != nil {
        // 对象已删除，忽略
        if apierrors.IsNotFound(err) {
            return reconcile.Result{}, nil
        }
        // 其他错误，重试
        return reconcile.Result{}, err
    }

    // 2. 检查是否正在被删除（处理 Finalizer）
    if !myResource.DeletionTimestamp.IsZero() {
        // 执行清理逻辑
        return r.reconcileDeletion(ctx, &myResource)
    }

    // 3. 核心调谐逻辑
    if err := r.reconcileNormal(ctx, &myResource); err != nil {
        // 业务逻辑失败，立即重试
        return reconcile.Result{Requeue: true}, err
    }

    // 4. 更新状态（如果需要）
    if err := r.Status().Update(ctx, &myResource); err != nil {
        return reconcile.Result{}, err
    }

    // 5. 调谐成功，不重试
    return reconcile.Result{}, nil
}

调试技巧： 在开发阶段，可以在 Reconcile 方法入口和出口处添加日志，打印 req 和 Result。使用 ctrl.Log.WithValues("namespace", req.Namespace, "name", req.Name) 可以结构化地记录每个请求的上下文。

4.7 生命周期中的关键时序点

理解以下时序点有助于诊断调谐循环中的性能问题或死锁：

从事件触发到 Reconcile 调用： 取决于工作队列的负载和速率限制。在低负载下通常为毫秒级。
Reconcile 执行时间： 完全由用户代码决定。建议设置客户端请求超时（如 10s），避免长时间阻塞 worker。
重试间隔： 默认指数退避：5ms → 10ms → 20ms → ... → 16min。可通过自定义 RateLimiter 调整。
控制器关闭时的行为： 当 Manager 关闭时，所有 worker 会等待当前正在执行的 Reconcile 完成（受 context.Context 取消信号控制），然后停止处理新请求。