14 Node.js 与 BFF
  ├─ 前置：03 JavaScript（异步）、10 网络（HTTP/缓存）
  ├─ 紧接：08 渲染（SSR 服务）、18 可观测（Trace/SLO）
  ├─ 交叉：12 安全（鉴权透传/SSRF）、17 架构（服务边界）
  └─ 长期：20 工程效能（平台化）

┌──────────────────────────────┐
│ 你的 JS 代码                  │
├──────────────────────────────┤
│ Node 标准库（fs/net/http...） │
├───────────────┬──────────────┤
│ V8（执行 JS）  │ libuv（异步） │
│ 单线程         │ 线程池/事件循环│
└───────────────┴──────────────┘

┌─ timers        setTimeout / setInterval 到期回调
├─ pending      系统级回调（如 TCP 错误）
├─ poll         取新 IO 事件、执行 IO 回调（可能在此阻塞等待）
├─ check        setImmediate
└─ close        关闭回调
每个阶段之间：清空微任务队列（Promise.then、queueMicrotask、process.nextTick 优先）

/**
 * 经典输出顺序题：理解宏任务与微任务的插队规则。
 */
console.log('1');

setTimeout(() => console.log('2'), 0);
setImmediate(() => console.log('3'));

Promise.resolve().then(() => console.log('4'));
process.nextTick(() => console.log('5'));

console.log('6');

// 输出：1 6 5 4 2 3（2/3 的顺序在主模块中不保证，在 IO 回调中 setImmediate 先）

// ESM（推荐）：静态、可摇树、顶层 await
import { readFile } from 'node:fs/promises';
export const name = 'bff';

// CJS：运行时 require，历史包袱
const { readFile } = require('fs/promises');
module.exports = { name: 'bff' };

// ESM 里取当前目录
import { fileURLToPath } from 'node:url';
import path from 'node:path';
const __dirname = path.dirname(fileURLToPath(import.meta.url));

/**
 * 不依赖框架，理解 Node 原生 HTTP 的最直接方式。
 * 真实项目用 Express/Koa/Fastify，但底层都是这套。
 */
import http from 'node:http';

const server = http.createServer((req, res) => {
  if (req.url === '/health') {
    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify({ ok: true }));
    return;
  }

  res.writeHead(404, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({ error: 'Not Found' }));
});

server.listen(3000, () => console.log('listening on 3000'));

/**
 * 中间件本质是「责任链」：每个函数可以处理、修改、或交给下一个。
 * 顺序就是执行顺序，鉴权要在业务之前，错误处理要在最后。
 */
function logger(req, res, next) {
  const start = Date.now();
  res.on('finish', () => {
    console.log(`${req.method} ${req.url} ${res.statusCode} ${Date.now() - start}ms`);
  });
  next();
}

function auth(req, res, next) {
  const token = req.headers.authorization?.replace('Bearer ', '');
  if (!token) return res.status(401).json({ error: 'unauthorized' });
  req.user = verify(token);
  next();
}

app.use(logger);
app.use('/api', auth);

/**
 * 配置三原则：启动时校验、缺省值明确、敏感信息只从环境注入。
 */
const config = {
  port: Number(process.env.PORT ?? 3000),
  nodeEnv: process.env.NODE_ENV ?? 'development',
  downstream: {
    order: required('ORDER_SERVICE_URL'),
    user: required('USER_SERVICE_URL'),
  },
  timeoutMs: Number(process.env.UPSTREAM_TIMEOUT ?? 3000),
};

function required(key) {
  const v = process.env[key];
  if (!v) throw new Error(`缺少环境变量 ${key}`);
  return v;
}

/**
 * ❌ 串行：总耗时 = 各接口之和
 */
async function slowOrderPage(id) {
  const order = await getOrder(id);      // 100ms
  const user = await getUser(order.uid); // 100ms
  const items = await getItems(id);      // 100ms
  return { order, user, items };         // ≈300ms
}

/**
 * ✅ 并发：总耗时 = 最慢的那个
 * 注意：user 依赖 order，只能两段式。
 */
async function fastOrderPage(id) {
  const [order, items] = await Promise.all([getOrder(id), getItems(id)]);
  const user = await getUser(order.uid);
  return { order, user, items }; // ≈200ms
}

/**
 * 部分失败要能降级：allSettled 而不是 all。
 */
const [orderRes, itemsRes, couponRes] = await Promise.allSettled([
  getOrder(id), getItems(id), getCoupons(id),
]);

