04.编写你的第一个 Node.js 微服务

在本章中，我们将使用 Seneca 以及其他能让我们能得益于微服务特性的框架，来构建一个基于微服务的电子商务软件。

微电子商务概览

编写微服务
调整微服务规模
创建 API
整合 Seneca 与 Express
通过 Seneca 持久化数据

我们要做的是使用流行的 JavaScript 框架创建一个聚合所有其他微服务的微服务，并为单页面应用（SPA，Single-Page Application）提供 API。

在本章中，我们将深入讨论以下 4 个微服务。

商品管理服务：负责添加、编辑和删除数据库中的商品信息，以及给客户提供商品信息。本服务只会对部分用户开放具有添加和删除商品功能的管理页面。
订单管理服务：负责管理订单与账单。
邮件服务：负责向客户发送邮件。
UI：负责给某个单页面应用提供其他微服务的特性，但是本章中我们只构建 JSON 接口。

微服务部署图如下:

从上图中可以看出，将部分微服务对外界隐藏，分别对不同的网络暴露了不同服务：

UI 将直接暴露在互联网上，所有人都可以访问它。
商品管理服务管理电子商务系统中的产品信息。它有以下两个对外接口：
- 为 UI 提供数据的 Seneca 服务端。
- 公司内部用于创建、更新和删除商品信息的 JSON API。
邮件服务是我们与客户的通信渠道。我们将通过该微服务阐述 Seneca 的优点，并会举例说明，当一个微服务宕机时，如何保证最终一致性和进行系统降级。
订单管理服务负责处理客户的订单。通过这个微服务，我们将讨论如何进行微服务数据的本地化，而不再是以系统全局共享的方式管理数据。你无法直接在本机数据库中获取商品名字或价格，而是需要通过其他微服务获取。

这个系统中并没有客户或员工信息管理功能，但是，基于上述的 4 个微服务，我们将能够深入微服务架构的核心理念。Seneca 拥有非常强大的数据存储与传输插件系统，使其能够很方便地与不同的数据存储系统、传输系统对接。

我们将使用 MongoDB 作为所有微服务的数据存储层。Seneca 提供了开箱即用的内存数据库插件，使用者可以直接开始编码。但是，内存数据库只能暂存数据，并不能持久化存储。

商品管理服务——双重核心

因为可以与 Express 直接整合，在 Seneca 上构建双重 API 是相当容易的。通过 Express，UI 可以向外界提供以下功能：编辑、添加、删除商品等，它是一个非常方便的框架。

同时，商品管理服务还可以通过Seneca TCP（Seneca 默认加载插件）让私有部分对外提供服务，因此内部网络中其他微服务（尤其是 UI）就能够访问到商品目录列表。商品管理服务将是小而具有内聚性的（它只管理商品），并且具备可伸缩性。虽然微小，但是该服务拥有处理电子商务系统中商品信息的所有能力。

我们需要做的第一件事情是定义商品管理服务的功能，如下所示：

获取数据库中所有商品信息。这在实际生产环境中或许不是一个好方法（因为一般在生产系统中可能会需要分页），但是在我们的例子中是可行的。
根据指定分类获取商品信息列表。与前一个功能类似，在生产系统中需要对结果进行分页。
根据指定 ID 获取商品信息。
将商品信息添加到数据库（本例中使用 MongoDB 作为数据库）。该功能会使用到 Seneca 的数据抽象能力，将微服务与实际存储系统解耦：我们能够（在理论上）轻易地将底层数据库从 Mongo 切换到其他存储系统。
删除商品信息。同样使用到 Seneca 的数据抽象。
编辑商品信息。

获取商品信息

为了获取商品信息，我们会直接从数据库中获取所有的商品信息返回给接口。在这种情况下，我们没有创建任何分页机制。但是，通常情况下，数据分页是避免数据库（也可能是应用，但主要是数据库）性能问题的好方法。

/**
 * 获取所有商品列表
 */
seneca.add({ area: 'product', action: 'fetch' }, function(args, done) {
  var products = this.make('products');
  products.list$({}, done);
});

这样，我们在 Seneca 中添加了一个可以返回数据库中所有商品信息的模式（pattern）。函数 products.list$() 有以下两个入参：

查询条件。
一个可以处理错误和结果对象的函数（记住错误优先回调法则）。

通过 seneca.add() 方法，我们将 done 函数传递给 list$ 方法。因为 Seneca 符合错误优先回调法则，所以这种方法有效。它相当于以下代码的简写：

seneca.add({ area: 'product', action: 'fetch' }, function(args, done) {
  var products = this.make('products');
  products.list$({}, function(err, result) {
    done(err, result);
  });
});

