Express.js 是用於開發 Node.js REST API 的優秀框架，但是它並沒有為您提供有關如何組織 Node.js 專案的任何線索。

雖然聽起來很傻，但這確實是個問題。

正確的組織 Node.js 專案結構將避免重複程式碼、提高服務的穩定性和擴充套件性。

這篇文章是基於我多年來在處理一些糟糕的 Node.js 專案結構、不好的設計模式以及無數個小時的程式碼重構經驗的探索研究。

如果您需要幫助調整 Node.js 專案架構，只需給我發一封信 [email protected]。

目錄目錄結構 三層架構 服務層 Pub/Sub 層 ️️️️依賴注入單元測試Cron Jobs 和重複任務 配置和金鑰 Loaders 目錄結構

這是我要談論的 Node.js 專案結構。

我在構建的每個 Node.js REST API 服務中都使用了下面這個結構，讓我們了解下每個元件的功能。

src │ app.js # App 入口 └───api # Express route controllers for all the endpoints of the app └───config # 環境變數和配置相關 └───jobs # 對於 agenda.js 的任務排程定義 └───loaders # 將啟動過程拆分為模組 └───models # 資料庫模型 └───services # 所有的業務邏輯應該在這裡 └───subscribers # 非同步任務的事件處理程式 └───types # 對於 Typescript 的型別宣告檔案（d.ts）

以上不僅僅是組織 JavaScript 檔案的一種方式...

三層架構

其思想是使用關注點分離原則將業務邏輯從 Node.js API 路由中移開。

因為有一天，您將希望在一個 CLI 工具上來使用您的業務邏輯，又或從來不使用。對於一些重複的任務，然後從 Node.js 伺服器上對它自己進行呼叫，顯然這不是一個好的主意。

不要將您的業務邏輯放入控制器中!!

你可能想用 Express.js 的 Controllers 層來儲存應用層的業務邏輯，但是很快你的程式碼將會變得難以維護，只要你需要編寫單元測試，就需要編寫 Express.js req 或 res 物件的複雜模擬。

判斷何時應該傳送響應以及何時應該在 “後臺” 繼續處理（例如，將響應傳送到客戶端之後），這兩個問題比較複雜。

