使用 Drizzle ORM 和 NestJS 构建 API：完整指南

Drizzle ORM 已成为增长最快的 TypeScript ORM，提供类似 SQL 的语法，具有完整的类型安全性和零运行时开销。 与 NestJS 结合，它创建了一个强大的堆栈，用于构建开发人员友好且高性能的生产 API。

要点

• Drizzle 提供类似 SQL 的查询以及完整的 TypeScript 推理——无需代码生成步骤
• NestJS 依赖注入与 Drizzle 数据库连接干净地集成
• 模式驱动的开发确保数据库和 TypeScript 类型保持同步
• Drizzle 推送和迁移命令无需停机即可处理架构演变

---

项目设置

安装

从 NestJS 项目开始并添加 Drizzle 依赖项：

npm install drizzle-orm postgres
npm install -D drizzle-kit @types/pg

我们推荐使用 postgres.js 驱动程序，因为它的性能优异。对于生产中的连接池，请考虑 PgBouncer 或无服务器优化驱动程序。

数据库连接模块

创建一个全局数据库模块，通过依赖注入提供 Drizzle 实例。使用 useFactory 定义 DB_TOKEN 提供程序，该提供程序从 DATABASE_URL 创建 postgres 客户端并返回 drizzle(client, \\\\\\\\{ schema \\\\\\\\})。导出令牌，以便任何服务都可以使用 @Inject("DRIZZLE_DB") 注入它。

---

模式定义

使用 Drizzle 表构建器定义数据库表。每个表导出一个使用 pgTable() 创建的 const，其中包含使用 uuid、varchar、timestamp、boolean 和其他列类型的列定义。列支持默认值（defaultRandom、defaultNow）、约束（notNull、unique）和关系。

定义关系

Drizzle 关系提供类型安全的预加载。使用relations()函数定义关系，用many()指定一对多，用one()指定多对一。引用列将外键映射到其父表主键。

---

查询构建

选择查询

Drizzle 查询像 SQL 一样读取，同时提供完整的类型推断：

• 简单选择：db.select().from(users)
• 过滤：db.select().from(users).where(and(eq(users.role, "admin"), eq(users.isActive, true)))
• 使用连接： db.select().from(users).leftJoin(orders, eq(users.id,orders.userId))
• 关系加载：db.query.users.findMany(\\\\\\\\{ with: {orders: true \\\\\\\\}, limit: 20 })

插入、更新、删除

// Insert with returning
const [newUser] = await this.db
  .insert(users)
  .values({ email: "[email protected]", name: "New User" })
  .returning();

// Update
await this.db
  .update(users)
  .set({ role: "admin", updatedAt: new Date() })
  .where(eq(users.id, userId));

// Delete
await this.db.delete(users).where(eq(users.id, userId));

---

交易

Drizzle 事务确保原子操作。使用接收事务对象 (tx) 的异步回调调用 db.transaction()。回调中的所有查询均以原子方式执行——如果有任何查询失败，则整个事务将回滚。

常见用例包括一起创建父记录和子记录、在处理订单时更新库存以及在帐户之间转移资金。

---

迁移

架构推送（开发）

在开发过程中，直接使用 drizzle-kit 推送来推送模式更改。这会将您的架构文件与数据库进行比较并应用更改。开发速度快，但不适合生产。

迁移文件（生产）

对于生产，使用 drizzle-kit generated 生成版本化的 SQL 迁移文件，然后使用 drizzle-kit migrate 应用它们。迁移文件可以在分段中进行审查、测试，并在 CI/CD 管道中应用。

---

NestJS 集成模式

服务模式

服务注入 Drizzle 数据库并使用动态过滤器构建查询：

@Injectable()
export class ProductsService {
  constructor(@Inject("DRIZZLE_DB") private db: DrizzleDB) {}

  async findAll(filters: ProductFilters) {
    const conditions = [];
    if (filters.category)
      conditions.push(eq(products.category, filters.category));
    if (filters.minPrice)
      conditions.push(gte(products.price, filters.minPrice));

    return this.db
      .select()
      .from(products)
      .where(conditions.length ? and(...conditions) : undefined)
      .orderBy(desc(products.createdAt))
      .limit(filters.limit || 20)
      .offset(filters.offset || 0);
  }
}

多租户

对于 SaaS 应用程序，每个查询都必须按organizationId 进行过滤。创建基础服务或中间件，确保所有数据库操作的租户隔离。切勿信任客户端提供的组织 ID——根据经过身份验证的会话进行验证。

参数化查询

Drizzle 默认使用参数化查询，防止 SQL 注入。切勿将 sql.raw() 与用户输入一起使用。相反，请使用 sql 模板文字，它会自动参数化插值。

---

性能最佳实践

1. 仅选择需要的列：使用 .select(\\\\\\\\{ id: users.id, name: users.name \\\\\\\\}) 而不是选择所有列
2. 使用索引：确保经常过滤的列有数据库索引
3. 限制结果：在列表查询上始终使用 .limit()
4. 批量插入：使用 .values([...array]) 进行批量插入而不是循环
5. 连接池：为您的工作负载配置适当的池大小
6. 惰性连接：使用代理模式将连接推迟到第一次查询

---

常见问题

问：Drizzle 与 NestJS 的 Prisma 相比如何？

Drizzle 更面向 SQL，并且运行时开销为零（无查询引擎）。 Prisma 使用自己的查询语言并需要生成的客户端。 Drizzle 具有更小的捆绑包尺寸和更快的冷启动速度，而 Prisma 则拥有更大的生态系统和更多的工具。

问：Drizzle 可以处理复杂的原始 SQL 吗？

是的。 SQL 模板文字支持原始查询，同时保持参数化安全性。 Drizzle 从不使用字符串连接进行查询，从而防止 SQL 注入。

问：生产中的连接池怎么样？

使用应用程序外部的 PgBouncer 或使用最大连接限制配置 postgres.js 驱动程序。对于无服务器环境，请使用具有内置池的无服务器优化驱动程序。

问：我们如何在不停机的情况下处理架构更改？

生成迁移文件，检查 SQL，在暂存中进行测试，然后在生产中应用。 PostgreSQL 中的大多数 ALTER TABLE 语句在执行时没有排它锁。避免在高峰时段进行需要重写表的操作。

---

下一步是什么

Drizzle ORM 与 NestJS 为构建生产 API 提供了类型安全、高性能的基础。类似 SQL 的 API 最大限度地减少了抽象差距，而 TypeScript 推理则消除了运行时类型错误。

联系 ECOSIRE 获取 API 开发帮助，或探索我们的 Odoo 集成服务 将自定义 API 与您的 ERP 连接。

---

由 ECOSIRE 发布——帮助企业利用企业软件解决方案进行扩展。