首页 > 代码库 > Koala编码规范

Koala编码规范

2024-07-26 12:18:50   214人阅读

Koala编码规范

1 前言

本文档是Koala项目编程风格规范的完整定义，项目模块源文件必须符合本文档设定的规则。
与其它的编程风格指南一样，这里所讨论的不仅仅是编码格式美不美观的问题， 同时也讨论一些约定及编码标准。

2 源文件

2.1 文件编码：UTF-8
2.2 命名：大写字母开头，驼峰式，只允许英文
2.3 文件结构按照顺序如下表所示：
    元素 要求
    1，许可证或版权信息
    2，package语句 package语句不换行
    3，import语句 不能使用通配符
    4，一个顶级类
     注：以上每个元素之间用一个空行隔开。


2.4 约定：
  • 代码必须格式化
  • 不能出现黄色提示
  • 类、方法必须写注释
  • 类和方法级的说明需要句号，参数和返回就不需要（示例如下表）
  • 代码保持清洁（不能留用//注释的代码等） 
示例
/**
 * 抽象实体类，可作为所有领域实体的基类。
 *
 * @author yang
 *
 */
@MappedSuperclass
public abstract class BaseEntity implements Entity {


/**
     * 获取仓储对象实例。如果尚未拥有仓储实例则通过InstanceFactory向IoC容器获取一个。
     * @return 仓储对象实例
     */
    public static EntityRepository getRepository() {
        if (repository == null) {
            repository =
 InstanceFactory.getInstance(EntityRepository.class);
        }
        return repository;
    }


}



3 命名规范

命名的关键要素是简短、意图清晰，遵守下面表格规则：

          元素         要求                                                               示例
  1. 项目模块 只能使用小写字母和中划线，以中划线分割单词 koala-security-core
  2. 包 只能使用小写字母 org.openkoala.security.core.domain
  3. 类 只能使用大小写字母，大驼峰式 EntityRepository.java
  4. 字段 只能使用大小写字母和下划线，小驼峰式 private String userAccount
  5. 方法 只能使用大小写字母，小驼峰式 findChildrenOfOrganization
  6. URL 只能使用小写字母和中划线 employee/get-posts-by-employee.koala
  7. JS、CSS、JSP 只能英文、数字和中划线 

4 模块约定

4.1领域层

? 包命名格式xxx.xxx.core.domain，例org.openkoala.security.core.domain
? 异常类放在xxx.xxx.core下，以xxxException结尾，必须是RuntimeException的子类
? JPA实体表、列名必须大写，以下划线分割，其中表名需是复数（例：KO_ACCOUNTABILITIES）
? JPA实体内容编写顺序，字段->构造函数->方法(动->静)->业务主键->属性
? 查询方法实现使用命名查询和CriteriaQuery查询对象，简单查询使用CriteriaQuery实现较快
? JPA实体的方法必须编写相对应的单元测试，并且有较高的覆盖率

4.2应用层

? 包命名格式xxx.xxx.application，例org.openkoala.security.application
? 接口必须编写详细的注释
? 接口方法必须编写相对应的单元测试，并且有较高的覆盖率

4.3门面层

? 包含fa?ade接口和DTO对象
? 包命名格式xxx.xxx.facade，例org.openkoala.security.facade
                     xxx.xxx.facade.dto，例org.openkoala.security.facade.dto
? 命令接口返回InvokeResult对象，查询接口返回Page对象，获取数据接口直接返回
? pom文件不能有任何技术依赖

4.4门面实现层

? 包含fa?ade接口实现和assembler装配器
? 包命名格式xxx.xxx.facade.impl，例org.openkoala.security.facade.impl
xxx.xxx.facade.impl.assembler，例org.openkoala.security.facade.impl.assembler
? Assembler类必须包含toEntity和toDTO方法，方法必须有对参数的不为空判断


Koala编码规范


联系
我们