正文

工程代码实践简单总结(代码片段)

软件开发随心记  软件开发随心记  2022-10-22  297

关键词：

一、背景

最近我们团队有幸接了两个0到1的项目，一期项目很紧急，团队成员也是加班加点，从开始编码到完成仅用了一星期多一点点，期间还不断反复斟酌代码如何抽象代码，如何写得更优雅，一遍又一遍的调整，我也是一次又次的阅读每个团队成员的代码，虽然还有些不如意，但整体来说还算是满意，参与项目的成员经过不断琢磨，对一些功能不断抽像，团队进步也是非常明显,以下举了几个样例。

那么这次我为什么对工程代码抓得更严，主要是之前交接了不少其它团队的工程，由于当时设计不够好，维护起来非常痛苦，也正是因为这些工程，我阅读了非常多的代码，对自己也有很大的启发和感想，因此希望我自己的团队能尽可能写好代码，减少维护上的一些痛苦。另外就是我们写的代码除了给机器执行外，更多的时候是给人读的，这个读代码的可能是后来的维护人员，所以呢也顺便总结一下。

二、衡量代码好环的原则

2.1 评判代码指标

实际上，咱们平时嘴中常说的“好”和“烂”，是对代码质量的一种描述。“好”笼统地表示代码质量高，“烂”笼统地表示代码质量低。对于代码质量的描述，除了“好”“烂”这样比较简单粗暴的描述方式之外，我们也经常会听到很多其他的描述方式。这些描述方法语义更丰富、更专业、更细化。我搜集整理了一下，罗列在了下面，一般有几下几标准，分别是可读性、可维护性、可扩展性、可复用性、灵活性、可测试性等等

可读性 readability
软件设计大师 Martin Fowler 曾经说过：“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.”翻译成中文就是：“任何傻瓜都会编写计算机能理解的代码。好的程序员能够编写人能够理解的代码。”Google 内部甚至专门有个认证就叫作 Readability。只有拿到这个认证的工程师，才有资格在 code review 的时候，批准别人提交代码。可见代码的可读性有多重要，毕竟，代码被阅读的次数远远超过被编写和执行的次数。
我个人认为，代码的可读性应该是评价代码质量最重要的指标之一。我们在编写代码的时候，时刻要考虑到代码是否易读、易理解。除此之外，代码的可读性在非常大程度上会影响代码的可维护性。毕竟，不管是修改 bug，还是修改添加功能代码，我们首先要做的事情就是读懂代码。代码读不大懂，就很有可能因为考虑不周全，而引入新的 bug。
既然可读性如此重要，那我们又该如何评价一段代码的可读性呢？我们需要看代码是否符合编码规范、命名是否达意、注释是否详尽、函数是否长短合适、模块划分是否清晰、是否符合高内聚低耦合等等。你应该也能感觉到，从正面上，我们很难给出一个覆盖所有评价指标的列表。这也是我们无法量化可读性的原因。
实际上，code review 是一个很好的测验代码可读性的手段。如果你的同事可以轻松地读懂你写的代码，那说明你的代码可读性很好；如果同事在读你的代码时，有很多疑问，那就说明你的代码可读性有待提高了
可维护性 maintainability
一般指的是在不破坏原代码设计的前提下，快速修改bug或增加代码，不会带来新bug，表明该代码的维护性比较好。落实到编码开发，所谓的“维护”无外乎就是修改 bug、修改老的代码、添加新的代码之类的工作。所谓“代码易维护”就是指，在不破坏原有代码设计、不引入新的 bug 的情况下，能够快速地修改或者添加代码。所谓“代码不易维护”就是指，修改或者添加代码需要冒着极大的引入新 bug 的风险，并且需要花费很长的时间才能完成。
可扩展性 extensibility
代码面对未来新需求的变化能力，一般来说，开发新需求的时候，不修改原代码或很少修改，即可达到需求开发的能力，通常会预留一些功能扩展点。
可复用性 reusability
尽量避免重复造轮子，即能够沉淀出一些通用的代码逻辑，保持与上层业务代码的解耦
灵活性 flexibility
这个词比较宽泛。通常与可维护性、可扩展性以及可复用性类似
可测试性
主要反映在写单测的时候。从两个方面体现：
1.单元测试是否容易编写；
2.写单元测试的时候，不能依赖环境，远程调用其他服务的借口，尽可能进行mock数据，保持服务之间的解耦。虽然要团队每人都按这个规范走很难，但我们团队有一个强制要求，就是每个功能函数不能超过50行代码，而且要求代码越短越好。
这几个维度是评判代码维度比较重要的几个指标。

