birdv3

0.3.39 • Public • Published

Bird 前后端分离开发工具

如何使用

安装 (作为开发依赖)

强烈推荐作为项目的一个开发依赖来使用, 这样, 你的bird配置已经整体的开发工具链, 都可以作为项目的一部分提交到代码中, 方便后续人员开发时使用

cd my-project-folder
npm install --save birdv3

推荐在你的项目中创建一个 bird/ 文件夹, 里面的结构如下:

bird/
    |-- birdfile.js
    |-- bird-server.js

其中, birdfile.js 为你的bird配置文件, 它的格式可以参照下面的 bird config

bird-server.js 很简单, 为:

var bird = require('birdv3')
bird('./birdfile.js')

安装 (作为全局的工具)

当然, bird也还是作为全局的命令使用, 但不推荐

npm install -g birdv3
bird ./some/path/to/birdfile.js

作为中间件使用

bird也支持中间件使用, 与开发依赖安装类似, 你需要有一个 birdfile.js, 然后在你的server脚本中, 加入以下的代码:

注意!! 最好把bird放置在所有其他的中间件或request handler后面

var bird = require('birdv3')

...

// 假设 app 是一个 express 服务器对象
app.all('*', bird('./path/to/birdfile.js'))

...

上报数据到接口平台

bird还可以将从服务器取回的数据上报,然后接口平台可以帮你生成可视化的接口文档

  • 配置样例
  • 如果projectId在配置中不存在,那么你将要在首次启动bird的时候配置一次
  • 如果需要修改projectId,请优先在config中修改

Bird config file 配置

参照带 注释的 Bird Config file

CHANGE LOG

v0.3.24

  • 增加上报接口平台功能
  • 增加配置projectId功能
  • 增加上报时候gzip content-encoding的处理
  • 增加上报时候的错误捕获而不影响其他流程

开发指南

代码组织

  • 本项目是一个 matriks 项目
  • 主要的bird核心在 project/locals/lib/ 下面
  • 入口文件为 index.js => project/locals/lib/index.js
  • 可执行脚本为 bin/bird.js

开发方向

当前的开发方向如下:

Current:

  • [] 加入 demo server 的功能 (罗心成, 王路远)
  • [] 加入 generic 的 auth 插件

Current Problems

  • devtools 不再支持, 如 window.birdv2.changeUser('ccx')
  • global 模式不再支持了

2016-05-27

  • 提高bird配置的可读性与有效性 (重构config的结构)
  • 实现配置文件的动态加载 (当前需要重新启动服务器)
  • fix 一些常见的bug
    • 如, debug: false的时候, 会影响所有其他正常的console.log输出
    • 没有指定username, 则静默式退出
    • 没有内网环境下, cheerio解析出错
  • 加入多一些合理的错误信息, 以方便用户调试和调整config
  • 快速生成本地 demo 的链接列表 @[ 给其他人看的 demo ]{c2i4y_gbr60jmp_iomwah1i}@
  • 引入 matriks 项目结构
  • 对代码组织进行简易重构

重构后的主要思路

  • 关于config的自动更新
    • 利用 setInterval 和 fs.stat 来动态检测 config 变化, 更新 js 引用对象 config
    • 参见 @[ 动态更新 config 对象 ]{t97zs_zd0tksdx_iom9u7yv}@
  • 逻辑重构思路
    • bird的两大核心:
      • 设置好目标的后端 server, 并利用 httpClient 来进行接口转发
        • 接口转发的逻辑:
          • 1 得到 request 时, 获取其 pathname
          • 2 将 pathname 提交给 routes 解析函数, 得到一个资源处理策略
          • 3 根据资源处理策略来处理该 request
          • 4 如果为接口转发, 首先做一些简单的配置, 生成一个转发的必要对象: urlOptions
          • 5 通过 plugin (一般是用于解决用户身份验证, 得到cookie), 修改 urlOptions
            • 参见 @[ 解析所用的 plugin, 并调用它 ]{t97zs_vd7sdnis_iomf0g31}@
          • 6 将最终得到的 urlOptions 作为转发的参数, 发送 http 或 https 的请求到目标后端服务器
          • 7 截取所有后端服务器的返回进行处理
          • 8 如果后端返回是 3XX, 403 等特殊的跟身份验证相关的状态值, 需要考虑是否进行 plugin 的 retry
            • 参见 @[ 特殊返回的处理, 如 3XX, 403 ]{t97zs_w0fege8q_iomeynf7}@
          • 9 否则, 如果是其他的状态, 我们就全量的写到给前端的 reponse 里, 实现最终的接口转发
      • 通过 routes (路由设置) 来判定资源的返回方式
        • 目前有三种资源类别: mock (假数据), static (静态资源), forward (接口转发)

