staff-engineering-skills-denormalization

用途

本技能用于在数据建模和编写代码时，检测并预防「反规范化陷阱」（Denormalization Trap）。它适用于以下场景：在表之间复制字段、在文档中嵌入关联数据、为规避连接而新增列、从多张表构建缓存对象，或编写在表之间「同步」数据的后台任务。

核心原则：每一份数据副本都是一项一致性义务。在为了规避连接而复制字段之前，应先问：谁更新这份副本、更新失败会怎样、如何检测数据漂移。

主要能力

快照与引用的区分

复制数据时的第一个问题：这是快照还是引用？

快照：某一时间点的值，复制是正确的。例如订单行项目在购买时的价格。产品价格之后可能变化，但订单价格不应变化。
引用：某事物的当前值，复制是危险的。例如存储在用户档案上的套餐名称。当套餐变化时，每一份副本在更新前都是错误的。

如果复制的是引用，就承担了一致性义务。如果无法回答检查清单中的全部四个问题，就不要反规范化。

一致性义务检查清单

对每一个反规范化字段，需要记录：

真实来源：哪张表/记录是权威的？
更新触发：源变化时，什么代码更新这些副本？
失败模式：更新中途失败会怎样？能容忍多陈旧？
修复机制：如何检测并修复漂移？是否有对账任务？

如果填不出来，就改用连接。

检测：即将反规范化时的信号

出现以下写法时应停下来评估：

写入时把字段从一张表复制到另一张表，例如 order.customerName = customer.name。客户改名后会怎样？
在文档中嵌入关联对象，例如 { user: { org: { plan: { name: "Pro" } } } }。每一层嵌套都是一份需要更新路径的副本。
为规避连接而新增列，例如把 planName 存在 user 表上以免通过 organization 连接。组织更换套餐时谁更新它？
从多张表构建缓存块，例如 buildFullProfile(userId) 把 user + org + plan + settings 连接成一个缓存对象。什么会使该块中每个字段失效？
在表之间「同步」数据的后台任务：如果存在，说明陷阱已经出现。它是否幂等？是否处理部分失败？
ON UPDATE CASCADE 或数据库触发器：这些把写放大隐藏在数据库内部，应用代码看不到。

默认方案：读取时连接

优先使用读取时连接，单一真实来源，始终一致。示例代码：

async function getUserProfile(userId: string) {
  return db.user.findUnique({
    where: { id: userId },
    include: {
      organization: {
        include: { plan: true },
      },
    },
  });
}

连接本身并不慢。在带索引的外键上做连接是快的。在假设需要反规范化之前先测量。

反规范化何时正当

仅当以下全部成立时才反规范化：

连接是被测量出的性能瓶颈（而非假设的）
源数据相对读取而言变化不频繁
每一份副本都有更新路径
有检测漂移的修复机制
可接受的陈旧窗口已定义并记录

使用方式（必须反规范化时的模式）

物化视图（数据库管理）

数据库拥有反规范化逻辑，刷新是原子的。示例：

await db.$executeRaw`
  CREATE MATERIALIZED VIEW user_profiles AS
  SELECT u.id, u.name, o.name as org_name, p.name as plan_name
  FROM users u
  JOIN organizations o ON u.org_id = o.id
  JOIN plans p ON o.plan_id = p.id
`;
await db.$executeRaw`REFRESH MATERIALIZED VIEW CONCURRENTLY user_profiles`

刷新之间会陈旧，但逻辑是声明式的，刷新是原子的，不会「忘记」更新某份副本。

事件驱动同步加修复任务

源变化时更新副本，示例：

async function handleOrgPlanChanged(event: OrgPlanChangedEvent) {
  const plan = await db.plan.findUnique({ where: { id: event.newPlanId } });
  let cursor: string | undefined;
  do {
    const users = await db.user.findMany({
      where: { orgId: event.orgId }, take: 100,
      cursor: cursor ? { id: cursor } : undefined,
      orderBy: { id: "asc" },
    });
    for (const user of users) {
      await db.user.update({
        where: { id: user.id },
        data: { cachedPlanName: plan.name },
      });
    }
    cursor = users.length === 100 ? users[users.length - 1].id : undefined;
  } while (cursor);
}

修复任务示例：

async function repairDenormalizedPlanNames() {
  const drifted = await db.$queryRaw`
    SELECT u.id, u.cached_plan_name, p.name as actual
    FROM users u
    JOIN organizations o ON u.org_id = o.id
    JOIN plans p ON o.plan_id = p.id
    WHERE u.cached_plan_name != p.name
  `;
  for (const row of drifted) {
    await db.user.update({
      where: { id: row.id },
      data: { cachedPlanName: row.actual },
    });
    logger.warn("Repaired drifted plan name", { userId: row.id });
  }
}

需要更多基础设施，但失败可恢复、漂移可检测、系统可自愈。

反模式

危险写法一：把 org 和 plan 数据复制进每条用户记录。当它们变化时谁更新 orgName 和 planName？

return db.user.create({
  data: {
    name: data.name, email: data.email, orgId: data.orgId,
    orgName: org.name,
    planName: plan.name,
    planFeatures: plan.features,
  },
});

危险写法二：更新 N 张表且无失败处理。如果 updateMany 超时怎么办？如果部分成功怎么办？

async function updateOrgName(orgId: string, newName: string) {
  await db.organization.update({ where: { id: orgId }, data: { name: newName } });
  await db.user.updateMany({ where: { orgId }, data: { orgName: newName } });
  await db.invoice.updateMany({ where: { orgId }, data: { orgName: newName } });
  await db.auditLog.updateMany({ where: { orgId }, data: { orgName: newName } });
}

限制

本技能为方法论与模式指导，未提供具体安装命令、收费信息或平台支持范围，这些内容暂未提供。

技能介绍

用途