Koa2 RESTful API 服务器脚手架

这是一个基于Koa2的轻量级Resultful API Server脚手架，支持ES6。

约定使用JSON格式传输数据，POST、PUT、DELET方法支持的Content-Type为application/x-www-form-urlencoded和multipart/form-data、application/json，可配置支持跨域。非上传文件推荐application/x-www-form-urlencoded。通常情况下返回application/json格式的JSON数据。

可选用mongodb、redis非关系型数据库和PostgreSQL, MySQL, MariaDB, SQLite, MSSQL关系型数据库，考虑RESTful API Server的实际开发需要，这里通过sequelize.js作为ORM，同时提通过Promise执行SQL直接操作Mysql数据库的方法（不管什么方法，注意安全哦）。

此脚手架只安装了一些和Koa2不冲突的搭建RESTful API Server的必要插件，附带每一个插件的说明。采用ESlint进行语法检查。

因此脚手架主要提供RESTful API，故暂时不考虑前端静态资源处理。基本目录结构与vue-cli保持一致，可配合React、AngularJS、Vue.js等前端框架使用。在Cordova/PhoneGap中使用时需要开启跨域功能。

免责声明： 此脚手架仅为方便开发提供基础环境，任何人或组织均可随意克隆使用，使用引入的框架需遵循原作者规定的相关协议（框架列表及来源地址在下方）。采用此脚手架产生的任何后果请自行承担，本人不对此脚手架负任何法律责任，使用即代表同意此条。

目前暂未加入软件测试模块，下一个版本会加入该功能并提供集成方案。

China大陆用户请自行优化网络。

开发使用说明

$ git clone https://github.com/yi-ge/koa2-API-scaffold.git

$ cd mv koa2-API-scaffold
$ npm install
$ npm run dev #可执行npm start跳过ESlint检查。

访问： http://127.0.0.1:3000/

另外一种方式，如果你使用git仓库管理你的代码：

$ git clone https://github.com/yi-ge/koa2-API-scaffold.git

$ mv koa2-API-scaffold `您的项目名称`
$ cd `您的项目名称`
$ rm -rf .git
$ git init
$ git remote add origin `您的git仓库地址`
$ npm install
$ npm run dev #可执行npm start跳过ESlint检查。

调试说明

$ npm start --debug

Or

$ npm start --debug

支持Node.js原生调试功能：https://nodejs.org/api/debugger.html

开发环境部署

生成node直接可以执行的代码到dist目录：

$ npm run build

$ npm run production # 生产模式运行

Or

$ node dist/app.js

PM2部署说明

提供了PM2部署RESTful API Server的示例配置，位于“pm2.js”文件中。

$ pm2 start pm2.js

PM2配合Docker部署说明： http://pm2.keymetrics.io/docs/usage/docker-pm2-nodejs/

Docker部署说明

$ docker pull node
$ docker run -itd --name RESTfulAPI -v "$PWD":/usr/src/app -w /usr/src/app node node ./dist/app.js

通过

$ docker ps

查看是否运行成功及运行状态

Linux/Mac 直接后台运行生产环境代码

有时候为了简单，我们也这样做：

$ nohup node ./dist/app.js > logs/out.log &

查看运行状态（如果有"node app.js"出现则说明正在后台运行）：

$ ps aux|grep app.js

查看运行日志

$ cat logs/out.log

监控运行状态

$ tail -f logs/out.log

配合Vue-cli部署说明

Vue-cli（Vue2）运行"npm run build"后会在"dist"目录中生成所有静态资源文件。推荐使用Nginx处理静态资源以达最佳利用效果，然后通过上述任意一种方法部署RESTful API服务器。前后端是完全分离的，请注意Koa2 RESTful API Server项目中config/main.json里面的跨域配置。

推荐的Nginx配置文件：

