缺失值的级联效应

错误的错误

用户看到402错误："积分不足，请充值。"

他检查账户，显示有50个积分。视频生成只需要1个积分。这是错误的错误消息。

真正的问题不是用户积分不足。是系统无法计算需要多少积分。

调用链中的断裂

从用户请求到错误返回，经历了一条完整的调用链。断点在成本计算环节。

断裂在成本计算。模型配置表中缺少 credit_cost_rules.base 字段，fallback 链条也失效，最终返回了 NULL。

这个 NULL 值像病毒一样在调用链中传播。

NULL的传播路径

扣费函数接收三个参数：jobId、userId、creditCost。

当 creditCost 是 NULL 时，会发生什么？

在 PostgreSQL 中，任何值与 NULL 的运算或比较都返回 NULL。50 - NULL 是 NULL，50 < NULL 也是 NULL。

这意味着扣费逻辑中的任何涉及 creditCost 的操作都会失败：

-- 尝试扣除积分
UPDATE profiles
SET credits = credits - p_credit_cost  -- NULL传播
WHERE id = p_user_id;

-- 或者在比较检查中
IF current_credits < p_credit_cost THEN  -- NULL比较
  -- 逻辑无法正确执行
END IF;

NULL 不会引发错误，但会让逻辑静默失败。最终，RPC 函数返回 {success: false, message: 'Insufficient credits'}，不是因为积分不够，是因为系统不知道需要多少积分。

防御层的位置

防御层应该放在哪里？

不应该在 RPC 函数里。RPC 函数的职责是扣费，不是验证成本是否有效。把验证逻辑放在那里，违反了 单一职责原则。

应该在 API Gateway。在调用 RPC 之前，检查成本计算的结果。如果 costSnapshot.base.source === 'missing'，直接返回500错误。

这个检测层只做一件事：确保进入扣费环节的成本值是有效的。

// ⚠️ 关键检查：阻止缺失定价配置的模型
if (costSnapshot.base.source === 'missing') {
  logger.error('Critical: Missing credit cost configuration', {
    model_id: modelConfig.id,
    user_id: userId,
    trace_id: traceId
  });

  // 发送告警
  await telegram.sendMessage(
    '🚨 Missing Credit Cost Configuration...'
  );

  // 返回500而非402
  return c.json({
    error: 'Model configuration error. Please contact support.',
    trace_id: traceId
  }, 500, corsHeaders);
}

这不是过度设计。这是在正确的层次做正确的事。

区分用户错误和系统错误

402错误和500错误的区别，不只是HTTP状态码。

402告诉用户："你的问题，去充值。"500告诉用户："我们的问题，在修了。"

当系统配置缺失导致无法计算成本，这是系统的问题。用户没有做错任何事。返回402是错误的责任归因。

正确的做法：

• 500错误：模型配置缺失（系统责任）
• 402错误：用户积分不足（用户责任）
• 400错误：输入参数错误（用户责任）

每种错误有不同的处理路径。500错误触发告警，通知工程师修复配置。402错误引导用户充值。400错误提示用户修正输入。

混淆这些错误，会让系统变得不可信。用户看到"积分不足"，充值后发现还是失败，就会失去信任。

防御性编程的本质

防御性编程不是到处加 if (x !== null)。

防御性编程是理解系统的失败模式，在关键路径上构建检测点。

关键路径是什么？是那些失败会导致级联效应的环节。成本计算就是这样的环节。它的输出会影响扣费、用户体验、财务准确性。

在这个环节构建防御层，有三个收益：

1. 早失败：在问题传播前捕获它
2. 清晰归因：明确是谁的责任
3. 可观测性：记录日志和告警，让工程师知道发生了什么

这和 调用链路追踪 的思路一致。追踪链路，找到断点，在断点处修复。不在表层打补丁，不在深层过度设计。

告警的价值

防御层不只是拦截错误，还要发出信号。

当检测到 Missing Cost，系统发送 Telegram 消息通知工程师。这不是可选的，是必需的。

没有告警，防御层只是延迟了问题。你拦截了 NULL，但没有修复配置缺失的根本原因。下次新模型上线，还会触发同样的问题。

有了告警，工程师会立即知道："有模型缺少定价配置。"他可以修复配置，验证修复，更新文档。问题在扩散前被解决。

这是 故障隔离 的一部分。不只是防止失败影响用户，还要防止失败被遗忘。

级联效应的更广泛模式

NULL 只是一种缺失值。还有其他形式：

• NaN：数学计算失败产生的"非数字"
• undefined：JavaScript 中未初始化的值
• 空字符串：有时被误用作"无值"
• -1：某些API用负数表示错误，但负数也可能是合法值

它们的共同点是：在类型系统中合法，但在业务逻辑中无效。

类型检查器会放行 cost: number | null，但业务逻辑不能处理 NULL 成本。这就是为什么需要运行时验证。

这和 运行时类型契约 的道理相同。静态类型保证语法正确，运行时检查保证语义正确。

防御层是语义检查。它确保进入关键逻辑的值，不只是类型正确，还是业务上有效。

最后

一个 NULL 值可以毁掉整个用户体验。不是因为 NULL 本身危险，而是因为它会传播。

防御层的价值，不在于写了多少 if 语句，而在于理解系统的关键路径，知道哪些失败会级联，在那些位置构建检测点。

这不是防御性编程的全部，但这是它的核心：在失败传播前拦截，在责任模糊前归因，在问题扩散前告警。

系统会失败。代码会出错。配置会缺失。这些是常态。防御层让这些失败可控、可观测、可修复。