Drizzle ORM 集成

本示例展示如何将 Drizzle ORM 集成到 VextJS 项目中，通过编写一个数据库插件实现类型安全的数据库操作。

为什么选择 Drizzle ORM？

特性	说明
类型安全	Schema 即类型，查询结果自动推断 TypeScript 类型
轻量	无运行时代码生成，零抽象开销
SQL-like	API 贴近 SQL 语法，学习成本低
多数据库	支持 PostgreSQL、MySQL、SQLite
迁移工具	内置 `drizzle-kit` 进行 schema 迁移
性能	无额外查询层，直接编译为 SQL

项目结构

drizzle-orm/
  ├── src/
  │   ├── config/
  │   │   ├── default.ts
  │   │   └── production.ts
  │   ├── db/
  │   │   ├── schema.ts              ← Drizzle schema 定义
  │   │   ├── index.ts               ← 数据库连接工厂
  │   │   └── migrate.ts             ← 迁移脚本
  │   ├── plugins/
  │   │   └── database.ts            ← 数据库插件
  │   ├── routes/
  │   │   ├── index.ts
  │   │   └── users.ts
  │   ├── services/
  │   │   └── user.ts
  │   └── index.ts
  ├── drizzle/                        ← 迁移文件（drizzle-kit 生成）
  ├── drizzle.config.ts               ← drizzle-kit 配置
  ├── package.json
  └── tsconfig.json

1. 安装依赖

本示例使用 SQLite（通过 better-sqlite3）作为演示数据库。生产环境中可替换为 PostgreSQL 或 MySQL。

npx vextjs create drizzle-orm-demo
cd drizzle-orm-demo

# Drizzle ORM + SQLite 驱动
pnpm add drizzle-orm better-sqlite3

# 开发依赖
pnpm add -D drizzle-kit @types/better-sqlite3

Tip

其他数据库驱动：

PostgreSQL：pnpm add drizzle-orm postgres 或 pnpm add drizzle-orm @neondatabase/serverless
MySQL：pnpm add drizzle-orm mysql2

更换驱动后只需修改 src/db/index.ts 中的连接逻辑和 src/db/schema.ts 中的表定义导入路径，业务代码几乎无需改动。

2. 数据库 Schema

使用 Drizzle 的 TypeScript-first schema 定义表结构。Schema 既是数据库表定义，也是 TypeScript 类型的来源。

// src/db/schema.ts
import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';
import { sql } from 'drizzle-orm';

// ── 用户表 ──────────────────────────────────────────────────

export const users = sqliteTable('users', {
  id: integer('id').primaryKey({ autoIncrement: true }),
  name: text('name').notNull(),
  email: text('email').notNull().unique(),
  age: integer('age'),
  role: text('role', { enum: ['admin', 'user', 'editor'] })
    .notNull()
    .default('user'),
  bio: text('bio'),
  avatarUrl: text('avatar_url'),
  createdAt: text('created_at')
    .notNull()
    .default(sql`(datetime('now'))`),
  updatedAt: text('updated_at')
    .notNull()
    .default(sql`(datetime('now'))`),
});

// ── 文章表（演示关联查询）──────────────────────────────────

export const posts = sqliteTable('posts', {
  id: integer('id').primaryKey({ autoIncrement: true }),
  title: text('title').notNull(),
  content: text('content').notNull(),
  authorId: integer('author_id')
    .notNull()
    .references(() => users.id, { onDelete: 'cascade' }),
  published: integer('published', { mode: 'boolean' })
    .notNull()
    .default(false),
  createdAt: text('created_at')
    .notNull()
    .default(sql`(datetime('now'))`),
  updatedAt: text('updated_at')
    .notNull()
    .default(sql`(datetime('now'))`),
});

// ── 导出推断类型 ────────────────────────────────────────────

/** 用户完整类型（查询结果） */
export type User = typeof users.$inferSelect;

/** 用户插入类型（创建时使用） */
export type NewUser = typeof users.$inferInsert;

/** 文章完整类型 */
export type Post = typeof posts.$inferSelect;