2.2 指导理论

高内聚低耦合几乎是每个程序员员都会挂在嘴边的，但这个词太过于宽泛，太过于正确，所以聪明的编程人员们提出了若干面向对象设计原则来衡量代码的优劣：

开闭原则 OCP (The Open-Close Principle)
单一职责原则 SRP (Single Responsibility Principle)
依赖倒置原则 DIP (Dependence Inversion Principle)
最少知识原则 LKP (Least Knowledge Principle)) / 迪米特法则 (Law Of Demeter)
里氏替换原则 LSP (Liskov Substitution Principle)
接口隔离原则 ISP (Interface Segregation Principle)
组合/聚合复用原则 CARP (Composite/Aggregate Reuse Principle)
这些理论想必大家都很熟悉了，是我们编写代码时的指导方针，按照这些原则开发的代码具有高内聚低耦合的特性，换句话说，我们可以用这些原则来衡量代码的优劣。

三、代码实现技巧

我相信每个工程师都想写出高质量的代码，不想一直写没有成长、被人吐槽的烂代码。那如何才能写出高质量的代码呢？针对什么是高质量的代码，我们刚刚讲到了七个最常用、最重要的评价指标。所以，问如何写出高质量的代码，也就等同于在问，如何写出易维护、易读、易扩展、灵活、简洁、可复用、可测试的代码，但要写好代码，也不是一蹴而就，需要非常多的实践与积累，下面简举例说明：

3.1 抽像能力

抽象思维是我们工程师最重要的思维能力，因为软件技术本质上就是一门抽象的艺术。我们工程师每天都要动用抽象思维，对问题域进行分析、归纳、综合、判断、推理，从而抽象出各种概念，挖掘概念和概念之间的关系，然后通过编程语言实现业务功能，所以，我们大部分的时间并不是在写代码，而是在梳理需求，理清概念，对需求有一个全局的认知。而抽像能力让我及团队切身感受到，它给我们在编码和设计上带来的质的变化。

案例一：异步Excel导出

其实导出Excel功能在我们工程里随处可见，特别是咱们的运营希望一次性导出越多数据越好，为了不给我们系统带来太大压力，对于大数据量的导出一般异步进行，针对于这样一个简单的功能，那么应该如何抽像呢？

普通的写法：

public String exportXXX(参数) throws Exception 
	//业务实现


public String exportXXX2(参数) throws Exception 
	//业务实现

抽像写法：

我们其实可以把每个异步导出看作是一个异步任务，而每个任务可导出的内容是不一样的，因此完全可以把导出抽像一个方法，由每个具体实现类去实现导出不同的内容，具体如下：

// export excel 
public interface IExcelExportTask 
    String export(BizCommonExportTask exportTask) throws Exception;

//样例实现类
XXXXExportTask implements IExcelExportTask 
	String export(BizCommonExportTask exportTask) throws Exception
    	public String export(BizCommonExportTask exportTask) throws Exception 
    	//组织数据筛选条件
        TestReq queryReq = GsonUtils.toObject(exportTask.getInputParams(),TestReq.class);
        String fileName = String.format("%s%s%s", exportTask.getUploadFileName(),System.currentTimeMillis(),".xlsx");

        String downUrl = excelService.uploadExcel(fileName, null, new Fetcher<PreOccupyModel>(PreOccupyModel.class) 
        	//循环获取数据
            @Override
            public List<TestModel> fetch(int pageNo, int pageSize) throws OspException
                TestQueryResp resp = testFethchLogic.fetchRecord(queryReq);
                return pageNo > resp.getPageNum() ? Collections.emptyList() :toExcelModel(resp);
            
        );
        return downUrl;
    