return {
  order: unwrap(orderRes, null),
  items: unwrap(itemsRes, []),
  coupons: unwrap(couponRes, []),   // 优惠券失败不影响主流程
  degraded: [orderRes, itemsRes, couponRes].some((r) => r.status === 'rejected'),
};

/**
 * 下游调用的三件套：超时、有限重试、熔断。
 * 缺超时 → 请求堆积；缺熔断 → 雪崩；滥用重试 → 流量放大。
 */
async function callUpstream(url, { timeout = 3000, retries = 1 } = {}) {
  for (let attempt = 0; attempt <= retries; attempt++) {
    const controller = new AbortController();
    const timer = setTimeout(() => controller.abort(), timeout);
    try {
      const res = await fetch(url, { signal: controller.signal });
      if (res.status >= 500 && attempt < retries) continue; // 只重试可恢复错误
      return res;
    } catch (err) {
      if (attempt === retries) throw err;
      await new Promise((r) => setTimeout(r, 100 * 2 ** attempt)); // 指数退避
    } finally {
      clearTimeout(timer);
    }
  }
}

/**
 * BFF 的鉴权职责：
 * 1) 校验用户会话（Cookie 或 token）
 * 2) 向下游透传「用户身份」，而不是透传原始凭证
 * 3) 不把用户 token 写进日志
 */
async function proxyWithUser(req, path) {
  const session = await readSession(req); // HttpOnly Cookie
  if (!session) throw new HttpError(401, '未登录');

  return fetch(`${config.downstream.order}${path}`, {
    headers: {
      'x-user-id': session.userId,
      'x-request-id': req.id,
      'x-tenant-id': session.tenantId,
    },
  });
}

/**
 * 两级缓存：进程内（快、易失效）+ 共享（Redis，跨实例一致）。
 * key 必须包含影响结果的维度：用户、语言、灰度分组。
 */
const local = new Map(); // 生产环境应换成 LRU 且有上限

async function getWithCache(key, ttlMs, loader) {
  const hit = local.get(key);
  if (hit && hit.expire > Date.now()) return hit.value;

  const value = await loader();
  local.set(key, { value, expire: Date.now() + ttlMs });
  return value;
}

/**
 * 统一错误模型：业务码 + HTTP 码 + 可展示消息 + 追踪 id。
 * 不要把堆栈返回给客户端。
 */
class HttpError extends Error {
  constructor(status, message, code = 'ERROR') {
    super(message);
    this.status = status;
    this.code = code;
  }
}

app.use((err, req, res, _next) => {
  const status = err.status ?? 500;
  if (status >= 500) logger.error({ err, requestId: req.id });

  res.status(status).json({
    code: err.code ?? 'INTERNAL',
    message: status >= 500 ? '服务暂时不可用' : err.message,
    requestId: req.id,
  });
});

/**
 * 收到 SIGTERM 后：
 * 1) 停止接收新连接
 * 2) 等待在途请求完成（有上限）
 * 3) 关闭连接池与定时器
 */
process.on('SIGTERM', async () => {
  server.close(async () => {
    await db.destroy();
    process.exit(0);
  });

  setTimeout(() => process.exit(1), 10_000).unref(); // 兜底强退
});

// ❌ 同步大计算：这 200ms 内所有请求都停住
app.get('/report', (req, res) => {
  const data = heavySyncCompute(); // 200ms CPU
  res.json(data);
});

// ✅ 移到 Worker 线程
import { Worker } from 'node:worker_threads';

app.get('/report', async (req, res) => {
  const result = await runInWorker('./report.worker.js', req.query);
  res.json(result);
});

# 提高线程池大小（注意 CPU 核数与内存）
UV_THREADPOOL_SIZE=8 node server.js

# 1) 看趋势：RSS 是否持续上涨且 GC 后不回落
node --inspect server.js

# 2) 抓堆快照（Chrome DevTools → Memory → Heap snapshot）
# 3) 对比 3 次快照，看「新增且未释放」的对象

/**
 * 有上限的 LRU：把「缓存」和「泄漏」区分开。
 */
class LRU {
  constructor(max = 500) {
    this.max = max;
    this.map = new Map();
  }
  get(k) {
    if (!this.map.has(k)) return undefined;
    const v = this.map.get(k);
    this.map.delete(k);
    this.map.set(k, v); // 提到最新
    return v;
  }
  set(k, v) {
    if (this.map.has(k)) this.map.delete(k);
    this.map.set(k, v);
    if (this.map.size > this.max) this.map.delete(this.map.keys().next().value);
  }
}

# CPU 火焰图
node --cpu-prof --cpu-prof-dir=./profiles server.js

