Vue 3 通常被看作纯前端框架，但在全栈项目、Electron 桌面应用或者 Node.js 中间层场景中，经常需要直接在项目中操作数据库。Sequelize 是 Node.js 生态里一个基于 Promise 的 ORM，它对 MySQL、PostgreSQL、SQLite 等主流数据库都有良好支持。把 Sequelize 和 Vue 3 的工程化体系结合起来，关键不在于怎么连数据库，而在于如何设计出清晰的分层结构，让数据访问代码与视图代码解耦，同时避开 Vue 响应式系统与 ORM 实例冲突的坑。
一、项目结构与分层设计
工程化的第一步是把目录结构定下来。很多人把数据库连接代码直接写在组件里，甚至写在 setup 函数内部，这样做的后果是每次组件挂载都会创建一个新的连接池，数据库资源很快就被耗尽。正确的做法是把数据访问层完全独立出来，组件只通过服务层调用。
推荐的结构大致如下：src 目录下分出 server、models、services、composables 等子目录。server 目录负责数据库连接初始化，models 目录存放模型定义，services 目录封装业务逻辑，composables 目录提供可以在组件中复用的异步数据组合函数。这种分层让每一层职责单一，后续无论是换数据库还是加缓存，改动范围都被控制在特定层内。
特别要注意的是，Sequelize 实例绝对不能直接放进 reactive 或者 ref。Vue 3 的响应式系统会递归代理对象的每一层属性，而 Sequelize 实例内部包含连接池、查询接口等大量复杂结构，被代理后不仅性能急剧下降，还可能因为 Proxy 拦截导致内部逻辑异常。正确的做法是用模块级变量持有实例，通过导出函数的方式访问。
二、封装 Sequelize 连接与模型定义
连接模块建议使用单例模式，配合环境变量读取配置。下面是一个典型的连接封装示例：
import { Sequelize } from 'sequelize';
// 模块级变量持有实例，避免被响应式系统代理
let instance = null;
export function getSequelize() {
if (instance) return instance;
instance = new Sequelize(
process.env.DB_NAME,
process.env.DB_USER,
process.env.DB_PASSWORD,
{
host: process.env.DB_HOST,
dialect: 'mysql',
pool: {
max: 10, // 连接池最大连接数
min: 2, // 最小空闲连接数
idle: 10000 // 空闲超时时间（毫秒）
},
logging: process.env.NODE_ENV === 'development' ? console.log : false
}
);
return instance;
}模型定义建议每个模型一个文件，保持独立可维护。定义好后统一在一个入口文件中注册关联关系并导出，这样模型之间的 belongsTo、hasMany 关联不会散落在业务代码里。示例：
import { DataTypes } from 'sequelize';
import { getSequelize } from '../server/db';
const sequelize = getSequelize();
export const Article = sequelize.define('Article', {
title: { type: DataTypes.STRING, allowNull: false },
content: { type: DataTypes.TEXT },
published: { type: DataTypes.BOOLEAN, defaultValue: false }
}, {
timestamps: true,
underscored: true // 字段名使用下划线风格
});在关联注册入口中，统一执行 Article.belongsTo(User) 这类关联声明，再导出所有模型。这种集中管理的方式在模型数量增多后优势会非常明显，排查关联问题时只需要看一个文件。
三、在组合式 API 中优雅地使用 ORM
组件层面不应该直接调用 Sequelize 的查询方法，而是通过 services 层的函数。服务层返回 Promise，正好与 Vue 3 的异步组件逻辑契合。可以封装一个通用的 useAsyncData 组合函数，统一处理加载状态和错误：
import { ref, shallowRef, onUnmounted } from 'vue';
export function useAsyncData(fetcher) {
const data = shallowRef(null); // shallowRef 避免深层代理
const loading = ref(false);
const error = ref(null);
let cancelled = false;
async function execute(...args) {
loading.value = true;
error.value = null;
try {
const result = await fetcher(...args);
if (!cancelled) data.value = result;
} catch (e) {
error.value = e;
} finally {
loading.value = false;
}
}
onUnmounted(() => { cancelled = true; });
return { data, loading, error, execute };
}这里有个细节值得注意：data 使用 shallowRef 而不是 ref。Sequelize 返回的实例对象带有大量内部方法（如 save、reload、destroy），如果用 ref 深层代理，模板更新时会遍历这些结构，性能开销不小。shallowRef 只追踪第一层引用变化，配合整体替换数据的写法，既保证响应式又保持轻量。
在组件中使用时，直接调用服务层函数传入 fetcher 即可。如果需要轮询刷新或条件查询，可以把参数变化 watch 起来重新执行。所有数据库细节都被隔离在服务层之后，组件代码保持干净。
四、事务处理与常见坑点
涉及多表写入时必须用事务保证一致性。Sequelize 的事务 API 基于 Promise，支持 callback 和手动两种风格。推荐使用 managed transaction 风格，任何一步抛错都会自动回滚：
import { getSequelize } from '../server/db';
import { Order, OrderItem } from '../models';
export async function createOrder(orderData, items) {
const sequelize = getSequelize();
const result = await sequelize.transaction(async (t) => {
const order = await Order.create(orderData, { transaction: t });
await OrderItem.bulkCreate(
items.map(item => ({ ...item, orderId: order.id })),
{ transaction: t }
);
return order;
});
return result;
}除了前面提到的响应式代理问题，还有几个高频坑需要留意。第一，连接池参数不能照抄默认值，生产环境要根据数据库 max_connections 和并发量调整，否则高并发下会出现等待队列堆积。第二，timestamps 选项和数据库实际的字段设计要保持一致，否则查询会报未知列错误，用 underscored 配合数据库的下划线命名习惯可以减少这类摩擦。第三，在 Vite 项目中，凡是引入 Sequelize 的代码都不能被打进浏览器 bundle，需要通过 SSR、外部进程或者动态 import 加条件守卫来隔离，判断依据通常是 typeof window === 'undefined'。
总结一下，工程化的核心是分层：连接层管实例、模型层管结构、服务层管业务、组合函数层管状态。层与层之间只通过 Promise 传递数据，Vue 3 的组合式 API 天然适合消费这些异步结果，只要管住响应式代理的边界，整套方案可以长期稳定运行。