public class XXXXExportTask1 implements IExcelExportTask 
    @Override
    public String export(BizCommonExportTask exportTask) throws OspException 
        TestQuery query = GsonUtils.toObject(exportTask.getInputParams(), TestQuery .class);
        String fileName = String.format("%s%s%s", exportTask.getUploadFileName(), System.currentTimeMillis(), ".xlsx");

        return excelService.uploadExcel(fileName, null, new Fetcher<ExportItemModel>(TestModel.class) 
            @Override
            public List<TestModel> fetch(int pageNo, int pageSize) throws OspException 
                return XXXXLogic.queryExportItem(query, pageNo, pageSize);
            
        );
    

//导出任务分发器
public class ExcelTaskDispacther extends ApplicationObjectSupport 
	public boolean dispacthTask(Long taskId) throws OspException 
        
        updateTaskStatus(exportTask,CommonExportStatus.CREATING,TransferExportStatus.CREATING,StringUtils.EMPTY);
        try 
            String beanName =  getBeanName();
            ExportTaskHandler exportTaskHandler = getApplicationContext().getBean(beanName , IExcelExportTask .class);
            if(exportTaskHandler == null) 
                log.warn(String.format("任务ID[%s]写入配置错误！", taskId));
                return false;
            
            
            updateTaskStatus(exportTask,CommonExportStatus.CREATE_SUCCESS,TransferExportStatus.CREATE_SUCCESS,StringUtils.EMPTY);
            log.info(String.format("任务ID[%s]RFID为[%s]处理成功", exportTask.getId(),rfid));
            return true;
         catch(BusiException ex) 
            log.info("任务ID[]失败，原因：", exportTask.getId(),ex.getMessage(),ex);
            updateTaskResult();
         catch(Exception ex) 
            log.info("任务ID[]失败，原因：", exportTask.getId(),ex.getMessage(),ex);
            updateTaskResult();
        
        return false;

案例二：系统通知

在微服务化流行的今天，为了提升系统吞吐量，系统职责越来越细，各系统模块需要频繁交互数据，那么对于复杂的数据交互场景，比如我们调拨单，调拨单在扭转的过程中需要与很多系统交互，跟门店、仓库、库存模块有非常多的交互，我们又该如何抽像呢，以下是调拨与各系统交互的代码示例

//接口定义
public interface BizNotificationHandler 
    /**
     * 抛异常会当失败处理
     * 是否需要重试由BizNotificationStatus返回状态来决定
     * @param bizNotification
     * @return
     * @throws OspException
     */
    BizNotificationStatus handleNotification(BizNotification bizNotification) throws OspException;


//推送调拨差异数据给库存系统
public class SyncDiffToSimsAndBackQuotaHandler implements BizNotificationHandler     
    @Override
    public BizNotificationStatus handleNotification(BizNotification bizNotification) throws OspException 
        //业务逻辑实现
        
        return BizNotificationStatus.PROCESS_SUCCESS;
    

//占用库存
public class TransferOccupyInventoryHandler implements BizNotificationHandler 
    @Override
    public BizNotificationStatus handleNotification(BizNotification bizNotification) throws OspException 
        //业务实现
    


//在GPDC生成新条码
public class GpdcGenerateNewBarcodeHandler implements BizNotificationHandler 
    @Override
    public BizNotificationStatus handleNotification(BizNotification bizNotification) throws OspException 
        //业务代码实现
    
｝