/** 文章插入类型 */
export type NewPost = typeof posts.$inferInsert;

Tip

Drizzle 的 $inferSelect 和 $inferInsert 类型工具非常强大：

$inferSelect — 从表定义推断查询结果类型（包含所有字段，id、createdAt 等为必填）
$inferInsert — 从表定义推断插入类型（有默认值的字段变为可选，如 role、createdAt）

这些类型可以直接用于服务层的参数和返回值声明，无需手动维护接口定义。

3. 数据库连接工厂

// src/db/index.ts
import { drizzle } from 'drizzle-orm/better-sqlite3';
import Database from 'better-sqlite3';
import * as schema from './schema.js';

export interface DatabaseConfig {
  /** SQLite 数据库文件路径 */
  url: string;
  /** 是否开启 WAL 模式（Write-Ahead Logging，提升并发性能） */
  wal?: boolean;
  /** 是否在连接时自动创建表（开发环境用） */
  autoCreate?: boolean;
}

/**
 * 创建 Drizzle ORM 数据库实例
 *
 * @param config 数据库配置
 * @returns { db, client }
 *   - db: Drizzle ORM 实例（用于查询）
 *   - client: better-sqlite3 原始客户端（用于关闭连接）
 */
export function createDatabase(config: DatabaseConfig) {
  const client = new Database(config.url);

  // WAL 模式：提升并发读写性能
  if (config.wal !== false) {
    client.pragma('journal_mode = WAL');
  }

  // 启用外键约束
  client.pragma('foreign_keys = ON');

  const db = drizzle(client, { schema });

  // 开发环境自动创建表
  if (config.autoCreate) {
    client.exec(`
      CREATE TABLE IF NOT EXISTS users (
        id INTEGER PRIMARY KEY AUTOINCREMENT,
        name TEXT NOT NULL,
        email TEXT NOT NULL UNIQUE,
        age INTEGER,
        role TEXT NOT NULL DEFAULT 'user',
        bio TEXT,
        avatar_url TEXT,
        created_at TEXT NOT NULL DEFAULT (datetime('now')),
        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
      );

      CREATE TABLE IF NOT EXISTS posts (
        id INTEGER PRIMARY KEY AUTOINCREMENT,
        title TEXT NOT NULL,
        content TEXT NOT NULL,
        author_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
        published INTEGER NOT NULL DEFAULT 0,
        created_at TEXT NOT NULL DEFAULT (datetime('now')),
        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
      );
    `);
  }

  return { db, client };
}

/** Drizzle DB 实例类型 */
export type DrizzleDB = ReturnType<typeof createDatabase>['db'];

Warning

生产环境中不要使用 autoCreate: true。应该使用 drizzle-kit 迁移工具管理数据库结构变更。autoCreate 仅用于快速开发和演示。

4. 数据库迁移配置

// drizzle.config.ts
import { defineConfig } from 'drizzle-kit';

export default defineConfig({
  schema: './src/db/schema.ts',
  out: './drizzle',
  dialect: 'sqlite',
  dbCredentials: {
    url: process.env.DATABASE_URL ?? './data/app.db',
  },
});

迁移命令：

# 生成迁移文件
pnpm drizzle-kit generate

# 执行迁移
pnpm drizzle-kit migrate

# 打开 Drizzle Studio（可视化数据库管理）
pnpm drizzle-kit studio

5. 数据库插件

// src/plugins/database.ts
import { definePlugin } from 'vextjs';
import { createDatabase } from '../db/index.js';
import type { DrizzleDB } from '../db/index.js';
import { users, posts } from '../db/schema.js';

