doc: add plugin doc #224

gxcsoccer · 2017-01-10T08:37:22Z

Checklist

npm test passes
tests and/or benchmarks are included
documentation is changed or added
commit message follows commit guidelines

Affected core subsystem(s)

Description of change

mention-bot · 2017-01-10T08:37:22Z

@gxcsoccer, thanks for your PR! By analyzing the history of the files in this pull request, we identified @popomore to be a potential reviewer.

popomore · 2017-01-10T08:42:01Z

就叫 plugin.md?

fengmk2 · 2017-01-10T09:41:02Z

docs/source/zh-cn/advanced/plugin.md

@@ -0,0 +1,361 @@
+
+title: 插件机制


插件开发

fengmk2 · 2017-01-10T10:08:49Z

docs/source/zh-cn/advanced/plugin.md

+
+## 前言
+
+插件机制是我们框架的一大特色。它不但可以保证框架核心的足够精简、稳定、高效，还可以促进业务逻辑的复用，生态圈的形成。有同学可能会问了


有同学可能会问了

有人可能会问了

fengmk2 · 2017-01-10T10:09:20Z

docs/source/zh-cn/advanced/plugin.md

+
+接下来我们就来逐一讨论
+
+## 为什么要插件？


问号可以去掉

fengmk2 · 2017-01-10T10:21:19Z

docs/source/zh-cn/advanced/plugin.md

+│   |   ├── context.js (可选)
+│   |   ├── application.js (可选)
+│   |   └── agent.js (可选)
+│   ├── proxy (可选)


proxy 开源版本不自带

fengmk2 · 2017-01-10T10:21:47Z

docs/source/zh-cn/advanced/plugin.md

+
+那区别在哪儿呢？
+
+1.  插件没有独立的 router 和 controller。这主要出于几点考虑：


多了空格

fengmk2 · 2017-01-10T10:26:45Z

docs/source/zh-cn/advanced/plugin.md

+    - `{String} name` - 插件名（必须配置），具有唯一性，配置依赖关系时会指定依赖插件的 name。
+    - `{Array} dependencies` - 当前插件强依赖的插件列表（如果依赖的插件没找到，应用启动失败）
+    - `{Array} optionalDependencies` - 当前插件的可选依赖插件列表（如果依赖的插件未开启，只会 warning，不会影响应用启动）
+    - `{Array} env` - 只有在指定运行环境才能开启，具体有哪些环境可以参考 [运行环境](../basics/env.md)


这里重点说明一下，一般情况下都不需要配置

fengmk2 · 2017-01-10T10:32:43Z

docs/source/zh-cn/advanced/plugin.md

+- `app/extend/response.js` - 扩展 koa#Response 对象
+- `app/extend/context.js` - 扩展 koa#Context 对象
+- `app/extend/application.js` - 扩展 app 对象
+- `app/extend/agent.js` - 扩展 agent 对象


helper.js 也是可以 extend 的

fengmk2 · 2017-01-10T10:33:24Z

docs/source/zh-cn/advanced/plugin.md

+
+1. 首先在 `app/middleware` 目录下定义好中间件实现
+
+	```js


代码块缩进有点大，应该2空格即可

fengmk2 · 2017-01-10T10:33:51Z

docs/source/zh-cn/advanced/plugin.md

+	  return staticCache(options);
+	};
+	```
+2. 在 `${plugin_root}/app.js` 中将中间件插入到合适的位置（例如：下面将 static 中间件放到 bodyParser 之前）


${plugin_root}/ 不需要写了，直接写 app.js

fengmk2 · 2017-01-10T10:35:03Z

docs/source/zh-cn/advanced/plugin.md

