实现 RESTful API

    CNode 社区现在 v1 版本的接口不是完全符合 RESTful 语义，在这篇文章中，我们将基于 CNode V1 的接口，封装一个更符合 RESTful 语义的 V2 版本 API。

    在 RESTful 风格的设计中，我们会通过响应状态码来标识响应的状态，保持响应的 body 简洁，只返回接口数据。以 资源为例：

    • GET /api/v2/topics
    • 响应状态码：200
    • 响应体：

    获取单个主题

    • GET /api/v2/topics/57ea257b3670ca3f44c5beb6
    • 响应状态码：200
    • 响应体：
    1. {
    2.   "id": "57ea257b3670ca3f44c5beb6",
    3.   "author_id": "541bf9b9ad60405c1f151a03",
    4.   "tab": "share",
    5.   "content": "content",
    6.   "title": "《一起学 Node.js》彻底重写完毕",
    7.   "last_reply_at": "2017-01-11T10:20:56.496Z",
    8.   "good": false,
    9.   "top": true,
    10.   "reply_count": 193,
    11.   "visit_count": 47633,
    12. }

    创建主题

    • POST /api/v2/topics
    • 响应状态码：201
    • 响应体：
    1. {
    2.   "topic_id": "57ea257b3670ca3f44c5beb6"
    3. }

    更新主题

    • PUT /api/v2/topics/57ea257b3670ca3f44c5beb6
    • 响应状态码：204
    • 响应体：空

    在接口处理发生错误的时候，如果是客户端请求参数导致的错误，我们会返回 4xx 状态码，如果是服务端自身的处理逻辑错误，我们会返回 5xx 状态码。所有的异常对象都是对这个异常状态的描述，其中 error 字段是错误的描述，detail 字段（可选）是导致错误的详细原因。

    例如，当客户端传递的参数异常时，我们可能返回一个响应，状态码为 422，返回响应体为：

    1. {
    2.   "error": "Validation Failed",
    3.   "detail": [ { "message": "required", "field": "title", "code": "missing_field" } ]
    4. }

    在约定好接口之后，我们可以开始动手实现了。

    初始化项目

    还是通过快速入门章节介绍的 npm 来初始化我们的应用

    开启 validate 插件

    我们选择 egg-validate 作为 validate 插件的示例。

    1. // config/plugin.js
    2. exports.validate = {
    3.   enable: true,
    4.   package: 'egg-validate',
    5. };

    注册路由

    1. module.exports = app => {
    2.   app.router.resources('topics', '/api/v2/topics', app.controller.topics);
    3. };

    通过 app.resources 方法，我们将 topics 这个资源的增删改查接口映射到了 app/controller/topics.js 文件。

    在 controller 中，我们只需要实现 app.resources 约定的 中我们需要提供的接口即可。例如我们来实现创建一个 topics 的接口：

    1. // app/controller/topics.js
    2. const Controller = require('egg').Controller;
    4. // 定义创建接口的请求参数规则
    5. const createRule = {
    6.   accesstoken: 'string',
    7.   # 'string',
    8.   tab: { type: 'enum', values: [ 'ask', 'share', 'job' ], required: false },
    9.   content: 'string',
    12. class TopicController extends Controller {
    13.   async create() {
    14.     const ctx = this.ctx;
    15.     // 校验 `ctx.request.body` 是否符合我们预期的格式
    16.     // 如果参数校验未通过，将会抛出一个 status = 422 的异常
    17.     ctx.validate(createRule, ctx.request.body);
    18.     // 调用 service 创建一个 topic
    19.     const id = await ctx.service.topics.create(ctx.request.body);
    20.     // 设置响应体和状态码
    21.     ctx.body = {
    22.       topic_id: id,
    23.     };
    24.     ctx.status = 201;
    25.   }
    26. }
    27. module.exports = TopicController;

    如同注释中说明的，一个 Controller 主要实现了下面的逻辑：

    1. 调用 validate 方法对请求参数进行验证。
    2. 用验证过的参数调用 service 封装的业务逻辑来创建一个 topic。
    3. 按照接口约定的格式设置响应状态码和内容。

    service 开发

    在 中，我们可以更加专注的编写实际生效的业务逻辑。

    在创建 topic 的 Service 开发完成之后，我们就从上往下的完成了一个接口的开发。

    统一错误处理

    正常的业务逻辑已经正常完成了，但是异常我们还没有进行处理。在前面编写的代码中，Controller 和 Service 都有可能抛出异常，这也是我们推荐的编码方式，当发现客户端参数传递错误或者调用后端服务异常时，通过抛出异常的方式来进行中断。

    • Controller 中 this.ctx.validate() 进行参数校验，失败抛出异常。
    • Service 中调用 this.ctx.curl() 方法访问 CNode 服务，可能由于网络问题等原因抛出服务端异常。
    • Service 中拿到 CNode 服务端返回的结果后，可能会收到请求调用失败的返回结果，此时也会抛出异常。

    框架虽然提供了默认的异常处理，但是可能和我们在前面的接口约定不一致，因此我们需要自己实现一个统一错误处理的中间件来对错误进行处理。

    1. // app/middleware/error_handler.js
    2. module.exports = () => {
    3.   return async function errorHandler(ctx, next) {
    4.     try {
    5.       await next();
    6.     } catch (err) {
    7.       // 所有的异常都在 app 上触发一个 error 事件，框架会记录一条错误日志
    8.       ctx.app.emit('error', err, ctx);
    10.       const status = err.status || 500;
    11.       // 生产环境时 500 错误的详细错误内容不返回给客户端，因为可能包含敏感信息
    12.       const error = status === 500 && ctx.app.config.env === 'prod'
    13.         ? 'Internal Server Error'
    14.         : err.message;
    16.       // 从 error 对象上读出各个属性，设置到响应中
    17.       if (status === 422) {
    18.         ctx.body.detail = err.errors;
    19.       }
    20.       ctx.status = status;
    21.     }
    22.   };
    23. };

    通过这个中间件，我们可以捕获所有异常，并按照我们想要的格式封装了响应。将这个中间件通过配置文件(config/config.default.js)加载进来：

    2. module.exports = {
    3.   // 加载 errorHandler 中间件
    4.   middleware: [ 'errorHandler' ],
    5.   // 只对 /api 前缀的 url 路径生效
    6.   errorHandler: {
    7.     match: '/api',
    8.   },
    9. };

    代码完成只是第一步，我们还需要给代码加上。

    Controller 测试

    我们先来编写 Controller 代码的单元测试。在写 Controller 单测的时候，我们可以适时的模拟 Service 层的实现，因为对 Controller 的单元测试而言，最重要的部分是测试自身的逻辑，而 Service 层按照约定的接口 mock 掉，Service 自身的逻辑可以让 Service 的单元测试来覆盖，这样我们开发的时候也可以分层进行开发测试。

    1. const { app, mock, assert } = require('egg-mock/bootstrap');
    3. describe('test/app/controller/topics.test.js', () => {
    4.   // 测试请求参数错误时应用的响应
    5.   it('should POST /api/v2/topics/ 422', () => {
    6.     app.mockCsrf();
    7.     return app.httpRequest()
    8.       .post('/api/v2/topics')
    9.       .send({
    10.         accesstoken: '123',
    11.       })
    12.       .expect(422)
    13.       .expect({
    14.         error: 'Validation Failed',
    15.         detail: [
    16.           { message: 'required', field: 'title', code: 'missing_field' },
    17.           { message: 'required', field: 'content', code: 'missing_field' },
    18.         ],
    19.       });
    20.   });
    22.   // mock 掉 service 层，测试正常时的返回
    23.   it('should POST /api/v2/topics/ 201', () => {
    24.     app.mockCsrf();
    25.     app.mockService('topics', 'create', 123);
    26.     return app.httpRequest()
    27.       .post('/api/v2/topics')
    28.       .send({
    29.         accesstoken: '123',
    30.         # 'title',
    31.         content: 'hello',
    32.       })
    33.       .expect(201)
    34.       .expect({
    35.         topic_id: 123,
    36.       });
    37. });

    上面对 Controller 的测试中，我们通过 创建了一个应用，并通过 SuperTest 来模拟客户端发送请求进行测试。在测试中我们会模拟 Service 层的响应来测试 Controller 层的处理逻辑。

    Service 层的测试也只需要聚焦于自身的代码逻辑， 同样提供了快速测试 Service 的方法，不再需要用 SuperTest 模拟从客户端发起请求，而是直接调用 Service 中的方法进行测试。

    上面对 Service 层的测试中，我们通过 egg-mock 提供的 方法创建了一个 Context 对象，并直接调用 Context 上的 Service 方法进行测试，测试时可以通过 app.mockHttpclient() 方法模拟 HTTP 调用的响应，让我们剥离环境的影响而专注于 Service 自身逻辑的测试上。

    完整的代码实现和测试都在 eggjs/examples/cnode-api 中可以找到。