摘要：是什么是一款頂級全棧開發(fā)框架。漸進(jìn)式開發(fā)由于模塊的高度內(nèi)聚，可以將業(yè)務(wù)以模塊的形式沉淀，在多個項目中重復(fù)使用，既可貢獻(xiàn)到開源社區(qū)，也可部署到公司內(nèi)部私有倉庫。模塊發(fā)布當(dāng)項目中的模塊代碼穩(wěn)定后，可以將模塊公開發(fā)布，貢獻(xiàn)到開源社區(qū)。

EggBorn.js是一款頂級Javascript全棧開發(fā)框架。

EggBorn.js是采用Javascript進(jìn)行全棧開發(fā)的最佳實踐。
EggBorn.js不重復(fù)造輪子，而是采用業(yè)界最新的開源技術(shù)，進(jìn)行全棧開發(fā)的最佳組合。
EggBorn.js前端采用Vue.js + Framework7 / Vue Router + Webpack，后端采用Koa.js + Egg.js，數(shù)據(jù)庫采用mysql。
EggBorn.js時刻跟蹤開源技術(shù)的最新成果，并持續(xù)優(yōu)化，使整個框架時刻保持最佳狀態(tài)。

Javascript技術(shù)的蓬勃發(fā)展，為前后端開發(fā)帶來了更順暢的體驗，顯著提升了開發(fā)效率。但仍有網(wǎng)友質(zhì)疑Javascript能否勝任大型Web應(yīng)用的開發(fā)。大型Web應(yīng)用的特點是隨著業(yè)務(wù)的增長，需要開發(fā)大量的頁面組件。面對這種場景，一般有兩種解決方案：

1 采用單頁面的構(gòu)建方式，缺點是產(chǎn)生的部署包很大。
2 采用頁面異步加載方式，缺點是頁面過于零散，需要頻繁與后端交互。

EggBorn.js實現(xiàn)了第三種解決方案：

3 頁面組件按業(yè)務(wù)需求歸類，進(jìn)行模塊化，并且實現(xiàn)了模塊的異步加載機(jī)制，從而彌合了前兩種解決方案的缺點，完美滿足大型Web應(yīng)用業(yè)務(wù)持續(xù)增長的需求。

業(yè)務(wù)模塊化：頁面組件按模塊組織

加載方式靈活：模塊既可異步加載，也可同步加載

模塊高度內(nèi)聚：模塊包括前端頁面組件和后端業(yè)務(wù)邏輯

參數(shù)配置靈活：模塊中的前后端可以多帶帶進(jìn)行參數(shù)配置

國際化：模塊中的前后端均支持獨立的國際化

模塊隔離：模塊的頁面、數(shù)據(jù)、邏輯、路由、配置等元素均進(jìn)行了命名空間隔離處理，避免模塊之間的變量污染與沖突

超級易用的事務(wù)處理：只需在路由記錄上配置一個參數(shù)，即可完美實現(xiàn)數(shù)據(jù)庫的事務(wù)處理。

漸進(jìn)式開發(fā)：由于模塊的高度內(nèi)聚，可以將業(yè)務(wù)以模塊的形式沉淀，在多個項目中重復(fù)使用，既可貢獻(xiàn)到npm開源社區(qū)，也可部署到公司內(nèi)部私有npm倉庫。

有了EggBorn.js，從此可復(fù)用的不僅僅是組件，還有業(yè)務(wù)模塊。

$ npm install -g egg-born

$ egg-born project_name
$ cd project_name
$ npm install

EggBorn.js目前提供了2個項目腳手架，分別是


front-backend-mysql  -- 前后端全棧項目模板

front                -- 前端項目模板，后端可采用其他方案

如果采用了front-backend-mysql模板，請配置mysql連接參數(shù)（空數(shù)據(jù)庫即可）

編輯src/backend/config/config.default.js文件

  // mysql
  config.mysql = {
    clients: {
      // donot change the name  
      __ebdb: {
        host: "127.0.0.1",
        port: "3306",
        user: "travis",
        password: "",
        database: "egg-born",
      },
    },
  };

啟動后端服務(wù)

$ npm run dev:backend

啟動前端服務(wù)

