feat: add Subscription (#1469)

Ref #1468

docs/source/en/basics/objects.md

@@ -270,6 +270,24 @@ We can get it via `ctx.coreLogger`, the difference between the Context Logger is
 
 We can get them via `this.logger` in Controller and Service instance, they are essentially a Context Logger, but additional file path will be added to logs, easy to locate the log print location.
 
+## Subscription
+
+Subscription is the model for subscribing, including consumer in message broker or schedule.
+
+The base class of Subscription is exported by egg.
+
+```js
+const Subscription = require('egg').Subscription;
+
+class Schedule extends Subscription {
+  // This method should be implemented
+  // subscribe can be generator function or async function
+  * subscribe() {}
+}
+```
+
+We recommend plugin developers to implement based on this model, For example, [Schedule](./schedule.md).
+
 [Koa]: http://koajs.com
 [Koa.Application]: http://koajs.com/#application
 [Koa.Context]: http://koajs.com/#context

docs/source/zh-cn/basics/objects.md

@@ -270,6 +270,24 @@ module.exports = {
 
 我们可以在 Controller 和 Service 实例上通过 `this.logger` 获取到它们，它们本质上就是一个 Context Logger，不过在打印日志的时候还会额外的加上文件路径，方便定位日志的打印位置。
 
+## Subscription
+
+订阅模型是一种比较常见的开发模式，譬如消息中间件的消费者或调度任务。因此我们提供了 Subscription 基类来规范化这个模式。
+
+可以通过以下方式来引用 Subscription 基类：
+
+```js
+const Subscription = require('egg').Subscription;
+
+class Schedule extends Subscription {
+  // 需要实现此方法
+  // subscribe 可以为 generator function 或 async function
+  * subscribe() {}
+}
+```
+
+插件开发者可以根据自己的需求基于它定制订阅规范，如[定时任务](./schedule.md)就是使用这种规范实现的。
+
 [Koa]: http://koajs.com
 [Koa.Application]: http://koajs.com/#application
 [Koa.Context]: http://koajs.com/#context

index.js

@@ -47,7 +47,13 @@ exports.Controller = require('./lib/core/base_context_class');
 exports.Service = require('./lib/core/base_context_class');
 
 /**
- * @member {Service} Egg#BaseContextClass
+ * @member {Subscription} Egg#Subscription
+ * @since 1.10.0
+ */
+exports.Subscription = require('./lib/core/base_context_class');
+
+/**
+ * @member {BaseContextClass} Egg#BaseContextClass
  * @since 1.2.0
  */
 exports.BaseContextClass = require('./lib/core/base_context_class');

test/index.test.js

@@ -13,6 +13,7 @@ describe('test/index.test.js', () => {
       'BaseContextClass',
       'Controller',
       'Service',
+      'Subscription',
       'startCluster',
     ]);
   });

test/lib/egg.test.js

@@ -223,6 +223,8 @@ describe('test/lib/egg.test.js', () => {
         .expect('hello')
         .expect(200);
 
+      yield sleep(1000);
+
       const logPath = path.join(utils.getFilepath('apps/base-context-class'), 'logs/base-context-class/base-context-class-web.log');
       const log = fs.readFileSync(logPath, 'utf8');
       assert(log.match(/INFO .*? \[service\.home\] appname: base-context-class/));