其实我们在与其它系统交互的时候，我们可以把每一个交互动作抽像成一个通知事件，每次交互的时候，写一个事件通知事件即可。

3.2 组合/聚合复用原则

关于组合/聚合复用原则，其实我们在项目过程会经常遇到，比如项目里会经常管理各种单据，像采购单、调拨单、收货单等，而对于每种单据都会有各种各样的较验，我们先来看一段建调拨单代码，具体如何下：

//接口定义
public interface TransferValidator 
    boolean validator(CreateTransferCtx ctx) throws OspException;

//接口实现1
public class W2sCrossPoQtyValidator implements TransferValidator 
    @Override
    public boolean validator(CreateTransferCtx ctx) throws OspException 
        //较验器代码实现
    
//接口实现2
public class W2sStoreBarcodeSaleLimitValidator implements TransferValidator 
    @Override
    public boolean validator(CreateTransferCtx ctx) throws OspException 
        //较验器代码实现
    


//较验器组装
public class TransferValidators 

    public ValidatorChain newChain() 
        return new ValidatorChain();
    

    public class ValidatorChain 
        private final List<TransferValidator> validators = new ArrayList<>();

        public ValidatorChain qtyValidator() 
            validators.add(qtyValidator);
            return this;
        

        public ValidatorChain transferRouteCfgValidator() 
            validators.add(transferRouteCfgValidator);
            return this;
        

        public ValidatorChain prodValidator() 
            validators.add(prodValidator);
            return this;
        

        public ValidatorChain w2sWarehouseStoreValidator() 
            validators.add(w2sWarehouseStoreValidator);
            return this;
        

        public ValidatorChain w2sStoreBarcodeSaleLimitValidator() 
            validators.add(w2sStoreBarcodeSaleLimitValidator);
            return this;
        

        public ValidatorChain w2sAssignPoValidator() 
            validators.add(w2sAssignPoValidator);
            return this;
        

        public ValidatorChain w2sCrossPoValidator() 
            validators.add(w2sCrossPoValidator);
            return this;
        

        public ValidatorChain w2sCrossPoQtyValidator() 
            validators.add(w2sCrossPoQtyValidator);
            return this;
        

        public ValidatorChain w2sCross4XupValidator() 
            validators.add(w2sCross4XupValidator);
            return this;
        

        public ValidatorChain repeatLineValidator() 
            validators.add(repeatLineValidator);
            return this;
        

        public ValidatorChain sstradeBarcodeValidator() 
            validators.add(sstradeBarcodeValidator);
            return this;
        

        public ValidatorChain s2wWarehouseStoreValidator() 
            validators.add(s2wWarehouseStoreValidator);
            return this;
        

        public boolean validator(CreateTransferCtx ctx) throws OspException 
            for (TransferValidator validator : validators) 
                if (!validator.validator(ctx)) 
                    return false;
                
            
            return true;
        
    


//业务代码使用
public interface TransferCreator 
    boolean createOrder(CreateTransferCtx ctx) throws OspException;


public abstract class DefaultTransferCreator implements TransferCreator 
     @Override
    public boolean createOrder(CreateTransferCtx ctx) throws OspException 
        validator(ctx)
        //实现业务逻辑
    

    protected abstract boolean validator(CreateTransferCtx ctx) throws OspException;
 
//店仓调拨单 
public class S2wRefundCreator extends DefaultTransferCreator 
	//较验器自由组装
    @Override
    protected boolean validator(CreateTransferCtx ctx) throws OspException 
        return transferValidators.newChain()
                .qtyValidator()
                .transferRouteCfgValidator()
                .prodValidator()
                .validator(ctx);

通过上面的示例，其实抽像并不难，难的是我们要花时间去思考，去理解，只有自己花足够的多时间，反复训练我相信比较容易做到，最近在两个新项目，我们团队的部分成员反馈做梦都在想如何实现更合理。

四、总结

