码农的自留地

2021-07-03

开发规范1.0

开发规范

所有的类,方法都必须有完整的注释

说明类的用途,内部方法的使用方法,出入参的返回

代码是给人看的,机器执行是次要的

不变的变量做常量,常量放在常量类

共用的方法做工具,工具放在工具类

不会不懂的先抽象,设计模式往里套

MVC有三宝,控制、逻辑、数据库

遇事不决先自问,做啥,有啥,还缺啥

开发基本流程

请严格按照开发的步骤提交到指定的分支

  • 开发功能 提交dev 开发分支
  • 准备测试 合并devtest测试
  • 测试通过 test分支合并到master主分支。准备发布上线
  • 发布完成后经过观察没有问题,打tag封版
  • 重复第一步

基本规范

  • 驼峰命名规则,除特殊情况应当遵守
  • 使用 static final 修饰的变量为全大写
  • 所有注释应当完备,注释与代码的比例为1:4

包路径规范

统一路径为xxx.xxx.{模块名称}.{功能包}

例如 xxx.xxx.entity -> 核心模块{实体映射包}

包名规范

包名明确区分所属功能,常用的包名如下

  • common 主要存放常用,共用内容,但是不放置实体映射
  • annotation 自定义注解包
  • config 配置类包
  • dao Datasource Access Object 数据访问对象
  • domain 领域对象,相较于实entity的实体映射,更多是的方式具体的业务实体
  • entity 实体映射,例如系统用户User.java等等
  • vo ViewObject 视图对象
  • logic 逻辑包,最小业务逻辑拆分
  • subscriber 订阅包,异步消息订阅实现类包
  • service service包
  • util 工具包,原则上通用工具方法由core统一提供
  • controller controller包
  • 等等...

组件实现规范/命名规范

  • entity 实现Entity 没有特殊命名要求
    例如
public class User implements Entity{}
  • dao 继承BaseDao 必须是xxxDao

例如

public interface UserDao extends BaseDao<User>{}
  • service

业务接口类必须 命名为xxxService

实现类命名为 xxxServiceImpl

service将细颗粒的logic组装

例如

public interface UserService extends Biz{}
@Service
public class UserServiceImpl extends UserService {
    @Autowired
    private ValidateDevice validateDevice;
    @Autowired
    private NotifyStore notifyStore;
    
    public Boolean perceptionOrder(String id) {
        BizContext.set("DeviceNo", id);
        DefaultChainFactory.build(
            validateDevice,
            notifyStore
        );
        return BizContext.get("NotifySuccess", Boolean.class);
        
    }
}
  • controller 继承BaseController 必须是xxxController
public class UserController extends BaseController{}

Restful接口统一返回BaseResponse<T>, 非Restful根据实际需求定义

  • logic 实现Logic 没有特别的命名要求,需要见名知意,表达具体的细颗粒度业务

例如 ValidateDevice 设备校验 RechargeAccount 账户充值

public class ValidateDevice implements Logic {
   
    @Autowired
    private DeviceDao deviceDao;
    
    public boolean run() {
        String id = BizContext.get("DeviceNo", String.class);
        return deviceDao.exists(id);
    }
}

注释规范

/**
 * 类注释应当包含以下4个
 * 
 * @author xxx 谁编写的这个类
 * @since 1.0 从哪个版本开始
 * @date 第一次编写的时间
 * @version 当前的版本
 * 
 * 如果对类进行的修改应当使用@modify 标注修改时间
 * @modify 李解 2020-07-28 12:36:49 更改了xxx方法内的逻辑
 * 该注释可以标注在类,或者方法上,根据情况判断
 */
public class Test{
    
    /** 常量必须大写,并且必须有对应的注释标注其作用*/
    private static final String SIGN = "";
    
    /**
     * 方法简要的阐述其作用,干什么,返回说明,有什么异常需要处理,例如:
     * 
     * @param value 需要增加的值
     * @return 增加后的值
     * @throws java.io.IOException IO异常
     * @throws NullPointerException 传入null值触发
     */
    public int plus(int value) throws IOException, NullPointerException{
        // 方法内应当使用单行注释,尽量简明扼要
        // 编写初期可以尝试使用注释写伪代码,构建逻辑,便于后续开发,例如
        
        // 对值做处理,判断 if(xxxxx)
        // 对传入值做递增操作 value++
        // 如果有异常抛出,交由上层处理 throw new RunTimeException
        return value + 1;
    }
    
}