项目开发任务列表

注意: 以下的README内容为 birdv2 的范围, 请随时关注项目的开发

config

  • bird的配制可是一个object,也可以是一个array, eg:
  var config = {
    name: 'ar',
    bird_port: 7676,
    staticFileRootDirPath: '../webapp',
    server: 'http://xx.xx.com:8901/ar/',
    uuap_server: 'http://xx.xx.com:8100',
    username: 'jay',
    password_suffix: ''
  };

  `or`
  var config = [{
    name: 'ar',
    bird_port: 7676,
    staticFileRootDirPath: '../webapp',
    server: 'http://xx.xx.com:8901/ar/',
    uuap_server: 'http://xx.xx.com:8100',
    username: 'jay',
    password_suffix: ''
  }, {
    name: 'ar2',
    bird_port: 7777,
    staticFileRootDirPath: '../webapp',
    server: 'http://xx.xx.com:8902/ar/',
    uuap_server: 'http://xx.xx.com:82S00',
    username: 'jay',
    password_suffix: ''
  }]
  • 下面是详细的配制说明,*表示必须的配制, #表示正在开发或功能不稳定的配制, 其他是可选项
  // *服务名字,本配制以ar为例
  name: 'ar',
  // *服务端口
  bird_port: 3000,
  // *静态文件目录,可以为相对路径,如:../build
  staticFileRootDirPath: '/home/zp/work/ar/src/main/webapp/resources',
  // *测试机地址,是否带`ar`看环境的context
  server: 'http://xx-xx.epc:8901/ar/',
  // *该测试机对应的uuap地址
  uuap_server: 'http://uuap_test.com:8100',
  // *你想用谁登录
  username: 'who_you_want',
  // *密码后缀,没有就留空
  password_suffix: '',
  // 是否开启dev-tools(提供切换用户等功能)default:false
  dev_tool: {
    type: 'input', // #暂时只有这一个,后续加select
    top: 20,       // 工具上边距
    right: 20      //右边距
  },
  // feapps专用登录,hard code this one. default:false
  bprouting: 'bprouting/BpFlowRouting?appindex=true',
  // 是否使用静态的cookie,录bird出问题了你还可以把cookie粘到这里,像旧版一样default:false
  cookie: 'sessionid=XXXXXXXXXXX',
  // 转发路由,你可以将本地的请求转发到指定的路径
  router: {  
      '/ar': '/ar-web' // 将http://xx-xx.epc:8901/ar/XX/XX -> http://xx-xx.epc:8901/ar-web/XX/XX 
  },
  // 登录方式,默认是使用uuap来登录,加载auths/uuap.js default:'uuap'
  auth_standalone: 'uuap',
  // #当cookie效了重新cookie,当然,你可以重启bird来手动获取.default:true
  keep_alive: true,
  // #使用本地的数据,不转发. 当服务器当了,你可以造些假数据来本地测试
  use_local_data: {
    '/ar': '/your/data/path'
  }

extendable

  • 如果你的项目不是用uuap登录的,那你需要配制auth_standalone选项, 然后在auths/目录下添加上对应的js文件,当然你可以联系我,告诉你项目的地址 及登录帐号, 让我帮你加

browser ci api

  • 打开浏览器的console,可以执行以下命令:
  • birdv2.use('uuap_name') 切换到其他用户登录

notice

  • 当获取的cookie失效时,如果response是重定向到其他url,bird会自动获取新cookie,并重定向回来,用户是感觉不到这个过程的。如果response是返回一个对象,使浏览器登出,跳转到 /logout,bird会根据request->header->referer又跳转回来,因为referer不包括锚点信息,对于angular用户会发现页面跳到默认页面;同理,手动点登出也会跳回来,只是换了个cookie

todo

  • track forward history??
  • forwarding local json data

Readme

Keywords

none

Package Sidebar

Install

npm i birdv3

Weekly Downloads

5

Version

0.3.39

License

MIT

Unpacked Size

185 kB

Total Files

107

Last publish

Collaborators

  • befe-owner
  • moyuyc