Chion82/项目架构文档.md

## 项目架构文档.md

      
    Raw
  

              项目架构文档.md
            
          
    #项目整体架构
##概述
本项目采用基于Node全栈式开发的NodeJS Midway架构，详细实现原理请参照 淘宝UED。

前端除了需要编写UI层的HTML、CSS和JavaScript等浏览器端UI和控制逻辑，还需要编写NodeJS中间层控制逻辑。NodeJS中间层与后端服务器进行RESTful通信并预渲染页面，同时返回部分静态文件。用户在浏览器端访问的服务器是NodeJS中间层的预渲染服务，真后端服务器不暴露。

交互图示如下：


##前后端交互流程

接口定义： 后端开发人员定义好全部RESTful API的URL、请求方式（GET/POST），并保存在NodeJS层的ModelProxy库的接口定义文件/interfaces.json中。  若在开发环境下，后端开发人员将提供全部RESTful API的mock数据，每个API以独立json文件保存在/interface_rules目录下，ModelProxy开启mock模式（/interfaces.json中status从online设置为mock）ModelProxy详细文档
调用接口：NodeJS中间层（使用expressjs框架）收到客户访问请求时，控制逻辑通过ModelProxy库调用上述API，并根据API需求必要时双向传递浏览器端和后端的Cookies数据。
预渲染： NodeJS中间层控制逻辑根据后端API返回的数据生成可视化数据（即将Models转换为View Models），调用模板（templates）文件并填充view models数据。
返回页面： NodeJS将经过预渲染的页面返回到用户浏览器。

##交互示例


完整示例：https://github.com/Chion82/NodeJS_midway_sample.git


后端接口为：


作用：计算两个正整数的和

URL： http://localhost:5000/api/sum

请求方式：GET

请求参数：a - 整数，第一个加数；b - 整数，第二个加数

返回值：status - 状态码，200为正常；sum - 相加结果


/interfaces.json

{
    "title": "Sample interfaces",
    "version": "1.0.0",
    "engine": "mockjs",
    "rulebase": "./interface_rules/",
    "status": "online",
	"interfaces": [
        {
            "name" : "RESTful API test interface",
	        "id" : "Test.sum",
            "urls" : {
                "online" : "http://localhost:5000/api/sum"
            }
        }
    ]
}

/interface_rules/Test.sum.rule.json

{
	"request" : {
		"a" : "",
		"b" : ""
	},
	"response" : {
		"status" : 200,
		"sum" : 100
	}
}

/routes/index.js

var express = require('express');
var router = express.Router();

//ModelProxy的初始化工作应在全局范围的/app.js里完成，此处为节省篇幅，在路由逻辑文件初始化
//整个NodeJS层中ModelProxy的初始化有且仅有一次
var ModelProxy = require('../lib/modelproxy.js')
ModelProxy.init('interfaces.json');

//生成Test对象作为该类API的父对象
var Test = new ModelProxy('Test.*');

/* URL路由控制逻辑 */
router.get('/', function(req, res, next) {
	//通过Test.sum调用该RESTful API
	Test.sum({
		'a' : req.query.a?req.query.a:0,//将GET参数作为API调用参数传入
		'b' : req.query.b?req.query.b:0
	}).done(function(data){//调用成功的回调函数
		if (data.status != 200) {
			res.send('Internal error');
			return;
		}
		//将API返回的结果作为模板参数，渲染index模板
		res.render('index',{ sum_result : data.sum })；
	})
});
#技术细节定义
##后端

语言：Python
Web框架：Flask
数据库：PostgreSQL + ORM
模块化：Flask Blueprint

##前端（NodeJS中间层）

Web框架：express.js
后端交互库/mock系统：ModelProxy
mock规则：mockjs
后端交互方式：RESTful API
前端交互方式：templates（模板）、RESTful API
HTML模板：swig
数据缓存：Redis

##前端（浏览器端）

包管理：bower
前端工作流：gulp.js （可能用到的插件：gulp-uglify, gulp-minify-html, gulp-minify-css, gulp-useref, gulp-rev, gulp-rev-replace）
预编译语言：LESS、JSX/ES6/CoffeeScript/JavaScript（待定）
MVVM库：AngularJS
UI：Bootstrap/Foundation/Semantic UI（待定）
JavaScript模块化：RequireJS、AMD

##生产环境

Linux发行版：CentOS 6/Debian/Arch Linux（待定）
wsgi容器：gunicorn/uwsgi（待定）
nginx + sock/本地端口反代

#模块划分
TODO
#接口定义
TODO