ant-army

ant-army

简单易用的轻量级Web框架，只有一个源代码文件。请求方法只提供了GET和POST，这两种方法完全足够。如果你喜欢RESTFul风格，可以去扩展它。

此框架不需要解析POST数据的扩展，会自动解析POST请求数据。并且可以灵活设置POST请求允许的最大数据量。

!注意：此框架是我在一个周末开发的，后来也在不断的更新。当时的目的是想用于教学以及针对个人学习使用。我会尽力去完善的更加专业，从开发计划来说，在2.0版本之前，不建议用于生产环境，或者仅可以用于对服务要求不是很严格的场景。

另一方面，在处理HTTP协议的时候，还没有加入数据压缩的支持，如果你的服务传输数据量不大可以使用，后续会加入压缩支持。

开发此框架之前，我一直使用PHP做Web开发，对LNMP架构比较了解。在PHP处理Web请求的时候，GET，POST提交的数据是被解析好，直接拿过来使用的，并且在$_FILES中可以找到上传的文件，我在使用express的时候是需要·配合其他扩展才可以完成这些操作的，所以我想设计一个能把GET，POST请求以及上传文件的操作自动处理的框架，但尽可能精简，不要过于复杂。

此框架在设计上从PHP的Slim框架得到一些灵感，在此也感谢Slim框架的设计者。

！使用node，开发环境一定要使用Linux，事实上，所有的服务端程序都要运行在Linux/Unix平台上，科学计算、机器学习等领域也都是在这些平台上，Windows上不能提供很好的支持，而且性能很差。如果你去了解，其实微软内部大量使用Linux，这也是微软公布过的。

本教程的示例使用了Linux命令，不要在Windows上试用。

安装

npm install ant-army

从Hello world开始

创建server.js文件，

const ant = require('ant-army');

ant.get('/', (req, res) => {
    res.end('Hello world\n');
});

ant.run('127.0.0.1', 3456);

终端运行：node server.js

浏览器访问http://127.0.0.1:3456即可查看结果，或者使用curl命令：

$ curl  'http://127.0.0.1:3456/'

输出结果：Hello world

写给基础用户：

curl是一个Linux/Unix上的命令，实现了很多常见协议，能够通过命令快速发送数据。可以用于测试环境，脚本处理，嵌入其他程序等。如果你没有此命令需要安装，安装方式如下：

CentOS/ReadHat分支：sudo yum install curl

Ubuntu/Debian分支：sudo apt install curl

如果你是root用户登录（命令提示符会变成#），则不需要加上sudo。

加入POST请求

POST请求发送的数据会自动解析，你的代码在处理请求时，可以通过req.POST获取POST提交的数据，通过req.GET获取url的query参数。数据以JSON键值对的形式存储。

ant框架提供了res.send函数用于发送响应数据，在其内部会调用res.end函数。res.send会自动序列化JSON对象，Array对象。

const ant = require('ant-army');

ant.get('/', (req, res) => {
    res.end('Hello world\n');
});

ant.post('/post-test', (req, res) => {
    res.send(req.POST);
});

ant.run('127.0.0.1', 3456);

终端运行curl命令：

curl  'http://127.0.0.1:3456/post-test' -d 'a=123&b=345'

输出结果：

{"a" : "123", "b" : "345"}

上传文件

上传是POST请求，所以会被ant自动解析，上传文件和普通的POST表单请求的HTTP头信息字段Content-Type值不同，普通表单提交是application/x-www-form-urlencoded，而要是上传文件是multipart/form-data，上传的文件在body中还有一个扩展的头信息，也会有Content-Type表示的是文件的具体类型。

ant框架会检测两种不同的提交类型，如果是普通POST提交，数据会放在req.POST中，而上传文件时往往也会伴随着其他的表单提交，但是那些非文件类型和文件数据都按照相同的格式存放，只不过扩展头信息没有Content-Type，此时这些字段仍然会被解析到req.POST中。

上传的文件数据都放在req.upload_files中，上传的文件数据会按照上传时name值进行分类，比如表单中：

<input type="file"  name="image">

上传时，服务端解析到的头信息表明了name的值，所以在req.upload_files['image']可以找到上传的文件，

注意这是一个数组，每个元素都是这样的形式：

{

	'filename'     :  文件的名称,

	'data'         : 文件数据,

 	'content-type' :  文件的媒体资源类型,  //比如image/png

}

所以对于单个文件可以从req.upload_files['images'][0]找到
如果你同时上传了name值为file和image的文件，并且每个都是多个，则会有req.upload_files['image']和req.upload_files['file']，每个都是数组，数组中的元素就是上传的文件数据和基本信息。

处理上传的文件是很简单的，ant提供了moveUploadFile接口处理上传的文件，实际上你可以用你自己的函数直接操作req.upload_files数据。

const ant = require('ant-army');

//设置上传文件的路径
ant.config.upload_path = './upload';

