Web平台开发手册

1、1 修订记录日期版本修订目的描述修订章节作者审核2015/07/291.0文档初建 黄秀伟2015/08/041.1文档内容完善黄秀伟目录1修订记录12说明42.1概述42.2子系统命名42.3资源准备42.4项目发布53模块化开发53.1开发协作方式53.2工程目录规范53.2.1src_cnpc目录：63.2.2resources目录63.2.3WEB-INF目录63.2.4Psyche目录63.3配置文件统一管理74开发步骤74.1导入项目74.2配置菜单74.3新建模块85功能开发85.1RBAC模型85.2权限配置85.2.1菜单配置menu.xml95.2.2操作配置operati

2、on.xml105.2.3权限注解RequiresPermissions115.2.4角色授权115.3Rest 支持125.3.1概念125.3.2REST开发125.4操作日志记录145.4.1实现原理145.4.2使用方法155.5表单验证155.6图表echarts155.6.1简介155.6.2使用方法165.7报表模块175.7.1简介175.7.2使用方法185.8系统变量185.9用户首选项186打包部署187进阶配置182 说明2.1 概述本文档是web平台开发手册，根据CSOC项目需要，结合泰合对项目级系统开发平台的要求而编写的，面向项目开发人员，包括开发规范及开发流程等。

3、web平台将提供给用户Web开发手册、web工程及项目使用的软件包。2.2 子系统命名我们需要各子系统确定英文简称，因为项目开发中的权限控制注解、菜单id、数据库名、项目发布名都要用到子系统简称。参见下表：子系统名称子系统简称门户子系统portal工作流系统workflow数据子系统data解析子系统analysis批处理子系统Batch processing？2.3 资源准备l 项目开发在Windows7 64位系统上，部署在Linux系统上。为了避免一些兼容性问题，请使用我们的提供的软件包进行开发，包括Tomcat、Eclipse、JDK、Mariadb 、HeidiSQL等。l 本框架使

4、用的组件及版本如下表：组件名称版本号Spring4.1.4Hibernate4.1.8Shiro1.2.0jQuery1.7Bootstrap3.3.4J2EE6Log4j1.2.17junit4.8.2jstl1.2echarts 项目发布由于各组之间的项目发布名称不能重复，故规定发布的项目名称为子系统英文简称，各组拿到项目后首先要将发布名称修改为自己的子系统简称。参见2.2子系统统命名章节。修改方法如下：项目导入eclipse后，右键项目名称>选择properties > web project settings à将context root 内容改为

5、子系统简称。3 模块化开发3.1 开发协作方式采用协作开发方式，web平台与其他系统做协作开发，我们会将web平台本身的功能打成jar包形式，其他组不允许修改平台的源码，只能在现有平台上按照规范开发自己系统的功能。3.2 工程目录规范工程要严格按照web框架要求进行开发。3.2.1 src_cnpc目录：用来存放开发模块的Java类及部分配置文件。在src_cnpc目录的pc的包下新建模块。格式：pc.模块名在模块下面建包，包名称要严格按照以下规范命名：l controller包：存放自己的controller访问控制层，因为要通过扫描所有的controller方法名来记录日志，所以命名必须为

6、controller，。l entity包：存放实体类l service包：存放自己的service接口，在service.impl存放实现类l dao包：存放dao的接口，在dao.impl下存放自己的实现类3.2.2 resources目录Ø WebContent/resources目录存放脚本、样式、图片等静态资源。Ø 分别在js，css，img下建子文件夹（要求文件夹名称与模块名相同）存放各个模块的js，css，img文件。3.2.3 WEB-INF目录Ø WebContent /WEB-INF目录中存放jsp页面。Ø 在jsp文件加下建子文件夹

7、（要求文件夹名称与模块名相同）存放各个模块的jsp文件。3.2.4 psyche目录Ø 在文件夹或包名是psyche的目录，存放的是平台所用的组件，其中psyche/common目录下存放的是通用组件。Ø 由于框架升级原因不允许对psyche下的目录做任何操作，（升级时会覆盖这个目录下的文件，如果有需要请联系架构组人员）。3.3 配置文件统一管理Web框架对配置文件进行统一管理，必须按照以下配置文件名称命名。Ø 基础配置文件：必须功能Ø menu.xml：菜单配置文件，存放在WEB-INF下的config目录下，为了初始化时提供一个demo界面，如果没有

8、配置menu.xml系统则会自动加载demo1中的菜单。Ø perties后台表单数据校验的配置文件，存放在src_cnpc下，后台校验必须要有。Ø 高级进阶配置文件：非必须功能。参见进阶配置章节。4 开发步骤4.1 导入项目l 我们会给出一个工程，拿到工程后首先导入eclipse，在数据库中创建数据库，库名称为子系统简称。 l 在根目录下的ddl文件夹中建脚本文件，名称为”子系统简称.sql” （非必须, 如果没有脚本可以省略）。l 手动初始化，执行ddl下的脚本导入数据库（打包不打进去），启动无报错后进行下一步。4.2 配置菜单导

