平台代码规约

本文档是研发规范的一部分，阐述了平台的代码规范、框架说明。

本文档未阐述一般性的Java源文件规范，相应的规范请参考：《Java源文件规约》。

Maven子项目模块划分

项目统一使用Maven进行管理，每一个系统模块会分为api、provider、service-webapp、biz、mvc和web-webapp包，方便实现各个项目之间的模块化管理，并尽可能的减少各模块之间的依赖。

api

• 各个模块间通过api进行通信。
• 存放service接口类、通讯实体类：QO、BO、DTO。

provider

• api 模块的实现，
• 存放数据库表和视图映射的entity、映射文件、Mapper接口。
• 实现主业务逻辑,包含对应的ServiceImpl，manager，dao层。
• 依赖api。

service-webapp

• 实现 dubbo 服务的注册功能。
• 依赖api、provider包

biz

• 实现 dubbo 服务的调用功能。
• 依赖api包

web

• 只有controller层,对外提供 http 接口服务，返回数据使用json格式。
• 实现业务请求的服务调用、结果返回功能。
• 依赖biz包

命名规则

类名

• controller层类名为：实体名(去掉DO) + Controller/WebController
• biz层类名为：实体名(去掉DO) + Biz
• service层类名为：实体名(去掉DO) + Service
• manager层类名为：实体名(去掉DO) + Manager
• dao层类名为：实体名(去掉DO) + Dao
• mapper层类名为：实体名(去掉DO) + Mapper

变量名

首字母小写，其他单词首字母大写（小驼峰命名法）

局部变量名

根据不同类型加不同的前缀或后缀

• Boolean：bIs+变量名（bIs中间的是i不是L）
• Char：c+变量名
• Byte：by+变量名
• Int、Integer：int+变量名
• Short：s+变量名
• Long：l+变量名
• Float：f+变量名
• Double：d+变量名
• String：str+变量名
• Map：变量名+Map
• List：变量名+List
• Date：形容词+Date

方法名

a) 查询方法：

• 分页查询方法：
  • 分页查询方法命名规则为：pageFindBy+名称,名称的取名要顾名思义；
  • 分页查询所有：pageFindAll；
  • 分页查询需要审核的数据:pageFindVerify；
  • 如： 分页查询所传的参数searchValue一般对应模块中的名称字段，在service层需要将该参数去掉前后空格；

• 普通查询方法：
  • 根据某个查询条件查询list方法为：listFindBy+查询条件；
  • 根据某个查询条件查询实体方法为：getBy+某个查询条件查询；
  • 根据主键查询实体：getById；

b) 操作方法： 操作方法是指对数据库进行新增、修改、删除等操作的方法，命名时要顾名思义

c) controller层写法：

• 常用命名：

• • 分页查询所有：pageFindAll
  • 分页查询未提交：pageFindEditing
  • 分页查询历史记录：pageFindHis
  • 分页查询待审核：pageFindWaitApv
  • 分页查询审核历史：pageFindApvHis
  • 分页查询可引用数据：pageFindCite
  • 根据主键查询：getById
  • 新增：save
  • 修改：edit
  • 删除：remove
  • 提交：submit
  • 审核：approve
  • 验证：check*

• • 注：其他方法在controller、biz、service、manager、dao、mapper层的方法名称以及mapper层中每个sql语句标签的id应完全对应。BaseDao中有基本的新增、修改、删除、根据id查询方法的调用，dao层方法名和mapper层id名对应关系为：pageFindAll->pageByQuery、getById->selectByPrimaryKey、save->insert、edit->updateByPrimaryKey、remove->deleteByPrimaryKey

Entity模块

• 实体名与数据库表名相同(省略下划线)使用大驼峰命名法+DO，如表名为AC_APPLY_INFO则实体名为AcApplyInfoDO

web模块

web controller

1. 所有Controller均为com.leon.framework.mvc.controller.BaseController的直接或间接子类。

2. 使用@@RestController进行注解。

3. Controller规约 [大模块名][子模块名]WebController，如：

 EbProjectInfoController

4. @RequestMapping规约 /api/[大模块名]/[子模块名]，如：

 @RequestMapping("/web/eb/projectinfo")
 public class EbProjectInfoController extends BaseController

5. Controller方法规约

Controller类中可以定义跳转JSP页面的方法，一般分为三个，管理页、新增页、修改页，可根据业务的需要有所不同。

在跳转页面的方法上方添加@RequestMapping注解括号中的字符串由: /[方法名] 组成。返回的字符串是跳转的页面的jsp文件所在views下的路径。其中修改页方法的参数列表的ModelMap对象用于携带数据到jsp页面上以供使用。

跳转修改页是要通过id调用service层的findById方法查询到对应的数据，并put进ModelMap对象中携带到前台。

6. 一个完整的Controller示例

/**
 * 项目信息Controller
 * 
 * @author jimmy_zhang
 * @since 2017年3月7日 下午5:02:41
 */
@Controller
@RequestMapping("/api/ap/projectinfo")
public class EbProjectInfoWebController extends BaseController {

    /**
     * 跳转项目管理信息页
     * 
     * @return
     * @author jimmy_zhang
     * @since 2017年3月7日 下午5:03:36
     */
    @RequestMapping("/manager")
    public String manager() {
        return "/eb/projectinfo/manager";
    }

    /**
     * 跳转项目信息修改页
     * 
     * @param model
     * @param id
     * @return
     * @author jimmy_zhang
     * @since 2017年3月7日 下午5:03:43
     */
    @RequestMapping("/edit")
    public String edit(ModelMap model, String id) {
        return "/eb/projectinfo/edit";
    }

