更新于 04/21/2019: 示例代码在这个 Github 项目中，欢迎参与优化

引言

在 node.js 领域中，Express.js 是一个为人所熟知的 REST APIs 开发框架。虽然它非常的出色，但是该如何组织的项目代码，却没人告诉你。

通常这没什么，不过对于开发者而言这又是我们必须面对的问题。

一个好的项目结构，不仅能消除重复代码，提升系统稳定性，改善系统的设计，还能在将来更容易的扩展。

多年以来，我一直在处理重构和迁移项目结构糟糕、设计不合理的 node.js 项目。而这篇文章正是对我此前积累经验的总结。

目录结构 ?

下面是我所推荐的项目代码组织方式。

它来自于我参与的项目的实践，每个目录模块的功能与作用如下：

  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)

而且，这不仅仅只是代码的组织方式...

3 层结构 ?

这个想法源自 关注点分离原则，把业务逻辑从 node.js API 路由中分离出去。

因为将来的某天，你可能会在 CLI 工具或是其他地方处理你的业务。当然，也有可能不会，但在项目中使用API调用的方式来处理自身的业务终究不是一个好主意...

☠️ 不要在控制器中直接处理业务逻辑!! ☠️

在你的应用中，你可能经为了图便利而直接的在控制器处理业务。不幸的是，这么做的话很快你将面对相面条一样复杂的控制器代码，“恶果”也会随之而来，比如在处理单元测试的时候不得不使用复杂的 request 或 response 模拟。

同时，在决定何时向客户端返回响应，或希望在发送响应之后再进行一些处理的时候，将会变得很复杂。

请不要像下面例子这样做.

  route.post('/', async (req, res, next) => {

    // 这里推荐使用中间件或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)
  });

使用服务层（service）来处理业务 ?

在单独的服务层处理业务逻辑是推荐的做法。

这一层是遵循适用于 node.js 的 SOLID 原则的“类”的集合

在这一层中，不应该有任何形式的数据查询操作。正确的做法是使用数据访问层.

• 从 express.js 路由中清理业务代码。

• 服务层不应包含 request 和 response。

• 服务层不应返回任何与传输层关联的数据，如状态码和响应头。

示例

  route.post('/', 
    validators.userSignup, // 中间件处理验证
    async (req, res, next) => {
      // 路由的实际责任
      const userDTO = req.body;

      // 调用服务层
      // 这里演示如何访问服务层
      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); // 依赖用户的数据记录 
      const salaryRecord = await SalaryModel.create(userRecord, companyRecord); // 依赖用户与公司数据

      ...whatever

      await EmailService.startSignupSequence(userRecord)

      ...do more stuff

      return { user: userRecord, company: companyRecord };
    }
  }

在 Github 查看示例代码

使用发布/订阅模式 ?️

严格来讲发布/订阅模型并不属于 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 };
    }

  }

同步的调用依赖服务仍不是最佳的解决办法.

更好的做法是触发事件，如：一个新用户使用邮箱方式注册了。

就这样，创建用户的Api 完成了它的功能，剩下的就交给订阅事件的处理器来负责。

  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)
  })

你可以使用 try-catch 来包裹 await 语句，或 通过 process.on('unhandledRejection',cb) 的形式注册 'unhandledPromise' 的事件处理器

Dependency Injection ?

D.I. or inversion of control (IoC) is a common pattern that will help the organization of your code, by 'injecting' or passing through the constructor the dependencies of your class or function.

By doing this way you will gain the flexibility to inject a 'compatible dependency' when, for example, you write the unit tests for the service, or when the service is used in another context.

Code with no D.I

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

Code with manual dependency injection

  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;
    }
  }

Now you can inject custom dependencies.

  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');

The amount of dependencies a service can have is infinite, and refactor every instantiation of it when you add a new one is a boring and error-prone task.

That's why dependency injection frameworks were created.

The idea is you declare your dependencies in the class, and when you need an instance of that class, you just call the 'Service Locator'.

Let's see an example using typedi an npm library that brings D.I to node.js

You can read more on how to use typedi in the official documentation

WARNING typescript example

  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

Now typedi will take care of resolving any dependency the UserService require.

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

Abusing service locator calls is an anti-pattern

Using Dependency Injection with Express.js in Node.js

Using D.I. in express.js is the final piece of the puzzle for this node.js project architecture.

Routing layer

  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 });
    });

Awesome, project is looking great!
It's so organized that makes me want to be coding something right now.

Visit the example repository

An unit test example ??

By using dependency injection and these organization patterns, unit testing becomes really simple.

You don't have to mock req/res objects or require(...) calls.

Example: Unit test for signup user method

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 and recurring task ⚡

So, now that the business logic encapsulated into the service layer, it's easier to use it from a Cron job.

You should never rely on node.js setTimeout or another primitive way of delay the execution of code, but on a framework that persist your jobs, and the execution of them, in a database.

This way you will have control over the failed jobs, and feedback of those who succeed.
I already wrote on good practice for this so, check my guide on using agenda.js the best task manager for node.js.

Configurations and secrets ?

Following the battle-tested concepts of Twelve-Factor App for node.js the best approach to store API Keys and database string connections, it's by using dotenv.

Put a .env file, that must never be committed (but it has to exist with default values in your repository) then, the npm package dotenv loads the .env file and insert the vars into the process.env object of node.js.

That could be enough but, I like to add an extra step.
Have a config/index.ts file where the dotenv npm package and loads the .env file and then I use an object to store the variables, so we have a structure and code autocompletion.

config/index.js

  const dotenv = require('dotenv');
  // config() will read your .env file, parse the contents, assign it to 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,
    }
  }

This way you avoid flooding your code with process.env.MY_RANDOM_VAR instructions, and by having the autocompletion you don't have to know how to name the env var.

Visit the example repository

加载器 ?️

加载器源于 W3Tech microframework 但不依赖于他们扩展。

这个想法是指，你可以拆分启动加载过程到可测试的独立模块中。

先来看一个传统的 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 !`);
    });
  }

  // 启动服务器
  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/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');

    // ... 更多加载器

    // ... 初始化 agenda
    // ... or Redis, or whatever you want
  }

express 加载器。

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;
  })

mongo 加载器

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;
  }

在 Github 查看更多加载器的代码示例

结语

我们深入的分析了 node.js 项目的结构，下面是一些可以分享给你的总结:

• 使用3层结构。

• 控制器中不要有任何业务逻辑代码。

• 采用发布/订阅模型来处理后台异步任务。

• 使用依赖注入。

• 使用配置管理，避免泄漏密码、密钥等机密信息。

• 将 node.js 服务器的配置拆分为可独立加载的小文件。

前往 Github 查看完整示例