工程实践

ORM 查询别悄悄放大：识别 N+1、批量加载与回归验证

用批量加载收拢查询路径

列表接口在测试数据上很快，上线后却随着分页条数变大而变慢，常见原因不是少了索引，而是 ORM 在循环里偷偷访问关联对象：先查一页主记录，再为每条记录各发一次查询。这类 N+1 问题的危险在于单条 SQL 很快，却会放大网络往返、连接占用和数据库解析成本。治理它的重点不是“多写一个 include”，而是让一次请求的查询数量可见、可预测、可回归。

先把 N+1 看成可计数的症状

假设订单列表需要显示客户名称。下面的代码先查询订单，再在循环中读取客户；页面返回 20 条订单时，可能执行 1 次订单查询和 20 次客户查询。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
const orders = await db.order.findMany({
  take: pageSize,
  orderBy: { createdAt: "desc" },
});

const response = [];
for (const order of orders) {
  const customer = await db.customer.findUnique({
    where: { id: order.customerId },
  });

  response.push({
    id: order.id,
    totalCents: order.totalCents,
    customerName: customer?.name ?? "unknown",
  });
}

N+1 不一定只发生在显式循环中。模板渲染时访问懒加载关系、序列化器逐项补齐字段、权限校验逐条查询资源，都可能制造相同模式。它的关键特征是：一条请求内反复出现形状相同、参数不同的 SQL。

观察项 健康信号 N+1 信号
查询总数 随页面大小基本稳定 随记录数近似线性增长
SQL 指纹 少量不同的访问路径 同一 WHERE id = ? 重复出现
连接等待 高峰时仍有余量 并发稍升就出现排队

用请求边界定位重复查询

一次请求触发重复查询

排查时不要只盯接口总耗时。为每个请求记录查询次数、归一化后的 SQL 指纹、累计耗时和调用位置；其中指纹应把具体参数替换为占位符，既能聚合同类语句，也避免把邮箱、订单号等敏感值写入日志。把这些指标按路由、分页大小和租户规模聚合，很容易看出“每多一条记录就多一次查询”的斜率。

本地调试可以打开 ORM 的 SQL 日志，但生产环境更适合做采样：记录慢请求的完整调用链，同时为所有请求保留轻量计数。定位后先确认业务确实需要这些关联字段；不需要的列不要为了方便一次性加载，查询数量少不代表传输的数据一定少。

用批量预取替代循环访问

对“多条订单属于多个客户”这种多对一关系，先收集唯一外键，再用一次 IN 查询取回关联对象，最后在内存中组装。查询数量从 1 + 订单数 收敛为稳定的 2 次。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
const orders = await db.order.findMany({
  take: pageSize,
  orderBy: { createdAt: "desc" },
});

const customerIds = [...new Set(orders.map((order) => order.customerId))];
const customers = await db.customer.findMany({
  where: { id: { in: customerIds } },
  select: { id: true, name: true },
});
const customerById = new Map(customers.map((customer) => [customer.id, customer]));

return orders.map((order) => ({
  id: order.id,
  totalCents: order.totalCents,
  customerName: customerById.get(order.customerId)?.name ?? "unknown",
}));

批量预取后的收敛数据流

关联形态 优先策略 容易忽略的边界
多对一 主查询 + IN 批量预取 先去重外键，空集合直接跳过
一对多 先分页主记录，再批量取子记录 避免 JOIN 让分页行数膨胀
多对多 批量查询关联表和目标表 明确排序、去重与最大返回量

预加载或 JOIN 也有用，但不能当成默认答案。一对多关系直接连接会复制主表行，既影响分页，也可能让返回体暴涨；此时两次有边界的查询往往更容易解释。若使用 DataLoader 一类批处理器，缓存应限定在单个请求内，不能把带权限或租户条件的对象随意放进进程级缓存。

把查询预算写进回归测试

修复一次 N+1 后，最容易在新字段、新模板或重构中复发。为核心列表接口设置查询预算，比只断言 HTTP 状态码更能守住性能约束。预算应基于业务访问路径制定，而不是机械追求最小数字。

1
2
3
4
5
6
7
8
const metrics = await countDatabaseQueries(async () => {
  await app.request("/orders?pageSize=20");
});

expect(metrics.total).toBeLessThanOrEqual(3);
expect(metrics.repeatedFingerprints).not.toContain(
  "SELECT customer WHERE id = ?"
);

测试数据应至少覆盖空页、普通页和包含重复外键的页面；若接口需要按权限过滤，也要让测试走真实的权限条件。上线后继续观察查询数分位值、数据库等待时间和连接池排队，确认批量加载没有把问题从“查询太多”转成“单次结果太大”。

N+1 的本质是数据访问边界被循环悄悄打散。把关联需求集中到请求边界，用批量查询明确表达，再用查询预算锁住结果，ORM 才能保留开发效率，而不会在数据量增长时变成隐形的性能债务。