查看“平台代码规约”的源代码

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

本文档未阐述一般性的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：<code>bIs+变量名</code>（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
** 分页查询待审核：pageFindWaitVerify
** 分页查询审核历史：pageFindVerifyHis
** 分页查询可引用数据：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，如表名为<code>AC_APPLY_INFO</code>则实体名为<code>AcApplyInfoDO</code>

==web模块==

===web controller===

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

2. 使用<code>@@RestController</code>进行注解。

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

  <span style="color:red">Eb</span><span style="color:blue">ProjectInfo</span>Controller

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

  @RequestMapping("/web/<span style="color:red">eb</span>/<span style="color:blue">projectinfo</span>")
  public class <span style="color:red">Eb</span><span style="color:blue">ProjectInfo</span>Controller extends BaseController

5. Controller方法规约

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

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

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

6. 一个完整的Controller示例

<syntaxhighlight lang="java">
/**
 * 项目信息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";
    }
}
</syntaxhighlight>

===view===

1. 存放路径规约

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

  /src/main/webapp/WEB-INF/views/<span style="color:red">eb</span>/<span style="color:blue">projectinfo</span>/<span style="color:green">manager</span>.jsp

2. HTML ID命名规约

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

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

  <span style="color:red">eb</span><span style="color:blue">ProjectInfo</span><span style="color:green">Manager</span><span style="color:sienna">SearchForm</span>

===javascript===

1. 存放路径规约

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

  /src/main/webapp/scripts/opensource/<span style="color:red">eb</span>/<span style="color:blue">projectinfo</span>/<span style="color:green">manager</span>.js

2. Javascript ViewModel对象命名规约

<code>[大模块名][子模块名][视图名]</code>，如：

  var <span style="color:red">eb</span><span style="color:blue">ProjectInfo</span><span style="color:green">Manager</span>Model = {
    init: function() {
      ...
    },
    ...
  };
  mainModel.callback = ebProjectInfoManagerModel.init;

3. 自动执行初始化

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

==service==

===controller===

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

2. 使用<code>@RestController</code>进行注解。

3. Controller规约
<code>[大模块名][子模块名]Controller</code>，如：

  <span style="color:red">Eb</span><span style="color:blue">ProjectInfo</span>Controller

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

  @RequestMapping("/<span style="color:red">eb</span>/<span style="color:blue">projectinfo</span>")
  public class <span style="color:red">Eb</span><span style="color:blue">ProjectInfo</span>Controller extends BaseController

5. Controller方法规约

所有方法无需使用<code>@ResponseBody</code>进行注解。

6. try catch处理

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

<syntaxhighlight lang="java">
    @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;
    }
</syntaxhighlight>

7. 新增方法

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

<syntaxhighlight lang="java">
    @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;
    }
</syntaxhighlight>

8. 修改方法

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

<syntaxhighlight lang="java">
    @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);
        }
    }
</syntaxhighlight>

9. 删除方法

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

<syntaxhighlight lang="java">
    @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;
    }
</syntaxhighlight>

==Controller中方法操作名==

以下列出了Controller中常用的操作，由于业务系统的复杂性，下表中的操作名'''肯定'''不能满足所有业务需求，如需新增操作名，请<span class="color:red">及时沟通</span>。

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

{| class="wikitable"
|-
! 操作名 !! 说明
|-
| print || 打印
|-
| import || 导入
|-
| export || 导出
|-
| report || 报表
|-
| publish || 发布
|}

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

{| class="wikitable"
|-
! 操作名 !! 说明
|-
| calc || 计算
|-
| count || 计数
|-
| exec || 执行
|-
| init || 初始化
|-
| pack || 封装
|-
| pay || 支付
|}