CSV 导出如何落地:Node.js 编码与浏览器下载实战

用零依赖 Node.js 与浏览器实现订单 CSV 导出,覆盖字段转义、公式注入边界、中文编码、背压与下载错误,附完整代码及十一项实测。

运营后台里,“把当前订单导出成 CSV”经常被估成一个按钮加一个接口。第一版也确实很快:查出所有记录,逗号连接,返回文件。等到客户名称里出现逗号、备注里出现换行、中文在表格软件里乱码,或者慢网络让服务进程的内存持续增长,才发现下载功能跨过了好几道协议边界。

本文做一个可以从空目录运行的订单导出示例。重点是文件格式、数据类型和浏览器交付,不接数据库,不引入前端框架,也不把取消操作单独扩展成任务调度系统。后端使用 Node.js 原生 HTTP 和 Streams,前端提供直接下载与小报表下载两条路径。所有数据都是固定规则生成的演示订单,不能把这个未接认证的服务直接暴露到公网。

一、先写清这份文件给谁使用

这里的目标读者是需要查看订单的业务人员。文件采用 UTF-8,第一行有列名,记录之间使用 CRLF,四列分别是订单号、客户、金额和备注。客户与备注属于不可信文本,允许逗号、双引号、中文及换行。金额来自服务端校验过的整数分,输出两位小数。订单号采用带字母前缀的应用内编号,不用纯数字伪装成文本。

有两个需要提前承认的取舍。首先,CSV 没有可靠的单元格类型声明,双引号负责字段边界,不负责阻止表格软件自动识别类型。手机号的前导零、很长的数字编号以及日期字符串,都可能被消费软件重解释。其次,给文本添加保护前缀会改变导出的原始数据。这份文件服务于人工查看,不承担数据库备份或无损数据交换的职责。

如果产品同时需要“给人看”和“给系统导入”,应建立两份有明确契约的输出。机器接口可以使用带字段类型说明的 JSON,或约定清楚的 CSV 方言;人用文件可以考虑明确指定文本单元格的工作簿。不要让同一份 CSV 靠文件名承担两个互相冲突的承诺。

二、环境、文件与启动方式

本次实际执行环境是 Node.js v24.22.1,没有第三方 npm 依赖。下面使用的模块均来自 Node.js。为缩小复现范围,示例包声明 Node.js 24 系列;这不是“最新版本”的推荐,也不表示其他主版本已经经过本文验证。前端需要支持 ES Modules、Fetch、AbortController 和 Blob URL 的现代浏览器。

创建一个空目录,把后续各代码块保存为标注的文件名。目录包含 package.json、csv.mjs、server.mjs、index.html、app.js 和 export.test.mjs。无需执行 npm install;运行 npm test 验证后,再运行 npm start。服务只监听本机的 127.0.0.1:3000。

package.json:

{
  "name": "orders-csv-demo",
  "private": true,
  "type": "module",
  "engines": { "node": ">=24 <25" },
  "scripts": { "start": "node server.mjs", "test": "node --test" }
}

三、先把每个字段编码正确

Array.join(',') 只能连接字符串,无法处理 CSV 的语法。对于含逗号、双引号或换行的字段,需要用双引号包住,并把字段内部的一个双引号写成两个。本文对文本字段一律加引号,避免按内容选择分支。记录之间用 CRLF,字段内部的换行保留。这样“备注有两行”仍然是一条订单,不能靠统计文件中的换行数来计算订单数。RFC 4180 的字段与转义规则

下面把编码分成三层:quote 处理文件语法;textCell 处理人工查看文件的文本策略;money 处理金额类型。把它们混成一个“万能 escape”函数,后面新增数字列时很容易忘记哪一层改变了数据。

csv.mjs:

import { setImmediate } from 'node:timers/promises';

export const BOM = Buffer.from([0xef, 0xbb, 0xbf]);
export const HEADER = '订单号,客户,金额(元),备注\r\n';
const MAX_TEXT_BYTES = 1024;