写出满足这些评价标准的高质量代码，我们需要掌握一些更加细化、更加能落地的编程方法论，包括面向对象设计思想、设计原则、设计模式、编码规范、重构技巧等。而所有这些编程方法论的最终目的都是为了编写出高质量的代码。
比如，面向对象中的继承、多态能让我们写出可复用的代码；编码规范能让我们写出可读性好的代码；设计原则中的单一职责、DRY、基于接口而非实现、里式替换原则等，可以让我们写出可复用、灵活、可读性好、易扩展、易维护的代码；设计模式可以让我们写出易扩展的代码；持续重构可以时刻保持代码的可维护性等等，以上示例仅供参考，也希望大家更多参与讨论。

容器实践线路图(代码片段)

...自己企业实践容器的时候，会认识到容器化不是一个简单工程，甚至会有一种茫然不知从何入手的感觉。本文总结了通用的企业容器化实施线路图，主要针对企业有存量系统改造为容器，或者部分新开发的系统使用容器技术的场... 查看详情

软件工程应用与实践（13）——jwt(代码片段)

2021SC@SDUSC文章目录一、内容概述二、源码分析2.1JWT配置2.2JwtAuthenticationRequest类2.3JwtAuthenticationResponse类2.4JwtTokenUtil类2.5UserAuthRestInterceptor类三、总结一、内容概述在老年健康管理系统中，权限验证是个很重要的内容。在本项... 查看详情

工程实践：到底要不要使用智能指针(代码片段)

工程实践：到底要不要使用智能指针前言从需求开始探讨问题智能指针现状unique_ptr示例shard_ptr接口该不该使用智能指针智能指针作为函数参数智能指针作为函数返回值如何选择智能指针注意不要踩的“坑”总结参考资料前言... 查看详情

软件工程应用与实践——邮件发送(代码片段)

2021SC@SDUSC文章目录一、概述二、代码分析2.1SMTP协议2.2邮件发送2.3发送带附件的邮件三、总结一、概述在的老年健康管理系统中，在注册和多权限验证时，需要向用户发送邮件验证码。此外，该系统实现了邮件发送... 查看详情

软件工程应用与实践——邮件发送(代码片段)

软件工程应用与实践——微服务治理(代码片段)

2021SC@SDUSC文章目录一、概述二、核心代码2.1微服务搭建2.2注册和配置中心2.2.1服务注册中心2.2.2配置中心2.3服务间通信三、总结一、概述在老年健康管理系统的后端代码中，使用了当前火热的微服务技术。微服务架构改变... 查看详情

软件工程应用与实践（12）——工具类分析(代码片段)

2021SC@SDUSC文章目录一、概述二、代码分析2.1IKAnalyzer5x类2.2IKTokenizer5x类2.3QueryUtil类2.4DBLog类2.5LogService接口和LogServiceImpl类三、总结一、概述在上一篇文章中，我们主要分析了代码生成包的工具类，和一部分搜索引擎包中... 查看详情

软件工程应用与实践——词云图的呈现(代码片段)

2021SC@SDUSC文章目录一、功能概述二、前端代码2.1echarts配置2.2echarts使用三、echarts源码分析四、总结一、功能概述在老年健康管理系统中，首页词云图是一个独特的功能。经过小组成员交流讨论，决定由我负责词云图代... 查看详情

软件工程应用与实践——知识图谱树形结构获取(代码片段)

2021SC@SDUSC目录一、知识图谱的结构二、前端代码2.1对axios请求的封装2.2树形控件代码及其分析三、后端代码3.1树形结构对应的实体类3.2填充知识树的过程3.3知识树的JSON表示四、总结一、知识图谱的结构老年健康知识图谱系统... 查看详情

maven学习笔记总结(代码片段)

Maven学习总结一、Maven简介1.1软件是一个工程我们在日常生活常能听到工程这个词，像桥梁工程、道路工程、南水北调工程等等。工程说简单点就是各个行业的从业人员通过总结规律或者方法，以最短的时间和人力、物... 查看详情