    /**
     * 跳转项目信息新增页
     * 
     * @return
     * @author jimmy_zhang
     * @since 2017年3月7日 下午5:03:47
     */
    @RequestMapping("/add")
    public String add() {
        return "/eb/projectinfo/add";
    }

    /**
     * 跳转项目信息列表页
     * 
     * @return
     * @author jimmy_zhang
     * @since 2017年3月7日 下午5:03:53
     */
    @RequestMapping("/show")
    public String show() {
        return "/eb/projectinfo/show";
    }
}

view

1. 存放路径规约

web模块下src/main/webapp/WEB-INF/views/[大模块名]/[子模块名]/[视图名(对应WebController方法名)].jsp，如：

 /src/main/webapp/WEB-INF/views/eb/projectinfo/manager.jsp

2. HTML ID命名规约

视图中尽量避免使用ID，如确定需要ID考虑到系统今后的扩展和维护的方便，视图中元素ID规则要保证全局唯一。

命名规约：[大模块名][子模块名][视图名][ID名]，如：

 ebProjectInfoManagerSearchForm

javascript

1. 存放路径规约

web模块下src/main/webapp/scripts/opensource/[大模块名]/[子模块名]/[视图名].js，如：

 /src/main/webapp/scripts/opensource/eb/projectinfo/manager.js

2. Javascript ViewModel对象命名规约

[大模块名][子模块名][视图名]，如：

 var ebProjectInfoManagerModel = {
   init: function() {
     ...
   },
   ...
 };
 mainModel.callback = ebProjectInfoManagerModel.init;

3. 自动执行初始化

文件末尾添加： mainModel.callback = ebProjectInfoManagerModel.init;

service

controller

1. 所有Controller均为com.opensource.common.base.BaseController的直接或间接子类。

2. 使用@RestController进行注解。

3. Controller规约 [大模块名][子模块名]Controller，如：

 EbProjectInfoController

4. @RequestMapping规约 /[大模块名]/[子模块名]，如：

 @RequestMapping("/eb/projectinfo")
 public class EbProjectInfoController extends BaseController

5. Controller方法规约

所有方法无需使用@ResponseBody进行注解。

6. try catch处理

将业务处理部分用try catch捕捉异常，第一个catch捕捉BusinessException异常，直接抛出，第二个catch捕捉Exception异常，创建一个BusinessException异常抛出，创建BusinessException异常是传参为BaseController的静态变量exception_Message和捕捉到的异常e。新增、修改、删除方法类同。

    @RequestMapping("/pageFindAll")
    public DataGrid<EbProjectInfoDO> pageFindAll(Integer page, Integer rows, String sort, EbProjectInfoDO entity) {
        DataGrid<EbProjectInfoDO> datagrid = new DataGrid<EbProjectInfoDO>();
        try {
            BaseUser user = (BaseUser) webContext.getSessionUser();
            datagrid = ebProjectInfoService.pageFindAll(page, rows, sort, entity, user);
        } catch (BusinessException be) {
            throw be;
        } catch (Exception e) {
            throw new BusinessException(BaseController.exception_Message, e);
        }
        return datagrid;
    }

7. 新增方法

新增方法（保存方法）的参数列表为模块实体类的对象，返回值为Json对象。在try中调用Service层的save方法进行保存，之后设置json对象的success属性为true，修改、删除方法类同。调用service层save方法时需要额外传递BaseUser对象，此对象从webContext中调用getSessionUser方法获取（当前登录人的信息）。

    @RequestMapping("/save")
    public Json save(EbProjectInfoDO entity) {
        Json json = new Json();
        try {
            BaseUser user = (BaseUser) webContext.getSessionUser();
            ebProjectInfoService.save(entity, user);
            json.setSuccess(true);
        } catch (BusinessException be) {
            throw be;
        } catch (Exception e) {
            throw new BusinessException(BaseController.exception_Message, e);
        }
        return json;
    }

8. 修改方法

修改方法与新增方法类同，调用service层edit方法进行修改数据。

    @RequestMapping("/edit")
    public Json edit(EbBidSectionDO entity) {
        try {
            Json json = new Json();
            ebBidSectionService.edit(entity);
            json.setSuccess(true);
            return json;
        } catch (BusinessException be) {
            throw new BusinessException(be.getMessage());
        } catch (Exception e) {
            throw new BusinessException(BaseController.exception_Message, e);
        }
    }

9. 删除方法

删除方法参数列表为模块主键id，通过主键删除数据，调用service层remove方法进行删除数据。

    @RequestMapping("/remove")
    public Json remove(String id) {
        Json json = new Json();
        try {
            ebProjectInfoService.remove(id);
            json.setSuccess(true);
        } catch (BusinessException be) {
            throw be;
        } catch (Exception e) {
            throw new BusinessException(BaseController.exception_Message, e);
        }
        return json;
    }

Controller中方法操作名

以下列出了Controller中常用的操作，由于业务系统的复杂性，下表中的操作名肯定不能满足所有业务需求，如需新增操作名，请及时沟通。

操作名	说明
get	获取一个对象
set	设置属性
find	获取对象列表（无分页）
pageFind	分页获取对象列表
save	新增/保存
edit	编辑/修改
remove	删除
submit	提交
check	验证（如数据有效性）
upload	上传
download	下载
*Batch	某个操作的批量操作，如deleteBatch

操作名	说明
print	打印
import	导入
export	导出
report	报表
publish	发布

操作名	说明
apply	申请
approve	审批
verify	审核
receive	接收
confirm	确认
start	启动
stop	停止
begin	开始
end	结束
process	处理
forward	前进
back	后退/退回
cancel	取消
assign	指派/分派
finish	完成

操作名	说明
calc	计算
count	计数
exec	执行
init	初始化
pack	封装
pay	支付