server
    {
        listen 80;
        listen [::]:80;
        server_name abc.com www.abc.com; #绑定域名
        index index.html index.htm;
        root  /www/app/dist; #Vue-cli编译后的dist目录

        location ~ .*\.(gif|jpg|jpeg|png|bmp|swf)$
        {
            expires      30d;
        }

        location ~ .*\.(js|css)?$
        {
            expires      12h;
        }

        location ~ /\.
        {
            deny all;
        }

        access_log off; #访问日志路径
    }

Docker中Nginx运行命令(将上述配置文件任意命名放置于nginx_config目录中即可)：

$ docker run -itd -p 80:80 -p 443:443 -v `pwd`/nginx_config:/etc/nginx/conf.d nginx

引入插件介绍

引入插件的版本将会持续更新

引入的插件：
koa nodemon babel-cli babel-register babel-plugin-transform-runtime babel-preset-es2015 babel-preset-stage-2 gulp gulp-eslint eslint eslint-config-standard eslint-friendly-formatter eslint-plugin-html eslint-plugin-promise

"koa-bodyparser": "^3.2.0", "koa-compose": "^3.1.0", "koa-convert": "^1.2.0", "koa-favicon": "^2.0.0", "koa-json": "^1.1.3", "koa-logger": "^1.3.0", "koa-multer": "^1.0.0", "koa-router": "^7.0.1", "koa-session": "^3.3.1", "koa-static2": "^0.1.8", "koa-onerror": "^3.0.1",

koa: HTTP框架
 Synopsis: HTTP framework.
 From: https://github.com/koajs/koa

babel-cli: Babel编译ES6代码为ES5代码
 Synopsis: Babel is a JavaScript compiler, ES6 to ES5.
 From: https://github.com/babel/babel/tree/master/packages/babel-cli

babel-register: Babel开发环境实时编译ES6代码
 Synopsis: Babel hook.
 From: https://github.com/babel/babel/tree/master/packages/babel-cli

babel-plugin-transform-runtime: Babel配置ES6的依赖项
babel-preset-es2015: 同上
babel-preset-stage-2: 同上

gulp: 基于流的自动化构建工具
 Synopsis: Gulp is a toolkit for automating painful or time-consuming tasks.
 From: https://github.com/gulpjs/gulp

gulp-eslint: gulp的ESLint检查插件
 Synopsis: A gulp plugin for ESLint.
 From: https://github.com/adametry/gulp-eslint

gulp-nodemon: 修改JS代码后自动重启
 Synopsis: nodemon will watch the files in the directory in which nodemon was started, and if any files change, nodemon will automatically restart your node application.
 From: https://github.com/remy/nodemon

eslint: JavaScript语法检查工具
 Synopsis: A fully pluggable tool for identifying and reporting on patterns in JavaScript.
 From:

eslint-config-standard: 一个ESlint配置  Synopsis: ESLint Shareable Config for JavaScript Standard Style.
 From: https://github.com/feross/eslint-config-standard

eslint-friendly-formatter: 使得ESlint提示在Sublime Text或iterm2中更友好，Atom也有对应的ESlint插件。
 Synopsis: A simple formatter/reporter for ESLint that's friendly with Sublime Text and iterm2 "click to open file" functionality
 From: https://github.com/royriojas/eslint-friendly-formatter

eslint-plugin-html: 检查HTML文件中的JS代码规范
 Synopsis: An ESLint plugin to extract and lint scripts from HTML files.
 From: https://github.com/BenoitZugmeyer/eslint-plugin-html

eslint-plugin-promise: 检查JavaScript promises
 Synopsis: Enforce best practices for JavaScript promises.  From: https://github.com/xjamundx/eslint-plugin-promise

eslint-plugin-promise: ESlint依赖项
 Synopsis: ESlint Rules for the Standard Linter.  From: https://github.com/xjamundx/eslint-plugin-standard

支持Koa2的中间件列表：https://github.com/koajs/koa/wiki

其它经常配合Koa2的插件：
koa-nunjucks-2:
一个好用的模版引擎，可用于前后端，nunjucks。https://github.com/mozilla/nunjucks

目录结构说明