9、入项目后第一件事就是确定配置系统的菜单，菜单是通过menu.xml文件配置的。该文件存放在：WEB-INF/config/子系统名下面，会显示在首页菜单列表位置，并且支持多级菜单。菜单的配置与权限有紧密关系，一定要慎重。给角色设置权限时会读取该文件，按照菜单授予对等操作权限。参见下面章节介绍的“权限配置“中的“菜单配置menu.xml”内容。4.3 新建模块参考工程目录规范，建模块、添加静态资源及jsp页面5 功能开发5.1 RBAC模型Web平台权限控制采用shiro+RBAC模型实现的。RBAC模型如下:模型分析：Ø 用户与角色是多对多的关系，一个用户可以拥有多个角色，一个角色可

10、以赋给多个用户；Ø 权限只赋予给角色，每个角色可以拥有多个权限，用户属于某个角色即拥有该角色所有的权限。5.2 权限配置权限通过注解和xml配置，xml分为菜单配置menu.xml和操作配置operation.xml。5.2.1 菜单配置menu.xmlmenu.xml文件是对菜单的配置，存放在：WEB-INF/config/子系统名下面，显示在首页菜单列表位置，支持多级菜单。Xml文件格式如下：<?xml version="1.0" encoding="UTF-8"?><root><menu name="

11、;权限管理" id = "workflow_pms"><img>/resources/img/demo1/pms.png</img><menu-item name="用户管理" id = "wf_pms_user"><img>/resources/img/demo1/user.png</img><url>pms/user/list.do</url></menu-item><menu-item name="角色

12、管理" id = "wf_pms_role"><img>/resources/img/demo1/role.png</img><url>pms/role/list.do</url></menu-item></menu><menu name="日志管理" id = "wf_log"><img>/resources/img/demo1/log.png</img><url>log/list.do</u

13、rl></menu></root>文件节点说明l <menu></menu>：一级菜单l <menu-item></menu-item>：子菜单属性说明：l name：模块名称（中文），必输项。l id：模块id（英文），唯一标识不能重复，必输项。(1) 一级模块id命名规范格式：子系统简称_模块名实例：wf_process含义：工作流系统中的流程管理模块id(2) 二级模块id命名规范（只支持2级）格式：一级模块id_模块名实例：wf_process_def含义：工作流系统中流程管理模块的子模块流程定义模块注：代码

14、中权限控制方法上的注解模块名要与id保持一致（参见下面的权限注解）。l img：菜单显示的图标，非必输。l url：访问地址，非必输。注意事项：1、配置中的id属性值是与权限控制注解中的模块名一致（详情参见权限注解章节）。2、菜单配置后，如果已经有角色的授权操作，那么id不可以再改变，如果id改变会影响已经入库的角色权限对应关系，后果很严重。5.2.2 权限注解RequiresPermissions将权限注解加在controller层的所有类的方法上的，如果不加，系统默认所有用户都有权限，请慎重考虑。格式: RequiresPermissions("模块名#操作类型")实例

15、: RequiresPermissions("portl_user#read")说明：l 模块名与操作类型必须用#分开：#前面是模块名称，不可重复，与menu.xml中的id一致；#后面的为操作类型，与operation.xml配置的操作类型保持一致。目前支持read、write、execute三种操作类型。5.2.3 操作配置operation.xmloperation.xml是操作类型配置文件，平台默认支持读、写、执行三个操作类型，该文件是平台内容，不允许各组修改，如需扩展请说明理由，我们再对系统进行升级。Xml配置如下：<operation> <it

16、em> read/读</item><item> write/写</item><item> execute/执行</ item></operation>说明：英文是权限注解中的操作类型，中文名是下面介绍的角色授权的列名，即操作类型。5.2.4 角色授权角色授权界面中，把所有menu.xml中的菜单节点的name值取出来作为行标题；把operation.xml中的item中文值即操作类型名作为列标题，用户提交后，将角色和权限信息保存至RolePermissionRel表中，存储权限编号为“模块名#操作类型名”。界面如下图

17、所示：读写执行权限管理用户模块角色模块。提交例如上例中点保存后的RolePermissionRel存储为如下信息：角色编号权限编号001portl_user#read001portl_user#execute001portl_role#write5.3 Rest 支持5.3.1 概念REST即表述性状态转移，是一组架构约束条件和原则，是一种针对网络应用的设计和开发方式，可以降低开发的复杂性，提高系统的可伸缩性。满足REST约束条件和原则的应用程序或设计就是RESTful。简单说是对系统资源访问的一种规范。5.3.2 REST开发开发过程中rest主要应用在子系统之间的通讯，统一规定使用REST