$ npm run dev:front

為了不斷沉淀業(yè)務(wù)模塊，達(dá)到高度可復(fù)用的效果，所有模塊的命名空間必須充分隔離，避免相互污染與沖突，故采用如下命名方式：

egg-born-module-{providerId}-{moduleName}

如模塊egg-born-module-a-version，各環(huán)節(jié)命名信息如下：

providerId: a

moduleName: version

fullName: egg-born-module-a-version

relativeName: a-version
前端頁面路由地址: /a/version/{page}
后端API路由地址：/a/version/{controller}/{action}

模塊既支持異步加載，也支持同步加載。默認(rèn)是異步加載，如果要同步加載，只需在模塊名稱后面加上-sync后綴，如模塊egg-born-module-aa-login-sync。

進(jìn)入src/module目錄執(zhí)行腳手架，創(chuàng)建模塊文件骨架

$ egg-born module_relative_name

EggBorn.js目前提供了2個模塊腳手架，分別是


module               -- 全棧模塊模板

module-front         -- 前端模塊模板

在front/src/routes.js中添加頁面路由，如

function load(name) {
  return require(`./pages/${name}.vue`).default;
}

export default [
  { path: "welcome/:who", component: load("welcome") },
  { path: "profile", component: load("profile"), meta: { requiresAuth: true } },
  { path: "/login", component: load("login") },
];

path: 路徑，支持參數(shù)。以/開頭，代表根頁面組件。login頁面組件通常這樣配置

component: 頁面組件對象

meta: 路由元數(shù)據(jù)

meta.requiresAuth: 如果頁面組件需要登錄，須設(shè)為true

在頁面中引用頁面組件，請使用絕對路徑，如

Vuex 是一個專為 Vue.js 應(yīng)用程序開發(fā)的狀態(tài)管理模式。EggBorn.js采用Vuex實現(xiàn)了完全隔離的模塊狀態(tài)管理機(jī)制。
在front/src/store.js中添加狀態(tài)，如

export default function(Vue) {

  return {
    state: {
      message: "hello world",
    },
  };

}

在頁面組件中訪問本模塊狀態(tài)

const message = this.$local.state.message;

在頁面組件中訪問其他模塊狀態(tài)

const message = this.$store.state[providerId][moduleName].message;

更多信息，請參閱: Vuex

在front/src/config/config.js中添加配置信息，如

export default {
  mode: 1,
};

只支持在頁面組件中訪問本模塊內(nèi)部的參數(shù)配置

const mode = this.$config.mode;

在front/src/config/locale目錄添加國際化文件
zh-cn.js文件中的語言定義示例如下

export default {
  mode: "模式",
  "Hello world! I"m %s.": "您好，世界！我是%s。",  
};

國際化語言采取全局合并的方式，有利于語言資源的共享，在頁面組件中訪問方式如下

const mode = this.$text("mode");
const message = this.$text("Hello world! I"m %s.","zhennann");

在backend/src/routes.js中添加api路由，如

const home = require("./controller/home.js");

module.exports = [
  { method: "get", path: "home/index", controller: home, action: "index", transaction: true },
];

method: get/post等方法

path: 路徑，支持參數(shù)

component: Controller對象

action: Controller方法，如果不設(shè)置，則自動采用path尾部單詞

transaction: 默認(rèn)為false，如果設(shè)為true，則啟用數(shù)據(jù)庫事務(wù)

在前端頁面組件中訪問本模塊api路由

this.$api.get("home/index").then(data => {
}).catch(err => {
});

在前端頁面組件中訪問其他模塊api路由

this.$api.get("/providerId/moduleName/home/index").then(data => {
}).catch(err => {
});

后端Controller的實現(xiàn)方式與Egg.js保持一致

module.exports = app => {
  class HomeController extends app.Controller {

    async index() {
      const message = await this.service.home.index();
      this.ctx.success(message);
    }

  }
  return HomeController;
};

更多信息，請參閱: Egg.js Controller

Service用于封裝業(yè)務(wù)邏輯，供Controller調(diào)用，實現(xiàn)方式與Egg.js保持一致。

module.exports = app => {
  class Home extends app.Service {

    async index() {
      const res = await this.ctx.db.queryOne("show tables");
      return res;
    }

  }

  return Home;
};

與Egg.js不同之處在于，Service使用ctx.db操作數(shù)據(jù)庫，從而自動支持?jǐn)?shù)據(jù)庫事務(wù)。
更多信息，請參閱: Egg.js Service

