轻量级开票系统数据库与API设计实战

1. 项目概述：为什么一个轻量级开票应用值得从零手撸数据库与API

“How To Build a Lightweight Invoicing App with Node: Database and API”——这个标题里藏着三个被日常开发严重低估的关键词： Lightweight（轻量） 、 Invoicing（开票） 、 Database and API（数据库与API） 。它不是教你怎么用现成的SaaS工具点几下生成发票，而是直指中小企业财务流程中最痛的痒处：既要满足真实业务场景（客户名称、税号、商品明细、税率、电子签章预留位、PDF导出），又不能背上ERP级别的臃肿架构。我做过7个不同行业的开票模块，从五金批发商的简易手写单扫描存档，到跨境电商服务商的多币种+VAT自动计算，发现90%的需求其实只需要一张 invoices 表、两张关联表（ invoice_items 和 clients ），外加5个核心API端点。Node.js在这里不是为了炫技，而是因为它天然适合这种I/O密集型、低计算负载、高并发读写的场景——用户开一张票平均耗时23秒，但后台要同时处理PDF渲染、邮件通知、库存扣减、税务校验四个异步任务，Node的事件循环模型比传统PHP或Java Spring Boot更省资源。你不需要Docker、K8s、微服务治理，一台4核8G的云服务器跑10个并发开票请求毫无压力。重点在于： 数据库设计必须拒绝“先建好再填数据”的懒人思维，API路由必须按业务动词而非资源名词组织 。比如 POST /invoice/generate 比 POST /invoices 更能表达意图， GET /invoice/pdf/:id 比 GET /invoices/:id/pdf 更符合前端调用直觉。这背后是三年踩坑换来的经验：当财务人员在凌晨两点发现某张发票税率填错需要紧急作废时，他不会关心你的RESTful是否规范，他只想要一个能立刻执行 PATCH /invoice/cancel/:id 并返回带时间戳操作日志的接口。所以这篇内容不是Node教程，而是一个从业十年的全栈开发者，在交付第23个开票系统后，把所有数据库字段命名逻辑、API错误码分级策略、PDF模板变量注入机制，全部摊开给你看。

2. 数据库设计：从财务合规倒推表结构，而不是从ORM模型正向生成

2.1 核心表结构设计原理：为什么Invoice表必须包含 issue_date 和 due_date 两个独立字段

开票系统最常被忽略的底层陷阱，是把日期当成纯技术字段处理。很多新手直接用 created_at 和 updated_at 覆盖业务含义，结果在财务对账时发现致命问题：一张发票的 开具日期 （法律效力起始日）和 付款截止日 （合同约定日）可能相隔30天，而 created_at 只能记录入库时间。我们实际业务中遇到过客户投诉：“你们3月5日开的票，为什么4月10日才发给我？导致我超期付款被银行罚息！”——根源就是系统把发票生成时间当成了开具时间。因此 invoices 表必须强制拆分：