获取指定类别的商品

获取指定类别的商品与获取所有商品信息非常类似。唯一的区别是，在获取指定类别商品时需要传入类别参数，根据参数来筛选结果。

/**
 * 获取指定类别的商品列表
 */
seneca.add(
  { area: 'product', action: 'fetch', criteria: 'byCategory' },
  function(args, done) {
    var products = this.make('products');
    products.list$({ category: args.category }, done);
  }
);

这段代码唯一明显的区别是多了一个 category 入参，该参数将会被委派给 Seneca 的数据抽象层，并且根据底层存储系统生成相应的查询语句。

根据 ID 获取商品

根据 ID 获取商品信息是最必要的功能之一，同时它的实现也存在难点。所谓的难点，并不是在编码层面。

/**
 * 根据id获取商品
 */
seneca.add({ area: 'product', action: 'fetch', criteria: 'byId' }, function(
  args,
  done
) {
  var product = this.make('products');
  product.load$(args.id, done);
});

该功能实现的难点在于如何生成 id。id 的生成是应用与数据库的一个关联点。Mongo 通过哈希生成一个复合 ID，而 MySQL 通常采用一个自增的整型数字来唯一标识每一行记录。如果想要将应用的存储系统从 MongoDB 切换为 MySQL，首先需要解决的问题是如何将以下哈希值转换为一个整型数字：

e777d434a849760a1303b7f9f989e33a

每个微服务的数据都应该存放在本地，这意味着改变某个实体的 ID 数据类型需要同时改变其他数据库中相关联的 ID 类型。

添加商品

/**
 * 添加商品
 */
seneca.add({ area: 'product', action: 'add' }, function(args, done) {
  var products = this.make('products');
  products.category = args.category;
  products.name = args.name;
  products.description = args.description;
  products.category = args.category;
  products.price = args.price;
  products.save$(function(err, product) {
    done(err, products.data$(false));
  });
});

我们使用了 Seneca 的辅助方法 product.data$(false)，通过它我们能够获取所需的实体数据，并且返回的数据中不会包含命名空间（域）、实体名、库名等我们并不关心的元数据信息。

删除商品

删除商品的操作通常根据 id 来完成：根据指定主键来定位和删除指定商品:

/**
 * 根据id删除指定商品
 */
seneca.add({ area: 'product', action: 'remove' }, function(args, done) {
  var product = this.make('products');
  product.remove$(args.id, function(err) {
    done(err, null);
  });
});

在这段代码中，除了错误发生时会返回错误信息之外，不会返回其他任何信息；因此，对于调用终端来说，只要没有错误信息返回就表明删除动作成功。

编辑商品

/**
 * 通过id获取商品信息并编辑
 */
seneca.edit({ area: 'product', action: 'edit' }, function(args, done) {
  seneca.act(
    { area: 'product', action: 'fetch', criteria: 'byId', id: args.id },
    function(err, result) {
      result.data$({
        name: args.name,
        category: args.category,
        description: args.description,
        price: args.price
      });
      result.save$(function(err, product) {
        done(product.data$(false));
      });
    }
  );
});

这是一个值得注意的场景：在编辑商品之前，需要先根据 id 取出商品信息，这个方法我们已经实现了。因此，需要做的是，取出商品信息后，将传入的数据放入相应字段并且保存。这是 Senec

整合各模块

正如我们之前提到的，商品管理服务具有双重性：一面是使用 Seneca 通过 TCP 传输数据给其他微服务，另一面是通过 Express（Node.js 的 Web 应用框架）以 REST 风格提供服务。我们将所有代码整合如下：

var plugin = function(options) {
  var seneca = this;

  /**
   * 获取所有商品列表
   */
  seneca.add({ area: 'product', action: 'fetch' }, function(args, done) {
    var products = this.make('products');
    products.list$({}, done);
  });

  /**
   * 根据分类获取商品列表
   */
  seneca.add(
    { area: 'product', action: 'fetch', criteria: 'byCategory' },
    function(args, done) {
      var products = this.make('products');
      products.list$({ category: args.category }, done);
    }
  );

  /**
   * 根据id获取商品
   */
  seneca.add({ area: 'product', action: 'fetch', criteria: 'byId' }, function(
    args,
    done
  ) {
    var product = this.make('products');
    product.load$(args.id, done);
  });

  /**
   * 添加商品
   */
  seneca.add({ area: 'product', action: 'add' }, function(args, done) {
    var products = this.make('products');
    products.category = args.category;
    products.name = args.name;
    products.description = args.description;
    products.category = args.category;
    products.price = args.price;
    products.save$(function(err, product) {
      done(err, products.data$(false));
    });
  });

  /**
   * 根据id删除商品
   */
  seneca.add({ area: 'product', action: 'remove' }, function(args, done) {
    var product = this.make('products');
    product.remove$(args.id, function(err) {
      done(err, null);
    });
  });

  /**
   * 根据id获取商品信息并编辑
   */
  seneca.add({ area: 'product', action: 'edit' }, function(args, done) {
    seneca.act(
      { area: 'product', action: 'fetch', criteria: 'byId', id: args.id },
      function(err, result) {
        result.data$({
          name: args.name,
          category: args.category,
          description: args.description,
          price: args.price
        });
        result.save$(function(err, product) {
          done(err, product.data$(false));
        });
      }
    );
  });
};

