@lianjia-fe/bucky-core
a node web server's core
Last updated 2 years ago by schacker .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install @lianjia-fe/bucky-core 
SYNC missed versions from official npm registry.

Bucky

基于 koa 开发的 node 框架 with ♥︎ by lianjia-fe

     __                __
    |  |--.--.--.----.|  |--.--.--.
    |  _  |  |  |  __||    <|  |  |
    |_____|_____|____||__|__|___  |
                            |_____|
    with ♥︎ by lianjia-fe

使用方式

通过 bucky-cli 生成你的项目 参见 https://github.com/LianjiaTech/bucky-cli

之后通过下面命令启动

$ npm install
$ npm run dev

项目结构

your-project
├── bin            // 上线 op 启动脚本
└── src            // 项目目录
    ├── actions    // 动作
    ├── apis       // 接口
    ├── configs    // 配置
    ├── models     // 数据对象
    ├── responses  // 返回封装
    ├── services   // 插件
    └── views      // 模版

CONFIG

bucky 很多工作都可以使用配置完成,配置的设置会分布在各个地方 需要了解 配置中环境的覆盖特征

通过 configs/nev 中可以设置当前的环境,默认使用 process.env.NODE_ENV 来外部注入

下面是 configs/app 的例子

import prodConfig from './_prod'

export default {

  name: PKG.name,

  // 项目监听的端口
  port: prodConfig.base.PORT,

  // 是否全局绑定 lodash
  _: true,

  // 是否前端有代理
  // 如果你的server 前面还有 nginx 等的代理则选择 true
  proxy: true
}

// 下面的特定环境可以深度合并到上面的默认环境
// 线上环境是上面的默认环境,不要乱改哦

// 开发环境配置
export const development = {
  port: 3000,
  proxy: false
}
// 测试环境配置
export const testing = {
  port: 3000,
  proxy: false
}

在 default, development, testing 中可以写不同的配置。

  • 在 production 环境中 配置为 default
  • 在 development 环境中 配置为 default + development
  • 在 testing 环境中 配置为 default + testing

数据是 两个数据的 深度 merge 得到的。

API

api 用于数据接口调用,规定数据格式和调用方式

在 apis 目录中添加配置文件,会自动生成api

可以通过 bucky api myAPI 创建

export default api => {

  api.config = {
    // 接口超时时间
    timeout: 10000,

    // 默认的返回值简单约定, {code: , data:, msg:} 的形式返回
    // 如果是这种返回形式的话,那么通过下面参数,做接口检查
    codeKey: 'code',
    dataKey: 'data',
    messageKey: 'msg',

    // 可以使用以下方法 处理 api 请求前的数据
    // requestHandler () {}

    // 可以使用以下方法 处理 api 返回的数据
    // responseHandler () {}

    // 当 [codeKey] === [successCode] 是认为请求成功
    successCode: 100000,

    // 接口的协议,域名,端口
    base: 'http://[domain]:[port]',

    // 上行格式 可以是:
    // application/x-www-form-urlencoded
    // multipart/form-data
    // application/json
    // 等等
    // contentType: 'application/x-www-form-urlencoded'
  }

  // 定义接口 这边的设置是在 config 基础上的
  // 内部的没有点的值复用 config 中的
  api('__api_name__', {

    // 接口 path, 可以使用 {xxx} 的方法动态修改 uri
    // 在请求的 uriReplacer 参数设置
    uri: 'i/{am}/a/path',

    // 接口访问方式 get | post | delete | put ...
    method: 'get',

    // 接口参数检查
    parameters: {
      // string: api.type.string.required,
      // number: api.type.number.required
    },

    // 是否使用缓存
    // 简单的缓存设置, 写使用的 redis 名即可
    // cache: 'cache',
    // 如果想自定义,可以使用下面的
    // cache: {
    //   redis: 'cache',
    //   key: req => req.method === 'GET' ? req.uri : null,
    //   fromCache: cache => JSON.parse(cache),
    //   toCache: data => JSON.stringify(data)
    // }
  })

  // api(....) 继续定义下一个接口
}

生成完之后,你可以用以下的方式调用

await API.[文件名].[定义接口名](data, option)

参数定义:

  • data {Object}: 接口请求参数,通过不同的 method,作为 search 或者 body
  • option {Object}: 可选 配置
    • query {Object}: 可选 post或着其他将data转化为body的时候动态加一些 query
    • uriReplacer {Object}: 可选 可以替换uri上 {xxxx} 中的值,动态修改uri
    • queryEncode {Boolean}: 可选 默认true 是否将 query 中的 value 做 encodeURIComponent

Model

