首页 > 编程语言 >java代码开发规范

java代码开发规范

时间:2024-05-14 17:00:45浏览次数:23  
标签:java 代码 规范 查询 索引 api 使用 null order

1、工程结构

 工程分为三个module :sdk、biz、api,api依赖biz biz依赖sdk

 1.1、api

  api功能主要是与外部的交互部分,包括向前端提供的接口,向外部提供的RPC服务的实现等。

  包分类;主要包括的package包括但不限于

包名 功能描述 规范 备注
api 向外部提供的RPC接口实现    
controller 与前端交互的Controller   可以使用@RestController注解
model 返回给前端的数据类 后缀规范Model  
factory model组装与拆解的factory 一般用Model名+Factory命名  
interceptor 拦截器    
resolver exception的resolver    
validator 参数校验类

参数校验器,一般来说只作为参数的校验。validate方法可以返回void,然后中间检验出错抛出异常。

 

1.2、biz

   业务核心部分,承接上下,联通api层与数据库、外部服务等。

包名 功能叙述 规范 备注
service 一般对应一张数据库表,对于此张表的原子操作

类似于对于表的一次插入,一次更新,一次条件查询等

一次联表的查询也可以记作一次条件查询

表名+Service 需要事务
action 一般组织一次动作,需要用到事物,可以由多个原子操作来组成

类似于:一次交易需要多个业务动作,先抵扣优惠,然后创建预付单.

类似于:CreatorOrderAction,PayOrderAction等

操作名+Action 需要事务
domain 领域模型,一般一个对应一张表 使用mybatis.generator自动生成  
mapper dao层    
remote/wrapper 对接外部服务,类似于调用下游provider、.外部http或其他RPC提供者 可以用Remote-+服务+Warpp.er来命名  
manager 高于Action的抽象层,可以用于组织多个Action,之间的逻辑,一般是用于组织多个动作的流程   需要事务
utils 工具类    
enums 枚举类    
calculator 复杂逻辑计算器,例如根据优惠券ID计算订单金额。discountCalculator    
generator 复杂string、结果的生成器    

1.3、sdk

  对外提供rpc服务的接口、dto以及枚举等,具体实现会放在api层

  remote包统一使用 1.0-SNAPSHOT 作为包管理。

  remote向外提供的接口一律只增不删不改,等到接口上线之后,确认老接口已经无流量后,才能进行删除。

2、整洁的代码

2.1代码整洁之道

  写简洁易懂的代码,推荐阅读《代码整洁之道》

2.2、一些需要强调的命名点

2.2.1 DTO

  DTO,全称为Data Transfer Object, 顾名思义,只是作为数据参数对象来使用,在我们的系统当中,DTO只作为系统之间RPC调用时传递的对象。在系统内部,例如由上层api层传向下层action层时候,应当转为系统内部的一个领域对象。

2.2.2 一些难以汇聚成一个领域对象的散装参数

  对于系统中数据的传递时,有时候一些参数难以用一个领域对象来进行概括的时候,例如一些面向动作的参数

public class DepositReceiveParam {
    private String outBizId;

    private FinanceOutBizTypeEnum financeOutBizTypeEnum;

    /**

     * 收款面向客户与否

     */

    private Boolean isCustomer;

    /**

     * 面向客户的话,关注此字段

     */

    private Integer customerId;

    /**

     * 面向门店的话,关注此字段

     */

    private List<PoiDepositReceiveParam> poiDepositReceiveParams;

    /**

     * 实际支付金额

     */

    private BigDecimal actualPayment;

    /**

     * 支付中心流水号

     */

    private String tradeNo;

    /**

     * 实际支付时间

     */

    private Integer payTime;

    /**

     * 支付方式

     */

    private PlatformEnum platformEnum;

    /**

     * 备注信息

     */

    private String comment;

}

  这样一个充值的动作,难以定义其领域对象,因为其是面向过程的。这个时候可以使用Param的命名形式来进行命名。

3、场景case

  这里会列举一些典型的场景,以代码的形式具体说明.

3.1、Controller的场景

  Controller的用处是与前端进行接口上的交互,总体流程来说就是

请求→ 根据请求获取(改变)数据→ 组装Model → 返回前端

  则Controller需要做的事情,就是将这个流程体现出来

  `一个典型的GET请求`