export default definePlugin({
  name: 'database',
  async setup(app) {
    const dbConfig = (app.config as any).database ?? {
      url: './data/app.db',
      wal: true,
      autoCreate: true,
    };

    app.logger.info({ url: dbConfig.url }, '正在连接数据库...');

    const { db, client } = createDatabase(dbConfig);

    // 挂载到 app
    app.extend('db', db);

    // 就绪钩子：验证连接 + 填充种子数据
    app.onReady(async () => {
      try {
        // 验证连接
        client.pragma('quick_check');
        app.logger.info('数据库连接验证成功');

        // 检查是否需要种子数据
        const userCount = db.select().from(users).all();
        if (userCount.length === 0) {
          app.logger.info('数据库为空，正在填充种子数据...');
          await seedDatabase(db);
          app.logger.info('种子数据填充完成');
        }
      } catch (err) {
        app.logger.error({ error: err }, '数据库初始化失败');
        throw err;
      }
    });

    // 关闭钩子：断开连接
    app.onClose(() => {
      client.close();
      app.logger.info('数据库连接已关闭');
    });
  },
});

/**
 * 填充种子数据（仅在数据库为空时执行）
 */
async function seedDatabase(db: DrizzleDB): Promise<void> {
  // 插入用户
  const insertedUsers = db
    .insert(users)
    .values([
      {
        name: 'Alice',
        email: 'alice@example.com',
        age: 28,
        role: 'admin',
        bio: '全栈开发者，热爱开源',
      },
      {
        name: 'Bob',
        email: 'bob@example.com',
        age: 32,
        role: 'user',
        bio: '前端工程师',
      },
      {
        name: 'Charlie',
        email: 'charlie@example.com',
        age: 25,
        role: 'editor',
        bio: '技术博客作者',
      },
    ])
    .returning()
    .all();

  // 插入文章
  db.insert(posts)
    .values([
      {
        title: 'VextJS 入门指南',
        content: '本文介绍如何使用 VextJS 构建高性能 RESTful API...',
        authorId: insertedUsers[0].id,
        published: true,
      },
      {
        title: 'Drizzle ORM 最佳实践',
        content: '探索 Drizzle ORM 的高级查询技巧...',
        authorId: insertedUsers[0].id,
        published: true,
      },
      {
        title: 'TypeScript 类型体操',
        content: '深入理解 TypeScript 的高级类型系统...',
        authorId: insertedUsers[2].id,
        published: false,
      },
    ])
    .run();
}

为 app.db 添加类型声明：

// types/vext.d.ts
import type { DrizzleDB } from '../src/db/index.js';

declare module 'vextjs' {
  interface VextApp {
    db: DrizzleDB;
  }

  interface VextConfig {
    database?: {
      url: string;
      wal?: boolean;
      autoCreate?: boolean;
    };
  }

  interface VextRequest {
    user?: {
      id: string;
      role: string;
    };
  }
}

6. 配置

// src/config/default.ts
export default {
  port: 3000,
  adapter: 'native',
  logger: {
    level: 'debug',
    pretty: true,
  },
  cors: {
    enabled: true,
    origins: ['*'],
  },
  response: {
    wrap: true,
    hideInternalErrors: false,
  },
  openapi: {
    enabled: true,
    title: 'Drizzle ORM 示例',
    version: '1.0.0',
    description: '使用 Drizzle ORM 集成的 VextJS RESTful API',
    tags: [
      { name: '基础', description: '基础接口' },
      { name: '用户', description: '用户管理接口' },
      { name: '文章', description: '文章管理接口' },
    ],
    securitySchemes: {
      bearerAuth: {
        type: 'http',
        scheme: 'bearer',
        bearerFormat: 'JWT',
      },
    },
    guardSecurityMap: {
      auth: 'bearerAuth',
    },
  },
  middlewares: [
    { name: 'auth' },
  ],
  // 数据库配置
  database: {
    url: './data/app.db',
    wal: true,
    autoCreate: true,
  },
};

// src/config/production.ts
export default {
  logger: {
    level: 'info',
    pretty: false,
  },
  response: {
    hideInternalErrors: true,
  },
  openapi: {
    enabled: false,
  },
  database: {
    url: process.env.DATABASE_URL ?? './data/production.db',
    autoCreate: false, // 生产环境使用迁移
  },
};

7. 服务层