18、ful的URL请求访问，即参数化的URL（将变量输入作为URL的一部分），URL中只含有名词，而不含有动词，示例：http:/localhost:8080/psyche/user/123含义：表示请求id为123的用户信息l 以对user资源的增删改查操作为示例，讲解如何做到符合rest规范开发。Ø user的获取，以GET方式请求：ControllerRequestMapping(“/user”)Public class UserControllerPrivate UserService userService;/使用GET获取资源RequestMapping(value=”/id

19、”,method=RequestMethod.GET)public String getUser(PathVariable(“id”) long id,Model model)Model.addUser(userService.getUserById(id);Return “user/view”;说明：UserController上的RequestMapping值与getUser方法上的RequestMapping的value值拼接是请求URL值。getUser方法上使用RequestMapping注解的value属性接收id参数值，method属性指定请求的方法类型使用PathVariabl

20、e注解传递方法参数，RequestMethod除了GET方法还有POST ，PUT，DELETE方法。Ø 使用PUT更新资源，如下:RequestMapping(value=”/id”,method=RequestMethod.PUT)ResponseStatus(HttpStatus.NO_CONTENT) /返回请求处理成功状态码，不包含任何返回信息public String putUser(PathVariable(“id”) long id,Model model,Valid User user)userService.saveuser(user);说明：方法上加Respon

21、seStatus(HttpStatus.NO_CONTENT)注解，用于返回请求处理成功状态码，但是不包含任何返回信息。Valid：实体设置+类+类的引用，直接将页面传过来的production对象中的信息封装到里面去了Ø 使用DELETE删除资源RequestMapping(value=”/id”,method=RequestMethod. DELETE)ResponseStatus(HttpStatus.NO_CONTENT) /返回请求处理成功状态码，不包含任务返回信息public String deleteUser(PathVariable(“id”) long id)use

22、rService.deleteuser(id);Ø 使用POST创建资源，新增user并返回JSON实体串RequestMapping(method=RequestMethod.POST)/处理POST请求ResponseStatus(HttpStatus.CREATE) /返回请求处理成功状态码，返回信息包含新创建资源的URLpublic RsponseBody User createUser(Valid User user, HttpServletResponse response) userService.saveUser(user);return user;/返回User资源

23、说明：使用RsponseBody注解，返回格式规定为JSON格式，即将user实体以JSON串形式返回。5.4 操作日志记录5.4.1 实现原理操作日志将记录用户的所有操作，通过Spring Aop把controller文件夹下所有类的方法作为切点进行拦截，截取出LogWrite (description = "操作描述")里的description内容，记录操作日志。记录的字段包括：用户ip、操作描述、操作的结果、访问的方法名、访问时间、操作异常类型、异常的详情等信息。5.4.2 使用方法在每一个controller层类的方法上加注解LogWrite (descripti

24、on = "操作描述")。如果操作类型为空则默认记录访问方法的url。5.5 表单验证表单校验分为前台校验和后台校验，要求严格按照下方规范开发。Ø 错误提示颜色：红色字体。Ø 提示信息位置：输入类型错误信息位置在输入框右上方；逻辑操作失败则弹出操作错误提示弹出框。Ø 前台校验使用jquery.validate控件来保证表单提交数据的合理性，可以通过对字段配置required，email，number等来决定字段的必填，是否是邮件类型，是否是数字等约束。详情参见前台表单校验文档Ø 后台采用Hibernate-validator来进行验证

25、，后台校验通过在实体类属性上配置注解NotNull，Email，Digits(integer=整数位数, fraction=小数位数)来定义约束。详情参见后台表单校验文档5.6 图表echarts5.6.1 简介图表采用ECharts控件，它是基于Canvas，纯Javascript图表库，提供直观，生动，可交互，可个性化定制的数据可视化图表。可提供商业产品常用图表库，底层基于ZRender，创建了坐标系，图例，提示，工具箱等基础组件，并在此上构建出折线图（区域图）、柱状图（条状图）、散点图（气泡图）、饼图（环形图）、K线图、饼图（环形图）、雷达图、地图、和弦图以及力导向布局图，同时支持任意维

26、度的堆积和多图表混合展现。示例图如下：5.6.2 使用方法由于考虑到兼容问题，不推荐使用IE浏览器。以下只是Echarts初步调研，还需进一步研究，细节有待完善.Ø 引入echarts.js文件<body><div id="main" style="height:400px;"></div> .<script src="./js/echarts.js"></script></body>Ø 配置require.conifg<body>

27、<div id="main" style="height:400px;"></div>.<scriptsrc="./js/echarts.js"></script><script type="text/javascript">require.config(paths: echarts: './js/dist' );</script></body>Ø 动态加载使用echarts<body><div id="main" style="height:400px;"></div><scriptsrc="./js/echa