@RequestMapping(value = "getOrder", method = RequestMethod.GET)
public Map<String, Object> getScheme(String orderId) {
    if (StringUtils.isBlank(orderId)) {
        throw new InvalidParamException("orderId不能为空");
    }
    Order order = orderService.getById(orderId);
    OrderModel orderModel = orderFactory.create(order);
    return ResponseTool.success(order);
}

  这是一个根据合同id获取对应的方案的接口,则主流程就是

  前端用orderId请求
  根据orderId去Service层获取方案
  将orderDo送入Factory中,组装成前端需要的Model
  返回给前端
  Controller层的逻辑很简单,主流程很清晰,一眼就能看出来是在做什么。

  如果需要传入多个参数,则可以考虑使用一个Model来包装起来,避免太多参数的情况
  Order和OrderModel的区别是什么呢?

3.1.1领域模型与Model的区别

  领域模型对应的是一张表,一个业务上的领域。在交易过程中中,Order则就对应的是一个订单,会落地到数据库的Order表中。

  然而在与前端交互的过程中,需要呈现给用户的,则不仅仅是一个order所承载的信息。因为对于用户来说,他需要看到自己的订单,也许要看到订单的支付信息,这些额外的信息,就不是由order来承载的,这些额外的信息的获取,也不是一个Controller的主流程所需要关心的部分,所以就会提出来,放在Factory中

3.2 Factory的场景

  接着上面说,则一个Order → OrderModel的Factory

  OrderFactory

public OrderModel create(Order order) {
   OrderModel model = new OrderModel();
    //填充基本信息
    fillBaseInfo(model, order);
    fillPayResult(model);
    fillAddress(model);
    return model;
}
  • 在Factory中,主要的工作就是组装一个Model出来、
  • 入参数一般为一个Domain或者List的形式
  • 同样,需要将主流程提取出来
  • 代码中主流程很容易就能看出来,

  • 填充基本信息
  • 组装支付信息
  • 组装地址信息
  • 返回

  对于一些填充的细节,则需要遵守一些效率上的规定,例如不能循环调用远程服务,走批量接口等,不能循环读库等

3.3 Service的场景

  Service则代表一次原子操作,例如一次对表的插入,一次更新,一次条件查询等

public List<Order> getByUserId(Integer userId) {
    OrderExample example = new OrderExample();
    example.createCriteria().andUserIdEqualTo(userId).andStatusIn(xxxx);
    return orderMapper.selectByExample(example);
}



public void save(Order order) {
    order.setCreateTime(DateUtil.unixTime());
    order.setCreatorId(UserUtils.getUser() == null ? 0 : UserUtils.getUser().getId());
    orderMapper.insertSelective(scheme);
}

3.4 Action的场景 

  Action则是对一系列原子操作的组合,也是一个完整的业务操作,一次完整的事务,Action也包含业务校验

public void doAction(ModifyTaskParam param) {
        log.info("开始处理修改任务分类");
        TaskClass taskClass = taskClassDao.getById(param.getTargetTask().getTask().getTaskClass());
        validateTaskClassExist(taskClass);
        validateTaskClassExist(taskClass, param.getTargetTask().getTask().getProject());
//        validateIsNotChildTask(taskClass);
        validateIsNotSection(taskClass);
        log.info("修改任务分类校验通过");
        fillTaskClass(param, taskClass);
        resetStatus(param, taskClass);
        transactionSynchronizer.sendEventAfterCommit(buildTaskClassChangeEvent(param, taskClass));
    }

  Actioin中,依然传入参数一般为一个领域对象,入参禁止为Model、DTO,model的作用于起于api止于api,在api层接收到了DTO后,应该转为一个系统内部的领域对象来使用。

3.5 Remote的场景

public Integer getShopIdByPoiId(Integer poiId) {
    try {
        Integer shopId = remoteResvPoiService.getShopIdByPoiId(poiId);
        LOGGER.info("getShopIdByPoiId get shopId={} by poiId={}", shopId, poiId);
        return shopId;
    } catch (Exception e) {
        LOGGER.error("getShopIdByPoiId error get shopId by poiId={}", poiId, e);
        throw new RpcException(e);
    }
}

3.6 Event的场景

  这是一个比较特殊的形式,指在程序内发送事件。什么时候应该用Event-Listener来组织代码呢?我觉得主要有两个地方

  流程长,分支多,入口点多

  这主要就可以参考老sc的上单流程。

  录单 → 提交方案 → 确认方案 → 充值 → 声讯复核 → 上线 → 同步阿波罗

  这样一个复杂的长链条,每一个流程都有依赖的地方,可能在每一个流程点上停止与开始,这个时候,就可以使用Event的形式来进行组织。

  每一个流程都以Event来传递,则任意路口只需要向外发出一个上一流程完成的事件,就可以无缝进行下一个流程。

  非主流程

  对于一些非主流程的操作,例如产品化后,产品结算的时候,同步写一份数据到点评M3库中,供数据分析使用,而并无其他作为。则其作为产品结算的非主流程,其优先级不高,直接写在一个Action中不太美观,可以拆分为一个Event去处理

