平台代码规约 - 版本历史

Leon：/* 方法名 */

2022-02-22T08:21:06Z

‎方法名

Leon：/* 方法名 */

2021-12-10T07:58:41Z

‎方法名

Leon：/* 方法名 */

2021-12-10T07:58:02Z

‎方法名

Leon：/* 方法名 */

2020-08-06T10:20:11Z

‎方法名

Leon：/* 方法名 */

2020-08-06T10:00:03Z

‎方法名

Leon：/* 方法名 */

2019-04-26T05:35:25Z

‎方法名

Leon：/* 方法名 */

2019-04-23T03:54:39Z

‎方法名

Leon：/* 方法名 */

2019-04-23T03:54:04Z

‎方法名

2019年4月20日 (六) 01:14 Leon

2019-04-20T01:14:07Z

Leon：创建页面，内容为“本文档是研发规范的一部分，阐述了平台的代码规范、框架说明。本文档未阐述一般性的Java源文件规范，相应的规范请参考…”

2019-04-11T11:20:24Z

创建页面，内容为“本文档是研发规范的一部分，阐述了平台的代码规范、框架说明。本文档未阐述一般性的Java源文件规范，相应的规范请参考…”

新页面

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

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

==Maven子项目模块划分==

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

===api===

各个模块间通过api进行通信。

===entity===

* 存放数据库表和视图映射的entity和view实体。
* 只依赖framework包。

===service===

* 实现主业务逻辑。
* 包含对应的controller，service，dao层。
* 依赖api及entity包。

===web===

* 只有controller层，实现页面的跳转。
* 依赖service包

==命名规则==

===类名===

* controller层类名为：实体名(去掉DO) + Controller/WebController
* service层类名为：实体名(去掉DO) + Service
* 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) 查询方法：
分页查询方法命名规则为：pageFind+名称,名称的取名要顾名思义
分页查询所有：pageFindAll
分页查询需要审核的数据:pageFindVerify
如：分页查询所传的参数searchValue一般对应模块中的名称字段，在service层需要将该参数去掉前后空格

普通查询方法：
查询所有方法findAll，

特定查询方法：用于明确用途的查询方法，命名规则为：find+用途名称，如findShow方法用于查询展示页所用的数据

其他查询方法命名规则为findBy+查询条件字段

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

常用命名：

* 新增：save
* 修改：edit
* 删除：remove
* 提交：submit
* 审核：verify

注：除跳转页面的方法外，其他方法在controller、service、dao层的方法名称以及mapper层中每个sql语句标签的id应完全对应。BaseDao中有基本的新增、修改、删除、根据id查询方法的调用，dao层方法名和mapper层id名对应关系为：save->insert、update->update、deleteById->delete、findById->getById

3. jsp与js命名规则
a) 模块管理页命名为：manager.jsp与其对应的js文件命名为manager.js
b) 其他跳转页面的命名，根据跳转页面方法的命名，如add跳转的jsp页面名称应为add.jsp与其对应的js文件名称为add.js

相应的Add.js中的对象名称应为baseCompanyAddModel

js文件中，常用方法：

* init初始化方法
* save保存方法
* edit修改方法
* remove删除方法
* submit提交方法

==Entity模块==

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

==web模块==

===web controller===

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

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

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

EbProjectInfoWebController

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

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

5. WebController方法规约

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

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

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

6. 一个完整的WebController示例