// src/services/user.ts
import type { VextApp, VextLogger } from 'vextjs';
import { users, posts } from '../db/schema.js';
import type { User, NewUser } from '../db/schema.js';
import { eq, like, or, sql, desc, asc, count } from 'drizzle-orm';

export default class UserService {
  private logger: VextLogger;

  constructor(private app: VextApp) {
    this.logger = app.logger.child({ service: 'UserService' });
  }

  /**
   * 分页查询用户列表
   *
   * 支持关键词搜索（按 name 或 email 模糊匹配）和排序。
   */
  async findAll(options: {
    page: number;
    limit: number;
    keyword?: string;
    sortBy?: 'name' | 'createdAt';
    sortOrder?: 'asc' | 'desc';
  }): Promise<{
    items: User[];
    total: number;
    page: number;
    limit: number;
    totalPages: number;
  }> {
    this.logger.debug(options, '查询用户列表');

    const db = this.app.db;
    const offset = (options.page - 1) * options.limit;

    // 构建 WHERE 条件
    const whereCondition = options.keyword
      ? or(
          like(users.name, `%${options.keyword}%`),
          like(users.email, `%${options.keyword}%`),
        )
      : undefined;

    // 构建排序
    const orderBy =
      options.sortBy === 'name'
        ? options.sortOrder === 'desc'
          ? desc(users.name)
          : asc(users.name)
        : options.sortOrder === 'asc'
          ? asc(users.createdAt)
          : desc(users.createdAt);

    // 查询数据
    const items = db
      .select()
      .from(users)
      .where(whereCondition)
      .orderBy(orderBy)
      .limit(options.limit)
      .offset(offset)
      .all();

    // 查询总数
    const [{ total }] = db
      .select({ total: count() })
      .from(users)
      .where(whereCondition)
      .all();

    return {
      items,
      total,
      page: options.page,
      limit: options.limit,
      totalPages: Math.ceil(total / options.limit),
    };
  }

  /**
   * 根据 ID 查询用户（含文章列表）
   */
  async findById(id: number): Promise<(User & { posts: any[] }) | null> {
    this.logger.debug({ userId: id }, '查询用户详情');

    const db = this.app.db;

    const user = db.select().from(users).where(eq(users.id, id)).get();

    if (!user) return null;

    // 查询该用户的文章
    const userPosts = db
      .select()
      .from(posts)
      .where(eq(posts.authorId, id))
      .orderBy(desc(posts.createdAt))
      .all();

    return {
      ...user,
      posts: userPosts,
    };
  }

  /**
   * 创建用户
   */
  async create(data: {
    name: string;
    email: string;
    age?: number;
    role?: 'admin' | 'user' | 'editor';
    bio?: string;
    avatarUrl?: string;
  }): Promise<User> {
    this.logger.info({ email: data.email }, '创建用户');

    const db = this.app.db;

    // 检查邮箱唯一性
    const existing = db
      .select({ id: users.id })
      .from(users)
      .where(eq(users.email, data.email))
      .get();

    if (existing) {
      this.app.throw(409, '邮箱已注册', 10001);
    }

    // 插入并返回完整记录
    const user = db
      .insert(users)
      .values({
        name: data.name,
        email: data.email,
        age: data.age,
        role: data.role ?? 'user',
        bio: data.bio,
        avatarUrl: data.avatarUrl,
      })
      .returning()
      .get();

    this.logger.info({ userId: user.id, email: user.email }, '用户创建成功');

    return user;
  }

  /**
   * 更新用户
   */
  async update(
    id: number,
    data: {
      name?: string;
      email?: string;
      age?: number;
      bio?: string;
      avatarUrl?: string;
    },
  ): Promise<User> {
    this.logger.info({ userId: id }, '更新用户');

    const db = this.app.db;

    // 检查用户是否存在
    const existing = db.select().from(users).where(eq(users.id, id)).get();
    if (!existing) {
      this.app.throw(404, '用户不存在');
    }

    // 如果更新邮箱，检查唯一性
    if (data.email && data.email !== existing.email) {
      const emailTaken = db
        .select({ id: users.id })
        .from(users)
        .where(eq(users.email, data.email))
        .get();

      if (emailTaken) {
        this.app.throw(409, '邮箱已被其他用户使用', 10002);
      }
    }

    // 更新记录
    const updated = db
      .update(users)
      .set({
        ...data,
        updatedAt: sql`datetime('now')`,
      })
      .where(eq(users.id, id))
      .returning()
      .get();

    this.logger.info({ userId: id }, '用户更新成功');

    return updated;
  }