3.7 Validator的场景

@Service

public class PrepayParamValidator {

    private static final Logger LOGGER = LoggerFactory.getLogger(PrepayParamValidator.class);

    public void validate(PrepayParamDTO prepayParamDTO) {
        if (prepayParamDTO.getCustomerId() == null) {
            LOGGER.error("no customer id for param={}", prepayParamDTO);
            throw new InvalidParamExceptoin("无客户id");
        }

        if (StringUtils.isBlank(prepayParamDTO.getTradeNo())) {
            LOGGER.error("no tradeNo for param={}", prepayParamDTO);
            throw new InvalidParamExceptoin("无流水号");
        }

        if (prepayParamDTO.getAmount() == null) {
            LOGGER.error("no amount for param={}", prepayParamDTO);
            throw new InvalidParamExceptoin("无充值金额");
        }

        if (StringUtils.isBlank(prepayParamDTO.getOperator())) {
            LOGGER.error("no Operator for param={}", prepayParamDTO);
            throw new InvalidParamExceptoin("无操作人");
        }

        if (prepayParamDTO.getPlatformEnum() == null) {
            LOGGER.error("no platform for param={}", prepayParamDTO);
            throw new InvalidParamExceptoin("无操作平台");
        }
    }
}

  这是一个典型的抛异常形式的validator,在发现某个参数出错之后,直接抛出异常,并带上对应的错误信息。这样相较于返回布尔值的validator来说,所携带的信息量更大。

4、日志规范

  api出入口必须加日志

  核心流程(action、manager)必须加日志

  外部调用request、response必须加日志

5、异常规范

6、数据库规范

6.1、基础规范

  1. 命名规范:
    1. 库名、表名、字段名必须使用小写字母或数字,不可以数字开头。多个单词或数字间用“_”分割,但禁止下划线间只是数字如resv_01_deposit。
    2. 库名、表名、字段名禁⽌超过32个字符。须见名知意。不要使用复数。
    3. 库名、表名、字段名禁⽌止使⽤用MySQL保留字。常用保留字如desc。
    4. 临时库、表名必须以tmp为前缀,并以⽇日期为后缀。
    5. 备份库、表必须以bak为前缀,并以日期为后缀。
    6. 索引命名,主键索引使用pk_字段名;唯一索引使用uk_字段名;普通索引使用idx_字段名。
  2. 使用规范
    1. 库、表、字段建议加好注释,明确表达其的意思,特别是表及字段。
    2. 库中不要保存大数据,如图片、文件。
    3. 尽量不在数据库层面做运算,复杂运算移到程序端cpu
    4. 拒绝大sql、大的事物、大的批量。
    5. 线上连线上、线下连线下环境隔离。

6.2、库表规范

  1. 库表规范
    1. 建立表的实体完整性。
      每个表要都含有主键。
    2. 不建议建立参照完整性,即外键。
      参照完整性父子表间的完整性约束,导致父子表操作相互影响带来较大的维护代价降低了可用性。
    3. 不建议用户定义完整性。
      不便于修改维护,可以在业务上实现。
    4. 慎用触发器。
      触发器存在较大的性能开销、触发器多级触发也不好控制维护。也非常容易被遗忘。
    5. 关于范式根据情况而定,没有正确必须与否。需要则适当冗余以提高性能。
      注意点:冗余的字段应该是不易变的字段否则难于维护一致
    6. 一表一实体。意义明确也方便扩展。
    7. 表根据情况可以预留字段。因为大表新加字段比较困难。

