/hc-bee

the framework for honeycomb micro-app

Primary LanguageJavaScript

hc-bee

recommended framework to develop service on honeycomb.

Build Status NPM Version NPM Downloads snyk status dependencies status

A application framework for building honeycomb's app 应用框架，用来构建运行在 honeycomb上的app

  • 运行在honeycomb-server 上
  • 自动路由
  • 插件机制
  • 便捷的配置
  • 集成日志

how to use

first you need install honeycomb-cli tools:

> npm i -g honeycomb-cli

then using honeycomb-cli init a project:

> honeycomb init demo  # this cmd will create dir named `demo` in current dir

cd into dir demo/, you will see the project structure as following:

appRoot/
       |- bin/
       |- config/
       |- middleware/
       |- controller/
       |- model/
       |- view/
       |- app.js
       |- package.json
       |- README.md

the package enter is ref to app.js

> cd demo
> make install
> honeycomb start

app now start

配置

  • package.json

package.json中，以下几个字段常用

  • name # app名字

  • version # app版本, 遵循semver

  • build # build number , 数字， [可选]

  • main # app的入口文件, demo里是app.js, 为空则寻址index.js 寻址规则同node_modules寻址

  • config/

app的config机制, 有一个很长的继承链路

config = {} < config/config.default.js < config/config_env.js < serverSizeConfig

本地开发的配置文件为 config/config_dev.js, 线上环境为 config/config_production.js

配置中的常见字段:

{
  serverName: '',
  port: '',
  middleware: {  // middleware插件
    midName: {
      enable: true,
      module: 'cors',
      config: {
        // config for middleware
      }
    }
  },
  extension: { // extension插件

  }
}

插件机制

根据上述config中的配置信息可知，framework定义了两种类型:

  • middleware

    middleware 主要是请求链路中的逻辑处理模块

  • extension

    extension 主要扩展 context, response, request 上的方法

插件的规则:

  • 每个插件都有自己的唯一id
  • 插件的配置结构如下
  {
    "enable": "", 
    "module": "", 
    "config": {}
  }

内置middleware:

  • [M] cookieParser
  • [M]cookieSession
  • csrf
  • rid
  • bodyParser
  • redirect allowDomains 配置
  • cors 中间件的 allowDomains配置和 redirect的相同，支持 glob pattern数组

内置extension:

  • jsonp
  • redirect
  • timer

controller

controller约定在controller/目录下，框架会递归扫描目录，并自动生成路由

express风格的常规controller方法定义

/**
 * 简单GET接口
 * @api {get} /
 * @param req
 * @param res
 * @nowrap 
 */
exports.ctrl = function (req, res, next) {
  res.end('hello');
};

/**
 * callback形式的封装，该接口默认返回json格式
 * @api {get} /
 * @param req
 * @param callback(err, data, options)
 */
exports.ctrl = function (req, callback) {
  callback(null, {}); // default is json callback
};

/**
 * html页面形式的返回
 * @api {get} /page
 */
exports.page = function (req, callback) {
  callback(null, {
    tpl: 'index.html', // view目录中的相对路径
    data: {}           // 模板中的变量
  }, 'html'); // default is json callback
};

/**
 * POST方法的接口
 * @api {post} /
 */
exports.post = function (req, callback) {}

/**
 * 多方法的接口
 * @api {post|patch|delete} /
 */
exports.post = function (req, callback) {}

generator写法(语法和常规写法兼容)：

/**
 * @api {get} /
 */
exports.ctrl = function* (req) {
  /**
   * 该模式兼容上述常规写法，只是支持controller方法使用yield
   * 同时新增以下语法支持：
   *  1. 异常直接throw
   *  2. return直接返回数据
   */
  if (req.url === '/exception') {
    throw new Error('error object');
  } else {
    return dataObj;  // 请求正常，返回正常的数据对象， 等同于 callback(null, dataObj);
  }
}
/**
 * @api {get} /
 */
exports.ctrl = function* (req, callback) {
  callback(null, data, opt);
}

async写法(同genFun，兼容常规写法):

/**
 * @api {get} /
 * @param req
 */
exports.ctrl = async function (req) {
  if (req.url === '/exception') {
    new Error('error object');
  } else {
    return dataObj;  // 请求正常，返回正常的数据对象， 等同于 callback(null, dataObj);
  }
}