this document is still waiting for translation, see Chinese Version
+Plugin Development
+Plugins is the most important feature in Egg framework. It keeps Egg simple, stable and effecient, and also it can make the best reuse of business logic, to build an entire ecosystem. Someone should be got confused:
+-
+
- Since Koa has already got the plugin feature, what's the point of the Egg plugins +
- What is the differences between middleware, plugin and application, what is the relationship +
- How can I use the plugin +
- How do I build a plugin +
- ... +
As we've already explained some these points in Chapter using plugins before. Now we are going through how to build a plugin.
+# Plugin Development
+# Quick Start with Scaffold
+You can choose plugin scaffold in egg-init for quick start.
+$ egg-init --type=plugin egg-hello |
# Directory of Plugin
+Plugin is actually a 'mini application', directory of plugin is as below
+. egg-hello |
It is almost the same as the application directory, what's the difference?
+-
+
-
+
Plugin have no independant router or controller. This is because:
+-
+
- Usually routers are strongly bound to application, it is not fit here. +
- An application might have plenty of dependant plugins, routers of plugin are very possible conflict with others. It would be a disaster. +
- If you really need a general router, you should implement it as middleware of the plugin. +
+ -
+
The specific information of plugin should be declared in the
+package.jsonbyeggPlugin：-
+
{String} name- plugin name(required), it must be unique, it will be used in the config of the dependencies of plugin.
+{Array} dependencies- the list of strong dependant plugins of current plugin(if one of these plugins here is not found, application startup plugin will be failed)
+{Array} optionalDependencies- this optional dependencies of this plugin.(if these plugins are not activated, only warnings would be occurred, and not affect the startup of the application).
+{Array} env- this option is avaliable only when specified the enviroment. The list of env please refer to env. This is optional, most time you can leave it.
+
+{
"name": "egg-rpc",
"eggPlugin": {
"name": "rpc",
"dependencies": [ "registry" ],
"optionalDependencies": [ "vip" ],
"env": [ "local", "test", "unittest", "prod" ]
}
}
+ -
+
No
+plugin.js：-
+
eggPlugin.dependenciesis for declaring dependencies only, not for importing, nor activating.
+- If you want to manage multiple plugins, you should do it inframework +
+
# Dependencies Management of Plugins
+The dependencies are managed by plugin himself, this is different from middleware. Before loading plugins, application will read dependencies from eggPlugin > dependencies and eggPlugin > optionalDependencies in package.json, and then sort out the loading orders according to their relationships, for example, the loading order of the following plugins is c => b => a
// plugin a |
** Attention: The values in dependencies and optionalDependencies are the eggPlugin.name of plugins, not package.name. **
The dependencies and optionalDependencies is studied from npm, most time we are using dependencies, it is recommended. There are about two situations to apply the optionalDependencies:
-
+
- Only get dependant in specific enviroment: for example, a authentication plugin, only depend on the mock plugin in development enviroment. +
- Weakly depending, for example: A depned on B, but without B, A can take other choice +
Pay attention: if you are using optionalDependencies, framework won't verify the activation of these dependencies, they are only for sorting loading orders. In such situation, the plugin will go through other ways such as interface detection to decide related logic.
# What is plugin capable of
+We've discussed what plugin is. Now what is it capable of?
+# Embeded Objects API Extension
+Extend the embeded objects of the framework, just like the application
+-
+
app/extend/request.js- extends Koa#Request
+app/extend/response.js- extends Koa#Response
+app/extend/context.js- extends Koa#Context
+app/extend/helper.js- extends Helper
+app/extend/application.js- extends Application
+app/extend/agent.js- extends Agent
+
# Insert Custom Middlewares
+-
+
- First, define and implement middleware inside directory
app/middleware
+
; |
-
+
- Insert middleware to the appropriate position in
app.js(e.g. insert static middleware before bodyParser )
+
const assert = require('assert'); |
# Initializations on Application Starting
+-
+
-
+
If you want to read some local config before startup
++// ${plugin_root}/app.js
const fs = require('fs');
const path = require('path');
module.exports = app => {
app.customData = fs.readFileSync(path.join(app.config.baseDir, 'data.bin'));
app.coreLogger.info('read data ok');
};
+ -
+
If you want to do some async starting bussiness, you can do it with
+app.beforeStartAPI+// ${plugin_root}/app.js
const MyClient = require('my-client');
module.exports = app => {
app.myClient = new MyClient();
app.myClient.on('error', err => {
app.coreLogger.error(err);
});
app.beforeStart(async () => {
await app.myClient.ready();
app.coreLogger.info('my client is ready');
});
};
+ -
+
You can add starting bussiness of agent with
+agent.beforeStartAPI+// ${plugin_root}/agent.js
const MyClient = require('my-client');
module.exports = agent => {
agent.myClient = new MyClient();
agent.myClient.on('error', err => {
agent.coreLogger.error(err);
});
agent.beforeStart(async () => {
await agent.myClient.ready();
agent.coreLogger.info('my client is ready');
});
};
+
# Setup Timing Task
+-
+
- Setup dependencies of schedule plugin in
package.json
+
{ |
-
+
- Create a new file in
${plugin_root}/app/schedule/directory to edit your timing task
+
exports.schedule = { |
# Best Practice of Global Instance Plugin
+Some plugins are made to introduce existing service into framework, like egg-mysql,egg-oss.They all need to create corresponding instance in application. We notice something when developing this kind of plugins:
+-
+
- Use different instances of the same service in one application(e.g:connect to two different MySQL Database) +
- Dynamically intialize connection after get config from other service(get MySQL server address from config center and then initialize connection) +
If each plugin make their own implementation, all sorts of configs and initializations will be chaotic. So the framework supply the app.addSingleton(name, creator) API to make it clear.
# Writing Plugin
+We have simplfied the egg-mysql plugin in order to use it in this tutorial
+// egg-mysql/app.js |
As you can see, all we need to do for this plugin is passing in the field that needed to be mounted and the corresponding initialize function. Framework will be in charge of managing all the configs and the way to access the instances.
+# Application Layer Use Case
+# Singelton
+-
+
- Declare MySQL config in config file +
// config/config.default.js |
-
+
- Access database by
app.mysqldirectly
+
// app/controller/post.js |
# Multiple Instances
+-
+
- Of cause we need to configure MySQL in the config file, but diffrent from singleton, we need to add
clientsin the config to configure each instance. The default configs(e.g. host and port) can be configured indefault.
+
// config/config.default.js |
-
+
- Access the right instance by
app.mysql.get('db1')
+
// app/controller/post.js |
# Dynamically Instantiate
+We can dynamically initialize instance without config when running the application.
+// app.js |
Access the instance by app.database
// app/controller/post.js |
Attention, when creating the instance dynamically, framework would read the default property in the config file as the default config
# Plugin Locate Rule
+When loading the plugins in the framework, it will follow the rules to locate them as below:
+-
+
-
+
If there is the path config, load them in path directly
+
+ -
+
If there is no path config, search them with the package name, the search orders are:
+-
+
node_modulesdirectory of the application root
+node_modulesdirectory of the dependencies
+node_modulesof current directory(generally for unit test compability)
+
+
# Plugin Specification
+We are expecting people could build new plugins. In the meantime we hope these plugins could follow the rules as below:
+-
+
-
+
Naming Rules
+-
+
npmpackages must append prefixegg-,and all letters must be lowcase,for example:egg-xxx. The long names should be concatenate with middlelines:egg-foo-bar.
+- The corresponding plugin should be named in camlecase. The name should be translated according to the middlelines of the
npmname:egg-foo-bar=>fooBar.
+ - The use of middlelines is not mandatory,for example:userservice(egg-userservice) and ser-service(egg-user-service) are both acceptable. +
+ -
+
+package.jsonRules-
+
- Add
eggPluginproperty according to the details discussed before.
+ - For index conveniet, add
egg,egg-plugin,eggPlugininkeywords.
+
+{
"name": "egg-view-nunjucks",
"version": "1.0.0",
"description": "view plugin for egg",
"eggPlugin": {
"name": "nunjucks",
"dep": [
"security"
]
},
"keywords": [
"egg",
"egg-plugin",
"eggPlugin",
"egg-plugin-view",
"egg-view",
"nunjucks"
],
}
+ - Add
# Why do not use the npm package name as the plugin name?
+Egg define the plugin name by the eggPlugin.name, it is only unique in application or framework, that means many npm packages might get the same plugin name, why design this way?
First, Egg plugin is not only support npm package, it also support search plugins in local directory. In Chapter progressive we mentioned how to make progress by using these two configs. Directory is more friendly to unit test. So, Egg can not ensure uniqueness through npm package name.
+More important, Egg can use this feature to make Adapter. For example, the plugin defined inTemplate Develop Spec was named as view, but there are plugins named egg-view-nunjucks and egg-view-react, the users only need to change the plugin and modify the templates, no need to modify the Controller, because all these plugins have implemented the same API.
Make the same featured plugins the same name and same API, can make quick switch between them. This is really really useful in template and database.