软件工程应用与实践（11）——工具类分析(代码片段)

2021SC@SDUSC文章目录一、概述二、主要代码2.1DateUtils2.2GeneratorUtils2.3DocumentUtil三、总结一、概述在老年健康管理系统中，有很多工具类，这些工具类在项目中扮演了关键的角色，很多功能都利用这些工具类实现，... 查看详情

软件工程应用与实践（10）——网关，服务熔断(代码片段)

2021SC@SDUSC文章目录一、概述二、代码分析2.1gateway网关2.1.2yml配置2.1.2java代码2.2服务熔断三、总结一、概述在上一篇文章中，我介绍了微服务治理中的服务注册，配置中心，服务间通信等内容，本博客重点介绍老... 查看详情

git工程开发实践——git内部实现机制(代码片段)

Git工程开发实践（二）——Git内部实现机制一、Git仓库内部实现简介Git本质上是一个内容寻址(content-addressable)的文件系统，根据文件内容的SHA-1哈希值来定位文件。Git核心部分是一个简单的键值对数据库(key-valuedatastore)。向Git数... 查看详情

软件工程实践总结

这个作业属于哪个课程2021春软件工程实践这个作业要求在哪里软件工程实践总结&个人技术博客这个作业的目标课程回顾与总结、个人技术总结其他参考文献软工实践寒假作业（2/2）、《构建之法》课程回顾与总结问题分析点... 查看详情

软件工程应用与实践——词云的获取(代码片段)

2021SC@SDUSC文章目录一、简介二、word文档分词2.1java引入jieba分词2.2读取word文档完成分词三、词云的获取3.1获取所有词3.2去除停用词四、总结一、简介经过小组分工和讨论后，决定由我负责分析词云的获取和整理的部分。在... 查看详情

软件工程应用与实践——词云的获取(代码片段)

工程实践之路：c++接口设计中的工厂模型(代码片段)

工程实践之路：C++接口设计中的工厂模型设计模式之工厂模式为什么使用工厂模式1.工厂设计模式是为了将对象的创建与使用进行分离2.其他好处简单工厂模式工厂方法模式抽象工厂模式参考资料上一篇文章写了《工程... 查看详情

git工程开发实践——git工程实践扩展(代码片段)

Git工程开发实践（六）——Git工程实践扩展一、Git提交日志规范1、Git提交日志模板Git支持对每次提交的日志信息进行规范，可以通过设置提交模板实现。建立一个gitCommitTemplate文件，内容为：#commitmessage包含三部分，header,body和fo... 查看详情

正文

工程代码实践简单总结(代码片段)

一、背景

二、衡量代码好环的原则

2.1 评判代码指标

2.2 指导理论

三、代码实现技巧

3.1 抽像能力

案例一：异步Excel导出

普通的写法：

抽像写法：

案例二：系统通知

3.2 组合/聚合复用原则

四、总结

容器实践线路图(代码片段)

软件工程应用与实践（13）——jwt(代码片段)

工程实践：到底要不要使用智能指针(代码片段)

软件工程应用与实践——邮件发送(代码片段)

软件工程应用与实践——邮件发送(代码片段)

软件工程应用与实践——微服务治理(代码片段)

软件工程应用与实践（12）——工具类分析(代码片段)

软件工程应用与实践——词云图的呈现(代码片段)

软件工程应用与实践——知识图谱树形结构获取(代码片段)

maven学习笔记总结(代码片段)

软件工程应用与实践（11）——工具类分析(代码片段)

软件工程应用与实践（10）——网关，服务熔断(代码片段)

git工程开发实践——git内部实现机制(代码片段)

软件工程实践总结

软件工程应用与实践——词云的获取(代码片段)

软件工程应用与实践——词云的获取(代码片段)

工程实践之路：c++接口设计中的工厂模型(代码片段)

git工程开发实践——git工程实践扩展(代码片段)