Skip to content

Home

Jump to bottom
Daniel Yin edited this page Sep 7, 2018 · 20 revisions

A lightweight and flexible web development framework.

快速开始

ibird继承自Koa，是Koa的一个上层框架。ibird在Koa之上做了一层轻量级的封装，以提供一些更便于日常开发的新特性。

ibird核心设计非常精简，主要做了两件事：

  1. 在Koa的基础上，增加了些常用功能：如路由、请求体解析、静态目录挂载、跨域设置等

  2. 提供了插件整合的能力

Hello ibird

const app = require('ibird').newApp();

// response
app.get('/', ctx => {
  ctx.body = `Hello ibird.`;
});

app.play();

特性列表

新建应用

新建应用有两种方式：

// 应用配置
const config = { port: 9999 };

// 1.快速新建应用
const app  = require('ibird').newApp(config);

// 2.使用`new`关键字
const App  = require('ibird').App;
const app = new App(config);

// 两种方式无任何区别，仅看个人习惯

注意：App继承自Koa。

应用配置

在新建应用时，框架内置了一些常用选项，可供开发者调用：

  • name - 应用名称标记，非必填参数，字符串类型，默认为ibird，主要在调用ibird.ctx(name)时使用（name的默认值也为ibird）。
  • port - 应用监听端口，非必填参数，数值类型，默认为3000。
  • uploadDir - 上传文件保存的目录，非必填参数，字符串类型，该参数也是是否解析请求中的文件数据的标记。
  • statics - 静态目录资源，非必填参数，对象结构，key为路由地址，value为资源本地目录。
  • prefix - 路由接口全局前缀，非必填参数，字符串类型。
  • middlewareDir - 中间件目录，非必填参数，字符串类型，系统运行时，该目录下所有的中间件都会被自动挂载（包括子目录）。
  • routesDir - 路由目录，功能同上。
  • cross - 是否支持跨域访问，非必填参数，布尔或对象类型，当值为对象时，原样传递给kcors
  • bodyOpts - 请求体解析配置，非必填参数，对象类型，参数值原样传递给koa-body
  • onInit - 初始化钩子函数，接收一个应用实例的参数（即app），初始化过程中的事件只能在该回调函数中订阅

注意：开发者完全可以扩展定义自己的选项。

上下文函数

在代码的任意处，通过框架提供的上下文函数ibird.context()（或别名ibird.ctx()）即可获取应用实例：

const ibird = require('ibird');
const app = ibird.ctx();

如果你创建了多个应用，则通过指定name的方式获取不同的应用实例：

const app1 = ibird.ctx('app1');
const app2 = ibird.ctx('app2');

注意：需要注意的是，如果你在创建应用时指定了name，那么在获取应用实例时一定也要指定相同的name（两处name的默认值皆为ibird）。

应用API

app.config(opts)

应用配置函数，一般不需要调用，因为在创建应用实例时已自动调用过，只有当你需要在系统运行时更新系统配置时，才需要调用该函数。

app.c()

配置读取函数，通过该函数获取当前应用配置。

app.use(fn)

中间件挂载函数，通过调用该函数手动挂载中间件。

app.useDir(dir)

中间件目录挂载函数，自动递归挂载指定目录下的所有中间件。

app.mount(fn)

路由挂载函数，通过调用该函数手动挂载路由，可指定路由函数或路由对象。

app.mountDir(dir)

路由目录挂载函数，自动递归挂载指定目录下的所有路由。

app.import(addon, opts)

插件引用函数，接收插件对象和插件配置两个参数。

app.play([port, callback])

系统启动函数，可在运行时传递端口和回调函数，该端口会覆盖配置中的port；当不需要监听端口时指定app.play(null)；当不需要覆盖端口时，只需要挂载默认回调函数时，指定app.play(callback)。

注意：以上仅为框架默认开放的API，根据ibird的设计理念，插件是可以自由扩展API的，详细描述请参考插件开发指南。

事件列表

框架在运行的过程中，会将不同的应用状态通过事件的方式发布出来，开发者可通过订阅这些事件来做不同的个性化处理，事件订阅方式为：

app.on('xxx', fn)

事件列表如下：

  1. ibird:app:config:pre - 配置加载前事件，监听函数参数列表：app应用实例，opts应用配置
  2. ibird:app:config:post - 配置加载后事件，参数列表：app应用实例
  3. ibird:app:use - 中间件挂载事件，参数列表：app应用实例，fn中间件函数
  4. ibird:app:useDir - 中间件目录挂载事件，参数列表：app应用实例，dir中间件目录
  5. ibird:app:mount - 路由挂载事件，参数列表：app应用实例，rt路由函数或对象
  6. ibird:app:mountDir - 路由目录挂载事件，参数列表：app应用实例，dir路由目录
  7. ibird:app:import:pre - 插件引用前事件，参数列表：app应用实例，addon插件对象，opts插件配置
  8. ibird:app:import:post - 插件引用后事件，参数列表：app应用实例，addon插件对象，opts插件配置
  9. ibird:app:initialize:pre - 应用初始化前事件（需在onInit中订阅），参数列表：app应用实例，opts应用配置
  10. ibird:app:initialize:post - 应用初始化后事件（需在onInit中订阅），参数列表：app应用实例，opts应用配置
  11. ibird:app:statics:pre - 静态目录挂载前事件（需在onInit中订阅），参数列表：app应用实例，statics静态目录配置部分
  12. ibird:app:statics:post - 静态目录挂载后事件（需在onInit中订阅），参数列表：app应用实例，statics静态目录配置部分
  13. ibird:app:play:pre - 应用启动前事件，参数列表：app应用实例，port启动时传递的端口（如果有），callback启动时传递的回调函数（如果有）
  14. ibird:app:play:post - 应用启动后事件，参数列表：app应用实例
  15. ibird:app:listen - 应用启动监听事件，参数列表：app应用实例

注意：如果你的订阅不起效，一般都是这两个原因：事件名不正确；事件订阅没有在事件触发之前。

插件机制

ibird奉行一切皆插件的信条，插件的扩展性非常强，插件既可以读取应用配置，也可以声明自己的路由和中间件，还可以扩展应用API。用户在引用插件的过程中，可以选择自动启用所有功能，也可以决定每个路由与中间件的挂载顺序。插件开发请参考插件开发指南。

Documentation

Clone this wiki locally