6.3、字段规范

  1. 选择合适的字段类型。定义字段考虑:选择正确的数据类型; 选择合适的精度。
    更小的数据类型。更少的空间、cpu、缓存能够带来更好的性能。
    越简单越好。能用数值型的就不要用字符型的。如数值比较要比字符比较性能好。
  2. 数值型
    正整数采用无符号整数。避免负数、同时扩大了范围。
    小数使用decimal,decimal是精确的小数。而float和double是非精确的可以用于近似值存在精度损失的问题。
  3. 日期型

    统一使用unix时间戳。int存储。时间戳不怕时区的问题。int数值型计算等性能也更好。

  4. 字符型
    char用于存储固定长度字符。如果长度固定如保存md5可以考虑使用性能要好于varchar。
    varchar是不固定长度字符。5.0.3之前的版本只可以保存255个,之后最大存储65535即63K的内容。varchar会用1字节或2字节存储字符串的长度。varchar(n<=255)实际占用n+1否则占用n+2个。
    避免使用text和blob类型的。占用空间大;不能检索完整长度也不能排序使用索引。如果需要拆出到单独的表来存储。
  5. 逻辑是非的使用is_xxx的表示。采用unsigned tinyint存储。
  6. 字段避免使用NULL。特别是要索引的字段,因为null字段索引需要额外空间处理、不能使用复核索引。
  7. 不允许使用enum。插入非法值时会插入null。

6.4、索引规范

  1.  基本规范
    不能过多,单表5个。过多对插入、更新带来过多性能开销。
    组合索引字段不超过5个。
    对字符串建立前缀索引。mysql从字符串左端开始处理字符串。前缀满足区分度情况下使索引边的更小,可以更多的放到内存减少IO等。但不能order by。所以不要对数值型建立前缀索引。
    不在索引列上做计算。不能使用索引导致全表扫描。
    禁止使用做模糊或全模糊匹配导致不能使用索引。可以支持xxx%的模糊查询。
    组合索引要注意最左比配原则。区分度高的字段在左边。
    不要对选择度低的字段建立索引。选择度=非重复行数|总数 ,越高越好。
    避免索引的重复索引
    避免冗余的索引
    利用覆盖索引。(覆盖索引:包含所有满足需要查询数据的索引叫覆盖索引。mysql使用b-tree索引来覆盖查询使用where中的列使用到索引且满足最左前缀,同时返回的列也在索引中。)
  2. 主键索引

    innodb对主键建立聚簇索引。其他索引属于辅助索引,期内保存着主键。辅助索引获取到数据需要一次辅助索引查询还需要一次主键索引得到数据。

   必须有主键。不然也会默认有。

   主键建议选择自增的。或者外部的方式生成数值型的主键。

  不用字符类型做主键。字符串较长导致辅助索引较大。

  主键索引不要更新。否则导致辅助索引的更新。

  不使用外键索引。参照完整性做父子表间的完整性约束,导致父子表操作相互影响带来较大的维护代价降低了可用性。

6.5、SQL规范

  1. 基础规范
    • 拒绝大的SQL。大的SQL可以进行拆分。大的SQL对资源利用率低。多个小sql缓存命中率高、利用多CPU、如有锁减小锁的粒度。
    • 拒绝大的事务。与事务无关的操作不要放在事务内。保持事务短小。
    • 不使用存储过程。存储过程难于调试扩展也没有移植性。
    • 减少使用运存函数。
    • 高并发数据库避免join
    • 使用预编译语句。比传递sql更高效。一次解析多次使用。避免sql注入。  
  2. select语句优化
    • 查询需要的列。避免select * 的方式。select * 基本上不能使用到覆盖索引、返回多余的数据增加IO、网络、CPU等资源、
    • 不要使用count(列名/常数)代替count()。count()是标准统计行数语法,统计与null无关。count(列名/常数)不会统计null列
    • count(distinct 列)统计非null得非重复行数。count(distinct 列1,列2)如果一列为null,另一列值不同也是0。
    • 注意sum类聚合函数NPE问题。如果为null sum返回的是null。
  3. where优化
    • 使用ISNULL()判断是否为null值。NULL与任何值的比较都为NULL。
    • in 操作控制数量,建议1000个以内或更少。
    • 同字段or操作改为in操作。or是O(n),in是O(logn);不同字段的or可以使用union
    • 保持一个range查询。多个范围查询对索引利用率不高。
    • 多个is null操作索引利用率也不高
    • 同数据类型间进行比较,避免隐式的类型转换。
    • 避免使用负向查询。not in 、not like、!= 等等。
  4. order by优化
    • order by利用索引前提是where和order by 条件要符合最左前缀条件同时where语句中的条件是等值条件。
  5. group by优化
    • group by如果不需要排序可是指定order by null
    • 使用索引要满足最左前缀
  6. limit优化
    • limit 10000,10实现方式是查询出10010行数据并丢弃前10000行数据
    • 如可以先查询出ID,在用in操作。如果有连续性则使用范围查询。
  7. join优化
    • mysql join算法使用的是nested loop join算法,通过驱动表的结果集作为循环数据的基础同下一张表进行循环过滤得到结果。
    • 避免join,更要避免大表的join。
    • 小表驱动大表进行查询。查询的列最好要命中index。
    • 不需要去重则使用union all替代union。union有去重开销。
  8. 更新操作优化
    • 大批量更新操作避免高峰期
    • 大批量更细操作打散。避免同步的延迟等。

