1. 项目概述与核心价值最近在带几个刚入行的前端小伙伴做项目发现一个挺普遍的现象一提到后端数据库操作很多人下意识就觉得这是后端工程师的活儿前端只管调接口就行。但实际情况是随着Node.js的普及和全栈开发模式的流行前端开发者直接操作数据库的场景越来越多了。比如你需要快速搭建一个本地开发用的Mock服务器或者写一个轻量级的脚本去处理一些数据迁移、报表生成的任务这时候如果还要等后端同事给你开接口效率就太低了。这个教程要解决的就是如何让你一个前端开发者能独立地使用Node.js去连接和操作SQL Server数据库。SQL Server在企业级应用里非常常见很多历史项目或者内部系统都在用它。掌握这个技能意味着你能更深入地理解数据流转的完整链条从界面到数据库“一杆到底”无论是解决线上问题还是开发内部工具都会从容很多。这不仅仅是多学一个技术点更是拓宽你技术视野和解决问题能力的关键一步。2. 环境准备与核心依赖解析动手之前得先把“厨房”收拾好。这里的环境准备不仅仅是安装软件更重要的是理解每个环节的作用和可能遇到的坑。2.1 Node.js运行环境搭建Node.js是我们的运行时基础。虽然热词里提到了各种安装问题比如nvm install 14.18.0或者Microsoft Visual C 2022缺失的错误但我的建议是直接使用Node.js的LTS长期支持版本目前是18.x或20.x。LTS版本更稳定社区支持更好能避免很多稀奇古怪的兼容性问题。安装方式强烈推荐使用nvmNode Version Manager来管理你的Node.js版本特别是如果你需要在不同项目间切换Node版本。Windows用户可以用nvm-windows。安装后在命令行执行nvm install 18.19.0以18.19.0为例然后nvm use 18.19.0即可。验证安装安装完成后打开终端或命令行输入node -v和npm -v能正确显示版本号就说明基础环境OK了。注意如果你在Windows上安装Node.js时遇到“Microsoft Visual C Redistributable is not installed”的错误那是因为一些Node.js的本地模块native addons编译时需要这个环境。去微软官网下载并安装最新的“Microsoft Visual C Redistributable”即可通常选择x64版本。2.2 初始化项目与安装核心驱动环境好了我们创建一个专门的项目来操作。别在现有的前端项目里直接搞容易引起依赖混乱。创建项目目录找个合适的位置新建一个文件夹例如node-sqlserver-demo。初始化package.json进入该目录打开终端执行npm init -y。这个命令会快速生成一个默认的package.json文件用来管理项目依赖。安装核心依赖连接SQL Server我们主要依靠一个叫做tedious的驱动包。它是纯JavaScript实现的是微软官方推荐的Node.js连接SQL Server的方案之一。在终端执行npm install tedious这个命令会把tedious及其依赖下载到项目的node_modules文件夹中并在package.json的dependencies里记录。为什么是tedious你可能也听说过msnodesqlv8或node-mssql。msnodesqlv8依赖Windows原生驱动跨平台性不好。node-mssql其实是一个上层封装它底层可以使用tedious默认或msnodesqlv8。对于新手和追求跨平台稳定性直接从tedious开始是最清晰、问题最少的路径。理解了tedious再去看node-mssql就会觉得非常简单。2.3 数据库连接信息准备在写代码之前你得知道你的“目的地”在哪里。你需要从数据库管理员那里或自己管理的SQL Server实例获取以下信息可以先用记事本记下来服务器server数据库所在的机器地址。本地开发通常是localhost或127.0.0.1也可能是.\SQLEXPRESS本地命名实例。远程服务器则是一个IP地址或域名。数据库名database你要连接的具体数据库名称。身份验证方式SQL Server身份验证需要用户名user和密码password。Windows身份验证通常用于本地开发使用当前Windows账户登录。在tedious中配置稍有不同需要设置authentication.type。端口portSQL Server默认监听1433端口。如果没改过一般就是这个。实操心得对于本地开发比如连接本机的SQL Server Express使用Windows身份验证往往比SQL Server身份验证更简单因为它不需要你记住额外的账号密码且权限管理更贴近系统。但在连接远程数据库时SQL Server身份验证是更通用的方式。3. 基础连接与首次查询实战理论说再多不如一行代码。我们现在就来建立第一个连接并执行一条简单的查询语句。3.1 建立数据库连接在项目根目录下创建一个名为app.js的文件。我们将从这里开始编码。首先引入我们安装的tedious模块中的Connection和Request类。Connection负责管理到数据库的连接本身而Request则代表一个要执行的SQL命令查询或修改。// app.js const { Connection, Request } require(tedious);接下来配置连接信息。我们以最常用的SQL Server身份验证为例// 数据库连接配置 const config { server: localhost, // 你的服务器地址 authentication: { type: default, // 使用SQL Server身份验证 options: { userName: your_username, // 替换为你的用户名 password: your_password, // 替换为你的密码 } }, options: { database: your_database_name, // 替换为你的数据库名 encrypt: true, // 使用加密连接对于Azure SQL或远程服务器很重要 trustServerCertificate: true, // 本地开发或自签名证书时可设为true port: 1433 // 默认端口如果修改过请替换 } };关键参数解析encrypt: true建议始终开启确保数据传输安全。尤其是在连接云数据库如Azure SQL Database时这是强制要求。trustServerCertificate: true当数据库使用自签名证书时常见于开发环境需要将此设为true来跳过证书验证。在生产环境中应使用有效的CA签名证书并将此选项设为false。现在用这个配置创建一个Connection实例并设置事件监听器。// 创建连接实例 const connection new Connection(config); // 监听连接成功事件 connection.on(connect, (err) { if (err) { console.error(连接失败:, err.message); } else { console.log(成功连接到SQL Server数据库); // 连接成功后在这里执行查询 executeStatement(); } }); // 监听连接错误事件 connection.on(error, (err) { console.error(连接错误:, err); }); // 开始连接 connection.connect();3.2 执行简单查询并处理结果连接成功后我们定义并执行一个查询。假设我们有一个Users表我们来查询所有用户。在connect事件回调中调用的executeStatement函数如下function executeStatement() { console.log(开始执行查询...); // 定义要执行的SQL语句 const sql SELECT id, username, email FROM Users; // 创建一个Request对象 const request new Request(sql, (err, rowCount) { if (err) { console.error(执行查询时出错:, err); } else { console.log(查询成功共返回 ${rowCount} 行数据。); } // 查询完毕后关闭连接重要 connection.close(); }); // 监听每一行数据返回的事件 request.on(row, (columns) { const row {}; columns.forEach(column { row[column.metadata.colName] column.value; }); console.log(读取到一行数据:, row); // 这里你可以将row存入数组供后续使用 }); // 执行请求 connection.execSql(request); }代码逐行解读new Request(sql, callback)创建请求。第一个参数是SQL字符串第二个参数是请求执行完毕后的回调函数无论成功与否都会执行。回调里的rowCount是受影响的行数对于SELECT是返回的行数。request.on(row, callback)这是核心。每当数据库返回一行结果时就会触发这个事件。回调函数的参数columns是一个数组包含了这一行所有列的信息。我们遍历它根据列名(colName)和值(value)构建成一个JavaScript对象方便使用。connection.execSql(request)将请求交给连接去执行。connection.close()在请求最终回调中关闭连接。这是一个好习惯避免连接泄露。对于需要频繁操作的场景可以考虑连接池但初次学习先显式关闭。3.3 运行你的第一个数据库程序保存app.js文件。在终端中确保你的路径在项目目录下然后运行node app.js如果一切配置正确你将看到类似以下的输出成功连接到SQL Server数据库 开始执行查询... 读取到一行数据: { id: 1, username: 张三, email: zhangsanexample.com } 读取到一行数据: { id: 2, username: 李四, email: lisiexample.com } 查询成功共返回 2 行数据。恭喜你已经完成了前端Node.js环境与SQL Server数据库的第一次对话。4. 核心操作进阶增删改查与参数化查询只会查询可不够我们得能完整地操作数据。同时安全是重中之重直接拼接SQL字符串是危险的行为我们必须使用参数化查询来防止SQL注入攻击。4.1 安全基石参数化查询Prepared Statements为什么必须参数化想象一下你的查询语句有一部分来自用户输入比如搜索框。如果直接拼接“SELECT * FROM Products WHERE name ” userInput “”。当用户输入‘ OR ‘1’‘1时整个语句的意思就变成了SELECT * FROM Products WHERE name ‘’ OR ‘1’‘1’条件永远为真导致泄露所有数据。这就是SQL注入。tedious使用Request对象的addParameter方法来添加参数。让我们以插入INSERT数据为例function insertUser() { const sql INSERT INTO Users (username, email, createdAt) VALUES (username, email, GETDATE()) ; const request new Request(sql, (err, rowCount) { if (err) { console.error(插入数据失败:, err); } else { console.log(成功插入 ${rowCount} 条记录。); } connection.close(); }); // 添加参数参数名、数据类型、值 request.addParameter(username, TYPES.VarChar, 王五); request.addParameter(email, TYPES.VarChar, wangwuexample.com); // 注意需要引入 TYPES 类型常量 const { TYPES } require(tedious); connection.execSql(request); }关键点SQL语句中使用参数名来定义参数占位符。addParameter方法需要三个参数参数名不带、SQL数据类型使用TYPES常量、参数值。TYPES中定义了所有SQL Server支持的数据类型如TYPES.Int,TYPES.NVarChar,TYPES.DateTime等。选择正确的类型很重要。4.2 完整CRUD操作示例我们将增、删、改、查和参数化查询结合起来写一个更综合的例子。假设我们连接成功后按顺序执行以下操作查、增、改、删。我们需要修改连接成功的回调使其按顺序执行一系列操作。为了处理异步我们用一个简单的“回调地狱”示例来演示流程实际项目建议使用Promise或async/await封装。// 需要引入 TYPES const { Connection, Request, TYPES } require(tedious); // ... 连接配置和连接创建代码同上 ... connection.on(connect, (err) { if (err) { console.error(连接失败:, err.message); return; } console.log(连接成功); // 1. 首先查询现有用户 queryUsers(() { // 2. 查询完成后插入一个新用户 insertNewUser(() { // 3. 插入完成后更新这个用户的邮箱 updateUserEmail(() { // 4. 最后删除这个用户清理测试数据 deleteUser(() { console.log(所有操作完成); connection.close(); }); }); }); }); }); function queryUsers(callback) { const sql SELECT id, username, email FROM Users; const request new Request(sql, (err) { if (err) console.error(查询失败:, err); console.log(--- 查询操作完成 ---); callback(); }); request.on(row, (cols) { console.log(用户: ${cols[0].value}, ${cols[1].value}, ${cols[2].value}); }); connection.execSql(request); } function insertNewUser(callback) { const sql INSERT INTO Users (username, email) VALUES (username, email); const request new Request(sql, (err, rowCount) { if (err) console.error(插入失败:, err); else console.log(插入成功影响行数: ${rowCount}); console.log(--- 插入操作完成 ---); callback(); }); request.addParameter(username, TYPES.VarChar, 测试用户); request.addParameter(email, TYPES.VarChar, testexample.com); connection.execSql(request); } function updateUserEmail(callback) { // 假设我们要更新刚才插入的‘测试用户’的邮箱 const sql UPDATE Users SET email newEmail WHERE username username; const request new Request(sql, (err, rowCount) { if (err) console.error(更新失败:, err); else console.log(更新成功影响行数: ${rowCount}); console.log(--- 更新操作完成 ---); callback(); }); request.addParameter(newEmail, TYPES.VarChar, updatedexample.com); request.addParameter(username, TYPES.VarChar, 测试用户); connection.execSql(request); } function deleteUser(callback) { const sql DELETE FROM Users WHERE username username; const request new Request(sql, (err, rowCount) { if (err) console.error(删除失败:, err); else console.log(删除成功影响行数: ${rowCount}); console.log(--- 删除操作完成 ---); callback(); }); request.addParameter(username, TYPES.VarChar, 测试用户); connection.execSql(request); }这个例子虽然用了多层回调俗称“回调地狱”但清晰地展示了四个基本操作的代码结构。在真实项目中你一定会用Promise或async/await来优化它让代码变成线性的、更易读的形式。5. 连接池管理与生产环境实践单个连接在简单脚本里够用但对于Web服务器或需要频繁操作数据库的应用频繁创建和销毁连接开销巨大。连接池Connection Pool就是解决方案它预先创建好一定数量的连接放在“池子”里应用需要时从池中取用用完后归还而不是关闭。5.1 为什么需要连接池想象一下你的Node.js API服务器每个用户请求都需要查询数据库。如果没有连接池每个请求都会经历“建立TCP连接 - 数据库登录认证 - 执行SQL - 断开连接”的完整过程。其中建立连接和认证的开销非常高在高并发下数据库和服务器都会不堪重负。连接池的优势性能提升避免了重复建立连接的开销。资源控制可以限制最大连接数防止数据库被过多连接拖垮。连接复用健康的连接可以被多个操作重复使用。tedious本身不直接提供连接池但我们可以使用另一个非常流行的库mssql它底层默认使用tedious并提供了开箱即用的连接池管理。这也是为什么很多项目直接选用mssql的原因。5.2 使用mssql库简化操作首先安装mssqlnpm install mssql使用mssql重写我们的查询示例你会发现代码简洁了很多const sql require(mssql); // 配置对象与tedious略有不同 const config { user: your_username, password: your_password, server: localhost, database: your_database_name, pool: { max: 10, // 连接池最大连接数 min: 0, // 连接池最小连接数 idleTimeoutMillis: 30000 // 连接在关闭前可以空闲的时间毫秒 }, options: { encrypt: true, trustServerCertificate: true } }; async function connectAndQuery() { try { // 连接到数据库内部管理连接池 await sql.connect(config); console.log(已连接到数据库通过连接池); // 执行一个简单查询 const result await sql.querySELECT id, username FROM Users; console.log(查询结果:, result.recordset); // recordset 就是结果数组 // 参数化查询也非常简洁 const userId 1; const result2 await sql.querySELECT * FROM Users WHERE id ${userId}; console.log(参数化查询结果:, result2.recordset); } catch (err) { console.error(数据库操作错误:, err); } finally { // 关闭连接池通常在应用关闭时调用 await sql.close(); console.log(连接已关闭); } } connectAndQuery();可以看到mssql的优势自动连接池sql.connect()会初始化连接池后续所有查询都从池中获取连接。Promise API直接支持async/await代码是线性的没有回调嵌套。模板字符串查询使用带标签的模板字符串sql.querySELECT ... WHERE id ${value}可以自动进行参数化处理既安全又方便。结果集格式友好查询结果直接放在result.recordset中是一个对象数组。生产环境建议对于大多数Node.js项目直接使用mssql库是更高效、更安全的选择。它封装了连接池、错误重试、事务等复杂逻辑让你能更专注于业务代码。tedious更适合需要极细粒度控制底层连接或者学习底层原理的场景。6. 常见错误排查与调试技巧在实际操作中你几乎一定会遇到各种连接或查询错误。别慌大部分错误都有明确的提示。这里整理了一份常见问题速查表。错误现象可能原因解决方案连接失败Login failed for user ‘xxx’1. 用户名或密码错误。2. SQL Server身份验证未启用。3. 用户没有访问该数据库的权限。1. 仔细核对用户名密码注意大小写。2. 在SQL Server Management Studio (SSMS)中检查服务器属性 - 安全性确保已启用“SQL Server和Windows身份验证模式”。3. 在SSMS中为该用户授予对应数据库的登录和访问权限。连接失败Cannot connect to localhost:1433或超时1. SQL Server服务未启动。2. TCP/IP协议未启用。3. 防火墙阻止了1433端口。4. 服务器地址或端口号错误。1. 打开“服务”找到“SQL Server (MSSQLSERVER)”或你的实例名确保其状态为“正在运行”。2. 使用“SQL Server配置管理器”在“SQL Server网络配置” - “XXX的协议”中启用“TCP/IP”。3. 在防火墙中添加入站规则允许1433端口。4. 确认服务器地址远程需用IP/域名和端口。连接失败Failed to connect to localhost:1433 - Could not connect (sequence)客户端驱动无法建立到服务器的网络连接。先尝试用SSMS能否连接同一地址。如果SSMS可以而Node不行可能是Node环境问题或驱动问题。尝试ping服务器地址检查网络连通性。执行查询错误Invalid object name ‘Users’1. 表名拼写错误。2. 连接配置中的database选项不正确导致连接到了错误的数据库。3. 表不在当前用户的默认架构下需要指定架构名如dbo.Users。1. 检查SQL语句中的表名。2. 确认config.options.database的值。3. 尝试在表名前加上架构名如SELECT * FROM dbo.Users。参数化查询错误The parameterized query ‘…’ expects the parameter ‘username’, which was not supplied在SQL语句中定义了参数如username但在代码中没有通过addParameter方法提供对应的值。检查Request对象确保为SQL中每一个开头的参数都调用了addParameter方法且参数名一致不含。错误Connection lost - The connection was closed by the server连接空闲时间过长被服务器断开。使用连接池如mssql可以自动处理断线重连。如果使用原始tedious连接需要自己监听error事件并实现重连逻辑。使用mssql时错误ConnectionError: Failed to connect to localhost:1433 - Could not connect (sequence)mssql底层使用tedious同样需要确保SQL Server服务、TCP/IP、防火墙等配置正确。排查步骤与上述tedious连接失败相同。另外确保安装的mssql和tedious版本兼容。调试心法从简到繁先确保最基本的连接sql.connect或new Connection能成功。可以写一个最简单的脚本只连接不执行任何查询。分离问题如果连接成功但查询失败将你的SQL语句复制到SSMS或Azure Data Studio里直接运行看是否是SQL语法或权限问题。善用错误信息Node.js和SQL Server返回的错误信息通常非常具体仔细阅读第一行往往就能定位到问题根源。查看详细日志在tedious的配置中可以设置options.debug为true或者在创建Connection时监听debug事件来获取更详细的通信日志。const connection new Connection(config); connection.on(debug, (message) { console.log(调试信息:, message); });7. 项目结构优化与异步流程控制当我们把数据库操作集成到一个真正的Node.js应用比如一个Express API服务器时代码的组织方式和异步处理就变得至关重要。我们不能把数据库配置和操作逻辑都堆在app.js里。7.1 模块化拆分一个良好的结构能让代码更易维护。我推荐这样组织你的项目node-sqlserver-project/ ├── config/ │ └── database.js # 数据库连接配置 ├── models/ # 数据模型/实体 │ └── userModel.js # 用户相关的数据库操作 ├── app.js # 应用主入口 ├── package.json └── .gitignore1. 集中管理配置 (config/database.js)// config/database.js const sql require(mssql); const dbConfig { user: process.env.DB_USER || your_username, password: process.env.DB_PASSWORD || your_password, server: process.env.DB_SERVER || localhost, database: process.env.DB_NAME || your_database, options: { encrypt: true, trustServerCertificate: true, }, pool: { max: 10, min: 0, idleTimeoutMillis: 30000 } }; // 导出一个获取连接池的函数 async function getConnection() { try { // sql.connect 会返回连接池多次调用返回同一个池 const pool await sql.connect(dbConfig); return pool; } catch (err) { console.error(数据库连接池创建失败:, err); throw err; // 向上抛出错误由调用者处理 } } module.exports { sql, // 也可以导出sql对象方便直接使用其方法 getConnection, dbConfig };2. 封装数据操作层 (models/userModel.js)// models/userModel.js const { getConnection, sql } require(../config/database); class UserModel { // 获取所有用户 async getAllUsers() { try { const pool await getConnection(); const result await pool.request().query(SELECT id, username, email FROM Users); return result.recordset; // 返回用户数组 } catch (err) { console.error(获取用户列表失败:, err); throw err; } } // 根据ID获取用户 async getUserById(id) { try { const pool await getConnection(); const result await pool.request() .input(id, sql.Int, id) // 使用.input方法添加参数 .query(SELECT * FROM Users WHERE id id); return result.recordset[0]; // 返回第一个用户对象或undefined } catch (err) { console.error(获取用户(ID: ${id})失败:, err); throw err; } } // 创建用户 async createUser(username, email) { try { const pool await getConnection(); const result await pool.request() .input(username, sql.VarChar, username) .input(email, sql.VarChar, email) .query(INSERT INTO Users (username, email) OUTPUT Inserted.id VALUES (username, email)); // OUTPUT Inserted.id 可以返回新插入行的id return result.recordset[0]; // 返回包含新id的对象如 { id: 10 } } catch (err) { console.error(创建用户失败:, err); // 这里可以处理特定错误如重复键错误 if (err.number 2627) { // SQL Server 唯一键冲突错误号 throw new Error(用户名或邮箱已存在); } throw err; } } } module.exports new UserModel(); // 导出一个单例实例7.2 在主应用中使用模型现在在你的主文件如app.js或路由文件中使用模型就非常清晰了// app.js const express require(express); const userModel require(./models/userModel); const app express(); app.use(express.json()); // 用于解析JSON请求体 // 获取所有用户的API端点 app.get(/api/users, async (req, res) { try { const users await userModel.getAllUsers(); res.json(users); } catch (err) { console.error(API /api/users 错误:, err); res.status(500).json({ error: 获取用户列表失败 }); } }); // 创建用户的API端点 app.post(/api/users, async (req, res) { const { username, email } req.body; if (!username || !email) { return res.status(400).json({ error: 用户名和邮箱为必填项 }); } try { const newUser await userModel.createUser(username, email); res.status(201).json({ message: 用户创建成功, userId: newUser.id }); } catch (err) { // 捕获模型层抛出的自定义错误 if (err.message 用户名或邮箱已存在) { return res.status(409).json({ error: err.message }); } res.status(500).json({ error: 创建用户失败 }); } }); const PORT process.env.PORT || 3000; app.listen(PORT, () { console.log(服务器运行在 http://localhost:${PORT}); });这样的结构将数据库配置、数据访问逻辑和Web API路由清晰地分离开。模型层 (UserModel) 负责所有与Users表交互的细节控制器层路由处理函数只关心HTTP请求和响应代码的可读性、可测试性和可维护性都大大提升。关于异步错误处理注意我们在所有async函数中都使用了try...catch。这是处理Promise拒绝rejection的标准做法可以防止未处理的Promise错误导致整个Node.js进程崩溃。在Web服务器中务必确保每个异步路由都有错误处理并向客户端返回适当的HTTP状态码和错误信息。
Node.js连接SQL Server全攻略：从前端到数据库的完整实践
1. 项目概述与核心价值最近在带几个刚入行的前端小伙伴做项目发现一个挺普遍的现象一提到后端数据库操作很多人下意识就觉得这是后端工程师的活儿前端只管调接口就行。但实际情况是随着Node.js的普及和全栈开发模式的流行前端开发者直接操作数据库的场景越来越多了。比如你需要快速搭建一个本地开发用的Mock服务器或者写一个轻量级的脚本去处理一些数据迁移、报表生成的任务这时候如果还要等后端同事给你开接口效率就太低了。这个教程要解决的就是如何让你一个前端开发者能独立地使用Node.js去连接和操作SQL Server数据库。SQL Server在企业级应用里非常常见很多历史项目或者内部系统都在用它。掌握这个技能意味着你能更深入地理解数据流转的完整链条从界面到数据库“一杆到底”无论是解决线上问题还是开发内部工具都会从容很多。这不仅仅是多学一个技术点更是拓宽你技术视野和解决问题能力的关键一步。2. 环境准备与核心依赖解析动手之前得先把“厨房”收拾好。这里的环境准备不仅仅是安装软件更重要的是理解每个环节的作用和可能遇到的坑。2.1 Node.js运行环境搭建Node.js是我们的运行时基础。虽然热词里提到了各种安装问题比如nvm install 14.18.0或者Microsoft Visual C 2022缺失的错误但我的建议是直接使用Node.js的LTS长期支持版本目前是18.x或20.x。LTS版本更稳定社区支持更好能避免很多稀奇古怪的兼容性问题。安装方式强烈推荐使用nvmNode Version Manager来管理你的Node.js版本特别是如果你需要在不同项目间切换Node版本。Windows用户可以用nvm-windows。安装后在命令行执行nvm install 18.19.0以18.19.0为例然后nvm use 18.19.0即可。验证安装安装完成后打开终端或命令行输入node -v和npm -v能正确显示版本号就说明基础环境OK了。注意如果你在Windows上安装Node.js时遇到“Microsoft Visual C Redistributable is not installed”的错误那是因为一些Node.js的本地模块native addons编译时需要这个环境。去微软官网下载并安装最新的“Microsoft Visual C Redistributable”即可通常选择x64版本。2.2 初始化项目与安装核心驱动环境好了我们创建一个专门的项目来操作。别在现有的前端项目里直接搞容易引起依赖混乱。创建项目目录找个合适的位置新建一个文件夹例如node-sqlserver-demo。初始化package.json进入该目录打开终端执行npm init -y。这个命令会快速生成一个默认的package.json文件用来管理项目依赖。安装核心依赖连接SQL Server我们主要依靠一个叫做tedious的驱动包。它是纯JavaScript实现的是微软官方推荐的Node.js连接SQL Server的方案之一。在终端执行npm install tedious这个命令会把tedious及其依赖下载到项目的node_modules文件夹中并在package.json的dependencies里记录。为什么是tedious你可能也听说过msnodesqlv8或node-mssql。msnodesqlv8依赖Windows原生驱动跨平台性不好。node-mssql其实是一个上层封装它底层可以使用tedious默认或msnodesqlv8。对于新手和追求跨平台稳定性直接从tedious开始是最清晰、问题最少的路径。理解了tedious再去看node-mssql就会觉得非常简单。2.3 数据库连接信息准备在写代码之前你得知道你的“目的地”在哪里。你需要从数据库管理员那里或自己管理的SQL Server实例获取以下信息可以先用记事本记下来服务器server数据库所在的机器地址。本地开发通常是localhost或127.0.0.1也可能是.\SQLEXPRESS本地命名实例。远程服务器则是一个IP地址或域名。数据库名database你要连接的具体数据库名称。身份验证方式SQL Server身份验证需要用户名user和密码password。Windows身份验证通常用于本地开发使用当前Windows账户登录。在tedious中配置稍有不同需要设置authentication.type。端口portSQL Server默认监听1433端口。如果没改过一般就是这个。实操心得对于本地开发比如连接本机的SQL Server Express使用Windows身份验证往往比SQL Server身份验证更简单因为它不需要你记住额外的账号密码且权限管理更贴近系统。但在连接远程数据库时SQL Server身份验证是更通用的方式。3. 基础连接与首次查询实战理论说再多不如一行代码。我们现在就来建立第一个连接并执行一条简单的查询语句。3.1 建立数据库连接在项目根目录下创建一个名为app.js的文件。我们将从这里开始编码。首先引入我们安装的tedious模块中的Connection和Request类。Connection负责管理到数据库的连接本身而Request则代表一个要执行的SQL命令查询或修改。// app.js const { Connection, Request } require(tedious);接下来配置连接信息。我们以最常用的SQL Server身份验证为例// 数据库连接配置 const config { server: localhost, // 你的服务器地址 authentication: { type: default, // 使用SQL Server身份验证 options: { userName: your_username, // 替换为你的用户名 password: your_password, // 替换为你的密码 } }, options: { database: your_database_name, // 替换为你的数据库名 encrypt: true, // 使用加密连接对于Azure SQL或远程服务器很重要 trustServerCertificate: true, // 本地开发或自签名证书时可设为true port: 1433 // 默认端口如果修改过请替换 } };关键参数解析encrypt: true建议始终开启确保数据传输安全。尤其是在连接云数据库如Azure SQL Database时这是强制要求。trustServerCertificate: true当数据库使用自签名证书时常见于开发环境需要将此设为true来跳过证书验证。在生产环境中应使用有效的CA签名证书并将此选项设为false。现在用这个配置创建一个Connection实例并设置事件监听器。// 创建连接实例 const connection new Connection(config); // 监听连接成功事件 connection.on(connect, (err) { if (err) { console.error(连接失败:, err.message); } else { console.log(成功连接到SQL Server数据库); // 连接成功后在这里执行查询 executeStatement(); } }); // 监听连接错误事件 connection.on(error, (err) { console.error(连接错误:, err); }); // 开始连接 connection.connect();3.2 执行简单查询并处理结果连接成功后我们定义并执行一个查询。假设我们有一个Users表我们来查询所有用户。在connect事件回调中调用的executeStatement函数如下function executeStatement() { console.log(开始执行查询...); // 定义要执行的SQL语句 const sql SELECT id, username, email FROM Users; // 创建一个Request对象 const request new Request(sql, (err, rowCount) { if (err) { console.error(执行查询时出错:, err); } else { console.log(查询成功共返回 ${rowCount} 行数据。); } // 查询完毕后关闭连接重要 connection.close(); }); // 监听每一行数据返回的事件 request.on(row, (columns) { const row {}; columns.forEach(column { row[column.metadata.colName] column.value; }); console.log(读取到一行数据:, row); // 这里你可以将row存入数组供后续使用 }); // 执行请求 connection.execSql(request); }代码逐行解读new Request(sql, callback)创建请求。第一个参数是SQL字符串第二个参数是请求执行完毕后的回调函数无论成功与否都会执行。回调里的rowCount是受影响的行数对于SELECT是返回的行数。request.on(row, callback)这是核心。每当数据库返回一行结果时就会触发这个事件。回调函数的参数columns是一个数组包含了这一行所有列的信息。我们遍历它根据列名(colName)和值(value)构建成一个JavaScript对象方便使用。connection.execSql(request)将请求交给连接去执行。connection.close()在请求最终回调中关闭连接。这是一个好习惯避免连接泄露。对于需要频繁操作的场景可以考虑连接池但初次学习先显式关闭。3.3 运行你的第一个数据库程序保存app.js文件。在终端中确保你的路径在项目目录下然后运行node app.js如果一切配置正确你将看到类似以下的输出成功连接到SQL Server数据库 开始执行查询... 读取到一行数据: { id: 1, username: 张三, email: zhangsanexample.com } 读取到一行数据: { id: 2, username: 李四, email: lisiexample.com } 查询成功共返回 2 行数据。恭喜你已经完成了前端Node.js环境与SQL Server数据库的第一次对话。4. 核心操作进阶增删改查与参数化查询只会查询可不够我们得能完整地操作数据。同时安全是重中之重直接拼接SQL字符串是危险的行为我们必须使用参数化查询来防止SQL注入攻击。4.1 安全基石参数化查询Prepared Statements为什么必须参数化想象一下你的查询语句有一部分来自用户输入比如搜索框。如果直接拼接“SELECT * FROM Products WHERE name ” userInput “”。当用户输入‘ OR ‘1’‘1时整个语句的意思就变成了SELECT * FROM Products WHERE name ‘’ OR ‘1’‘1’条件永远为真导致泄露所有数据。这就是SQL注入。tedious使用Request对象的addParameter方法来添加参数。让我们以插入INSERT数据为例function insertUser() { const sql INSERT INTO Users (username, email, createdAt) VALUES (username, email, GETDATE()) ; const request new Request(sql, (err, rowCount) { if (err) { console.error(插入数据失败:, err); } else { console.log(成功插入 ${rowCount} 条记录。); } connection.close(); }); // 添加参数参数名、数据类型、值 request.addParameter(username, TYPES.VarChar, 王五); request.addParameter(email, TYPES.VarChar, wangwuexample.com); // 注意需要引入 TYPES 类型常量 const { TYPES } require(tedious); connection.execSql(request); }关键点SQL语句中使用参数名来定义参数占位符。addParameter方法需要三个参数参数名不带、SQL数据类型使用TYPES常量、参数值。TYPES中定义了所有SQL Server支持的数据类型如TYPES.Int,TYPES.NVarChar,TYPES.DateTime等。选择正确的类型很重要。4.2 完整CRUD操作示例我们将增、删、改、查和参数化查询结合起来写一个更综合的例子。假设我们连接成功后按顺序执行以下操作查、增、改、删。我们需要修改连接成功的回调使其按顺序执行一系列操作。为了处理异步我们用一个简单的“回调地狱”示例来演示流程实际项目建议使用Promise或async/await封装。// 需要引入 TYPES const { Connection, Request, TYPES } require(tedious); // ... 连接配置和连接创建代码同上 ... connection.on(connect, (err) { if (err) { console.error(连接失败:, err.message); return; } console.log(连接成功); // 1. 首先查询现有用户 queryUsers(() { // 2. 查询完成后插入一个新用户 insertNewUser(() { // 3. 插入完成后更新这个用户的邮箱 updateUserEmail(() { // 4. 最后删除这个用户清理测试数据 deleteUser(() { console.log(所有操作完成); connection.close(); }); }); }); }); }); function queryUsers(callback) { const sql SELECT id, username, email FROM Users; const request new Request(sql, (err) { if (err) console.error(查询失败:, err); console.log(--- 查询操作完成 ---); callback(); }); request.on(row, (cols) { console.log(用户: ${cols[0].value}, ${cols[1].value}, ${cols[2].value}); }); connection.execSql(request); } function insertNewUser(callback) { const sql INSERT INTO Users (username, email) VALUES (username, email); const request new Request(sql, (err, rowCount) { if (err) console.error(插入失败:, err); else console.log(插入成功影响行数: ${rowCount}); console.log(--- 插入操作完成 ---); callback(); }); request.addParameter(username, TYPES.VarChar, 测试用户); request.addParameter(email, TYPES.VarChar, testexample.com); connection.execSql(request); } function updateUserEmail(callback) { // 假设我们要更新刚才插入的‘测试用户’的邮箱 const sql UPDATE Users SET email newEmail WHERE username username; const request new Request(sql, (err, rowCount) { if (err) console.error(更新失败:, err); else console.log(更新成功影响行数: ${rowCount}); console.log(--- 更新操作完成 ---); callback(); }); request.addParameter(newEmail, TYPES.VarChar, updatedexample.com); request.addParameter(username, TYPES.VarChar, 测试用户); connection.execSql(request); } function deleteUser(callback) { const sql DELETE FROM Users WHERE username username; const request new Request(sql, (err, rowCount) { if (err) console.error(删除失败:, err); else console.log(删除成功影响行数: ${rowCount}); console.log(--- 删除操作完成 ---); callback(); }); request.addParameter(username, TYPES.VarChar, 测试用户); connection.execSql(request); }这个例子虽然用了多层回调俗称“回调地狱”但清晰地展示了四个基本操作的代码结构。在真实项目中你一定会用Promise或async/await来优化它让代码变成线性的、更易读的形式。5. 连接池管理与生产环境实践单个连接在简单脚本里够用但对于Web服务器或需要频繁操作数据库的应用频繁创建和销毁连接开销巨大。连接池Connection Pool就是解决方案它预先创建好一定数量的连接放在“池子”里应用需要时从池中取用用完后归还而不是关闭。5.1 为什么需要连接池想象一下你的Node.js API服务器每个用户请求都需要查询数据库。如果没有连接池每个请求都会经历“建立TCP连接 - 数据库登录认证 - 执行SQL - 断开连接”的完整过程。其中建立连接和认证的开销非常高在高并发下数据库和服务器都会不堪重负。连接池的优势性能提升避免了重复建立连接的开销。资源控制可以限制最大连接数防止数据库被过多连接拖垮。连接复用健康的连接可以被多个操作重复使用。tedious本身不直接提供连接池但我们可以使用另一个非常流行的库mssql它底层默认使用tedious并提供了开箱即用的连接池管理。这也是为什么很多项目直接选用mssql的原因。5.2 使用mssql库简化操作首先安装mssqlnpm install mssql使用mssql重写我们的查询示例你会发现代码简洁了很多const sql require(mssql); // 配置对象与tedious略有不同 const config { user: your_username, password: your_password, server: localhost, database: your_database_name, pool: { max: 10, // 连接池最大连接数 min: 0, // 连接池最小连接数 idleTimeoutMillis: 30000 // 连接在关闭前可以空闲的时间毫秒 }, options: { encrypt: true, trustServerCertificate: true } }; async function connectAndQuery() { try { // 连接到数据库内部管理连接池 await sql.connect(config); console.log(已连接到数据库通过连接池); // 执行一个简单查询 const result await sql.querySELECT id, username FROM Users; console.log(查询结果:, result.recordset); // recordset 就是结果数组 // 参数化查询也非常简洁 const userId 1; const result2 await sql.querySELECT * FROM Users WHERE id ${userId}; console.log(参数化查询结果:, result2.recordset); } catch (err) { console.error(数据库操作错误:, err); } finally { // 关闭连接池通常在应用关闭时调用 await sql.close(); console.log(连接已关闭); } } connectAndQuery();可以看到mssql的优势自动连接池sql.connect()会初始化连接池后续所有查询都从池中获取连接。Promise API直接支持async/await代码是线性的没有回调嵌套。模板字符串查询使用带标签的模板字符串sql.querySELECT ... WHERE id ${value}可以自动进行参数化处理既安全又方便。结果集格式友好查询结果直接放在result.recordset中是一个对象数组。生产环境建议对于大多数Node.js项目直接使用mssql库是更高效、更安全的选择。它封装了连接池、错误重试、事务等复杂逻辑让你能更专注于业务代码。tedious更适合需要极细粒度控制底层连接或者学习底层原理的场景。6. 常见错误排查与调试技巧在实际操作中你几乎一定会遇到各种连接或查询错误。别慌大部分错误都有明确的提示。这里整理了一份常见问题速查表。错误现象可能原因解决方案连接失败Login failed for user ‘xxx’1. 用户名或密码错误。2. SQL Server身份验证未启用。3. 用户没有访问该数据库的权限。1. 仔细核对用户名密码注意大小写。2. 在SQL Server Management Studio (SSMS)中检查服务器属性 - 安全性确保已启用“SQL Server和Windows身份验证模式”。3. 在SSMS中为该用户授予对应数据库的登录和访问权限。连接失败Cannot connect to localhost:1433或超时1. SQL Server服务未启动。2. TCP/IP协议未启用。3. 防火墙阻止了1433端口。4. 服务器地址或端口号错误。1. 打开“服务”找到“SQL Server (MSSQLSERVER)”或你的实例名确保其状态为“正在运行”。2. 使用“SQL Server配置管理器”在“SQL Server网络配置” - “XXX的协议”中启用“TCP/IP”。3. 在防火墙中添加入站规则允许1433端口。4. 确认服务器地址远程需用IP/域名和端口。连接失败Failed to connect to localhost:1433 - Could not connect (sequence)客户端驱动无法建立到服务器的网络连接。先尝试用SSMS能否连接同一地址。如果SSMS可以而Node不行可能是Node环境问题或驱动问题。尝试ping服务器地址检查网络连通性。执行查询错误Invalid object name ‘Users’1. 表名拼写错误。2. 连接配置中的database选项不正确导致连接到了错误的数据库。3. 表不在当前用户的默认架构下需要指定架构名如dbo.Users。1. 检查SQL语句中的表名。2. 确认config.options.database的值。3. 尝试在表名前加上架构名如SELECT * FROM dbo.Users。参数化查询错误The parameterized query ‘…’ expects the parameter ‘username’, which was not supplied在SQL语句中定义了参数如username但在代码中没有通过addParameter方法提供对应的值。检查Request对象确保为SQL中每一个开头的参数都调用了addParameter方法且参数名一致不含。错误Connection lost - The connection was closed by the server连接空闲时间过长被服务器断开。使用连接池如mssql可以自动处理断线重连。如果使用原始tedious连接需要自己监听error事件并实现重连逻辑。使用mssql时错误ConnectionError: Failed to connect to localhost:1433 - Could not connect (sequence)mssql底层使用tedious同样需要确保SQL Server服务、TCP/IP、防火墙等配置正确。排查步骤与上述tedious连接失败相同。另外确保安装的mssql和tedious版本兼容。调试心法从简到繁先确保最基本的连接sql.connect或new Connection能成功。可以写一个最简单的脚本只连接不执行任何查询。分离问题如果连接成功但查询失败将你的SQL语句复制到SSMS或Azure Data Studio里直接运行看是否是SQL语法或权限问题。善用错误信息Node.js和SQL Server返回的错误信息通常非常具体仔细阅读第一行往往就能定位到问题根源。查看详细日志在tedious的配置中可以设置options.debug为true或者在创建Connection时监听debug事件来获取更详细的通信日志。const connection new Connection(config); connection.on(debug, (message) { console.log(调试信息:, message); });7. 项目结构优化与异步流程控制当我们把数据库操作集成到一个真正的Node.js应用比如一个Express API服务器时代码的组织方式和异步处理就变得至关重要。我们不能把数据库配置和操作逻辑都堆在app.js里。7.1 模块化拆分一个良好的结构能让代码更易维护。我推荐这样组织你的项目node-sqlserver-project/ ├── config/ │ └── database.js # 数据库连接配置 ├── models/ # 数据模型/实体 │ └── userModel.js # 用户相关的数据库操作 ├── app.js # 应用主入口 ├── package.json └── .gitignore1. 集中管理配置 (config/database.js)// config/database.js const sql require(mssql); const dbConfig { user: process.env.DB_USER || your_username, password: process.env.DB_PASSWORD || your_password, server: process.env.DB_SERVER || localhost, database: process.env.DB_NAME || your_database, options: { encrypt: true, trustServerCertificate: true, }, pool: { max: 10, min: 0, idleTimeoutMillis: 30000 } }; // 导出一个获取连接池的函数 async function getConnection() { try { // sql.connect 会返回连接池多次调用返回同一个池 const pool await sql.connect(dbConfig); return pool; } catch (err) { console.error(数据库连接池创建失败:, err); throw err; // 向上抛出错误由调用者处理 } } module.exports { sql, // 也可以导出sql对象方便直接使用其方法 getConnection, dbConfig };2. 封装数据操作层 (models/userModel.js)// models/userModel.js const { getConnection, sql } require(../config/database); class UserModel { // 获取所有用户 async getAllUsers() { try { const pool await getConnection(); const result await pool.request().query(SELECT id, username, email FROM Users); return result.recordset; // 返回用户数组 } catch (err) { console.error(获取用户列表失败:, err); throw err; } } // 根据ID获取用户 async getUserById(id) { try { const pool await getConnection(); const result await pool.request() .input(id, sql.Int, id) // 使用.input方法添加参数 .query(SELECT * FROM Users WHERE id id); return result.recordset[0]; // 返回第一个用户对象或undefined } catch (err) { console.error(获取用户(ID: ${id})失败:, err); throw err; } } // 创建用户 async createUser(username, email) { try { const pool await getConnection(); const result await pool.request() .input(username, sql.VarChar, username) .input(email, sql.VarChar, email) .query(INSERT INTO Users (username, email) OUTPUT Inserted.id VALUES (username, email)); // OUTPUT Inserted.id 可以返回新插入行的id return result.recordset[0]; // 返回包含新id的对象如 { id: 10 } } catch (err) { console.error(创建用户失败:, err); // 这里可以处理特定错误如重复键错误 if (err.number 2627) { // SQL Server 唯一键冲突错误号 throw new Error(用户名或邮箱已存在); } throw err; } } } module.exports new UserModel(); // 导出一个单例实例7.2 在主应用中使用模型现在在你的主文件如app.js或路由文件中使用模型就非常清晰了// app.js const express require(express); const userModel require(./models/userModel); const app express(); app.use(express.json()); // 用于解析JSON请求体 // 获取所有用户的API端点 app.get(/api/users, async (req, res) { try { const users await userModel.getAllUsers(); res.json(users); } catch (err) { console.error(API /api/users 错误:, err); res.status(500).json({ error: 获取用户列表失败 }); } }); // 创建用户的API端点 app.post(/api/users, async (req, res) { const { username, email } req.body; if (!username || !email) { return res.status(400).json({ error: 用户名和邮箱为必填项 }); } try { const newUser await userModel.createUser(username, email); res.status(201).json({ message: 用户创建成功, userId: newUser.id }); } catch (err) { // 捕获模型层抛出的自定义错误 if (err.message 用户名或邮箱已存在) { return res.status(409).json({ error: err.message }); } res.status(500).json({ error: 创建用户失败 }); } }); const PORT process.env.PORT || 3000; app.listen(PORT, () { console.log(服务器运行在 http://localhost:${PORT}); });这样的结构将数据库配置、数据访问逻辑和Web API路由清晰地分离开。模型层 (UserModel) 负责所有与Users表交互的细节控制器层路由处理函数只关心HTTP请求和响应代码的可读性、可测试性和可维护性都大大提升。关于异步错误处理注意我们在所有async函数中都使用了try...catch。这是处理Promise拒绝rejection的标准做法可以防止未处理的Promise错误导致整个Node.js进程崩溃。在Web服务器中务必确保每个异步路由都有错误处理并向客户端返回适当的HTTP状态码和错误信息。