<syntaxhighlight lang="java">
/**
* 项目信息WebController
*
* @author jimmy_zhang
* @since 2017年3月7日下午5:02:41
*/
@Controller
@RequestMapping("web/eb/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/eb/projectinfo/manager.jsp

2. HTML ID命名规约

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

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

ebProjectInfoManagerSearchForm

===javascript===

1. 存放路径规约

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

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

2. Javascript ViewModel对象命名规约

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

var ebProjectInfoManagerModel = {
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>，如：

EbProjectInfoController

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

@RequestMapping("/eb/projectinfo")
public class EbProjectInfoController 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中常用的操作，由于业务系统的复杂性，下表中的操作名'''肯定'''不能满足所有业务需求，如需新增操作名，请及时沟通。

{| 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 || 支付
|}

@@ 第92行： / 第92行： @@
 ** 分页查询未提交：pageFindEditing
 ** 分页查询历史记录：pageFindHis
-** 分页查询待审核：pageFindWaitApprove
+** 分页查询待审核：pageFindWaitApv
-** 分页查询审核历史：pageFindApproveHis
+** 分页查询审核历史：pageFindApvHis
 ** 分页查询可引用数据：pageFindCite
 ** 根据主键查询：getById

@@ 第92行： / 第92行： @@
 ** 分页查询未提交：pageFindEditing
 ** 分页查询历史记录：pageFindHis
-** 分页查询待审核：pageFindWaitVerify
+** 分页查询待审核：pageFindWaitApprove
-** 分页查询审核历史：pageFindVerifyHis
+** 分页查询审核历史：pageFindApproveHis
 ** 分页查询可引用数据：pageFindCite
 ** 根据主键查询：getById

@@ 第100行： / 第100行： @@
 ** 删除：remove
 ** 提交：submit
-** 审核：verify
+** 审核：approve
 ** 验证：check*

@@ 第94行： / 第94行： @@
 ** 分页查询待审核：pageFindWaitVerify
 ** 分页查询审核历史：pageFindVerifyHis
 ** 根据主键查询：getById
 ** 新增：save

@@ 第90行： / 第90行： @@
 ** 分页查询所有：pageFindAll
 ** 根据主键查询：getById
 ** 新增：save
@@ 第96行： / 第100行： @@
 ** 提交：submit
 ** 审核：verify
 **注：其他方法在controller、biz、service、manager、dao、mapper层的方法名称以及mapper层中每个sql语句标签的id应完全对应。BaseDao中有基本的新增、修改、删除、根据id查询方法的调用，dao层方法名和mapper层id名对应关系为：pageFindAll->pageByQuery、getById->selectByPrimaryKey、save->insert、edit->updateByPrimaryKey、remove->deleteByPrimaryKey

@@ 第72行： / 第72行： @@
 a)	查询方法：
 *分页查询方法：
-**分页查询方法命名规则为：pageFind+名称,名称的取名要顾名思义；
+**分页查询方法命名规则为：pageFindBy+名称,名称的取名要顾名思义；
 **分页查询所有：pageFindAll；
 **分页查询需要审核的数据:pageFindVerify；
@@ 第78行： / 第78行： @@
 *普通查询方法：
-**根据某个查询条件查询list方法为：listBy+查询条件；
+**根据某个查询条件查询list方法为：listFindBy+查询条件；
 **根据某个查询条件查询实体方法为：getBy+某个查询条件查询；
 **根据主键查询实体：getById；

@@ 第97行： / 第97行： @@
 ** 审核：verify
-**注：其他方法在controller、biz、service、manager、dao、mapper层的方法名称以及mapper层中每个sql语句标签的id应完全对应。BaseDao中有基本的新增、修改、删除、根据id查询方法的调用，dao层方法名和mapper层id名对应关系为：pageFindAll->pageByQuery,getById->selectByPrimaryKey、save->insert、edit->updateByPrimaryKey、remove->deleteByPrimaryKey
+**注：其他方法在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模块==

@@ 第5行： / 第5行： @@
 ==Maven子项目模块划分==
-项目统一使用Maven进行管理，每一个系统模块会分为api、entity、service和web包，方便实现各个项目之间的模块化管理，并尽可能的减少各模块之间的依赖。
+项目统一使用Maven进行管理，每一个系统模块会分为api、provider、service-webapp、biz、mvc和web-webapp包，方便实现各个项目之间的模块化管理，并尽可能的减少各模块之间的依赖。
 ===api===
-各个模块间通过api进行通信。
+* 各个模块间通过api进行通信。
-===entity===
+===provider===
-* 存放数据库表和视图映射的entity和view实体。
+* api 模块的实现，
-* 只依赖framework包。
+* 存放数据库表和视图映射的entity、映射文件、Mapper接口。
-===service===
+===service-webapp===
-* 实现主业务逻辑。
+* 实现 dubbo 服务的注册功能。
-* 包含对应的controller，service，dao层。
+* 依赖api、provider包
-* 依赖api及entity包。
 ===web===
-* 只有controller层，实现页面的跳转。
+* 只有controller层,对外提供 http 接口服务，返回数据使用json格式。
-* 依赖service包
+* 实现业务请求的服务调用、结果返回功能。
 ==命名规则==
@@ 第32行： / 第41行： @@
 * controller层类名为：实体名(去掉DO) + Controller/WebController
 * service层类名为：实体名(去掉DO) + Service
 * dao层类名为：实体名(去掉DO) + Dao
 * mapper层类名为：实体名(去掉DO) + Mapper
@@ 第84行： / 第95行： @@
 * 审核：verify
-注：除跳转页面的方法外，其他方法在controller、service、dao层的方法名称以及mapper层中每个sql语句标签的id应完全对应。BaseDao中有基本的新增、修改、删除、根据id查询方法的调用，dao层方法名和mapper层id名对应关系为：save->insert、update->update、deleteById->delete、findById->getById
+注：除跳转页面的方法外，其他方法在controller、service、dao层的方法名称以及mapper层中每个sql语句标签的id应完全对应。BaseDao中有基本的新增、修改、删除、根据id查询方法的调用，dao层方法名和mapper层id名对应关系为：save->insert、update->update、deleteById->deleteByPrimaryKey、findById->selectByPrimaryKey
 ==Entity模块==
@@ 第108行： / 第106行： @@
 ===web controller===
-. 所有WebController均为<code>com.opensource.common.base.BaseController</code>的直接或间接子类。
+. 所有Controller均为<code>com.leon.framework.mvc.controller.BaseController</code>的直接或间接子类。
-. 使用<code>@Controller</code>进行注解。
+. 使用<code>@@RestController</code>进行注解。
-. WebController规约
+. Controller规约
 <code>[大模块名][子模块名]WebController</code>，如：
-   <span style="color:red">Eb</span><span style="color:blue">ProjectInfo</span>WebController
+   <span style="color:red">Eb</span><span style="color:blue">ProjectInfo</span>Controller
 . @RequestMapping规约
-<code>/web/[大模块名]/[子模块名]</code>，如：
+<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>WebController extends BaseController
+   public class <span style="color:red">Eb</span><span style="color:blue">ProjectInfo</span>Controller extends BaseController
-. WebController方法规约
+. Controller方法规约
 Controller类中可以定义跳转JSP页面的方法，一般分为三个，管理页、新增页、修改页，可根据业务的需要有所不同。
@@ 第131行： / 第129行： @@
 跳转修改页是要通过id调用service层的findById方法查询到对应的数据，并put进ModelMap对象中携带到前台。
-. 一个完整的WebController示例
+. 一个完整的Controller示例
 <syntaxhighlight lang="java">
 /**
-  * 项目信息WebController
+  * 项目信息Controller
+  *
   * @author jimmy_zhang
@@ 第141行： / 第139行： @@
   */
 @Controller
-@RequestMapping("web/eb/projectinfo")
+@RequestMapping("/api/ap/projectinfo")
 public class EbProjectInfoWebController extends BaseController {

平台代码规约 - 版本历史

Leon：/* 方法名 */

Leon：/* 方法名 */

Leon：/* 方法名 */

Leon：/* 方法名 */

Leon：/* 方法名 */

Leon：/* 方法名 */

Leon：/* 方法名 */

Leon：/* 方法名 */

2019年4月20日 (六) 01:14 Leon

Leon：创建页面，内容为“本文档是研发规范的一部分，阐述了平台的代码规范、框架说明。 本文档未阐述一般性的Java源文件规范，相应的规范请参考…”

Leon：创建页面，内容为“本文档是研发规范的一部分，阐述了平台的代码规范、框架说明。本文档未阐述一般性的Java源文件规范，相应的规范请参考…”