Model 用于构建数据对象

在 models 目录中添加配置文件

可以通过 bucky model MyModel 创建

model 的命名必须首字母大写(通过 bucky-cli 会自动给你转化首字母),必须是个类

export default class MyModel {

  // 实例初始化方法
  constructor () {}

  // 静态方法
  static staticFunction () { }

  // 静态同步方法
  static async staticAsyncFunction () { }

   // 实例方法
  staticFunction () { }

  // 实例同步方法
  static async asyncFunction () { }
}

Action

action 是最终业务实现。一个业务对应一个action

在 actions 目录中添加配置文件

可以通过 bucky action /my/path/here 创建

在没有其他干扰的情况下, action 文件的目录路径即为访问路径

action 在 configs/action 有一些配置

  • defaultAction: action 中的默认值

一个action的配置

export default {

  // csrf 作用是判断来访者身份,如果是 false 不会判断
  // 默认操作是,如果是 post, put, delete 操作,并且 来访者 域名和当前域名不匹配则会拒绝访问
  // 如果 csrf 为 字符串 或者 字符串 数组(可以是minimatch),则相当于设置白名单,白名单中的会被认可
  // csrf: false,
  // csrf: [
  //  '*.lianjia.com',    // minimatch
  //  'aaa.lianjia.com',  // 域名
  //  '*',  // 匹配所有
  //  ''    // 允许 空 referer
  //  ],


  // cors 是否允许 异步跨域访问
  // cors: '*',
  // cors: 'http://lianjia.com',
  // cors: {
  //  origin: 'http://lianjia.com',
  //  methods: 'GET, POST',
  //  Headers: 'X-Requested-With'
  // },

  // 如果路由命中则会走这个方法
  // 可以在 rewrite redirect 修改路由指向
  async handler (ctx) {

    // ctx 为 koa 的 context 上下文
    // 详见: http://koajs.com/#context

    // ctx.request  为 koa request 对象
    // 详见: http://koajs.com/#request

    // ctx.response 为 koa response 对象
    // 详见: http://koajs.com/#response

    // 使用 ctx.request.query 获取 url query 参数
    // 使用 ctx.request.body 获取通过 x-www-form-urlencoded 方式提交的 body
    // 使用 ctx.request.form 获取 formData 方式提交的 form 表单

    // 使用 API.xxx, Model.xxx 调用 api model 中声明的 接口 和 类

    // 使用 ctx.render 渲染模版
    // 默认使用 ejs, 可以在 config/view 中设置
    // ctx.render('index', { title: 'bucky' })

    // 页面未找到
    // ctx.notFound()

    // 页面无权限
    // ctx.forbidden()

    // 页面跳转
    // ctx.redirect('http://lianjia.com')

    // 页面跳转(使用js方式)
    // ctx.redirect('http://lianjia.com', {viaJavascript: true})

    // 系统错误,并且报错
    // ctx.serverError(new Error('server error'))

    // ajax 返回
    // ctx.ajax({greeting: 'hello world'})

    // ajax 返回异常
    // ctx.ajax(null, {error: true, message: '加载失败'})
  },

  // 如果 handler 代码出错,可以在 catchError 中捕获处理错误
  // 如果没有 catchError, 则会自动抛 500 错误,并返回错误内容
  // async catchError (ctx, error) { },
}

Response

response 是对数据返回的封装

默认封装为

ctx.notFound() 返回页面不存在 使用 404.ejs 模版渲染空页面

ctx.forbidden() 返回页面没权限 使用 403.ejs 模版渲染空页面

ctx.serverError(error) 返回页面服务错误 使用 500.ejs 模版渲染空页面

  • error {Error} 错误对象

ctx.redirect(url, {viaJavascript}) 返回页面需要跳转 使用 302.ejs 模版渲染空页面

  • url {String} 跳转的页面地址
  • viaJavascript {Boolean} 是否使用 javascript 的方式跳转

ctx.ajax(data, {error, message}) 渲染 ajax 数据返回(json)

  • data {Any} 可选 返回数据对象
  • error {Boolean|Any} 可选 是否错误(默认错误类型), 制定错误类型 (错误类型在 configs/response 中规定)
  • message {Any} 可选 错误的描述

ctx.jsonp(data, {error, message, handlerKey}) 渲染 jsonp 数据返回(json)

  • data {Any} 可选 返回数据对象
  • error {Boolean|Any} 可选 是否错误(默认错误类型), 制定错误类型 (错误类型在 configs/response 中规定)
  • message {Any} 可选 错误的描述
  • handlerKey {String} 可选 jsonp 钩子的 query 的 key