module.exports = plugin;

var seneca = require('seneca')();
seneca.use(plugin);
seneca.use('mongo-store', {
  name: 'seneca',
  host: '127.0.0.1',
  port: '27017'
});

seneca.ready(function(err) {
  seneca.act('role:web', {
    use: {
      prefix: '/products',
      pin: { area: 'product', action: '*' },
      map: {
        fetch: { GET: true },
        edit: { GET: false, POST: true },
        delete: { GET: false, DELETE: true }
      }
    }
  });

  var express = require('express');
  var app = express();
  app.use(require('body-parser').json());

  // Seneca与Express集成
  app.use(seneca.export('web'));

  app.listen(3000);
});

我们构建了一个 Seneca 插件，该插件能够被不同的微服务复用，并且包含了前文中提到的商品管理服务需要的所有方法定义。

以上代码可以分为下列两个部分：

首先，和 Mongo 建立连接，指定 Mongo 为本地数据库。我们使用 mongo-store 插件实现以上功能（插件代码地址为https://github.com/senecajs/seneca-mongo-store，作者是 Richard Rodger，同时也是 Seneca 的作者）。
第二部分对于我们来说是个新内容。如果你曾经使用过 jQuery，可能会产生熟悉感。回调函数 seneca.ready() 需要处理调用 API 前 Seneca 和 Mongo 可能没有建立连接的情况。同时，它也包含了集成 Express 和 Seneca 的代码。

以下是应用的 package.json 文件的配置内容：

{
  "name": "Product Manager",
  "version": "1.0.0",
  "description": "Product Management sub-system",
  "main": "index.js",
  "keywords": ["microservices", "products"],
  "author": "David Gonzalez",
  "license": "ISC",
  "dependencies": {
    "body-parser": "^1.14.1",
    "debug": "^2.2.0",
    "express": "^4.13.3",
    "seneca": "^0.8.0",
    "seneca-mongo-store": "^0.2.0",
    "type-is": "^1.6.10"
  }
}

集成 Express 与 Seneca——如何创建 REST API

seneca.act('role:web', {
  use: {
    prefix: '/products',
    pin: { area: 'product', action: '*' },
    map: {
      fetch: { GET: true },
      edit: { PUT: true },
      delete: { GET: false, DELETE: true }
    }
  }
});

var express = require('express');
var app = express();
app.use(require('body-parser').json());

// 这一步对Seneca与Express进行了集成
app.use(seneca.export('web'));

app.listen(3000);

提供了下列三个 REST 服务端点：

/products/fetch
/products/edit
/products/delete

首先，我们指定 Seneca 根据配置执行 role:web action。配置信息中使用了 /product 作为所有 URL 的前缀，同时将相关 action 与匹配模式 {area: "product", action: "*"} 绑定。虽然我们在本书中第一次接触这种方式，但是这确实是 Seneca 中将 action 与 URL 绑定的一种可行方式，指明 product 这个 area 的处理程序。也就是说，/products/fetch 将与 {area: 'products',action: 'fetch'} 匹配。这或许有点难理解，但是一旦你习惯了这种用法，会发现它相当强大。这可以使我们通过约定的方式将 action 与 URL 松耦合。

在以上配置中，map 属性里指定了服务端点对于不同操作允许的 HTTP 请求类型：fetch 操作对应 GET 方法、edit 操作允许 PUT 方法，而 delete 操作只允许 DELETE 方法。通过这种方式，我们可以合理地控制应用的语义。你可能对余下的代码比较熟悉，即创建一个 Express 应用，并使用到下列两个插件：

JSON 解析器
Seneca Web 插件

到这里，我们已经完成了 Seneca 与 Express 的集成。如果想为 Seneca 添加新的可通过 API 提供服务的 action，唯一需要做的就是修改 map 属性，将 action 与相应的 HTTP 请求绑定。