為了支持大型Web系統(tǒng)的開發(fā)，EggBorn.js支持模塊后端Controller之間的調(diào)用，如

const message = await this.ctx.performAction({
  method: "get",
  url: "home/index",
  query: {
    username: "kevin",
  },
  params: {
    mode: 1,
  },
  body: {
    content: "ready",
  },
});

method: get/post等方法

url: 訪問本模塊的Controller使用相對路徑，訪問其他模塊的Controller使用以/開頭的絕對路徑。

query、params、body: 與常規(guī)的Controller參數(shù)保持一致

后端數(shù)據(jù)庫操作與Egg.js保持一致

更多信息，請參閱: Egg.js MySQL

EggBorn.js提供了更為便利的數(shù)據(jù)庫事務(wù)實現(xiàn)方式，只需在后端api路由記錄中配置transaction參數(shù)，Service使用ctx.db操作數(shù)據(jù)庫。
如果是主Controller通過ctx.performAction調(diào)用子Controller，數(shù)據(jù)庫事務(wù)開啟規(guī)則如下：

在backend/src/config/config.js中添加配置信息，如

module.exports = appInfo => {
  const config = {};

  config.message = "Hello world! I"m %s.";

  return config;
};

訪問本模塊內(nèi)部的參數(shù)配置示例如下

const message = this.ctx.config.message;

在backend/src/config/locale目錄添加國際化文件
zh-cn.js文件中的語言定義示例如下

module.exports = {
  "Hello world! I"m %s.": "您好，世界！我是%s。",
  "not found": "未發(fā)現(xiàn)",
};

國際化語言采取全局合并的方式，有利于語言資源的共享，訪問方式如下