ctx.render(templatePath, data, {layout})

  • templatePath {String} 对应的 views 目录下的文件的路径,从 views 算 relative 路径
  • data {Object} 渲染模版的数据
  • layout {False|String} 渲染模版外层layout模版(false为没有)

View

view 是模版渲染的模版的存放位置

可以在 configs/view 中设置模版引擎配置

export default {

  // 你想使用的模版类型,默认是 ejs
  template: 'ejs',

  // 项目 外层框架的模版 位置 (相对于 views 文件夹)
  layout: 'layout',

  // 拼装模版数据,在这边写,每次都会带上
  // 可以在这边定义 静态文件的版本号 之类的东西
  data: {
    title: 'bucky'
  },

  // ejs 的配置
  ejs: {
    compileDebug: false,
    delimiter: '%',
    ext: '.ejs'
  }

}

跳转

跳转规则设置

可以修改 configs/redirect 和 configs/rewrite 来修改跳转,

区别是 redirect 是通过 302 来实现的, rewrite 是通过内部修改 url 的情况实现的。

在 rewrite 中可以通过 ctx.originalUrl 为转化之前的 url

export default [

  // rewrite 规则
  // 动态改变 url 让其走到对应的路由
  // 是 app 内部逻辑
  // 规则从上到下,如果匹配则不会再往下走了

  // from 可以是 正则,方法,字符串
  // 当url 被 正则匹配 或 方法返回非空 或 字符串匹配 minimatch
  // 则会走到对应的 to
  // to 可以是字符串,也可以是方法
  // 如果是方法 参数接收 正则匹配的match值, 方法返回值, 字符串是否匹配的布尔值
  // 返回为 字符串

  // 这个例子是改写 页面图标 的路由
  { from: '/favicon.ico', to: '/public/favicon.ico' }

]

Redis

设置 redis 配置

export default {

  // 配置一个名为 "cache" 的 redis
  // 参见 http://redis.js.org/#api-rediscreateclient
  cache: {
    host: '127.0.0.1',
    port: '6379',
  }

}

使用

可以通过对应配置中 redis 名称,在全局 Redis.[redis 名称] 来获取对应的 redis 使用池 在会掉闭包中执行redis命令, 不需要释放 redis 句柄

记得对应的 async await 的使用 具体 redis 命令 查看 http://devdocs.io/redis/

const result = await Redis.cache(async redis => {
  await redis.hset(cacheKey, name, value)
  return await redis.hget(cacheKey, name)
})

hashCache

因为常见的 redis 使用是缓存,所以可以使用封装的 hashCache 方法,更加简单调用

await Redis.cache.hashCache.get('some_name', 'some_value')
await Redis.cache.hashCache.set('some_name')

通过 hashCache 使用默认的 redis key 存储对象 你可以通过 name_space 来区分存储 hash 池

await Redis.cache.hashCache('name_space').get('some_name', 'some_value')
await Redis.cache.hashCache('name_space').set('some_name')

MySQL

设置 MySQL 配置

export default {

  // 配置一个名为 "store" 的 mysql
  // 参见 https://www.npmjs.com/package/mysql#pooling-connections
  store: {
    host: '127.0.0.1',
    port: '3306',
    user: 'root',
    password: '123456',
    database: 'test'
  }

}

使用

可以通过对应配置中 mysql 名称,在全局 MySQL.[mysql 名称] 来获取对应的 mysql 使用池 在会掉闭包中执行mysql命令, 不需要释放 mysql 句柄

记得对应的 async await 的使用

const items = await MySQL.store(async store => {
  return await store.query(`select * from pet where name='${name}'`)
})
await MySQL.store(async store => {
  await store.query(`insert into pet(type, name) values('${type}','${name}')`)
})

可以使用 https://www.npmjs.com/package/sql 来声称 sql语句。 更加方便,并且避免sql注入

插件 service

书写自定义 koa 插件,也可以改造现有 koa 插件进来

Lodash

当在 configs/app.js 中设置 _: true, 即 全局中 _ 即位 lodash 句柄,哪都可以用

已经封装的功能

Form Parse / Body Parse

  • 如果 接口通过 'multipart/form-data' 或者 'application/octet-stream' 等方式发送的 formData 请求,请使用 ctx.form 或者 ctx.request.form 方式获取,如果是文件类型,返回是stream

  • 如果 接口通过 'application/x-www-form-urlencoded' 或者 'application/json' 等方式请求的,请使用 ctx.body 或者 ctx.request.body 方式获取(该方式不可能是文件)

Static Server (静态资源)

设置 configs/static.js

