在express.js应用中，当需要在主应用文件与独立的路由模块之间共享并修改一个全局数组时，`app.locals`提供了一种简洁有效的解决方案。本文将详细介绍如何利用`app.locals`在`index.js`中定义一个数组，并在路由处理函数（如`module.js`）中安全地访问和更新该数组，确保数据在整个应用生命周期内的可访问性与一致性。
在构建复杂的Express.js应用时，我们经常需要将路由逻辑拆分到独立的模块中，以保持代码的整洁和可维护性。然而，这种模块化也带来了一个常见问题：如何在主应用文件（通常是index.js）中定义一个全局变量（例如一个数组），并允许不同的路由模块访问并修改它？直接通过require或module.exports传递复杂对象可能会导致循环依赖或管理上的混乱。Express.js 提供了一个优雅的解决方案——app.locals。
理解 app.locals
app.locals 是 Express 应用程序对象上的一个属性，用于存储应用程序级别的本地变量。这些变量在整个应用程序的生命周期中都可用，并且可以在任何地方通过 req.app.locals 或直接通过 app.locals 访问。它特别适用于存储那些在整个应用中都需要共享和访问的数据，例如配置信息、辅助函数或本教程中讨论的共享数组。
共享与修改全局数组的实现
以下是如何在主文件 (index.js) 中定义一个数组，并通过 app.locals 传递给路由模块 (module.js) 进行访问和修改的详细步骤。
1. 在主应用文件 (index.js) 中定义和暴露数组
首先，在你的主应用文件 (index.js) 中定义一个数组，并将其挂载到 app.locals 上。
// index.js const express = require('express'); const app = express(); const port = 3000; // 定义一个全局数组 let sharedArray = []; // 将 sharedArray 挂载到 app.locals // 这样在任何地方都可以通过 req.app.locals.mySharedArray 访问 app.locals.mySharedArray = sharedArray; // 引入路由模块 app.use(express.json()); // 用于解析POST请求体 app.use('/create', require('./routes/myModule')); // 假设你的路由文件在 ./routes/myModule.js app.get('/', (req, res) => { res.send(`当前共享数组内容: ${JSON.stringify(req.app.locals.mySharedArray)}`); }); app.listen(port, () => { console.log(`服务器运行在 http://localhost:${port}`); console.log('初始共享数组:', app.locals.mySharedArray); });
在这个 index.js 文件中：
- 我们创建了一个名为 sharedArray 的普通 javaScript 数组。
- 通过 app.locals.mySharedArray = sharedArray;，我们将这个数组附加到了 app.locals 对象上。注意，我们给它起了一个新的键名 mySharedArray，这是在路由中访问时需要使用的名称。
- 我们配置了一个 /create 路由，它将由 myModule.js 文件中的路由器处理。
- 添加了一个简单的根路由 /，用于展示当前 sharedArray 的内容，方便测试。
2. 在路由模块 (myModule.js) 中访问和修改数组
接下来，在你的路由模块中，你可以通过 req.app.locals 来访问这个共享数组，并对其进行操作。
// routes/myModule.js const express = require('express'); const router = express.Router(); router.post('/', async (req, res) => { // 从 req.app.locals 中获取共享数组 let currentSharedArray = req.app.locals.mySharedArray; // 假设请求体中包含要添加到数组的数据 const newItem = req.body.item; if (newItem) { currentSharedArray.push(newItem); // 修改数组 console.log('数组已更新:', currentSharedArray); res.status(200).json({ message: '项目已添加到共享数组', currentArray: currentSharedArray }); } else { res.status(400).json({ message: '请求体中缺少要添加的项目' }); } }); router.get('/', (req, res) => { // 也可以在GET请求中查看数组内容 res.status(200).json({ message: '当前共享数组内容', currentArray: req.app.locals.mySharedArray }); }); module.exports = router;
在这个 myModule.js 文件中：
- 在 router.post(‘/’) 处理器内部，我们通过 req.app.locals.mySharedArray 访问了在 index.js 中定义的 sharedArray。
- 我们从请求体 (req.body.item) 中获取新数据，并使用 push() 方法将其添加到 currentSharedArray 中。由于 currentSharedArray 引用的是 index.js 中定义的同一个数组对象，因此对它的修改会反映在整个应用程序中。
- 添加了一个简单的 GET /create 路由来直接查看该路由模块中访问到的数组内容。
运行与测试
- 确保你的项目结构如下：
your-express-app/ ├── index.js └── routes/ └── myModule.js
- 安装 express：npm install express
- 运行 index.js：node index.js
- 打开浏览器访问 http://localhost:3000，你将看到初始的空数组。
- 使用 curl 或 postman 发送 POST 请求到 http://localhost:3000/create：
curl -X POST -H "Content-Type: application/json" -d '{"item": "first-item"}' http://localhost:3000/create
你将收到响应，并且服务器控制台会打印更新后的数组。
- 再次访问 http://localhost:3000，你会发现数组已经包含了 “first-item”。
- 可以多次发送 POST 请求，每次添加不同的项目，然后刷新根路径或访问 http://localhost:3000/create (GET 请求)来观察数组的变化。
注意事项与最佳实践
- 全局性与可变性： app.locals 中的数据是应用程序级别的，对它的修改会影响所有后续请求。如果共享的数据是可变的（如本例中的数组），并且会被多个请求并发修改，需要考虑潜在的竞态条件。在javascript的单线程事件循环模型下，对于简单的数组操作通常不是大问题，但对于更复杂的数据结构或需要严格同步的场景，可能需要额外的同步机制（例如使用队列、数据库或专门的状态管理库）。
- 数据类型： app.locals 可以存储任何 JavaScript 值，包括对象、数组、函数等。
- 用途： app.locals 最适合存储那些在应用程序启动时初始化，并在整个应用程序生命周期中保持相对稳定或需要全局访问的数据。例如：应用程序名称、版本号、数据库连接池、共享配置对象等。
- 与 res.locals 的区别： res.locals 用于存储在单个请求-响应周期内有效的变量，通常用于模板渲染时传递数据。而 app.locals 则是应用程序级别的。
- 避免过度使用： 尽管 app.locals 方便，但过度依赖全局变量可能导致代码难以测试和维护。对于请求特定的数据或需要更严格隔离的数据，应考虑使用中间件、请求对象 (req.body, req.params, req.query) 或依赖注入等其他机制。
总结
通过 app.locals，Express.js 提供了一种强大而直接的方式来在应用程序的不同模块之间共享和修改全局数据。本教程展示了如何设置一个共享数组，并在路由处理程序中安全地访问和更新它。理解 app.locals 的作用及其适用场景，将帮助你构建更健壮、更模块化的 Express.js 应用程序。