route.post('/', async (req, res, next) => { // 這應該是一箇中間件或者應該由像 Joi 這樣的庫來處理 // Joi 是一個數據校驗的庫 github.com/hapijs/joi const userDTO = req.body; const isUserValid = validators.user(userDTO) if(!isUserValid) { return res.status(400).end(); } // 這裡有很多業務邏輯... const userRecord = await UserModel.create(userDTO); delete userRecord.password; delete userRecord.salt; const companyRecord = await CompanyModel.create(userRecord); const companyDashboard = await CompanyDashboard.create(userRecord, companyRecord); ...whatever... // 這就是把一切都搞砸的“優化”。 // 響應被髮送到客戶端... res.json({ user: userRecord, company: companyRecord }); // 但程式碼塊仍在執行 :( const salaryRecord = await SalaryModel.create(userRecord, companyRecord); eventTracker.track('user_signup',userRecord,companyRecord,salaryRecord); intercom.createUser(userRecord); gaAnalytics.event('user_signup',userRecord); await EmailService.startSignupSequence(userRecord) });

將業務邏輯用於服務層

這一層是放置您的業務邏輯。

遵循適用於 Node.js 的 SOLID 原則，它只是一個具有明確目的的類的集合。

這一層不應存在任何形式的 “SQL 查詢”，可以使用資料訪問層。

從 Express.js 的路由器移除你的程式碼。不要將 req 或 res 傳遞給服務層不要從服務層返回任何與 HTTP 傳輸層相關的資訊，例如 status code（狀態碼）或者 headers

例子

route.post('/',  validators.userSignup, // 這個中間層負責資料校驗 async (req, res, next) => { // 路由層實際負責的 const userDTO = req.body; // 呼叫 Service 層 // 關於如何訪問資料層和業務邏輯層的抽象 const { user, company } = await UserService.Signup(userDTO); // 返回一個響應到客戶端 return res.json({ user, company }); });

這是您的服務在後臺的執行方式。

import UserModel from '../models/user';import CompanyModel from '../models/company';export default class UserService { async Signup(user) { const userRecord = await UserModel.create(user); const companyRecord = await CompanyModel.create(userRecord); // needs userRecord to have the database id  const salaryRecord = await SalaryModel.create(userRecord, companyRecord); // depends on user and company to be created ...whatever await EmailService.startSignupSequence(userRecord) ...do more stuff return { user: userRecord, company: companyRecord }; }}

釋出與訂閱層

pub/sub 模式超出了這裡提出的經典的 3 層架構，但它非常有用。

現在建立一個使用者的簡單 Node.js API 端點，也許是呼叫第三方服務，也許是一個分析服務，也許是開啟一個電子郵件序列。

不久之後，這個簡單的 “建立” 操作將完成幾件事，最終您將獲得 1000 行程式碼，所有這些都在一個函式中。

這違反了單一責任原則。

因此，最好從一開始就將職責劃分，以使您的程式碼保持可維護性。

import UserModel from '../models/user'; import CompanyModel from '../models/company'; import SalaryModel from '../models/salary'; export default class UserService() { async Signup(user) { const userRecord = await UserModel.create(user); const companyRecord = await CompanyModel.create(user); const salaryRecord = await SalaryModel.create(user, salary); eventTracker.track( 'user_signup', userRecord, companyRecord, salaryRecord ); intercom.createUser( userRecord ); gaAnalytics.event( 'user_signup', userRecord ); await EmailService.startSignupSequence(userRecord) ...more stuff return { user: userRecord, company: companyRecord }; } }

強制呼叫依賴服務不是一個好的做法。

一個最好的方法是觸發一個事件，即 “user_signup”，像下面這樣已經完成了，剩下的就是事件監聽者的事情了。

import UserModel from '../models/user'; import CompanyModel from '../models/company'; import SalaryModel from '../models/salary'; export default class UserService() { async Signup(user) { const userRecord = await this.userModel.create(user); const companyRecord = await this.companyModel.create(user); this.eventEmitter.emit('user_signup', { user: userRecord, company: companyRecord }) return userRecord } }

現在，您可以將事件處理程式/偵聽器拆分為多個檔案。

eventEmitter.on('user_signup', ({ user, company }) => { eventTracker.track( 'user_signup', user, company, ); intercom.createUser( user ); gaAnalytics.event( 'user_signup', user );})

eventEmitter.on('user_signup', async ({ user, company }) => { const salaryRecord = await SalaryModel.create(user, company);})

eventEmitter.on('user_signup', async ({ user, company }) => { await EmailService.startSignupSequence(user)})

你可以將 await 語句包裝到 try-catch 程式碼塊中，也可以讓它失敗並通過 'unhandledPromise' 處理 process.on('unhandledRejection',cb)。

依賴注入

DI 或控制反轉（IoC）是一種常見的模式，通過 “注入” 或通過建構函式傳遞類或函式的依賴關係，有助於程式碼的組織。

通過這種方式，您可以靈活地注入“相容的依賴項”，例如，當您為服務編寫單元測試時，或者在其他上下文中使用服務時。

沒有 DI 的程式碼

import UserModel from '../models/user';import CompanyModel from '../models/company';import SalaryModel from '../models/salary'; class UserService { constructor(){} Sigup(){ // Caling UserMode, CompanyModel, etc ... }}

帶有手動依賴項注入的程式碼

export default class UserService { constructor(userModel, companyModel, salaryModel){ this.userModel = userModel; this.companyModel = companyModel; this.salaryModel = salaryModel; } getMyUser(userId){ // models available throug 'this' const user = this.userModel.findById(userId); return user; }}

在您可以注入自定義依賴項。

import UserService from '../services/user';import UserModel from '../models/user';import CompanyModel from '../models/company';const salaryModelMock = { calculateNetSalary(){ return 42; }}const userServiceInstance = new UserService(userModel, companyModel, salaryModelMock);const user = await userServiceInstance.getMyUser('12346');

服務可以擁有的依賴項數量是無限的，當您新增一個新服務時，重構它的每個例項化是一項乏味且容易出錯的任務。這就是建立依賴注入框架的原因。

這個想法是在類中定義你的依賴，當你需要一個類的例項時只需要呼叫 “Service Locator” 即可。

現在讓我們來看一個使用 TypeDI 的 NPM 庫示例，以下 Node.js 示例將引入 DI。

可以在官網檢視更多關於 TypeDI 的資訊。

typescript 示例

import { Service } from 'typedi';@Service()export default class UserService { constructor( private userModel, private companyModel,  private salaryModel ){} getMyUser(userId){ const user = this.userModel.findById(userId); return user; }}

services/user.ts

現在 TypeDI 將負責解決 UserService 需要的任何依賴項。

import { Container } from 'typedi';import UserService from '../services/user';const userServiceInstance = Container.get(UserService);const user = await userServiceInstance.getMyUser('12346');

濫用 service locator 呼叫是一種 anti-pattern（反面模式）

依賴注入與 Express.js 結合實踐

在 Express.js 中使用 DI 是 Node.js 專案體系結構的最後一個難題。

路由層

route.post('/',  async (req, res, next) => { const userDTO = req.body; const userServiceInstance = Container.get(UserService) // Service locator const { user, company } = userServiceInstance.Signup(userDTO); return res.json({ user, company }); });

太好了，專案看起來很棒！它是如此的有條理，使我現在想編碼。

單元測試示例

通過使用依賴項注入和這些組織模式，單元測試變得非常簡單。

你不必模擬 req/res 物件或 require(...) 呼叫。

示例：使用者註冊方法的單元測試

tests/unit/services/user.js

import UserService from '../../../src/services/user'; describe('User service unit tests', () => { describe('Signup', () => { test('Should create user record and emit user_signup event', async () => { const eventEmitterService = { emit: jest.fn(), }; const userModel = { create: (user) => { return { ...user, _id: 'mock-user-id' } }, }; const companyModel = { create: (user) => { return { owner: user._id, companyTaxId: '12345', } }, }; const userInput= { fullname: 'User Unit Test', email: '[email protected]', }; const userService = new UserService(userModel, companyModel, eventEmitterService); const userRecord = await userService.SignUp(teamId.toHexString(), userInput); expect(userRecord).toBeDefined(); expect(userRecord._id).toBeDefined(); expect(eventEmitterService.emit).toBeCalled(); }); }) })

Cron Jobs 和重複任務

因此，既然業務邏輯封裝到了服務層中，那麼從 Cron job 中使用它就更容易了。

您不應該依賴 Node.js setTimeout 或其他延遲程式碼執行的原始方法，而應該依賴於一個將您的 Jobs 及其執行持久化到資料庫中的框架。

這樣您將控制失敗的 Jobs 和一些成功者的反饋，可參考我寫的關於最佳 Node.js 工作管理員 softwareontheroad.com/nodejs-scal…

配置和金鑰

遵循經過測試驗證適用於 Node.js 的 Twelve-Factor App（十二要素應用 12factor.net/）概念，這是儲存 API 金鑰和資料庫連結字串的最佳實踐，它是用的 dotenv。

放置一個 .env 檔案，這個檔案永遠不能提交（但它必須與預設值一起存在於儲存庫中），然後，這個 dotenv NPM 包將會載入 .env 檔案並將裡面的變數寫入到 Node.js 的 process.env 物件中。

這就足夠了，但是，我想增加一個步驟。有一個 config/index.ts 檔案，其中 NPM 包 dotenv 載入 .env

檔案，然後我使用一個物件儲存變數，因此我們具有結構和程式碼自動完成功能。

config/index.js

const dotenv = require('dotenv'); // config() 將讀取您的 .env 檔案，解析其中的內容並將其分配給 process.env dotenv.config(); export default { port: process.env.PORT, databaseURL: process.env.DATABASE_URI, paypal: { publicKey: process.env.PAYPAL_PUBLIC_KEY, secretKey: process.env.PAYPAL_SECRET_KEY, }, paypal: { publicKey: process.env.PAYPAL_PUBLIC_KEY, secretKey: process.env.PAYPAL_SECRET_KEY, }, mailchimp: { apiKey: process.env.MAILCHIMP_API_KEY, sender: process.env.MAILCHIMP_SENDER, } }

這樣，您可以避免使用 process.env.MY_RANDOM_VAR 指令來充斥程式碼，並且通過自動補全，您不必知道如何命名環境變數。

Loaders

我從 W3Tech 的微框架中採用這種模式，但並不依賴於它們的包裝。

這個想法是將 Node.js 的啟動過程拆分為可測試的模組。

讓我們看一下經典的 Express.js 應用初始化

const mongoose = require('mongoose'); const express = require('express'); const bodyParser = require('body-parser'); const session = require('express-session'); const cors = require('cors'); const errorhandler = require('errorhandler'); const app = express(); app.get('/status', (req, res) => { res.status(200).end(); }); app.head('/status', (req, res) => { res.status(200).end(); }); app.use(cors()); app.use(require('morgan')('dev')); app.use(bodyParser.urlencoded({ extended: false })); app.use(bodyParser.json(setupForStripeWebhooks)); app.use(require('method-override')()); app.use(express.static(__dirname + '/public')); app.use(session({ secret: process.env.SECRET, cookie: { maxAge: 60000 }, resave: false, saveUninitialized: false })); mongoose.connect(process.env.DATABASE_URL, { useNewUrlParser: true }); require('./config/passport'); require('./models/user'); require('./models/company'); app.use(require('./routes')); app.use((req, res, next) => { var err = new Error('Not Found'); err.status = 404; next(err); }); app.use((err, req, res) => { res.status(err.status || 500); res.json({'errors': { message: err.message, error: {} }}); }); ... more stuff  ... maybe start up Redis ... maybe add more middlewares async function startServer() {  app.listen(process.env.PORT, err => { if (err) { console.log(err); return; } console.log(`Your server is ready !`); }); } // Run the async function to start our server startServer();

如您所見，應用程式的這一部分可能真是一團糟。

這是一種有效的處理方法。

const loaders = require('./loaders');const express = require('express');async function startServer() { const app = express(); await loaders.init({ expressApp: app }); app.listen(process.env.PORT, err => { if (err) { console.log(err); return; } console.log(`Your server is ready !`); });}startServer();

現在目的很明顯 loaders 僅僅是一個小檔案。

loaders/index.js

 import expressLoader from './express'; import mongooseLoader from './mongoose'; export default async ({ expressApp }) => { const mongoConnection = await mongooseLoader(); console.log('MongoDB Intialized'); await expressLoader({ app: expressApp }); console.log('Express Intialized'); // ... more loaders can be here // ... Initialize agenda // ... or Redis, or whatever you want }

The express loader

loaders/express.js

import * as express from 'express';import * as bodyParser from 'body-parser';import * as cors from 'cors';export default async ({ app }: { app: express.Application }) => { app.get('/status', (req, res) => { res.status(200).end(); }); app.head('/status', (req, res) => { res.status(200).end(); }); app.enable('trust proxy'); app.use(cors()); app.use(require('morgan')('dev')); app.use(bodyParser.urlencoded({ extended: false })); // ...More middlewares // Return the express app return app;})

The mongo loader

loaders/mongoose.js

import * as mongoose from 'mongoose'export default async (): Promise<any> => { const connection = await mongoose.connect(process.env.DATABASE_URL, { useNewUrlParser: true }); return connection.connection.db;}

結論

我們深入研究了經過生產測試的 Node.js 專案結構，以下是一些總結的技巧：

使用 3 層架構。不要將您的業務邏輯放入 Express.js 控制器中。使用 Pub/Sub 模式併為後臺任務觸發事件。進行依賴注入，讓您高枕無憂。切勿洩漏您的密碼、機密和 API 金鑰，請使用配置管理器。將您的 Node.js 伺服器配置拆分為可以獨立載入的小模組。