通用WEB项目DEMO说明文档

通用WEB项目DEMO说明文档

项目结构说明

• src：java代码（包含配置文件）
• db：SQL脚本
• doc：文档相关
• produard：混淆相关代码
• WebContent：前端代码（包含jar包）
• build.properties：Ant项目构建配置文件
• build.xml：Ant项目构建运行文件
• README.md ：项目说明文档

遵循原则：约定大于规范

混淆说明

• 是否混淆开关：build.properties文件 deploy.isObfuscate 属性（true:混淆，false:不混淆）
• 关于混淆建议：
  • 因为构建是开启混淆比较慢，所以建议平时开发不开启混淆，提升开发速度。注意：上测试之前一定要混淆跑一遍。
  • 混淆具体配置，参见：/proguard/***.pro文件

通常，Controller层，Jre包以及自己引用的第三方jar包不混淆；Mybatis自动生成代码、过滤器代码、配置文件代码不混淆；
不混淆依据：通常导致混淆报错原因是混淆后类名和方法名改变，不赘述。与Spring的创建Bean和注入有关；

后端代码开发

文件结构约定

• 包名约定
  • 业务模块：com.公司名.项目名.模块名
  • 通用模块：com.公司名.项目名.common
  • 项目Java配置模块：com.公司名.项目名.config（包含AOP日志/异常处理等）
  • Mybaits代码模块：com.公司名.项目名.mybatis
  • 配置文件：config
  • 说明：
    • 这里没有按照“公司名.项目名”命名，按实际情况而定。
  • 示例：
    

Mybatis自动生成

这里没有完全实现自动化。需要开发者自行配置：
- MybatisStartUp.java 文件对应的两个路径
- generatorConfig.xml 对应路径以及连接数据库相关配置参数，还有相关表的配置

建议：稍加一些代码即可实现自动化配置。

properties文件参数引入

• Spring提供的引入方式为：@Value("${}")
• 所有通常开发者会在用到的时候直接引入。缺点：一个配置可能引入多次，当配置文件修改需要修改多处，维护困难。
• 建议封装为对象。实例参见：PropertiesConfig.java
• 同时引用多个参数时可封装为方法返回对象或者Map。

AOP处理

这里AOP处理主要两方面：

• 日志打印（这里仅仅做日志打印辅助，不能完全代替手动打印日志）
• 异常处理

日志打印

后端一般分为三层：Controller、Service、Dao
一般建议AOP拦截Controller层，打印入参出参。

• 指定方法或参数不打印
• 在默写情况我们不想打印某些参数，但是又被AOP拦截了。这时建议提供不打印日志注解。参考代码：实例代码NonAopLog.java类及其相关实现。
• 关于日志的一些建议：我觉得日志的作用是记录项目运行的状态，为了让运维人员更好的去了解正在运行的项目。但是这并不意味着日志越多越好，缺点不赘述。一般AOP日志基本上记录了一个业务处理的入参出参，简单的增删改基本上就没有必要再打印日志了，在业务逻辑稍微复杂一些，出现逻辑分支的时候，这里最好是打印日志。而我们在定义接口时接口的功能尽量单一，不要一个接口把所有的事都做完，难以维护。所以一般情况，逻辑不会太复杂，日志也不用打印太多。还有一点是，异常日志交给异常处理就行，如何理解，参见下一节。

异常处理

Java里将Exception异常分为两种：受检异常和不受检异常。额，如何深入理解，看书去。在这里作为一个开发人员，我将异常分为以下几类：

• 系统异常 - SystemException（比如：系统参数错误，非正常业务逻辑错误等）
• 业务异常 - BusinessException（比如：用户名不对，密码错误等）
• 参数校验异常 - CheckException（比如：字段不能为空等)
• 相关代码参见：config包代码

这里只要是使用try catch处理不能使业务流程正常的异常一律往上一层抛，直到Controller层，到AOP拦截，统一处理，打印异常参数，栈信息，并返回前端对应的信息。
当我们碰到像IOException这种受检异常时，如果不能使业务正常话，封装为BusinessException跑向上一层。

common包代码

• 实例：
  

common包代码一般建议开发人员不要改动，这里是经过验证的通用的且和业务无关的代码，新项目可以直接拷贝使用。
一般开发人员的通用代码，可以放入业务代码的common包中，如该代码经过评审，方可移入。
Common中常见的一些包：

• util包：以静态方法的形式被调用
• component：以Spring组件的形式被调用，这里有以下几种组件：
  • http包：Http接口调用的组件
  • message包：平安消息云发送短信组件
  • AuditingFieldsHelper：审计字段插入更新组件
• constant包：常量包
• Controller包：Controller层需要的类
• exception包：常用的异常定义
• business包：该包是common中唯一业务相关的代码，是各个业务模块公用的业务代码。

关于对外接口

提供对外接口的时候需要一些验证，demo实例里是将验证过程封装，减少代码冗余，详细情况见代码即可。

以为有验证，所以Postman测试行不通，所以模拟验证方法写了测试类，具体情况见代码。

前端代码开发

文件结构约定

• 文件夹约定
  • 引用文件：assets（如：jquery，bootstrap等）
  • css/html/images/js：按业务模块区分，如有公共部分，则提取出对应的common文件夹
    

通用文件建议

• 一般建议提取一下几个通用文件夹：
  • AjaxUtil.js：Ajax请求的封装。好处：便于请求响应的统一处理。（如：错误提示的统一风格显示，日志打印，页面跳转等等）
  • LogUtil.js：日志的封装。好处：所有日志代码的入口，提供是否打印日志开关。好处：一般开发测试的时候，打开打印日志，上生产则关闭。
  • cookieUtil.js：cookie工具类
  • sessionStorageUtil：sessionStorage和LocalStorage的封装，封装建议：双层Map封装。好处：存取以及清空时可按业务分类，避免遗漏处理。
  • pageSwitch.js：页面跳转代码统一入口。好处：逻辑更为清晰。
  • constants.js：常量定义。
  • responseCode.js：响应码的定义。（与后端响应配套出现）