# 一体化诊断（clinic）
npx clinic doctor -- node server.js
npx clinic flame -- node server.js

/**
 * 复用下游连接：避免每次请求都 TCP + TLS 握手。
 * Node 18+ 的 fetch 底层 undici 默认有连接池。
 */
import { Agent, setGlobalDispatcher } from 'undici';

setGlobalDispatcher(new Agent({
  connections: 100,
  keepAliveTimeout: 10_000,
  headersTimeout: 5_000,
  bodyTimeout: 10_000,
}));

/**
 * 请求 id 贯穿 BFF → 下游 → 日志，是排查的第一步。
 */
app.use((req, res, next) => {
  req.id = req.headers['x-request-id'] ?? crypto.randomUUID();
  res.setHeader('x-request-id', req.id);
  next();
});

/**
 * 舱壁模式：不同下游用不同并发池，避免一个慢依赖拖垮全部。
 */
const pools = {
  order: new Semaphore(50),
  user: new Semaphore(100),
  recommend: new Semaphore(20), // 非核心，限得更死
};

一级：超时缩短 + 返回缓存
二级：返回兜底数据（空列表/默认配置）
三级：关闭非核心模块（推荐位、广告）
四级：静态降级页

QPS × 平均响应时间 = 并发数（Little 定律）
并发数 × 单请求内存 = 内存需求

订单 200ms → 商品 400ms（串行）→ 用户 150ms → 优惠券 800ms → 推荐 500ms
总耗时 ≈ 2050ms，P99 4s

订单（核心，必须先拿，才能知道商品/用户 id）
  ├─ 商品（依赖订单）
  ├─ 用户（依赖订单）
  ├─ 优惠券（依赖订单）
  └─ 推荐（不依赖订单，可并行/可延后）

/**
 * 两段式并发 + 降级 + 缓存。
 * 核心依赖失败 → 抛错；非核心失败 → 兜底 + 标记降级。
 */
async function getOrderPage(id, user) {
  const order = await getOrder(id); // 核心

  const [items, profile, coupons] = await Promise.all([
    getItems(order.itemIds).catch(() => []),
    getUser(order.uid).catch(() => null),
    getCoupons(order.id, user).catch(() => []),
  ]);

  return {
    order,
    items,
    user: profile,
    coupons,
    degraded: !profile || coupons.length === 0,
  };
}

/**
 * 组合中间件，返回可直接调用的函数。
 * @param {Array<(ctx: any, next: () => Promise<void>) => any>} middlewares
 * @returns {(ctx: any, next?: () => Promise<void>) => Promise<void>}
 */
function compose(middlewares) {
  if (!Array.isArray(middlewares)) throw new TypeError('middlewares 必须是数组');
  middlewares.forEach((fn) => {
    if (typeof fn !== 'function') throw new TypeError('中间件必须是函数');
  });

  return function composed(ctx, next) {
    let index = -1;

    /** 执行第 i 个中间件 */
    const dispatch = (i) => {
      if (i <= index) return Promise.reject(new Error('next() 被重复调用'));
      index = i;

      let fn = middlewares[i];
      if (i === middlewares.length) fn = next;
      if (!fn) return Promise.resolve();

      try {
        return Promise.resolve(fn(ctx, () => dispatch(i + 1)));
      } catch (err) {
        return Promise.reject(err);
      }
    };

    return dispatch(0);
  };
}

/**
 * 并发聚合：限制并发数，单项失败不拖垮整体，支持整体超时。
 * @param {Record<string, () => Promise<any>>} tasks
 * @param {{concurrency?: number, timeout?: number}} [options]
 * @returns {Promise<{data: Record<string, any>, errors: Record<string, Error>}>}
 */
async function aggregate(tasks, { concurrency = 5, timeout = 800 } = {}) {
  const entries = Object.entries(tasks);
  const data = {};
  const errors = {};
  let cursor = 0;

  /** 单项执行：超时后放弃等待（下游仍应支持取消） */
  const runOne = async ([key, fn]) => {
    try {
      data[key] = await Promise.race([
        fn(),
        new Promise((_, reject) => setTimeout(() => reject(new Error(`${key} 超时`)), timeout)),
      ]);
    } catch (err) {
      errors[key] = err;
    }
  };

  /** 工作协程：从共享游标取任务 */
  const worker = async () => {
    while (cursor < entries.length) {
      const item = entries[cursor++];
      await runOne(item);
    }
  };

  await Promise.all(Array.from({ length: Math.min(concurrency, entries.length) }, worker));
  return { data, errors };
}