.
├── README.md
├── .babelrc                # Babel 配置文件
├── .editorconfig           # 编辑器风格定义文件
├── .eslintignore           # ESlint 忽略文件列表
├── .eslintrc.js            # ESlint 配置文件
├── .gitignore              # Git 忽略文件列表
├── gulpfile.js             # Gulp配置文件
├── package.json            # 描述文件
├── pm2.js                  # pm2 部署示例文件
├── build                   # build 入口目录
│   └── dev-server.js       # 开发环境 Babel 实时编译入口
├── config
│   └── main.js             # 主配置文件（*谨防泄密！）
├── src                     # 源代码目录，编译后目标源代码位于 dist 目录
│   ├── app.js              # koa 配置
│   ├── config              # 配置目录
│   ├── controllers         # 控制器
│   ├── index.js            # 入口文件
│   ├── models              # 模型
│   ├── routes              # 路由
│   └── services            # service
└── logs                    # 日志目录

各类主流框架调用RESTful API的示例代码（仅供参考）

AngularJS (Ionic同)

$http({
	method: "post",
	url: "http://localhost:3000/xxx",
	data: {para1:"para1",para2:"para2"},
	headers: {
	    'Content-Type': 'application/x-www-form-urlencoded'
	}
 }).success(function (data) {
 }).error(function (data) {
 });

jQuery

$.ajax({
  cache: false,
  type: 'POST',
  url: "http://localhost:3000/xxx",
  data: {
      para1: para1
  },
  async: false,
  dataType: "json",
  success: function (result) {
  },
  error: function (err) {
      console.log(err);
  }
});

// 上传文件
//创建FormData对象
var data = new FormData();
//为FormData对象添加数据
//
$.each($('#inputfile')[0].files, function (i, file) {
  data.append('upload_file', file);
});
$.ajax({
  url: 'http://127.0.0.1:3000/api/upload_oss_img_demo',
  type: 'POST',
  data: data,
  cache: false,
  contentType: false,    //不可缺
  processData: false,    //不可缺
  success: function (data) {
    console.log(data);
    if (data.result == "ok") {
      $("#zzzz").attr("src", data.img_url);
    }

  }
});

MUI

mui.ajax({ url: "http://localhost:3000/xxx", dataType: "json",
  success: function(data){

  },
  error: function(data){
      console.log("error!");
  }
});

JavaScript

  var xhr = new XMLHttpRequest()
  xhr.open("POST", "http://localhost:3000/xxx", true) //POST或GET，true（异步）或 false（同步）
  xhr.setRequestHeader("Content-type", "application/x-www-form-urlencoded")
  xhr.withCredentials = true
  xhr.onreadystatechange = function () {
      if (obj.readyState == 4 && obj.status == 200 || obj.status == 304) {
          var gotServices = JSON.parse(xhr.responseText)
      }else{
          console.log("ajax失败了")
      }
  }
  xhr.send({para1: para1})

vue-resource

https://github.com/pagekit/vue-resource

// global Vue object
Vue.http.post('/someUrl', [body], {
  headers: {"Content-type", "application/x-www-form-urlencoded"}
}).then(successCallback, errorCallback);

fetch

https://github.com/github/fetch

fetch('/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Hubot',
    login: 'hubot',
  })
}).then(function(response) {
  // response.text()
}).then(function(body) {
  // body
})

// 文件上传
var input = document.querySelector('input[type="file"]')

var data = new FormData()
data.append('file', input.files[0])
data.append('user', 'hubot')

fetch('/avatars', {
  method: 'POST',
  body: data
})

superagent

https://github.com/visionmedia/superagent

request.post('/user')
 .set('Content-Type', 'application/json')
 .send('{"name":"tj","pet":"tobi"}')
 .end(callback)

在React中可以将上述任意方法其置于componentDidMount()中，Vue.js同理。

彻底移除ESlint方法

删除package.json的devDependencies中所有eslint开头的插件，根目录下的“.eslintignore、.eslintrc.js”文件，并且修改package.json的dev为：

"dev": "gulp start"

删除gulpfile.js中的lint、eslint_start两个任务，并且把default改为“gulp.task('default', ['start']”。