CREATE TABLE invoices (
  id SERIAL PRIMARY KEY,
  invoice_number VARCHAR(32) NOT NULL UNIQUE, -- 业务编号，非自增ID
  client_id INTEGER NOT NULL REFERENCES clients(id),
  issue_date DATE NOT NULL, -- 法律意义上的开票日，需人工选择或默认为今日
  due_date DATE NOT NULL,   -- 合同约定付款日，可基于账期自动计算
  currency CHAR(3) NOT NULL DEFAULT 'CNY', -- ISO 4217标准，避免用'¥'等符号
  tax_rate DECIMAL(5,2) NOT NULL DEFAULT 0.00, -- 精确到小数点后两位
  status VARCHAR(16) NOT NULL DEFAULT 'draft' CHECK (status IN ('draft','issued','paid','cancelled','overdue')),
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

提示： invoice_number 字段绝不能用 SERIAL 自增。真实场景中客户要求编号规则如 INV-2024-SH-0001 （地区+年份+序列），必须由应用层生成并保证唯一性。我们采用Redis原子计数器+业务前缀拼接方案，实测在1000QPS下冲突率为0。

2.2 关联表设计：为什么 invoice_items 必须冗余 unit_price 和 tax_amount

新手常犯的错误是试图用“规范化”消灭所有冗余，把商品单价存在 products 表，开票时动态关联查询。这在财务系统中是灾难性的——今天卖100元的商品，三个月后查历史发票时，如果该商品已下架或调价，你将无法还原当时的真实交易价格。 invoice_items 表必须固化所有开票瞬间的状态：

CREATE TABLE invoice_items (
  id SERIAL PRIMARY KEY,
  invoice_id INTEGER NOT NULL REFERENCES invoices(id) ON DELETE CASCADE,
  description TEXT NOT NULL, -- 允许手动输入，不强制关联product表
  quantity INTEGER NOT NULL DEFAULT 1 CHECK (quantity > 0),
  unit_price DECIMAL(12,2) NOT NULL, -- 开票时锁定的价格
  tax_rate DECIMAL(5,2) NOT NULL DEFAULT 0.00, -- 可能与invoice主税率不同（如免税商品）
  tax_amount DECIMAL(12,2) NOT NULL DEFAULT 0.00, -- 预计算值，避免实时计算误差
  line_total DECIMAL(12,2) NOT NULL, -- quantity * unit_price，含税总价
  sort_order INTEGER DEFAULT 0 -- 支持拖拽调整行顺序
);

注意： line_total 不是简单 quantity * unit_price ，而是 quantity * unit_price * (1 + tax_rate) 。我们曾因前端JS浮点计算精度问题（0.1+0.2=0.30000000000000004）导致金额对不上，最终强制在数据库触发器中用 NUMERIC 类型重算并校验。

2.3 客户表设计：为什么 clients 表要预留 tax_id 和 bank_account 但不设NOT NULL约束

中小企业开票需求千差万别：个体户可能只要姓名和电话，一般纳税人必须提供税号，出口企业还需SWIFT代码。若强行用 NOT NULL 约束，会导致大量无效数据或绕过验证。我们的解法是分层设计：

CREATE TABLE clients (
  id SERIAL PRIMARY KEY,
  name VARCHAR(128) NOT NULL,
  contact_name VARCHAR(64),
  phone VARCHAR(32),
  email VARCHAR(128),
  address TEXT,
  tax_id VARCHAR(64), -- 统一社会信用代码/税号，长度可变
  bank_name VARCHAR(128),
  bank_account VARCHAR(64),
  bank_swift VARCHAR(11), -- 仅出口业务需要
  is_tax_payer BOOLEAN DEFAULT FALSE, -- 是否一般纳税人，控制税号必填逻辑
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

业务层校验规则：当 is_tax_payer = true 时，API接收请求时必须校验 tax_id 非空且符合15/18位数字+字母规则（正则 ^[a-zA-Z0-9]{15,18}$ ）。这样既保持数据库灵活性，又确保关键业务规则不被绕过。

2.4 索引策略：三个救命索引让查询速度提升20倍

没有索引的开票系统就像没有导航的出租车——功能完整但永远找不到目的地。我们针对高频查询场景设计了三类索引：

1. 复合索引应对多条件筛选 ：财务人员最常查“某客户在某时间段内所有已开票未付款的发票”，对应SQL：

   SELECT * FROM invoices 
   WHERE client_id = ? AND status = 'issued' AND due_date < NOW();
   

   创建索引：

   CREATE INDEX idx_invoices_client_status_due ON invoices(client_id, status, due_date);
   

2. 函数索引解决模糊搜索痛点 ：客户名称常需拼音首字母搜索（如输“zhang”查“张三”），PostgreSQL支持函数索引：

   CREATE INDEX idx_clients_name_pinyin ON clients 
   USING gin (lower(name) gin_trgm_ops);
   

   配合pg_trgm扩展， WHERE lower(name) LIKE '%zhang%' 查询从2.3秒降至0.015秒。

3. 部分索引节省空间 ： invoice_items 表中95%的数据属于 status='issued' 的发票，为 draft 状态建索引纯属浪费。创建部分索引：

   CREATE INDEX idx_invoice_items_issued ON invoice_items(invoice_id) 
   WHERE invoice_id IN (SELECT id FROM invoices WHERE status = 'issued');
   

实操心得：上线前务必用 EXPLAIN ANALYZE 测试所有API对应的SQL。我们曾发现一个 GET /invoices?status=paid&sort=due_date 接口因缺少 status 字段索引，高峰期响应达8秒。加索引后稳定在42ms内。

3. API设计：用业务语义驱动路由，而非技术框架惯性

3.1 路由设计哲学：为什么放弃RESTful，选择动词优先的路径结构

当团队争论“ PUT /invoices/123 还是 PATCH /invoices/123/status ”时，我直接拿出财务总监的原始需求文档——她写的不是“更新资源状态”，而是“我要把这张发票标记为已收款”。RESTful的抽象在开票领域制造了认知鸿沟：前端工程师理解 PATCH ，但财务人员需要的是 POST /invoice/mark-paid 。我们最终采用业务动词路由，所有端点以 /invoice/ 开头，后接动作：

这种设计让前端调用像说人话：“我要开票”就调 /invoice/issue ，“我要打印”就调 /invoice/pdf/123 。更重要的是，它天然支持权限控制——财务专员有 /invoice/issue 权限，但无 /invoice/cancel 权限，比基于资源的RBAC更精准。

3.2 请求体设计：为什么用扁平化JSON而非嵌套对象

对比两种请求体设计：

嵌套式（常见但低效）：

{
  "invoice": {
    "client_id": 456,
    "issue_date": "2024-03-01",
    "items": [
      { "description": "服务器托管", "quantity": 1, "unit_price": 5000 }
    ]
  }
}

扁平式（我们采用）：

{
  "client_id": 456,
  "issue_date": "2024-03-01",
  "items": [
    { "description": "服务器托管", "quantity": 1, "unit_price": 5000 }
  ]
}

理由很实在：前端表单数据就是扁平的。用户在页面填“客户下拉框”、“开票日期选择器”、“商品明细表格”，JavaScript直接 FormData.entries() 就能转成扁平对象。嵌套式强迫前端做一次无意义的包装，后端再解包，徒增出错概率。我们统计过，嵌套式请求在测试环境出现 invoice.client_id is undefined 错误的概率是扁平式的3.7倍。

3.3 响应体标准化：为什么所有成功响应都包含 data 和 meta 字段

财务系统最怕“成功却没结果”。比如 POST /invoice/issue 返回200，但前端不知道新发票号是多少，只能再查一次。我们强制所有成功响应遵循同一结构：

{
  "success": true,
  "data": {
    "id": 123,
    "invoice_number": "INV-2024-SH-0001",
    "issue_date": "2024-03-01",
    "total_amount": 5650.00
  },
  "meta": {
    "timestamp": "2024-03-01T14:22:33+08:00",
    "version": "1.2"
  }
}

data 字段承载业务核心数据， meta 提供上下文信息。特别注意 timestamp ——它不是服务器当前时间，而是该操作在数据库事务提交完成后的精确时间戳，用 NOW() AT TIME ZONE 'Asia/Shanghai' 获取，确保财务审计时时间可追溯。

3.4 错误处理：为什么定义12个具体HTTP状态码而非笼统的400

财务操作容错率极低，模糊错误码会让问题排查变成猜谜游戏。我们为开票场景定制了12个错误码，每个对应明确修复动作：

实操心得：在Express中间件中统一处理错误，用 switch(error.code) 分发。曾有个客户反馈“开票失败但没提示”，查日志发现是 400 BAD_REQUEST 泛化错误。我们立即增加 VALIDATION_ERROR 子类型，现在所有校验失败都返回 422 UNPROCESSABLE_ENTITY 并附带具体字段名。

4. 核心功能实现：从数据库连接到PDF生成的全链路代码解析

4.1 数据库连接池配置：为什么 max 设为10而非默认的5

Node.js的单线程特性决定了数据库连接池是性能瓶颈关键。PostgreSQL官方推荐连接数公式： max_connections = (CPU核心数 × 2) + effective_cache_size 。但我们实测发现，盲目提高 max 值反而降低性能——连接建立/销毁开销超过复用收益。通过 pgBench 压测不同配置：

结论： max: 10 是最佳平衡点。配置代码如下：

const { Pool } = require('pg');

const pool = new Pool({
  host: process.env.DB_HOST || 'localhost',
  port: process.env.DB_PORT || 5432,
  database: process.env.DB_NAME || 'invoicing',
  user: process.env.DB_USER || 'app',
  password: process.env.DB_PASSWORD || 'secret',
  max: 10, // 关键参数
  min: 2,   // 最小连接数，避免冷启动延迟
  idleTimeoutMillis: 30000, // 空闲30秒释放
  connectionTimeoutMillis: 2000, // 连接超时2秒
  ssl: process.env.NODE_ENV === 'production' ? { rejectUnauthorized: false } : false
});

// 连接健康检查
pool.on('error', (err) => {
  console.error('Unexpected error on idle client', err);
  process.exit(-1);
});

注意：生产环境必须配置 ssl: { rejectUnauthorized: false } ，否则PostgreSQL 12+会拒绝非SSL连接。但 rejectUnauthorized: false 存在中间人攻击风险，实际部署时应替换为公司CA证书路径。

4.2 发票生成核心逻辑：如何用事务保证金额计算绝对准确

开票最核心的逻辑不是CRUD，而是 金额计算的原子性 。 invoice_items 的 line_total 必须等于 quantity * unit_price * (1 + tax_rate) ，且总金额必须与各明细行之和严格相等。我们用PostgreSQL的 SERIALIZABLE 隔离级别+应用层校验双保险：

// services/invoiceService.js
async function generateInvoice(clientId, items, issueDate, dueDate) {
  const client = await getClientById(clientId);
  
  // 1. 开启事务
  const client = await pool.connect();
  try {
    await client.query('BEGIN TRANSACTION ISOLATION LEVEL SERIALIZABLE');
    
    // 2. 插入主表
    const invoiceRes = await client.query(
      'INSERT INTO invoices (client_id, issue_date, due_date, status) VALUES ($1, $2, $3, $4) RETURNING id',
      [clientId, issueDate, dueDate, 'draft']
    );
    const invoiceId = invoiceRes.rows[0].id;
    
    // 3. 批量插入明细（关键：预计算所有金额）
    const itemValues = items.map((item, index) => [
      invoiceId,
      item.description,
      item.quantity,
      item.unit_price,
      item.tax_rate,
      // 精确计算：避免JS浮点误差
      Math.round(item.quantity * item.unit_price * item.tax_rate * 100) / 100,
      Math.round(item.quantity * item.unit_price * (1 + item.tax_rate) * 100) / 100,
      index
    ]);
    
    const valuesPlaceholder = itemValues.map((_, i) => `($${i * 7 + 1}, $${i * 7 + 2}, ...)`).join(', ');
    await client.query(
      `INSERT INTO invoice_items (invoice_id, description, quantity, unit_price, tax_rate, tax_amount, line_total, sort_order) VALUES ${valuesPlaceholder}`,
      itemValues.flat()
    );
    
    // 4. 应用层二次校验（防数据库计算异常）
    const totalCheck = await client.query(
      'SELECT SUM(line_total) as total FROM invoice_items WHERE invoice_id = $1',
      [invoiceId]
    );
    if (Math.abs(totalCheck.rows[0].total - expectedTotal) > 0.01) {
      throw new Error('金额校验失败：明细合计与预期不符');
    }
    
    await client.query('COMMIT');
    return { success: true, invoiceId };
    
  } catch (err) {
    await client.query('ROLLBACK');
    throw err;
  } finally {
    client.release();
  }
}

实操心得： Math.round(x * 100) / 100 是财务计算的黄金法则。我们曾用 parseFloat((a * b).toFixed(2)) 导致0.01元误差，客户拒付整张发票。现在所有金额运算强制走此模式。

4.3 PDF生成方案：为什么放弃Puppeteer选择pdfmake

Puppeteer生成PDF看似强大，但在开票场景有三大硬伤：1）内存占用大（单次渲染峰值300MB）；2）启动慢（首次加载Chromium需8秒）；3）字体嵌入复杂（中文需手动加载 .ttf ）。pdfmake是纯JS库，体积仅120KB，渲染10页发票平均耗时320ms，内存占用<15MB。

核心模板代码：

// utils/pdfGenerator.js
const pdfMake = require('pdfmake');
const fonts = {
  Roboto: {
    normal: 'fonts/Roboto-Regular.ttf',
    bold: 'fonts/Roboto-Medium.ttf',
    italics: 'fonts/Roboto-Italic.ttf',
    bolditalics: 'fonts/Roboto-MediumItalic.ttf'
  }
};
const printer = new pdfMake(fonts);

function generateInvoicePDF(invoiceData) {
  const docDefinition = {
    pageSize: 'A4',
    pageMargins: [40, 60, 40, 60],
    header: {
      columns: [
        { text: '上海某某科技有限公司', fontSize: 16, bold: true },
        { text: `发票号：${invoiceData.invoice_number}`, alignment: 'right' }
      ],
      margin: [0, 20, 0, 20]
    },
    content: [
      // 客户信息区块
      {
        layout: 'noBorders',
        table: {
          widths: ['*', '*'],
          body: [
            [{ text: '客户名称：' + invoiceData.client.name }, { text: '开票日期：' + invoiceData.issue_date }],
            [{ text: '税号：' + (invoiceData.client.tax_id || '—') }, { text: '付款截止：' + invoiceData.due_date }]
          ]
        }
      },
      // 商品明细表（关键：金额右对齐）
      {
        table: {
          headerRows: 1,
          widths: [120, '*', 60, 60, 80],
          body: [
            ['商品描述', '数量', '单价', '税率', '金额'],
            ...invoiceData.items.map(item => [
              { text: item.description, style: 'itemDesc' },
              { text: item.quantity, alignment: 'center' },
              { text: `¥${item.unit_price}`, alignment: 'right' },
              { text: `${item.tax_rate * 100}%`, alignment: 'center' },
              { text: `¥${item.line_total}`, alignment: 'right' }
            ])
          ]
        }
      }
    ],
    styles: {
      itemDesc: { fontSize: 10, lineHeight: 1.2 }
    }
  };

  return printer.createPdfKitDocument(docDefinition);
}

module.exports = { generateInvoicePDF };

注意： pdfmake 的 table.widths 必须显式指定，否则中文列宽会崩塌。我们测试过 * 自适应在多语言混合时失效，最终采用固定像素宽度+ textWrap: { charWrap: true } 保底。

4.4 API安全加固：为什么JWT令牌必须包含 scope 字段且校验粒度到按钮级

开票系统不是博客，一个越权访问可能造成百万损失。我们不用简单的 role: 'admin' ，而是为每个用户分配细粒度 scope 数组：

{
  "user_id": 123,
  "scopes": ["invoice:read", "invoice:issue", "invoice:cancel", "client:write"]
}

路由守卫中间件：

function requireScope(requiredScope) {
  return (req, res, next) => {
    const token = req.headers.authorization?.split(' ')[1];
    if (!token) return res.status(401).json({ error: 'MISSING_TOKEN' });
    
    try {
      const payload = jwt.verify(token, process.env.JWT_SECRET);
      if (!payload.scopes?.includes(requiredScope)) {
        return res.status(403).json({ error: 'INSUFFICIENT_SCOPE', required: requiredScope });
      }
      req.user = payload;
      next();
    } catch (err) {
      res.status(401).json({ error: 'INVALID_TOKEN' });
    }
  };
}

// 使用示例
router.post('/invoice/issue', requireScope('invoice:issue'), issueInvoiceHandler);
router.patch('/invoice/cancel/:id', requireScope('invoice:cancel'), cancelInvoiceHandler);

实操心得： scope 必须在登录时由后端生成，禁止前端传入。我们曾发现某客户前端代码泄露 scope 生成逻辑，攻击者伪造token获得 invoice:cancel 权限。现在所有scope均由RBAC系统动态计算，JWT只作为传输载体。

5. 部署与运维：从本地开发到生产环境的平滑过渡

5.1 环境配置管理：为什么用 .env.local 而非 process.env.NODE_ENV

NODE_ENV=production 只是告诉Express启用缓存，对数据库连接、API密钥等无实质影响。我们采用四层环境配置：

加载逻辑（ config/index.js ）：

require('dotenv').config({ path: `.env.${process.env.NODE_ENV || 'development'}` });
require('dotenv').config({ path: '.env.default', override: true });

module.exports = {
  db: {
    host: process.env.DB_HOST,
    port: parseInt(process.env.DB_PORT),
    database: process.env.DB_NAME,
    user: process.env.DB_USER,
    password: process.env.DB_PASSWORD
  },
  jwt: {
    secret: process.env.JWT_SECRET,
    expiresIn: '24h'
  }
};

提示： override: true 确保 .env.default 能覆盖其他文件的缺失值，避免 undefined 错误。

5.2 日志规范：为什么用Pino而非Console.log，且必须包含 invoice_id

财务操作日志不是为了debug，而是为了审计。 console.log('Invoice issued') 在审计时毫无价值。Pino的结构化日志可直接对接ELK：

const pino = require('pino');
const logger = pino({
  level: process.env.LOG_LEVEL || 'info',
  transport: {
    target: 'pino-pretty',
    options: { colorize: true }
  }
});

// 在API路由中
app.post('/invoice/issue', async (req, res) => {
  try {
    const result = await issueInvoice(req.body);
    logger.info({
      event: 'INVOICE_ISSUED',
      invoice_id: result.invoiceId,
      client_id: req.body.client_id,
      user_id: req.user.id,
      amount: result.total_amount
    }, 'Invoice issued successfully');
    res.json({ success: true, data: result });
  } catch (err) {
    logger.error({
      event: 'INVOICE_ISSUE_FAILED',
      invoice_id: req.body.invoice_id || 'N/A',
      error_code: err.code || 'UNKNOWN',
      stack: err.stack
    }, 'Failed to issue invoice');
    res.status(500).json({ error: err.message });
  }
});

实操心得：所有日志必须包含 event 字段，便于ELK中用 event:INVOICE_ISSUED 快速过滤。我们曾用 grep 查日志，10分钟找不到问题，改用Kibana后30秒定位。

5.3 健康检查端点：为什么 /health 必须检查数据库连接而非仅进程存活

K8s的liveness probe若只检查 200 OK ，会导致“服务活着但数据库挂了”的假象。我们的 /health 端点执行真实数据库查询：

app.get('/health', async (req, res) => {
  try {
    // 执行轻量查询，不涉及业务表
    await pool.query('SELECT 1');
    res.json({ 
      status: 'ok', 
      timestamp: new Date().toISOString(),
      uptime: process.uptime()
    });
  } catch (err) {
    res.status(503).json({ 
      status: 'unavailable', 
      error: 'Database connection failed',
      timestamp: new Date().toISOString()
    });
  }
});

注意：生产环境Nginx需配置 proxy_read_timeout 10 ，避免健康检查超时被误判。

5.4 监控告警：为什么用Prometheus暴露 invoice_created_total 指标

财务系统监控不是看CPU，而是看业务指标。我们用 prom-client 暴露关键计数器：

const client = require('prom-client');
const collectDefaultMetrics = client.collectDefaultMetrics;

// 创建自定义指标
const invoiceCreatedTotal = new client.Counter({
  name: 'invoice_created_total',
  help: 'Total number of invoices created',
  labelNames: ['status', 'currency'] // 按状态和币种维度
});

// 在开票成功后
invoiceCreatedTotal.labels({ status: 'issued', currency: 'CNY' }).inc();

// 暴露指标端点
app.get('/metrics', async (req, res) => {
  res.set('Content-Type', client.register.contentType);
  res.end(await client.register.metrics());
});

Grafana看板配置：当 rate(invoice_created_total{status="issued"}[1h]) < 5 持续10分钟，触发企业微信告警——这意味着开票服务可能卡死，而非单纯流量下降。

实操心得：指标命名必须带 _total 后缀，这是Prometheus规范。我们曾因命名 invoice_created 导致Grafana无法计算 rate() ，排查3小时才发现是命名问题。

6. 常见问题与排查技巧实录：来自23个生产环境的真实案例

6.1 问题速查表：高频故障现象与根因分析

6.2 数据库连接泄漏排查：如何用 pg_stat_activity 定位泄漏点

连接泄漏是Node开票系统的头号杀手。当 SHOW DATABASES 显示连接数持续增长，执行：

-- 查看所有活动连接及对应应用名
SELECT pid, application_name, client_addr, backend_start, state, query 
FROM pg_stat_activity 
WHERE state = 'active' OR state = 'idle in transaction'
ORDER BY backend_start DESC 
LIMIT 10;

典型泄漏场景：忘记 client.release() 。我们在 invoiceService.js 中强制要求所有数据库操作必须包裹在 try/finally 中：

async function getInvoice(id) {
  const client = await pool.connect(); // 获取连接
  try {
    const res = await client.query('SELECT * FROM invoices WHERE id = $1', [id]);
    return res.rows[0];
  } finally {
    client.release(); // 关键！必须释放
  }
}

提示：在 pool.on('connect') 中打日志，记录每次连接获取时间，配合 pg_stat_activity 可精确定位泄漏代码行。

6.3 PDF渲染空白页：字体路径与跨域的双重陷阱

pdfmake 渲染空白页90%是字体问题。排查步骤：

1. 检查字体文件路径 ： fonts/Roboto-Regular.ttf 必须相对于 node_modules/pdfmake/ 目录，而非项目根目录。正确路径应为 ./node_modules/pdfmake/fonts/Roboto-Regular.ttf 。

2. 验证字体加载 ：在 pdfGenerator.js 中添加调试：

   console.log('Font path:', require('path').resolve(__dirname, '../fonts/Roboto-Regular.ttf'));
   

3. Nginx跨域配置 ：若PDF通过CDN分发，需在Nginx中添加：

   location ~* \.(ttf|woff|woff2|eot)$ {
     add_header Access-Control-Allow-Origin "*";
     add_header Access-Control-Allow-Methods "GET, POST, OPTIONS";
   }
   

6.4 JWT令牌失效：时钟不同步导致 exp 验证失败

服务器时间与客户端时间偏差超过 clockTolerance （默认60秒）时， jwt.verify() 会抛 token expired 。解决方案：

1. 服务端校准时间 ： sudo ntpdate -s time.nist.gov
2. JWT验证时放宽容错 ：

   jwt.verify(token, secret, { clockTolerance: 120 }); // 容忍2分钟
   

3. 前端同步时间 ：在登录后调用 /api/time 获取服务器时间，校准本地时钟。

实操心得：我们给所有JWT添加 iat （issued at）字段，前端可计算 Date.now() - iat 判断本地时钟偏差，偏差>30秒时提示用户校准。

6.5 索引失效导致慢查询：如何用 EXPLAIN ANALYZE 定位

当`GET /invoices?client_id=4