• View 插件开发
  • 插件目录结构
  • 插件命名规范
  • View 基类
    • 参数
  • 插件配置
    • helper
    • 安全相关
    • 单元测试

    View 插件开发

    绝大多数情况，我们都需要读取数据后渲染模板，然后呈现给用户，而框架并不强制使用某种模板引擎，由开发者来自行选型，具体参见模板渲染。

    本文将阐述框架对 View 插件的规范约束, 我们可以依此来封装对应的模板引擎插件。以下以 egg-view-ejs 为例。

    插件目录结构

    1. egg-view-ejs
    2. ├── config
    3. │   ├── config.default.js
    4. │   └── config.local.js
    5. ├── lib
    6. │   └── view.js
    7. ├── app.js
    8. ├── test
    9. ├── History.md
    10. ├── README.md
    11. └── package.json

    插件命名规范

    • 遵循插件开发规范
    • 插件命名约定以 egg-view- 开头

    • package.json 配置如下，插件名以模板引擎命名，比如 ejs

      1. {
      2.   "name": "egg-view-ejs",
      3.   "eggPlugin": {
      4.     "name": "ejs"
      5.   },
      6.   "keywords": [
      7.     "egg",
      8.     "egg-plugin",
      9.     "egg-view",
      10.     "ejs"
      11.   ],
      12. }

    • 配置项也以模板引擎命名

      1. // config/config.default.js
      2. module.exports = {
      3.   ejs: {},
      4. };

    View 基类

    接下来需提供一个 View 基类，这个类会在每次请求实例化。

    View 基类需提供 render 和 renderString 两个方法，支持 generator function 和 async function（也可以是函数返回一个 Promise）。render 方法用于渲染文件，而 renderString 方法用于渲染模板字符串。

    以下为简化代码，可直接查看源码

    1. const ejs = require('ejs');
    3. module.exports = class EjsView {
    5.   render(filename, locals) {
    6.     return new Promise((resolve, reject) => {
    7.       // 异步调用 API
    8.       ejs.renderFile(filename, locals, (err, result) => {
    9.         if (err) {
    10.           reject(err);
    11.         } else {
    12.           resolve(result);
    13.         }
    14.       });
    15.     });
    16.   }
    18.   renderString(tpl, locals) {
    19.     try {
    20.       // 同步调用 API
    21.       return Promise.resolve(ejs.render(tpl, locals));
    22.     } catch (err) {
    23.       return Promise.reject(err);
    24.     }
    25.   }
    26. };

    参数

    render 方法的三个参数

    • filename: 是完整的文件的路径，框架查找文件时已确认文件是否存在，这里不需要处理
    • locals: 渲染所需的数据，数据来自 app.locals，ctx.locals 和调用 render 方法传入的。框架还内置了 ctx，request, ctx.helper 这几个对象。
    • viewOptions: 用户传入的配置，可覆盖模板引擎的默认配置，这个可根据模板引擎的特征考虑是否支持。比如默认开启了缓存，而某个页面不需要缓存。

    renderString 方法的三个参数

    • tpl: 模板字符串，没有文件路径。
    • locals: 同 render。
    • viewOptions: 同 render。

    插件配置

    根据上面的命名约定，配置名一般为模板引擎的名字，比如 ejs。

    插件的配置主要来自模板引擎的配置，可根据具体情况定义配置项，如 ejs 的配置。

    1. // config/config.default.js
    2. module.exports = {
    3.   ejs: {
    4.     cache: true,
    5.   }
    6. };

    helper

    框架本身提供了 ctx.helper 供开发者使用，但有些情况下，我们希望对 helper 方法进行覆盖，仅在模板渲染时生效。

    在模板渲染中，我们经常会需要输出用户提供的 html 片段，通常需要使用 egg-security 插件提供的 helper.shtml 清洗下

    1. <div>{{ helper.shtml(data.content) | safe }}</div>

    但如上代码所示，我们需要加上 | safe 来告知模板引擎，该 html 是安全的，无需再次 escape，直接渲染。

    而这样用起来比较麻烦，而且容易遗忘，所以我们可以封装下：

    • 先提供一个 helper 子类：
    1. // {plugin_root}/lib/helper.js
    2. module.exports = app => {
    3.   return class ViewHelper extends app.Helper {
    4.     // safe 由 [egg-view-nunjucks] 注入，在渲染时不会转义，
    5.     // 否则在模板调用 shtml 会被转义
    6.     shtml(str) {
    7.       return this.safe(super.shtml(str));
    8.     }
    9.   }
    10. };
    • 在渲染时使用自定义的 helper
    1. // {plugin_root}/lib/view.js
    2. const ViewHelper = require('./helper');
    4. module.exports = class MyCustomView {
    5.   render(filename, locals) {
    6.     locals.helper = new ViewHelper(this.ctx);
    8.     // 调用 Nunjucks render
    9.   }
    10. }

    具体代码可查看

    安全相关

    模板和安全息息相关，egg-security 也给模板提供了一些方法，模板引擎可以根据需求使用。

    首先声明对 egg-security 的依赖：

    1. {
    2.   "name": "egg-view-nunjucks",
    3.   "eggPlugin": {
    4.     "name": "nunjucks",
    5.     "dep": [
    6.       "security"
    7.     ]
    8.   }
    9. }

    此外，框架提供了 app.injectCsrf 和 app.injectNonce，更多可查看安全章节。

    单元测试

    作为一个高质量的插件，完善的单元测试是必不可少的，我们也提供了很多辅助工具使插件开发者可以无痛的编写测试，具体参见单元测试和插件中的相关内容。