开发入门

发布时间: 2022-10-12 15:24:13

写在前面

CmsWing 是基于 Egg.js开发,并且完全遵循Egg.js的约束规范，所以您要使用CmsWing进行开发，请先了解Egg.js文档，如果您本身就是Egg.js的使用者，那么可以直接上手进行开发。

编写 Controller

如果您熟悉 web 开发模式或MVC，那么我们第一步应该需要编写 Controller（控制器）和 Router（路由）。
我们编写控制器的时候要继承 /core/base_controller.js cmswing的基础控制器，

// app/controller/cms/web.js
'use strict';
const Controller = require('../../core/base_controller');
class WebController extends Controller {
  async index(){
  this.ctx.body = '你好世界'
 }
}
module.exports = WebController;

在Egg.js里面配置路由映射需要在文件中手写:

// app/router.js
module.exports = (app) => {
  const { router, controller } = app;
  router.get('/', controller.home.index);
};

在CmsWing无需在文件中手动配置，在后台系统-开发管理-路由管理里面添加管理路由

静态资源

Egg 内置了 static 插件，线上环境建议部署到 CDN，无需该插件。
static 插件默认映射 /public/* -> app/public/* 目录
此处，我们把静态资源都放到 app/public 目录即可：

app/public
├── css
│   └── news.css
└── js
    ├── lib.js
    └── news.js

模版渲染

绝大多数情况，我们都需要读取数据后渲染模板，然后呈现给用户。故我们需要引入对应的模板引擎。

我们使用 Nunjucks 来渲染

为列表页编写模板文件，一般放置在 app/view 目录下，我们按照模块来归纳放置，比如cms模块，我们就把模版放置在 app/view/cms下面

<!-- app/view/cms/news/list.html -->
<html>
  <head>
    <title>Hacker News</title>
    <link rel="stylesheet" href="/public/cms/css/news.css" />
  </head>
  <body>
    <ul class="news-view view">
      {% for item in list %}
      <li class="item">
        <a href="{{ item.url }}">{{ item.title }}</a>
      </li>
      {% endfor %}
    </ul>
  </body>
</html>

添加Controller

// app/controller/cms/news.js 控制器文件我们也 按照模块放置在 app/controller/cms 目录下
const Controller = require('../../core/base_controller');
class NewsController extends Controller {
  async list() {
    const dataList = {
      list: [
        { id: 1, title: 'this is news 1', url: '/news/1' },
        { id: 2, title: 'this is news 2', url: '/news/2' },
      ],
    };
    await this.ctx.render('cms/news/list.html', dataList);
  }
}
module.exports = NewsController;

添加路由（因为没有在项目中真实创建Controller，下图中的控制器和方法没有对应，实际开发中要选择你真实的控制器和方法）

编写 service

实际应用中，Controller 一般不会自己产出数据，也不会包含复杂的逻辑，复杂的过程应抽象为业务逻辑层 Service。
service 跟 controller一样我们也推荐按照模块放置，我们来添加一个 Service 抓取 Hacker News 的数据，如下：

// app/service/cms/news.js
const Service = require('egg').Service;
class NewsService extends Service {
  async list(page = 1) {
    // read config
    const { serverUrl, pageSize } = this.config.news;

    // use build-in http client to GET hacker-news api
    const { data: idList } = await this.ctx.curl(
      `${serverUrl}/topstories.json`,
      {
        data: {
          orderBy: '"$key"',
          startAt: `"${pageSize * (page - 1)}"`,
          endAt: `"${pageSize * page - 1}"`,
        },
        dataType: 'json',
      },
    );

    // parallel GET detail
    const newsList = await Promise.all(
      Object.keys(idList).map((key) => {
        const url = `${serverUrl}/item/${idList[key]}.json`;
        return this.ctx.curl(url, { dataType: 'json' });
      }),
    );
    return newsList.map((res) => res.data);
  }
}

module.exports = NewsService;

然后稍微修改下之前的 Controller

// app/controller/cms/news.js
const Controller = require('../../core/base_controller');

class NewsController extends Controller {
  async list() {
    const ctx = this.ctx;
    const page = ctx.query.page || 1;
    const newsList = await ctx.service.cms.news.list(page);
    await ctx.render('cms/news/list.html', { list: newsList });
  }
}

module.exports = NewsController;

还需增加 app/service/cms/news.js 中读取到的配置

// config/config.default.js
// 添加 news 的配置项
exports.news = {
  pageSize: 5,
  serverUrl: 'https://hacker-news.firebaseio.com/v0',
};

编写模型

CmsWing 可以通过后台自动生成 Sequelize 模型，无需手动编写model文件，我们在后台系统-开发管理-模型管理创建模型

比如我们创建一个 cms_doc 的模型来存放文章内容

会在项目 app/model 目录下自动生成模型文件

在Controller使用模型，我们可以改写下上面的例子

// app/controller/cms/news.js
const Controller = require('../../core/base_controller');

class NewsController extends Controller {
  async list() {
    const ctx = this.ctx;
    const map = {};
    const page = ctx.query.page || 1;
    const limit = 10;
    map.offset = (Number(page) - 1) * limit;
    map.limit = Number(limit);
    const newsList = await ctx.model.CmsDoc.findAndCountAll(map);
    await ctx.render('cms/news/list.html', { list: newsList });
  }
}

module.exports = NewsController;

编写扩展

遇到一个小问题，我们的资讯时间的数据是 UnixTime 格式的，我们希望显示为便于阅读的格式。框架提供了一种快速扩展的方式，只需在 app/extend 目录下提供扩展脚本即可，具体参见扩展。在这里，我们可以使用 View 插件支持的 Helper 来实现：

// app/extend/helper.js
const moment = require('moment');
exports.relativeTime = (time) => moment(new Date(time * 1000)).fromNow();

在模板里面使用：

<!-- app/view/cms/news/list.html -->
{{ helper.relativeTime(item.time) }}

编写 Middleware

比如我们后台要对用户进行验证，Middleware 编写的时候我们也是推荐按模块放置

// app/middleware/sys/authAdminToken.js 
'use strict';
module.exports = options => {
  return async function authAdminToken(ctx, next) {
    // 支持 options.exclude
    if (options && ctx.helper._.find(options.exclude, o => ctx.url.indexOf(o) !== -1)) return await next();
    const token = ctx.session.adminToken || ctx.get('token');
    const userInfo = ctx.helper.deToken(token);
    if (userInfo) {
      ctx.userInfo = userInfo;
      await next();
    } else {
      if (ctx.request.accepts([ 'json', 'html' ]) === 'html') {
        ctx.session.adminToken = null;
        ctx.redirect('/admin/login');
      } else {
        ctx.body = {
          status: 401,
          msg: '未登录',
          data: { isLogin: false },
        };
      }
    }

  };
};

现在可以在【路由管理】里面，对需要验证的模块或者路由，添加这个Middleware

配置文件

写业务的时候，不可避免的需要有配置文件，框架提供了强大的配置合并管理功能：

支持按环境变量加载不同的配置文件，如 config.local.js， config.prod.js 等等。
应用/插件/框架都可以配置自己的配置文件，框架将按顺序合并加载。
具体合并逻辑可参见配置文件。

// config/config.default.js
exports.robot = {
  ua: [/curl/i, /Baiduspider/i],
};

// config/config.local.js
// only read at development mode, will override default
exports.robot = {
  ua: [/Baiduspider/i],
};

// app/service/some.js
const Service = require('egg').Service;

class SomeService extends Service {
  async list() {
    const rule = this.config.robot.ua;
  }
}

module.exports = SomeService;

单元测试

单元测试非常重要，框架也提供了 egg-bin 来帮开发者无痛的编写测试。

测试文件应该放在项目根目录下的 test 目录下，并以 test.js 为后缀名，即 {app_root}/test/**/*.test.js。

// test/app/middleware/robot.test.js
const { app, mock, assert } = require('egg-mock/bootstrap');

describe('test/app/middleware/robot.test.js', () => {
  it('should block robot', () => {
    return app
      .httpRequest()
      .get('/')
      .set('User-Agent', 'Baiduspider')
      .expect(403);
  });
});

执行测试：

npm test

就这么简单，更多请参见Egg.js官网单元测试。

写在结尾

短短几段内容，只能当作抛砖引玉，我们建议开发者继续阅读其他章节

最后更新时间: 2023-10-03 19:36:50

你还没有登录，请先！