+	// plugins/static/app.js
+	const assert = require('assert');
+
+	module.exports = function (app) {


module.exports = app => {

fengmk2 · 2017-01-10T10:37:54Z

docs/source/zh-cn/advanced/plugin.md

+2. 在 `${plugin_root}/app.js` 中将中间件插入到合适的位置（例如：下面将 static 中间件放到 bodyParser 之前）
+
+	```js
+	// plugins/static/app.js


这个注释可以删除了。

fengmk2 · 2017-01-10T10:40:02Z

docs/source/zh-cn/advanced/plugin.md

+	const fs = require('fs');
+	const path = require('path');
+
+	module.exports = function(app) {


fengmk2 · 2017-01-10T10:42:01Z

docs/source/zh-cn/advanced/plugin.md

+	};
+	```
+
+- 如果有异步启动逻辑，可以使用 generator 方式


不要提同步异步了，都告诉读者写 generator function 吧

不行，这里得改改。

这里改一下：如果是异步启动逻辑，那么可以在 app/init.js 通过 generator 来实现

gxcsoccer · 2017-01-10T14:43:58Z

都改了，请 review

fengmk2 · 2017-01-10T15:46:52Z

docs/source/zh-cn/advanced/cluster.md


 ```js
-// ${baseDir}/agent.js
+// ${app_root}/agent.js


${app_root}/ 可以不用写的。

fengmk2 · 2017-01-10T15:49:53Z

docs/source/zh-cn/advanced/plugin.md

+    - `{String} name` - 插件名（必须配置），具有唯一性，配置依赖关系时会指定依赖插件的 name。
+    - `{Array} dependencies` - 当前插件强依赖的插件列表（如果依赖的插件没找到，应用启动失败）
+    - `{Array} optionalDependencies` - 当前插件的可选依赖插件列表（如果依赖的插件未开启，只会 warning，不会影响应用启动）
+    - `{Array} env` - 只有在指定运行环境才能开启，具体有哪些环境可以参考 [运行环境](../basics/env.md)。改配置是可选的，一般情况下都不需要配置


改配置 => 此配置

fengmk2 · 2017-01-10T15:50:52Z

docs/source/zh-cn/advanced/plugin.md

+  module.exports = app => {
+	// 将 static 中间件放到 bodyParser 之前
+	const index = app.config.coreMiddleware.indexOf('bodyParser');
+	assert(index >= 0, 'bodyParser 中间件必须存在');


缩进是2空格

fengmk2 · 2017-01-10T16:03:20Z

其他 ok 了。

fengmk2

LGTM

fengmk2 · 2017-01-10T16:34:11Z

@gxcsoccer 需要 rebase 一下

codecov-io · 2017-01-11T03:19:42Z

Current coverage is 97.75% (diff: 100%)

No coverage report found for master at 01f9390.

Powered by Codecov. Last update 01f9390...8679743

gxcsoccer · 2017-01-11T03:25:40Z

搞定

gxcsoccer added type: document WIP labels Jan 10, 2017

gxcsoccer force-pushed the doc-plugin branch 2 times, most recently from 97021d6 to 44570f4 Compare January 10, 2017 08:40

popomore mentioned this pull request Jan 10, 2017

中文文档 #34

Closed

31 tasks

gxcsoccer force-pushed the doc-plugin branch 6 times, most recently from b853a8e to d5e638b Compare January 10, 2017 09:36

gxcsoccer requested review from atian25, dead-horse, fengmk2, leoner, popomore and shaoshuai0102 January 10, 2017 09:37

fengmk2 reviewed Jan 10, 2017

View reviewed changes

docs/source/zh-cn/advanced/plugin.md Outdated

@@ -0,0 +1,361 @@

title: 插件机制

Copy link

Member

fengmk2 Jan 10, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

插件开发

fengmk2 reviewed Jan 10, 2017

View reviewed changes

gxcsoccer force-pushed the doc-plugin branch 2 times, most recently from edab2ba to 5372b15 Compare January 10, 2017 14:42

gxcsoccer force-pushed the doc-plugin branch from 5372b15 to 8679743 Compare January 10, 2017 14:47

fengmk2 reviewed Jan 10, 2017

View reviewed changes

fengmk2 approved these changes Jan 10, 2017

View reviewed changes

gxcsoccer force-pushed the doc-plugin branch 2 times, most recently from eae86a1 to b410bec Compare January 11, 2017 03:21

doc: add plugin doc

d07bee1

gxcsoccer force-pushed the doc-plugin branch from b410bec to d07bee1 Compare January 11, 2017 03:25

gxcsoccer merged commit 1c65bde into master Jan 11, 2017

gxcsoccer deleted the doc-plugin branch January 11, 2017 03:25


		## 前言

		插件机制是我们框架的一大特色。它不但可以保证框架核心的足够精简、稳定、高效，还可以促进业务逻辑的复用，生态圈的形成。有同学可能会问了


		那区别在哪儿呢？

		1. 插件没有独立的 router 和 controller。这主要出于几点考虑：


		1. 首先在 `app/middleware` 目录下定义好中间件实现

		```js


		接下来我们就来逐一讨论

		## 为什么要插件？

Uh oh!

doc: add plugin doc #224

doc: add plugin doc #224

Uh oh!

Conversation

gxcsoccer commented Jan 10, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Affected core subsystem(s)

Description of change

Uh oh!

mention-bot commented Jan 10, 2017

Uh oh!

popomore commented Jan 10, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fengmk2 Jan 10, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gxcsoccer commented Jan 10, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fengmk2 commented Jan 10, 2017

Uh oh!

fengmk2 left a comment

Choose a reason for hiding this comment

Uh oh!

fengmk2 commented Jan 10, 2017

Uh oh!

codecov-io commented Jan 11, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Current coverage is 97.75% (diff: 100%)

Uh oh!

gxcsoccer commented Jan 11, 2017

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

gxcsoccer commented Jan 10, 2017 •

edited

Loading

fengmk2 Jan 10, 2017 •

edited

Loading

codecov-io commented Jan 11, 2017 •

edited

Loading