export function quote(value) {
  return `"${String(value).replaceAll('"', '""')}"`;
}

export function textCell(value) {
  const text = String(value ?? '');
  if (Buffer.byteLength(text, 'utf8') > MAX_TEXT_BYTES) {
    throw new RangeError('text field exceeds 1024 UTF-8 bytes');
  }
  // Human-facing export: a leading apostrophe is part of the CSV data.
  return quote("'" + text);
}

export function money(cents) {
  if (!Number.isSafeInteger(cents)) throw new TypeError('invalid cents');
  const absolute = Math.abs(cents);
  return `${cents < 0 ? '-' : ''}${Math.floor(absolute / 100)}.${String(absolute % 100).padStart(2, '0')}`;
}

export async function* demoRows(count, { signal }) {
  const names = ['张三', '李,四', '=1+2'];
  const notes = ['正常订单', '他说"请核对"\n第二行', '@SUM(1,2)'];
  for (let i = 0; i < count; i++) {
    signal.throwIfAborted();
    yield {
      id: `ORD-${String(i + 1).padStart(6, '0')}`,
      customer: names[i % 3],
      cents: 1990 + i,
      note: notes[i % 3]
    };
    if (i % 128 === 127) await setImmediate(undefined, { signal });
  }
}

export async function* csvChunks(rows) {
  yield BOM;
  yield Buffer.from(HEADER);
  for await (const row of rows) {
    if (!/^ORD-\d{6}$/.test(row.id)) throw new TypeError('invalid order id');
    yield Buffer.from([
      quote(row.id), textCell(row.customer), money(row.cents), textCell(row.note)
    ].join(',') + '\r\n');
  }
}

这段代码有几个刻意的限制。每个客户或备注字段最多接受 1024 个 UTF-8 字节,超出就失败,不能悄悄截断后仍声称导出了原始备注。字节数与 JavaScript 字符串长度不是一回事,中文通常需要多个 UTF-8 字节;测试因此放入了 342 个“中”来触发限制。订单号通过固定语法检查,任意外部字符串不能绕过文本策略进入这列。

金额接受安全整数分,避免直接把用户输入的字符串拼进数字列。负数金额仍然可以表示退款,不应被一条针对所有字段的公式过滤规则破坏。这里的减号由受限数字格式化产生,用户无法借它拼出表达式。对于超过安全整数范围的金额,生产系统需要整数大数或明确的十进制定点方案,不能仅删掉校验。

demoRows 每次产出一条记录,并定期让出事件循环。csvChunks 逐行编码,开头只写一次 BOM 和列名。空结果同样有列名,不用零字节文件让用户猜测导出是否失败。这里把 null 文本转成空文本后仍加保护前缀,因此原始字节中会留下一个单引号;它不保留数据库 NULL 与空串的区别,不能拿来做备份恢复。

公式注入的边界要放在代码旁边

CSV 合法,不代表打开它的表格软件不会执行公式。仅用双引号包住等号开头的文本,没有给单元格声明“文本类型”。本例统一给不可信文本添加单引号前缀,再做 CSV 引号转义,不只检查第一位是否为等号,因而也覆盖示例中的加减号、制表符、前导空格和全角符号输入。

这是一项有适用范围的防护,不是跨软件安全保证。 前缀会进入文件数据,在部分工具里可见;保存 CSV 再重新打开时,保护可能发生变化。OWASP 明确提醒不同表格软件与下游消费者不存在通用的 CSV 净化策略,并特别说明 Excel 保存后重开的风险。因此本文测试证明的是“输出字节按策略编码”,不是“任何版本的 Excel 都不会执行公式”。OWASP CSV Injection

对于会接收陌生人提交内容、又要求员工反复保存编辑的高风险场景,我更倾向于生成具有明确文本单元格类型的工作簿,并禁止把用户内容写入公式字段。无论采用哪种格式,都需要用目标软件和目标地区设置验收,不能用一次无害的等号示例替代安全检查。