const notFound = this.ctx.text("not found");
const message = this.ctx.text("Hello world! I"m %s.", "zhennann");

在backend/src/config/errors.js文件中添加錯誤代碼

// error code should start from 1001
module.exports = {
  1001: "not found",
};

返回錯誤信息示例如下

this.ctx.fail(1001);

也可拋出異常示例如下

this.ctx.throw(1001);

EggBorn.js通過package.json文件管理模塊依賴關(guān)系。
比如，模塊aa-module1依賴aa-module2，需要在模塊aa-module1的package.json文件中作如下配置

{
  "name": "egg-born-module-aa-module1",
  "version": "0.0.1",
  "eggBornModule": {
    "dependencies": {
      "aa-module2": "0.0.1"
    }
  },
  "dependencies": {
    "egg-born-module-aa-module2": "^0.0.1"
  }
}

設(shè)置"egg-born-module-aa-module2": "^0.0.1"，是為了在安裝模塊aa-module1時自動安裝模塊aa-module2。如果模塊沒有公開發(fā)布，就不必設(shè)置。

模塊一般都要操作數(shù)據(jù)庫，當(dāng)模板版本升級時，數(shù)據(jù)庫結(jié)構(gòu)也有可能變動。EggBorn.js實現(xiàn)了模塊數(shù)據(jù)版本的管理，便于業(yè)務(wù)模塊的積累沉淀。

在模塊的package.json文件中配置fileVersion為當(dāng)前數(shù)據(jù)版本

{
  "name": "egg-born-module-aa-module1",
  "version": "0.0.1",
  "eggBornModule": {
    "fileVersion": 1
  }
}

在模塊后端添加Api路由

{ method: "post", path: "version/update", controller: version }

添加version Controller

module.exports = app => {
  class VersionController extends app.Controller {

    async update() {
      await this.service.version.update(this.ctx.getInt("version"));
      this.ctx.success();
    }

  }
  return VersionController;
};

添加version Service

module.exports = app => {

  class Version extends app.Service {

    async update(version) {
      if (version === 1) {
        // do something
      }
    }

  }

  return Version;
};

當(dāng)啟動后端服務(wù)時，EggBorn.js自動檢測模塊數(shù)據(jù)版本的變化，并執(zhí)行相應(yīng)的路由，完成數(shù)據(jù)的版本升級。

當(dāng)項目中的模塊代碼穩(wěn)定后，可以將模塊公開發(fā)布，貢獻(xiàn)到開源社區(qū)。也可以在公司內(nèi)部建立npm私有倉庫，然后把模塊發(fā)布到私有倉庫，形成公司資產(chǎn)，便于重復(fù)使用。
模塊發(fā)布步驟如下

$ cd path/to/module      -- 進(jìn)入模塊目錄
$ npm install            -- 安裝模塊依賴
$ npm run build:front    -- 構(gòu)建前端代碼
$ npm run build:backend  -- 構(gòu)建后端代碼
$ npm publish            -- 發(fā)布至npm倉庫

目前只支持后端測試驅(qū)動

在backend/test/controller目錄添加Controller測試文件

// controller/home.test.js
const { app, mock, assert } = require("egg-mock/bootstrap");
const parseMockUrl = function(url) {
  const prefix = app.mockUtil.parseUrlFromPackage(__dirname);
  return `${prefix}${url}`;
};

describe("test/controller/home.test.js", () => {

  it("action:index", async () => {
    const result = await app.httpRequest().get(parseMockUrl("home/index"));
    assert(result.body.code === 0);
  });

});

在backend/test/service目錄添加Service測試文件

// service/home.test.js
const { app, mock, assert } = require("egg-mock/bootstrap");
const parseMockUrl = function() {
  return app.mockUtil.parseUrlFromPackage(__dirname);
};

describe("test/service/home.test.js", () => {

  it("index", async () => {
    const ctx = app.mockContext({ mockUrl: parseMockUrl() });
    const message = await ctx.service.home.index();
    assert(message);
  });

});

在項目根目錄執(zhí)行測試

$ npm run test:backend
$ npm run cov:backend

前端架構(gòu)提供兩種方案

Vue.js + Framework7
Vue.js + Vue Router

Framework7是移動開發(fā)專屬UI界面庫，內(nèi)置路由機(jī)制。
Vue Router是Vue.js官方路由庫，使用Vue Router可搭配其他各種UI界面庫。

在src/front/main.js文件中進(jìn)行切換

// choose one

//   framework7
import main from "./framework7/main.js";

//   vuerouter
// import main from "./vuerouter/main.js";

// export
export default main;

src/front/config/config.js文件中的參數(shù)配置可以覆蓋模塊的參數(shù)

export default{
  module: {
    "aa-hello": {
      mode: 2,
    },
  },
};

在src/front/config/locale目錄添加國際化文件，可以覆蓋模塊的國際化語言
zh-cn.js文件中的語言定義示例如下

export default {
  mode: "模式",
};

后端架構(gòu)基于Egg.js，完整支持Egg.js提供的所有功能與特性

更多信息，請參閱: Egg.js

src/backend/config/config.default.js文件中的參數(shù)配置可以覆蓋模塊的參數(shù)

module.exports = appInfo => {
  const config = {};

  // module config
  config.module = {
    "aa-hello": {
      mode: 2,
    },
  };

  return config;
};

在src/backend/config/locale目錄添加國際化文件，可以覆蓋模塊的國際化語言
zh-cn.js文件中的語言定義示例如下

module.exports = {
  mode: "模式",
};

$ npm run build:front

$ npm run start:backend

$ npm run stop:backend

編輯build/config.js文件

// backend
const backend = {
  port: 7002,
  hostname: "127.0.0.1",
};

強(qiáng)烈建議使用nginx托管前端靜態(tài)資源，并反向代理后端服務(wù)，配置如下

server {
  listen 80;
  server_name example.com www.example.com;
  set $node_port 7002;

  root /path/to/www;

  location  /api/ {
    proxy_http_version 1.1;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Host $http_host;
    proxy_set_header X-NginX-Proxy true;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_pass http://127.0.0.1:$node_port$request_uri;
    proxy_redirect off;
  }

}

有任何疑問，歡迎提交 issue， 或者直接修改提交 PR！