  /**
   * 删除用户
   *
   * 由于设置了 ON DELETE CASCADE，关联的文章会自动删除。
   */
  async delete(id: number): Promise<void> {
    this.logger.info({ userId: id }, '删除用户');

    const db = this.app.db;

    const existing = db
      .select({ id: users.id })
      .from(users)
      .where(eq(users.id, id))
      .get();

    if (!existing) {
      this.app.throw(404, '用户不存在');
    }

    db.delete(users).where(eq(users.id, id)).run();

    this.logger.info({ userId: id }, '用户删除成功');
  }

  /**
   * 统计用户数量
   */
  async count(): Promise<number> {
    const [{ total }] = this.app.db
      .select({ total: count() })
      .from(users)
      .all();

    return total;
  }
}

8. 路由

根路由

// src/routes/index.ts
import { defineRoutes } from 'vextjs';

export default defineRoutes((app) => {
  app.get('/', {
    docs: {
      summary: '健康检查',
      tags: ['基础'],
    },
  }, async (_req, res) => {
    const userCount = await app.services.user.count();
    res.json({
      status: 'ok',
      uptime: Math.floor(process.uptime()),
      database: 'connected',
      users: userCount,
      timestamp: new Date().toISOString(),
    });
  });
});

用户路由

// src/routes/users.ts
import { defineRoutes } from 'vextjs';

export default defineRoutes((app) => {
  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  // GET /users/list — 分页查询用户列表
  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  app.get('/list', {
    validate: {
      query: {
        page: 'number:1-',
        limit: 'number:1-100',
        keyword: 'string?',
      },
    },
    docs: {
      summary: '用户列表',
      description: '分页查询用户列表。支持按姓名或邮箱关键词搜索。',
      tags: ['用户'],
      responses: {
        200: {
          description: '查询成功',
          example: {
            items: [
              {
                id: 1,
                name: 'Alice',
                email: 'alice@example.com',
                age: 28,
                role: 'admin',
                bio: '全栈开发者',
                createdAt: '2026-03-05 00:00:00',
              },
            ],
            total: 3,
            page: 1,
            limit: 10,
            totalPages: 1,
          },
        },
      },
    },
  }, async (req, res) => {
    const { page, limit, keyword } = req.valid('query');
    const result = await app.services.user.findAll({ page, limit, keyword });
    res.json(result);
  });

  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  // GET /users/:id — 查询用户详情（含文章）
  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  app.get('/:id', {
    validate: {
      param: { id: 'number:1-' },
    },
    docs: {
      summary: '获取用户详情',
      description: '查询用户详情，包含该用户发布的所有文章。',
      tags: ['用户'],
      responses: {
        200: { description: '查询成功' },
        404: { description: '用户不存在' },
      },
    },
  }, async (req, res) => {
    const { id } = req.valid('param');
    const user = await app.services.user.findById(id);

    if (!user) {
      app.throw(404, '用户不存在');
    }

    res.json(user);
  });

  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  // POST /users — 创建用户（需认证）
  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  app.post('/', {
    validate: {
      body: {
        name: 'string:1-50',
        email: 'email',
        age: 'number:0-200?',
        role: 'enum:admin,user,editor?',
      },
    },
    middlewares: ['auth'],
    docs: {
      summary: '创建用户',
      description: '创建新用户。需要 Bearer Token 认证。邮箱必须唯一。',
      tags: ['用户'],
      responses: {
        201: { description: '创建成功' },
        400: { description: '参数校验失败' },
        401: { description: '未认证' },
        409: { description: '邮箱已注册' },
      },
    },
  }, async (req, res) => {
    const body = req.valid('body');
    const user = await app.services.user.create(body);
    res.json(user, 201);
  });

  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  // PUT /users/:id — 更新用户（需认证）
  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  app.put('/:id', {
    validate: {
      param: { id: 'number:1-' },
      body: {
        name: 'string:1-50?',
        email: 'email?',
        age: 'number:0-200?',
      },
    },
    middlewares: ['auth'],
    docs: {
      summary: '更新用户',
      description: '更新用户信息。只需传入需要更新的字段。',
      tags: ['用户'],
      responses: {
        200: { description: '更新成功' },
        400: { description: '参数校验失败' },
        401: { description: '未认证' },
        404: { description: '用户不存在' },
        409: { description: '邮箱已被占用' },
      },
    },
  }, async (req, res) => {
    const { id } = req.valid('param');
    const body = req.valid('body');
    const user = await app.services.user.update(id, body);
    res.json(user);
  });

  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  // DELETE /users/:id — 删除用户（需认证）
  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  app.delete('/:id', {
    validate: {
      param: { id: 'number:1-' },
    },
    middlewares: ['auth'],
    docs: {
      summary: '删除用户',
      description: '删除用户及其所有文章（CASCADE）。不可逆操作。',
      tags: ['用户'],
      responses: {
        204: { description: '删除成功' },
        401: { description: '未认证' },
        404: { description: '用户不存在' },
      },
    },
  }, async (req, res) => {
    const { id } = req.valid('param');
    await app.services.user.delete(id);
    res.status(204).json(null);
  });
});