BOM 是消费端兼容选择

文件开头的 EF BB BF 用于帮助某些软件识别 UTF-8。微软说明,带 BOM 的 UTF-8 CSV 通常可以在 Excel 中正常打开;不带 BOM 时,也可通过文本导入选择编码。Microsoft:正确打开 UTF-8 CSV

因此,本例同时发送 charset=utf-8 和 BOM。前者描述 HTTP 内容,后者跟着保存后的文件走。BOM 不是所有 CSV 消费者都需要的东西,有些导入程序会把它误读为第一列名称的一部分。如果未来增加机器导出端点,要把是否带 BOM 写进接口契约,而不是在每条记录之前追加一次。

四、HTTP 接口要让慢接收者反过来限制生成速度

下一层把记录源接到 HTTP 响应。示例只接受 GET,count 限制在零到五万,同一个参数重复出现也拒绝。先处理请求错误,再设置附件响应头,避免把“参数错误”下载成一个伪装的 CSV 文件。进程内最多允许两个导出,第三个返回 429;这只是演示的资源保护,后面会说明生产环境为什么不能照搬这个数字。

server.mjs:

import { createServer } from 'node:http';
import { readFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { Readable } from 'node:stream';
import { pipeline } from 'node:stream/promises';
import { demoRows, csvChunks } from './csv.mjs';

const index = readFileSync(new URL('./index.html', import.meta.url));
const app = readFileSync(new URL('./app.js', import.meta.url));

export function createApp({
  makeRows = demoRows, timeoutMs = 30_000, onExportDone = () => {}
} = {}) {
  let active = 0;
  return createServer((req, res) => {
    async function handle() {
      res.setHeader('Cache-Control', 'no-store');
      res.setHeader('X-Content-Type-Options', 'nosniff');
      const url = new URL(req.url, 'http://localhost');
      if (req.method !== 'GET') {
        res.writeHead(405, { Allow: 'GET' }).end('GET required');
        return;
      }
      if (url.pathname === '/' || url.pathname === '/app.js') {
        const html = url.pathname === '/';
        res.writeHead(200, {
          'Content-Type': html ? 'text/html; charset=utf-8' : 'text/javascript; charset=utf-8'
        }).end(html ? index : app);
        return;
      }
      if (url.pathname !== '/api/orders.csv') {
        res.writeHead(404).end('not found');
        return;
      }
      const values = url.searchParams.getAll('count');
      const countText = values[0] ?? '1000';
      if (values.length > 1 || !/^\d{1,5}$/.test(countText) || Number(countText) > 50000) {
        res.writeHead(400, { 'Content-Type': 'text/plain; charset=utf-8' })
          .end('count 必须是 0 到 50000 的整数');
        return;
      }
      if (active >= 2) {
        res.writeHead(429, { 'Retry-After': '5' }).end('export busy');
        return;
      }
      active++;
      const controller = new AbortController();
      const stop = () => {
        if (!res.writableFinished) controller.abort();
      };
      res.once('close', stop);
      const timer = setTimeout(() => controller.abort(), timeoutMs);
      timer.unref();
      let outcome = 'failed';
      try {
        const filename = encodeURIComponent('订单导出.csv');
        res.writeHead(200, {
          'Content-Type': 'text/csv; charset=utf-8',
          'Content-Disposition': `attachment; filename="orders.csv"; filename*=UTF-8''${filename}`
        });
        const source = Readable.from(
          csvChunks(makeRows(Number(countText), { signal: controller.signal })),
          { objectMode: false, highWaterMark: 16 * 1024 }
        );
        await pipeline(source, res, { signal: controller.signal });
        outcome = 'finished';
      } catch {
        // A failed HTTP pipeline must not append JSON to the CSV response.
        res.destroy();
      } finally {
        clearTimeout(timer);
        res.off('close', stop);
        active--;
        onExportDone({ outcome, aborted: controller.signal.aborted });
      }
    }
    handle().catch(() => {
      if (!res.headersSent && !res.destroyed) res.writeHead(500).end('internal error');
      else res.destroy();
    });
  });
}

if (process.argv[1] === fileURLToPath(import.meta.url)) {
  createApp().listen(3000, '127.0.0.1', () => {
    console.log('Open http://127.0.0.1:3000');
  });
}

Readable.from 接收异步迭代器,pipeline 将它与 HTTP 响应连接起来。当下游接收变慢,流内部会停止继续拉取上游,而不是继续把全部订单写进一个无限增长的字符串。这里显式关闭 objectMode,让读取缓冲以字节为尺度,并把阈值设为 16 KiB。Node.js 文档也强调 highWaterMark 是开始施加背压的阈值,不是进程内存的硬上限。Node.js 24 Streams 文档

真正的内存边界还取决于单行大小、数据库驱动的预取、HTTP 和系统缓冲,以及同时运行多少导出。本例限制文本字段大小,正是为了避免“一次 yield 一条记录”却在一条记录里塞入几百兆数据。替换数据源时,如果先用查询方法把全部订单装进数组,再交给 Readable.from,内存峰值早已发生,末端换成流没有补救作用。

Content-Disposition 同时给出 ASCII 回退文件名和 UTF-8 编码的中文文件名,文件名由应用固定生成,不接收用户提供的路径或控制字符。支持 filename* 的客户端可以使用中文名称。它只是下载建议,最终文件名与保存行为仍受浏览器设置影响。MDN:Content-Disposition

代码没有设置 Content-Length,因为生成前还不知道完整文件长度,也不为了算长度先生成一遍。它不会根据记录条数猜测字节数:中文、引号转义、备注换行都会改变长度。Cache-Control 采用 no-store,避免订单内容被普通 HTTP 缓存复用;它不能撤回用户已经保存到硬盘的文件。

一旦开始输出,就不能再改成错误 JSON

接口把失败分成两类。参数不合法、并发槽位不足等检查发生在流开始之前,可以返回清楚的状态码。数据源中途出错、超过时限或客户端断开,则终止这条响应,不能在已经输出的 CSV 后面追加 JSON,也不能假装补上一行“导出失败”就形成了完整文件。

这里直接让失败的 pipeline 结束响应。前端 fetch 可能已经拿到 200,但读取响应体会失败;测试专门覆盖了这个状态。所谓“接口返回成功”,必须区分收到了响应头和收完了完整响应体。对于必须证明每一条记录都交付完整的审计文件,更稳妥的方案是先生成文件,成功校验行数与摘要后再提供下载。实时直出无法在开始传输前承诺后续数据源永不失败。

三十秒的总时限防止单个连接无限占用资源;响应关闭时也通知数据源退出。示例中的延迟支持 AbortSignal,因此可以及时收尾。真实数据库查询是否会随信号停止,需要按驱动能力实现并测试,不能因为外层调用了 abort 就认定数据库已经取消。

五、浏览器下载需要两条不同的交付路径

第一条路径是普通链接,浏览器直接向导出接口请求文件。它不把整个响应先读进页面 JavaScript,适合直接下载。用户在浏览器下载管理器里查看进度或取消,页面不要伪装一个自己无法可靠知道的“已保存成功”状态。

第二条路径用 fetch 获取小报表。优势是能够在页面展示 HTTP 错误,并在接收期间通过按钮取消。代价是 blob() 要读取完整响应后才返回 Blob,不能把它当作“大文件流式落盘”的证明。MDN:Response.blob()

index.html:

<!doctype html>
<html lang="zh-CN">
<meta charset="utf-8">
<title>订单 CSV 导出</title>
<h1>订单 CSV 导出</h1>
<p>演示数据。文本列可能包含保护用的单引号。</p>
<p><a href="/api/orders.csv?count=50000">交给浏览器直接下载 50000 条</a></p>
<button id="start">下载小报表(1000 条)</button>
<button id="cancel" disabled>取消小报表</button>
<p id="status" role="status"></p>
<script type="module" src="/app.js"></script>
</html>

app.js:

const start = document.querySelector('#start');
const cancel = document.querySelector('#cancel');
const status = document.querySelector('#status');
let controller;
cancel.onclick = () => controller?.abort();

start.onclick = async () => {
  controller = new AbortController();
  start.disabled = true;
  cancel.disabled = false;
  status.textContent = '正在接收报表…';
  try {
    const response = await fetch('/api/orders.csv?count=1000', {
      signal: controller.signal,
      credentials: 'same-origin'
    });
    if (!response.ok) throw new Error(`导出失败:HTTP ${response.status}`);
    if (!response.headers.get('Content-Type')?.startsWith('text/csv')) {
      throw new Error('服务器没有返回 CSV');
    }
    const blob = await response.blob();
    controller.signal.throwIfAborted();
    const href = URL.createObjectURL(blob);
    const link = document.createElement('a');
    link.href = href;
    link.download = '订单导出.csv';
    link.textContent = '若未自动下载,请点击保存 CSV';
    link.onclick = () => {
      setTimeout(() => { URL.revokeObjectURL(href); link.remove(); }, 60_000);
    };
    status.replaceChildren(link);
    link.click();
  } catch (error) {
    status.textContent = error.name === 'AbortError' ? '已取消接收报表' : error.message;
  } finally {
    controller = undefined;
    start.disabled = false;
    cancel.disabled = true;
  }
};

小报表固定请求一千条演示记录,接口和字段大小也有上限;真实项目仍应给这一条路径设置适合目标设备的文件字节预算。不能只根据“一千条”判断文件必然很小,一千条长文本和一千条订单编号的体积差距很大。

前端先检查状态码与内容类型,再读取 Blob。否则登录过期返回的 HTML 页面,可能被用户保存为 CSV。这个检查只能避免明显的响应类型错误,不证明文件内容本身符合业务契约。代码没有读取响应头中的文件名,因为本例已约定固定中文名称;若改成动态文件名,应使用可靠的头部解析并限制文件名字符,不要把整段头部字符串直接赋给下载属性。

下载按钮得到 Blob 后创建对象 URL,并保留一个可手动点击的链接,方便自动下载被浏览器策略拦住时继续操作。链接触发后六十秒回收对象 URL,避免长时间持有数据。这个延迟是示例的交互取舍,不是下载完成回调;实际产品可以保留单独的下载项,由用户清除时回收。MDN:revokeObjectURL()

取消按钮只负责 fetch 正在接收的阶段。Blob 已经交给浏览器下载后,页面按钮无法可靠撤回浏览器下载任务,因此 finally 会禁用它。前端文案使用“已取消接收报表”,不把动作范围扩大成已经删除本地文件或取消了所有服务端工作。

六、把失败场景变成可以执行的测试

下面测试使用 Node.js 自带的测试运行器,不需要测试框架。它会启动只监听本机的临时端口,验证实际 HTTP 字节和异常行为。测试中的慢数据源、断连与故障都通过依赖注入实现,生产路由没有暴露故障开关。

特别注意背压测试的结论:它阻塞一个 Writable 的写回调,检查上游没有把一万块数据全部提前生成。这验证本地流链路会暂停拉取,不是互联网吞吐测试,也不能证明反向代理不会缓冲。代码不依赖一个精确的预读块数,而是使用明显低于总量的边界,减少对内部调度细节的耦合。

export.test.mjs:

import test from 'node:test';
import assert from 'node:assert/strict';
import { once } from 'node:events';
import { get } from 'node:http';
import { setTimeout as delay } from 'node:timers/promises';
import { Readable, Writable } from 'node:stream';
import { pipeline } from 'node:stream/promises';
import { BOM, HEADER, quote, textCell, money, csvChunks } from './csv.mjs';
import { createApp } from './server.mjs';

async function serve(t, options) {
  const server = createApp(options);
  server.listen(0, '127.0.0.1');
  await once(server, 'listening');
  t.after(async () => {
    server.closeAllConnections();
    await new Promise(resolve => server.close(resolve));
  });
  return `http://127.0.0.1:${server.address().port}`;
}

async function until(predicate) {
  for (let i = 0; i < 100; i++) {
    if (predicate()) return;
    await delay(10);
  }
  assert.fail('condition not reached within 1 second');
}

const row = { id: 'ORD-000001', customer: '张三', cents: 1990, note: '正常' };

test('CSV escaping and text protection', () => {
  assert.equal(quote('甲,"乙"\n丙'), '"甲,""乙""\n丙"');
  for (const value of ['=1+2', '+1', '-1', '@x', '\t=1', '\r=1', '\n=1', '=1', '  =1']) {
    assert.equal(textCell(value), quote("'" + value));
  }
  assert.equal(textCell(null), '"\'"');
  assert.throws(() => textCell('中'.repeat(342)), /1024/);
});

test('money uses integer cents', () => {
  assert.equal(money(1990), '19.90');
  assert.equal(money(-1), '-0.01');
  assert.equal(money(0), '0.00');
  assert.throws(() => money(1.5));
  assert.throws(() => money(Number.MAX_SAFE_INTEGER + 1));
});

test('zero rows still has one BOM and a header', async () => {
  const chunks = [];
  for await (const chunk of csvChunks([])) chunks.push(chunk);
  assert.deepEqual(Buffer.concat(chunks), Buffer.concat([BOM, Buffer.from(HEADER)]));
});

test('invalid source data is rejected', async () => {
  const consume = async value => {
    for await (const chunk of csvChunks([value])) void chunk;
  };
  await assert.rejects(consume({ ...row, id: '=1+2' }), /invalid order id/);
  await assert.rejects(consume({ ...row, note: 'x'.repeat(1025) }), /1024/);
});

test('HTTP body bytes, UTF-8 and download headers', async t => {
  const base = await serve(t);
  const response = await fetch(`${base}/api/orders.csv?count=3`);
  assert.equal(response.status, 200);
  assert.equal(response.headers.get('Content-Type'), 'text/csv; charset=utf-8');
  assert.equal(response.headers.get('Cache-Control'), 'no-store');
  assert.match(response.headers.get('Content-Disposition'), /filename\*=UTF-8''%/);
  const bytes = Buffer.from(await response.arrayBuffer());
  assert.deepEqual(bytes.subarray(0, 3), BOM);
  assert.equal(bytes.subarray(3).toString(), HEADER +
    '"ORD-000001","\'张三",19.90,"\'正常订单"\r\n' +
    '"ORD-000002","\'李,四",19.91,"\'他说""请核对""\n第二行"\r\n' +
    '"ORD-000003","\'=1+2",19.92,"\'@SUM(1,2)"\r\n');
});

test('invalid counts fail before CSV headers; POST is rejected', async t => {
  const base = await serve(t);
  for (const query of ['count=-1', 'count=1.5', 'count=50001', 'count=1&count=2', 'count=']) {
    const response = await fetch(`${base}/api/orders.csv?${query}`);
    assert.equal(response.status, 400);
    assert.equal(response.headers.get('Content-Disposition'), null);
    await response.text();
  }
  const post = await fetch(`${base}/api/orders.csv`, { method: 'POST' });
  assert.equal(post.status, 405);
  await post.text();
});

test('a blocked sink cannot eagerly consume the complete source', async () => {
  let produced = 0;
  let first;
  const source = Readable.from((async function* () {
    for (let i = 0; i < 10000; i++) {
      produced++;
      yield Buffer.alloc(1024);
    }
  })(), { objectMode: false, highWaterMark: 4096 });
  const sink = new Writable({ highWaterMark: 1024, write(_chunk, _encoding, callback) {
    first ??= callback;
  } });
  const controller = new AbortController();
  const done = pipeline(source, sink, { signal: controller.signal });
  const rejected = assert.rejects(done, { name: 'AbortError' });
  await until(() => Boolean(first));
  await delay(20);
  assert.ok(produced < 20, `unexpected eager production: ${produced}`);
  controller.abort();
  await rejected;
});

test('client disconnect releases the source and export slot', async t => {
  let released = false;
  const results = [];
  const base = await serve(t, {
    makeRows: async function* (_count, { signal }) {
      try {
        while (true) { yield row; await delay(20, undefined, { signal }); }
      } finally { released = true; }
    },
    onExportDone: result => results.push(result)
  });
  await new Promise((resolve, reject) => {
    const request = get(`${base}/api/orders.csv`, response => {
      response.once('data', () => { response.destroy(); resolve(); });
    });
    request.on('error', reject);
  });
  await until(() => released && results.length === 1);
  assert.equal(results[0].outcome, 'failed');
  assert.equal(results[0].aborted, true);
});

test('third simultaneous export is rejected and slots recover', async t => {
  let done = 0;
  const base = await serve(t, {
    makeRows: async function* (_count, { signal }) {
      while (true) { yield row; await delay(100, undefined, { signal }); }
    },
    onExportDone: () => done++
  });
  const first = await fetch(`${base}/api/orders.csv`);
  const second = await fetch(`${base}/api/orders.csv`);
  const third = await fetch(`${base}/api/orders.csv`);
  assert.equal(third.status, 429);
  await third.text();
  await first.body.cancel();
  await second.body.cancel();
  await until(() => done === 2);
  const next = await fetch(`${base}/api/orders.csv`);
  assert.equal(next.status, 200);
  await next.body.cancel();
  await until(() => done === 3);
});

test('a failure after output starts truncates, never appends JSON', async t => {
  const base = await serve(t, {
    makeRows: async function* () {
      yield row;
      await delay(20);
      throw new Error('injected source failure');
    }
  });
  const response = await fetch(`${base}/api/orders.csv`);
  assert.equal(response.status, 200);
  await assert.rejects(response.arrayBuffer());
});

test('deadline aborts a slow export', async t => {
  let released = false;
  const base = await serve(t, {
    timeoutMs: 50,
    makeRows: async function* (_count, { signal }) {
      try { yield row; await delay(5000, undefined, { signal }); }
      finally { released = true; }
    }
  });
  const response = await fetch(`${base}/api/orders.csv`);
  await assert.rejects(response.arrayBuffer());
  await until(() => released);
});

运行命令:

node --version
npm test
npm start

保持服务运行,在另一个终端检查一个小文件:

curl --fail --show-error --dump-header headers.txt   'http://127.0.0.1:3000/api/orders.csv?count=3'   --output orders.csv
node --input-type=module -e "import {readFileSync} from 'node:fs'; const b=readFileSync('orders.csv'); console.log(b.subarray(0,3).toString('hex')); console.log(b.subarray(3).toString('utf8'));"
curl --include 'http://127.0.0.1:3000/api/orders.csv?count=50001'

第一条检查应看到附件响应头,文件前三字节打印为 efbbbf。去掉 BOM 后有中文列名和三条记录,第三条客户文本带保护单引号。第二条命令应得到 400,而不是一个正常附件。备注本身含换行,因此直接用 wc -l 计算订单数会得到错误的业务结论;应使用理解引号的 CSV 解析器。

本文已经执行的验证: 在 Node.js v24.22.1 下,十一项自动化测试全部通过,随后又连续运行三次,每次仍为十一项通过。另一次真实本地 HTTP 请求导出五万条演示订单,完整响应为 2,558,710 字节,BOM 为 efbbbf,末条订单号为 ORD-050000。这个字节数只适用于本文固定数据,不是任意五万条业务订单的容量预测。

本文没有执行的验证: 没有在真实 Chrome、Safari、Firefox 或 Excel、LibreOffice 中操作下载和打开文件,没有通过生产代理链路,也没有接入真实数据库。因此不能把 Node.js 中的 fetch 测试写成浏览器实测,更不能据此宣称某个表格软件的公式处理已通过安全验收。

浏览器验收应分别检查直接下载和小报表两条路径,在限制网速后观察取消、错误提示与重复点击;目标表格软件应检查中文、逗号、嵌入换行、保护前缀显示、金额列,以及保存再打开后的内容变化。样本中的公式保持无害,不需要执行联网或系统命令来验证是否发生公式解释。

七、接入真实业务前还要补哪些约束

首先补认证和授权。这个示例只使用本机演示数据,没有登录系统;生产查询必须从服务端会话取得用户及租户上下文,并把租户条件写入数据查询。不能从 URL 接收 tenantId 就相信调用者有访问该租户订单的权限。可导出的列也应由服务端白名单控制,避免前端隐藏的手机号、内部备注或成本字段被导出接口直接带出。

其次明确数据一致性。导出期间订单可能持续变化:按当前状态逐批读取、按某一时刻的快照读取,以及生成“截至某时点”的报表,是不同契约。实时流式响应只解决字节交付,不会自动提供数据库快照。长事务可能占用连接并延长旧版本保留时间;批量查询也可能看到不同时间的状态。应该先给业务方解释文件的时间范围,再选择相应的数据读取方案。

第三,把性能预算写在业务边界上。示例的两个并发槽只对单个进程有效,部署多个实例后不会自动变成全站两个。生产还需要每个用户或租户的导出频率、任务并发、最大日期跨度、最大行数与连接占用预算。这里只用一个总时限做兜底,实际还应区分数据库查询超时、用户下载过慢和代理空闲超时,避免一个简单数字掩盖不同故障。

第四,经过真实入口验证。应用按块发送,不代表每一层代理立即转发;压缩、响应缓冲和平台时限都可能改变首字节时间与内存使用。应观察应用进程的内存、已产出行数、传输持续时间和失败阶段,而不是只看最终有没有下载到一个文件。日志记录任务标识、范围、条数和错误类别即可,不要记录整份客户备注,更不要为了调试把完整导出文件长期落在日志目录。

最后,考虑文件离开系统之后的生命周期。导出链接鉴权成功,只能证明某次下载获得授权;文件保存后无法靠原有会话控制传播。如果业务要求审计、撤销、审批或对敏感列做脱敏,这些约束应在生成前执行。改成离线生成时,临时文件和对象存储还需要保留期限、访问鉴权及失败清理,不应因为“已经是 CSV”就降级为公开下载链接。

八、我更看重的验收标准

导出功能的难点,是让业务数据经过每一层解释后仍符合约定。数据库看见的是带类型的记录,CSV 编码器看见的是字符与分隔符,HTTP 传递的是字节,浏览器负责下载,表格软件又会重新推断类型。任何一层做了隐式转换,最后都可能成为业务人员手里的错误报表。

因此,我不会用“能下载五万条”作为完成定义。更有用的标准是:异常字符没有破坏列边界;不可信文本使用了明确且经过目标软件验收的策略;失败不会伪装成完整成功;慢消费者不会迫使应用提前装下全部数据;页面准确表达自己知道的状态。本文的零依赖实现把这些边界拆成了可运行的代码和测试,也明确留下了浏览器、表格软件与生产数据源的验收工作。

当导出需求进一步变成跨小时任务、可重试文件或有审计要求的交付物,就应进入专门的报表生成流程。小型实时 CSV 继续保持简单,复杂交付另建清楚的契约,比让一个下载按钮承担越来越多无法兑现的承诺更容易维护。

相关文章

评论

登录后即可参与讨论

暂无评论。