ant.post('/upload', (req, res) => {

    if (req.upload_files['image'] !== undefined) {
        
        /*
        	moveUploadFile接受4个参数：
        	files        : 文件列表，是一个数组
        	file_index   : 文件数组的索引值，默认为0
        	upload_name  : 上传文件的名称，这个名称不一定要和req.upload_files键值对应，
        				   主要作用是会在上传目录下自动创建此目录然后把文件上传至此目录
        	target_file  : 目标文件的路径，是包括名称的路径，如果不提供则会使用默认的名称生成						   方式
        	此函数最开始调用是异步的形式，现在的版本有意设计成了同步的形式。
        */
        var up_ret = ant.moveUploadFile(req.upload_files['image'], 0, 'image');
        
        if (up_ret === false) {
            res.send('Error : file not found');
        } else if (up_ret.message !== undefined) {
            //上传出错会返回Error对象
            res.send(up_ret.message);
        } else {
            //正常的数据
            res.send(up_ret);
        }

    } else {
        res.send('Error: file not found');
    }
});

ant.run('127.0.0.1', 3456);

/*

终端运行命令：
curl  'http://127.0.0.1:3456/upload' -F 'image=@tmp/d6.jpg'
参数-F表示上传文件，tmp/d6.jpg是本机的文件路径

返回结果：
{
    "filename"    : "1026592302902308aabadd9a9030d2638c3d2c0e.jpg",
    "orgname"     : "d6.jpg",
    "path"        : "./upload/image",
    "upload_name" : "image"
}
*/

路由

此框架的路由模式非常简单：除了普通的字符串情况之外，只提供了两种用变量的情况。

/*
/content/:id
  :开头的是必须的变量。

/content/:id/@type
  @开头的是可选择，并且只能出现在路由的最后。

这种路由，在回调函数中，需要有一个args参数作为回调函数的第三个参数，以变量的名称作为索引值。
*/

ant.get('/content/:id', (req, res, args) => {
    res.send(args['id']);
});

/*
    此时，请求/content/1234，响应的结果是1234。
*/

配置选项

你可以通过ant.config获取配置选项，并且可以直接修改。在使用ant.run或ant.ants运行时会自动生效。

ant.config = {

    //此配置表示POST提交表单的最大字节数，也是上传文件的最大限制，
    //注意在run函数中设置了上限的最小值，如果用户设置的上限过低则会自动改为最小值。
    post_max_size   : 10000000,

    //静态文件根目录
    static_path     : '',

    //开启静态文件支持
    static_on       : false,

    //开启守护进程，守护进程用于上线部署，要使用ants接口，run接口不支持
    daemon          : false,

    log_file        : './access.log',

    error_log_file  : './error.log',

    /*
            日志类型：
                stdio   标准输入输出，可用于调试
                ignore  没有
                file    文件，此时会使用log_file以及error_log_file 配置的文件路径

            这个选项以及两个日志文件配置只有在开启daemon的情况下才会生效
        */
    log_type        : 'stdio',
    

    //默认上传路径，自动上传函数会使用
    upload_path     : './upload',

    //开启HTTPS
    https_on        : false,

    //HTTPS密钥和证书的路径，启用http_on会使用此选项
    https_options   : {
        key     : '',
        cert    : ''
    },
    
};

静态文件支持

const ant = require('ant-army');

ant.config.static_on = true;
ant.config.static_path = './static';

ant.run('127.0.0.1', 3456);

/*
你需要做的就这么多，这已经实现了一个静态文件服务器。你只需要把文件放在当前目录的static目录中即可。
即使有子目录也可以访问。
比如在static目录存在文件main.css
在浏览器访问127.0.0.1:3456/main.css就可以直接获取main.css的数据。
静态文件服务和动态路由是可以同时共存的，如果是为了灵活，或者说一个单独的静态文件服务，可以分开部署。
*/

中间件

ant提供了简单的中间件模式，比如你想支持session会话，上传文件进行过滤都可以使用中间件完成。

中间件调用的最后一定要有next.method(req, res, next.next);说实话，设计成这个样子我也不是十分满意，最开始的版本是要求中间件必须是同步的处理过程，但是由于很多操作可能会涉及到异步，所以中间件使用了Promise回调链，这是一个自动执行的过程，所以也要求必须要这样写。中间件可以是同步，也可以使用Proimse完成异步操作。

后续的版本中计划简化中间件的编写，不过如果仅仅是编写简单的中间件逻辑上并不复杂。并且我也开发了几个常用的中间件，可以直接使用。

ant的中间件是一个接收三个参数的函数：

//如果请求可以通过中间件，则在最后一定要有：return next.method(req, res, next.next);
function(req, res, next) {
    ...
    ...
    return next.method(req, res, next.next);
}

//使用Promise
function(req, res, next) {
    return new Promise((rv, rj) => {
        ...
        rv({
            req  : req,
            res  : res,
            next : next
        });
    }).then((rr) => {
        ...
        return rr.next.method(rr.req, rr.res, rr.next.next);
    });
}

中间件支持路由匹配，如果不设置，默认为所有路由都会经过中间件的处理。 ant提供了两个接口用于添加中间件，ant.addmiddle 和 ant.usemiddle，ant.usemiddle会调用ant.addmiddle。

ant.addmiddle添加中间件：

//只对/test路由才会起作用
ant.addmiddle((req, res, next){
    ...
    return next.method(req, res, next.next);
}, '/test');

使用中间件支持跨域

ant.addmiddle((req, res, next){
    res.setHeader('Access-Control-Allow-Origin', '*');
    return next.method(req, res, next.next);
}, '');