9. 入口文件

// src/index.ts
import { bootstrap } from 'vextjs';

bootstrap().catch((err) => {
  console.error('启动失败:', err);
  process.exit(1);
});

10. 运行与验证

# 创建数据目录
mkdir -p data

# 启动开发服务器
pnpm dev

接口验证

# 健康检查
curl http://localhost:3000/
# → {"code":0,"data":{"status":"ok","database":"connected","users":3,...},"requestId":"..."}

# 查询用户列表
curl "http://localhost:3000/users/list?page=1&limit=10"
# → {"code":0,"data":{"items":[...],"total":3,"page":1,"limit":10,"totalPages":1},"requestId":"..."}

# 搜索用户
curl "http://localhost:3000/users/list?page=1&limit=10&keyword=alice"
# → 只返回匹配 "alice" 的用户

# 查询用户详情（含文章）
curl http://localhost:3000/users/1
# → {"code":0,"data":{"id":1,"name":"Alice",...,"posts":[...]},"requestId":"..."}

# 创建用户
curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer user-1-admin" \
  -d '{"name":"Diana","email":"diana@example.com","age":26}'
# → 201 {"code":0,"data":{"id":4,"name":"Diana","email":"diana@example.com",...},"requestId":"..."}

# 更新用户
curl -X PUT http://localhost:3000/users/4 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer user-1-admin" \
  -d '{"name":"Diana Updated","age":27}'
# → {"code":0,"data":{"id":4,"name":"Diana Updated","age":27,...},"requestId":"..."}

# 删除用户
curl -X DELETE http://localhost:3000/users/4 \
  -H "Authorization: Bearer user-1-admin"
# → 204 No Content

# 邮箱唯一性校验
curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer user-1-admin" \
  -d '{"name":"Test","email":"alice@example.com"}'
# → 409 {"code":10001,"message":"邮箱已注册","requestId":"..."}

11. 测试

// test/users.test.ts
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import { createTestApp } from 'vextjs/testing';
import type { TestApp } from 'vextjs';

