建議收藏：不容錯過的 Node.js 項目架構

Express.js 是用於開發 Node.js REST API 的優秀框架，可是它並無爲您提供有關如何組織 Node.js 項目的任何線索。

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

正確的組織 Node.js 項目結構將避免重複代碼、提升服務的穩定性和擴展性。

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

若是您須要幫助調整 Node.js 項目架構，只需給我發一封信 sam@softwareontheroad.com。

目錄
目錄結構
三層架構
服務層
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: 'test@example.com',
 };

 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 服務器配置拆分爲能夠獨立加載的小模塊。