6.6、程序事务配置规范

  1. 事务建议rollback for=exception
  2. 业务数据库读写master。避免不同步带来的问题。如果读写分离了则不能更新完立即查询。

转自:https://blog.csdn.net/qq_40338564/article/details/120467570

标签:java,代码,规范,查询,索引,api,使用,null,order
From: https://www.cnblogs.com/jdy1022/p/18191688

相关文章

  • 探究——C# .net 代码混淆/加壳
    背景:保密。过程:先查询一下常见的加壳工具:DotFuscator,官方自带,据说免费版混淆程度不高ConfuserEx,只支持.NETFramework2.0/3.0/3.5/4.0/4.5/4.6/4.7/4.8,不支持.NETCoreVirboxProtector,很好很优秀,但是收费NETReactor,最新6.9版收费,PJ版到4.9不支持.NETCoreObfu......
  • 【java】异常 (详解)
     在Java中,将程序执行过程中发生的不正常行为称为异常  比如以下几个异常1.算术异常 因为 0不能当被除数,所以报出了异常,这种异常就叫作算数异常 2.空指针异常  3.数组越界异常   4.在编译时就发现了异常 那有的异常在编译时就被发现,有的要在运行之......
  • 实现Python日志点击跳转到代码位置的方法
    前言在软件开发过程中,日志是一种非常重要的工具,用于记录程序运行时的状态、错误信息以及调试信息。当程序出现问题时,定位到具体的代码位置对于排查问题至关重要。本文将介绍如何在Python日志中实现点击跳转到代码位置的功能,以提高调试效率。为什么需要点击跳转功能?通常情况下,......
  • Go-Zero定义API实战:探索API语法规范与最佳实践(五)
    前言上一篇文章带你实现了Go-Zero模板定制化,本文将继续分享如何使用GO-ZERO进行业务开发。通过编写API层,我们能够对外进行接口的暴露,因此学习规范的API层编写姿势是很重要的。通过本文的分享,你将能够学习到Go-Zero的API语法规范,以及学会实际上手使用。概述下文所说的是api......
  • wsdl文件生成java客户端
    生成java客户端  公司内部服务使用webservice进行交互,而且对方提供了wsdl文件。我的目标是就是通过wsdl文件,完成双方对接。wsdl文件->java文件wsimport-keep-pcom.wsdl.commonsendImMessage.wsdl.xml-keep表示保留生成的.java文件-p指定生成的Java类的包名  通......
  • java.net.SocketException: Connection reset
    今天在学习socket编程的时候遇到了一个bug:java.net.SocketException:Connectionreset先来看一下自己的代码:服务端:publicclassServerSocketDemo{publicstaticvoidmain(String[]args){try{//建立一个ServerSocketServerS......
  • Playwright执行 JavaScript 脚本:探索浏览器自动化的新境界
    前言我们在进行web自动化时,经常遇到一些不好操作的元素,普通的元素定位和操作容易报错,如果我们使用的selenium的话,就可以使用selenium调用js脚本进行操作。在playwright中也有类似的方法,使用page.evaluate()执行JavaScript脚本。page.evaluate()和page.evaluate_handle()之间的......
  • java所有集合的相互关系是什么
    Java集合框架是一个设计精良、功能强大的工具集,用于存储和操作对象集合。它大致分为以下几类,并且各类之间存在一定的层级关系和功能差异:###顶级接口(根接口)1.**Collection**:是最基础的集合接口,所有集合类都直接或间接实现了这个接口。它定义了基本的集合操作,如添加元素(`add(......
  • java所有集合的相互关系是什么
    Java集合框架是一个设计精良、功能强大的工具集,用于存储和操作对象集合。它大致分为以下几类,并且各类之间存在一定的层级关系和功能差异:###顶级接口(根接口)1.**Collection**:是最基础的集合接口,所有集合类都直接或间接实现了这个接口。它定义了基本的集合操作,如添加元素(`add(......
  • git 查看当前代码是在哪个 tag 上
    在Git中,查看当前代码所在的tag可以使用以下命令:###查看当前提交所对应的所有tag如果你想查看当前HEAD或者某个特定的commit对应的所有tag,可以使用下面的命令:gittag--containsHEAD这个命令会列出包含当前HEAD的所有tag。如果你想查看某个特定commit的......