describe('用户 CRUD (Drizzle)', () => {
  let testApp: TestApp;
  const AUTH = 'Bearer user-1-admin';

  beforeEach(async () => {
    testApp = await createTestApp({
      plugins: true, // 加载数据库插件
      config: {
        database: {
          url: ':memory:', // 使用内存数据库，测试间隔离
          autoCreate: true,
        },
      },
    });
  });

  afterEach(async () => {
    await testApp?.close();
  });

  it('GET /users/list 应返回种子数据', async () => {
    const res = await testApp.request
      .get('/users/list')
      .query({ page: 1, limit: 10 });

    expect(res.status).toBe(200);
    expect(res.body.data.total).toBe(3); // 种子数据 3 个用户
    expect(res.body.data.items[0]).toHaveProperty('id');
    expect(res.body.data.items[0]).toHaveProperty('name');
    expect(res.body.data.items[0]).toHaveProperty('email');
  });

  it('GET /users/:id 应包含关联文章', async () => {
    const res = await testApp.request.get('/users/1');

    expect(res.status).toBe(200);
    expect(res.body.data.name).toBe('Alice');
    expect(Array.isArray(res.body.data.posts)).toBe(true);
    expect(res.body.data.posts.length).toBeGreaterThan(0);
  });

  it('POST /users 应创建用户并返回自增 ID', async () => {
    const res = await testApp.request
      .post('/users')
      .set('Authorization', AUTH)
      .send({
        name: 'Diana',
        email: 'diana@example.com',
        age: 26,
      });

    expect(res.status).toBe(201);
    expect(res.body.data.id).toBe(4); // 种子数据占了 1-3
    expect(res.body.data.role).toBe('user'); // 默认值
    expect(res.body.data.createdAt).toBeDefined();
  });

  it('DELETE /users/:id 应级联删除文章', async () => {
    // Alice (id=1) 有 2 篇文章
    const deleteRes = await testApp.request
      .delete('/users/1')
      .set('Authorization', AUTH);

    expect(deleteRes.status).toBe(204);

    // 确认用户和文章都已删除
    const getRes = await testApp.request.get('/users/1');
    expect(getRes.status).toBe(404);
  });
});

Drizzle 高级用法

关联查询（Relations API）

Drizzle 支持声明式的关联查询，避免手动 JOIN：

import { relations } from 'drizzle-orm';
import { users, posts } from './schema.js';

// 声明关联关系
export const usersRelations = relations(users, ({ many }) => ({
  posts: many(posts),
}));

export const postsRelations = relations(posts, ({ one }) => ({
  author: one(users, {
    fields: [posts.authorId],
    references: [users.id],
  }),
}));

// 使用关联查询
const usersWithPosts = await db.query.users.findMany({
  with: {
    posts: {
      where: eq(posts.published, true),
      orderBy: desc(posts.createdAt),
      limit: 5,
    },
  },
});

事务

import { eq, sql } from 'drizzle-orm';

// 事务：转账操作
async function transfer(fromId: number, toId: number, amount: number) {
  await db.transaction(async (tx) => {
    // 扣减
    tx.update(accounts)
      .set({ balance: sql`balance - ${amount}` })
      .where(eq(accounts.id, fromId))
      .run();

    // 增加
    tx.update(accounts)
      .set({ balance: sql`balance + ${amount}` })
      .where(eq(accounts.id, toId))
      .run();

    // 记录交易
    tx.insert(transactions)
      .values({ fromId, toId, amount, type: 'transfer' })
      .run();
  });
}

子查询与聚合

import { eq, count, avg, gt, sql } from 'drizzle-orm';

// 统计每个用户的文章数
const userPostCounts = db
  .select({
    userId: users.id,
    name: users.name,
    postCount: count(posts.id),
  })
  .from(users)
  .leftJoin(posts, eq(users.id, posts.authorId))
  .groupBy(users.id)
  .having(gt(count(posts.id), 0))
  .all();

// 子查询：查询文章数大于平均值的用户
const avgPostCount = db
  .select({ avg: avg(count(posts.id)) })
  .from(posts)
  .groupBy(posts.authorId);

const activeAuthors = db
  .select()
  .from(users)
  .where(
    gt(
      db
        .select({ count: count() })
        .from(posts)
        .where(eq(posts.authorId, users.id)),
      sql`(SELECT AVG(cnt) FROM (SELECT COUNT(*) as cnt FROM posts GROUP BY author_id))`,
    ),
  )
  .all();