export default {

  // 静态路径
  staticPath: '/public',

  // 静态文件夹路径
  staticDir: path.resolve(__dirname, '../statics'),

  // 文件是否返回 etag 头
  etag: true,

  // 文件是否返回 Last-Modified 头
  lastModified: true,

  // 用户客户端缓存时间
  maxAge: 60
}

默认 Models

Utils

Model.Utils 提供一些可使用的方法集合

  • appendSearch 往 uri 上追加 search
  • @param {Object} object
  • @param {Boolean} encode
  • @return {String}
  • assert 错误检查,如果命中抛异常
  • @param {Boolean} 错误检查
  • @param {String} 输出信息模版
  • @param {...any} 模版的参数
  • request requset 库

  • requestAsync 异步 request 封装,同 requset 库

  • escapeHTML 转移 HTML 特殊字符

  • @param {String}
  • @param {String}
  • deepMerge 深拷贝
  • @param {Object}
  • @param {Object}
  • @param {Object}
  • formatPath 格式化 url 路径
  • @param {String}
  • @return {String}
  • /fsdfsd/fdsfdsf//fds///dfsds/ => /fsdfsd/fdsfdsf/fds/dfsds
  • getPkg 获取 package.json
  • @return {Object}
  • getType getType 获取对象类型
  • @param {any} object
  • @return {string} boolean|number|string|function|array|date|regexp|object|error
  • isIP 是否是 ip 格式
  • @param {String}
  • @param {Boolean}
  • match 匹配字符串
  • @param {String} string
  • @param {Regexp|Function|String} rule
  • @param {Any} 给 Function 类型的 rule 添加参数
  • @return {any}
  • md5 返回md5值
  • @param {String} string
  • @return {String}
  • noop 空方法

  • object2Search 将 object 转化成 query

  • @param {Object} object
  • @param {Boolean} encode
  • @return {String}
  • objectForEach 循环对象元素
  • @param {Object} object Object, 最好是一个纯对象
  • @param {Function} iteratee 循环函数
  • @return {Object} 类似Array.map 将 iteratee 返回的数据组成新对象
  • promisify 将 node callback 方式转化成 promise 的方式
  • @param {Function} originalFunction
  • @param {any} context
  • @param {Boolean} returnMulitArgs
  • @return {Promise}
  • string2Array 转换字符串到数组
  • @param {String} string
  • @param {String} spliter
  • @return {Array}
  • uuid 获取随机 id
  • @return {String}

测试部署

确保测试的 node 环境 >= 6.4.4

推荐测试安装 pm2 进行管理 node 服务,在 测试机 使用 npm install -g pm2 的方式安装。

测试可以通过 pm2 list, pm2 start, pm2 delete 等命令管理服务,简单明了。

安装完 pm2 后,通过如下代码启动 node 服务(测试环境)

pm2 delete <项目名,测试自己定,不要和其他项目重复就可以>
cd  <项目源码目录>
pm2 start npm --name "<项目名,测试自己定,不要和其他项目重复就可以>" -- run test

如果 pm2 命令找不到,请自行做下映射关系 /usr/local/node/bin/pm2 -> pm2

上线部署

  1. 需要注意,在 configs/_prod.js 文件,这个文件会读取 op 服务的配置。需要修改 hostName 变量为你的上线文件夹名(基本是你上线域名),其他代码一般不需要修改。

  2. 线上是通过 bin/run.js 启动服务的,而不是 npm script。一般这个文件不需要做修改。已经统一配置了。

推荐第三方 node modules

moment

npm install moment

A lightweight JavaScript date library for parsing, validating, manipulating, and formatting dates.

mathjs

npm install mathjs

Math.js is an extensive math library for JavaScript and Node.js. It features a flexible expression parser with support for symbolic computation, comes with a large set of built-in functions and constants, and offers an integrated solution to work with different data types like numbers, big numbers, complex numbers, fractions, units, and matrices. Powerful and easy to use.

accounting-js

npm install accounting-js

accounting-js is a tiny JavaScript library for number, money and currency parsing/formatting. It's lightweight, fully localisable, has no dependencies, and works great client-side or server-side. Use standalone or as a nodeJS/npm and AMD/requireJS module.

Current Tags

  • 0.1.2                                ...           latest (2 years ago)

3 Versions

  • 0.1.2                                ...           2 years ago
  • 0.1.1                                ...           2 years ago
  • 0.1.0                                ...           2 years ago
Downloads
Today 0
This Week 3
This Month 3
Last Day 0
Last Week 0
Last Month 1
Dependencies (14)
Dev Dependencies (11)
Dependents (0)
None

Copyright 2014 - 2016 © taobao.org |