基于RESTful API开发的一个简单的WEB APP

在一个小Demo项目中,需要:

前后端配合完成数据配置(CRUD), 数据展示(前端主要用ECharts对数据进行图表展示);

后端完成数据的收集(实际上就是一个HTTP Server, 接收数据源POST请求提交的数据, 进行存储), 并对原始数据进行汇总和统计;

后端还需要提供RESTful风格的API, 与前端传递数据.

之前做的大部分开发工作, 包括使用的框架(Struts, Spring MVC, Django, Flask等),

都包含了前端view(或是template)部分的工作, 因此对于这种前后端完全分离的项目还是第一次实践.

不过, RESTful API在内外部对接时倒是用过很多次了, 因此这篇文章不会过多地涉及RESTful API的格式规范等内容.
(也可以参见这篇文章, 说的比较详细, 而且具有实际应用价值).

RESTful API接口文档

既然是前后端完全分离, 基于RESTful API协作,

那么一个接口全面, 定义详细, 最好再带上demo的API文档就是必不可少的了,

这也是前后端分别开发的重要依据.

编写这个API文档可不容易, 主要挑战集中在:

  1. 尽量考虑到全面的接口功能, 如有遗漏要尽快完善并重新发布文档
  2. 文档格式规范, 尤其是交互使用的json数据格式
  3. 每个接口最好配上一个demo request/response
  4. 随着开发的进行和需求的变化, 文档的变动会非常频繁, 需要及时维护

在这种架构下, 一个数据表的CRUD操作就会涉及到3-4个API接口, 同时每个接口需要有准确合理的数据和返回值,

虽然是个小Demo项目, API接口文档可足足写了11页, 下面是这个文档的几个小片段:

数据分析->人群属性->基本属性数据接口
接口:/console/crowd/basic
方法:GET
参数:无
返回:
{
“性别”: {“category”: [“男性”,
                “女性”,
                “未知”
               ],
       “data”: [{“name”: “男性”, “value”: 0.46},
            {“name”: “女性”, “value”: 0.45},
            {“name”: “未知”, “value”: 0.09}
           ]
        }
“人生阶段”:{…},
  …
}

数据分析->客流分析->频次时长接口
接口:/console/customerflow/freq
方法:GET
参数:
    start_date: 开始日期
    end_date: 结束日期
    device_id: 店铺ID
返回:
{  //进店频次
freq: {“category”: [
                “category_1”    //1次
                “category_2”    //2-3次
                “category_3”    //4-5次
                “category_4”    //6次以上
               ],
       “data”: [{“name”: “category_1”, “value”: 1},
            {“name”: ” category_2”, “value”: 2},
            {“name”: “category_4”, “value”: 4},
                …
           ]
        },
//停留时长
stay: {“category”: [
                “category_1”        //0-10分钟
                “category_2”        //10-30分钟
                “category_3”        //30-60分钟
                “category_4”        //60分钟以上
               ],
       “data”: [{“name”: “category_1”, “value”: 2},
            {“name”: ” category_2”, “value”: 3},
            {“name”: “category_4”, “value”: 4},
                …
           ]
        }

优缺点的思考

优点

在前后端分离的架构下,

基于RESTful API接口文档, 前后端开发人员可以完全独立地进行开发工作, 将另一端假想作已经存在的实体即可.

并根据接口文档的修改, 随时调整自己负责的代码.

这样前后端的开发非常独立, 不会受另一端的bug, 进度等等问题的影响.

同时, 两端的开发人员只需要关心自己那一侧的功能和代码即可,

不用像之前在MVC框架下开发时,

前端人员要了解不同的框架中模板语言的用法,

后端人员则要了解javascript等的用法.

缺点

对开发人员严格按照接口文档进行代码开发的要求很高;

相对于之前的框架式开发, 前端代码量会有些增加(主要在REST接口数据组织处理部分).


Comments

blogroll

social