动态条件构建

import { and, or, eq, like, gte, lte, sql } from 'drizzle-orm';
import type { SQL } from 'drizzle-orm';

interface UserFilter {
  keyword?: string;
  role?: string;
  minAge?: number;
  maxAge?: number;
}

function buildUserFilter(filter: UserFilter): SQL | undefined {
  const conditions: SQL[] = [];

  if (filter.keyword) {
    conditions.push(
      or(
        like(users.name, `%${filter.keyword}%`),
        like(users.email, `%${filter.keyword}%`),
      )!,
    );
  }

  if (filter.role) {
    conditions.push(eq(users.role, filter.role));
  }

  if (filter.minAge !== undefined) {
    conditions.push(gte(users.age, filter.minAge));
  }

  if (filter.maxAge !== undefined) {
    conditions.push(lte(users.age, filter.maxAge));
  }

  return conditions.length > 0 ? and(...conditions) : undefined;
}

// 使用
const items = db
  .select()
  .from(users)
  .where(buildUserFilter({ keyword: 'alice', role: 'admin', minAge: 20 }))
  .all();

使用 PostgreSQL

切换到 PostgreSQL 只需修改两个文件：

// src/db/schema.ts — 改用 pg 导入
import {
  pgTable,
  serial,
  text,
  integer,
  timestamp,
  boolean,
} from 'drizzle-orm/pg-core';

export const users = pgTable('users', {
  id: serial('id').primaryKey(),
  name: text('name').notNull(),
  email: text('email').notNull().unique(),
  age: integer('age'),
  role: text('role').notNull().default('user'),
  createdAt: timestamp('created_at').notNull().defaultNow(),
  updatedAt: timestamp('updated_at').notNull().defaultNow(),
});

// src/db/index.ts — 改用 pg 驱动
import { drizzle } from 'drizzle-orm/postgres-js';
import postgres from 'postgres';
import * as schema from './schema.js';

export function createDatabase(config: { url: string }) {
  const client = postgres(config.url);
  const db = drizzle(client, { schema });
  return { db, client };
}

业务代码（服务层、路由层）完全无需修改。

项目模式总结

层级	职责	文件
Schema	表定义 + 类型推断	`src/db/schema.ts`
连接工厂	创建数据库实例	`src/db/index.ts`
插件	初始化连接、挂载 `app.db`、清理	`src/plugins/database.ts`
服务层	业务逻辑 + Drizzle 查询	`src/services/user.ts`
路由层	请求校验 + 调用服务 + 响应	`src/routes/users.ts`
类型声明	`app.db` 类型扩展	`types/vext.d.ts`

核心原则

Schema 即类型：使用 $inferSelect / $inferInsert 从 Drizzle schema 推断类型，不手动维护接口
插件管理生命周期：数据库连接的创建和销毁由插件负责，通过 app.extend() 和 app.onClose() 管理
服务层封装查询：所有 Drizzle 查询封装在服务层，路由层只做编排
路由层声明式：路由专注于校验规则、文档配置和服务调用

下一步

📖 Prisma ORM 集成 — 另一种流行的 ORM 集成方案
📖 Zod 校验集成 — 更强大的参数校验
📖 插件 — 深入了解 VextJS 插件系统
📖 服务层 — 深入了解服务层设计模式
📖 测试 — 测试数据库相关的业务逻辑

#Drizzle ORM 集成

#为什么选择 Drizzle ORM？

#项目结构

#1. 安装依赖

#2. 数据库 Schema

#3. 数据库连接工厂

#4. 数据库迁移配置

#5. 数据库插件

#6. 配置

#7. 服务层

#8. 路由

#根路由

#用户路由

#9. 入口文件

#10. 运行与验证

#接口验证

#11. 测试

#Drizzle 高级用法

#关联查询（Relations API）

#事务

#子查询与聚合

#动态条件构建

#使用 PostgreSQL

#项目模式总结

#核心原则

#下一步