邮件服务：一个常见的问题

邮件服务是我们编写一个微服务时的首选，考虑到它有以下特点：

只处理一个功能点。
处理得很好。
持有自己的专有数据。

如何发送邮件

标题
内容
目标地址

接口定义

虽然邮件服务的实现看起来容易，但是企业邮件功能最后可能变得一团糟。因此，我们首先要明确最小需求：

如何渲染邮件？
- 邮件渲染是否属于邮件操作的限界上下文？
- 是否另起一个微服务负责邮件渲染？
- 是否使用第三方工具管理邮件？
是否保留已发送邮件数据以备审计需要？

在这个微服务中，我们使用了 Mandrill，它支持企业级邮件发送、追溯已发送邮件和创建可在线编辑的邮件模板。

var plugin = function(options) {
  var seneca = this;
  /**
   * 使用模板发送邮件
   */
  seneca.add({ area: 'email', action: 'send', template: '*' }, function(args, done) {
    // TODO: More code to come.
  });

  /**
   * 发送包含内容的邮件
   */
  seneca.add({ area: 'email', action: 'send' }, function(args, done) {
    // TODO: More code to come.
  });
};

我们有两种邮件发送模式：一种是使用模板，另一种是在发送请求中自带内容。

设置Mandrill

首先，需要创建一个Mandrill账户。访问网址https://mandrillapp.com并用邮箱进行注册后，即可以进行访问，如下图所示：

现在已经创建了一个账户，可用该账户进入测试模式。单击右上角邮箱地址所在位置，开启菜单栏中的测试模式。Mandrill 左边栏会变为橘黄色。

接下来，我们将创建一个API key，它是Mandrill API需要使用的登录信息。单击 Settings -> SMTP & API Info，添加一个新的key（别忘了勾选标记key为测试使用的复选框）。如下图所示：

你现在唯一需要的信息就是生成的key。让我们对API进行如下测试：

var mandrill = require("mandrill-api/mandrill");
var mandrillClient = new mandrill.Mandrill("<YOUR-KEY-HERE>");

mandrillClient.users.info({}, function(result){
  console.log(result);
}, function(e){
  console.log(e);
});

只需要以上几行代码，就可以测试Mandrill是否已经启动并运行，以及key是否正确。

亲自动手在微服务中集成Mandrill

我们将会用到Mandrill的一小部分API，如果你想使用其他功能，可以从这个网址中获取到相关信息：https://mandrillapp.com/api/docs/。

 /**
 * 发送包含内容的邮件
 */
seneca.add({area: "email", action: "send"}, function(args, done) {
  console.log(args);
  var message = {
    "html": args.content,
    "subject": args.subject,
    "to": [{
      "email": args.to,
      "name": args.toName,
      "type": "to"
    }],
    "from_email": "info@micromerce.com",
    "from_name": "Micromerce"
  }
  mandrillClient.messages.send({"message": message}, function(result) {
    done(null, {status: result.status});
  }, function(e) {
    done({code: e.name}, null);
  });
});

第一个发送信息的方法并没有使用到模板。我们只是从应用中获取了一段HTML形式的内容（以及一些其他参数）并通过Mandrill完成发送。

如果发生异常，以上代码会返回 e.name，我们可以将其作为错误码。此时，分支流将因为错误码信息被终止，我们将这称为数据耦合。我们的软件组件并没有依赖于之前的约定，而依赖了传入的内容。

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

04.编写你的第一个Node.js微服务.md

04.编写你的第一个Node.js微服务.md

04.编写你的第一个 Node.js 微服务

微电子商务概览

商品管理服务——双重核心

获取商品信息

获取指定类别的商品

根据 ID 获取商品

添加商品

删除商品

编辑商品

整合各模块

集成 Express 与 Seneca——如何创建 REST API

邮件服务：一个常见的问题

如何发送邮件

接口定义

设置Mandrill

亲自动手在微服务中集成Mandrill

Files

04.编写你的第一个Node.js微服务.md

Latest commit

History

04.编写你的第一个Node.js微服务.md

File metadata and controls

04.编写你的第一个 Node.js 微服务

微电子商务概览

商品管理服务——双重核心

获取商品信息

获取指定类别的商品

根据 ID 获取商品

添加商品

删除商品

编辑商品

整合各模块

集成 Express 与 Seneca——如何创建 REST API

邮件服务：一个常见的问题

如何发送邮件

接口定义

设置Mandrill

亲自动手在微服务中集成Mandrill