代码整洁之道：一个提升代码可读性的小技巧

写在开头

如何写好代码，一千个人眼中有一千个哈姆雷特，但是我认为有一点的是写好代码的公理，不可撼动，即对代码可读性的追求。最近在工作中面对了太多可读性不佳的代码，使得对于旧有代码的维护和分析困难重重，心力憔悴。

基于“严于律己，宽以待人”的思想，遇到这种旧有代码尚可以接受，但为了避免未来这种可读性不佳的代码出于己手，我最近开始认真的思考这个问题——如何提高代码的可读性，使得代码变得整洁，甚至赏心悦目。

下面我就从“控制流”的角度分享一下我对提高代码可读性的一些思考。

什么是控制流

对于任意一个系统的任意系统行为，都可以将其进行步骤化拆解。

例如对于用户详细信息查询行为进行步骤化拆解，可以拆解为：查询条件校验 -> 查询用户基本信息 -> 根据用户基本信息查询用户详细信息 -> 结果校验 -> 返回。以上对于系统行为的步骤拆解方式，拆解出来的步骤1 -> 步骤2 -> 步骤3 -> ……，总结起来其实就是行为的控制流。

即任何系统行为都可以拆解为一段控制流。 而控制流具有以下特性：

1. 控制流描述目的或动机，对于控制流中的任意流程节点，其只关心该步骤的目的或者动机，与实现目的的过程没有关系，于此相反，控制节点反而是对一段过程的总结。
2. 控制流与实现细节无关， 对于控制流中的任意流程节点，无论你如何实现它，流程节点的目的和意义都不会发生变化。例如对于用户详情查询控制流中的“查询用户基本信息”节点而言，无论你的实现细节是从缓存中查询还是从数据库中查询，其目的就是“输出用户信息交付给控制流下一流程节点”，不会随着存储源的变化而发生改变。

代码整洁小技巧：基于控制流编程

下面通过一个简单的例子来看看如何找到控制流以此一个冗长混沌的代码一步一步进行可读性的优化的。

public class UserService {

    @Autowired
    private UserInfoDAO userInfoDao;

    @Autowired
    private UserDetailDAO userDetailDao;

    public User queryUserDetail(UserDO queryCondition) {
        String username = queryCondition.getUsername();
        String userId = queryCondition.getUserId();
        if (username == null) {
            throw new IllegalArgumentException("用户名不能为空");
        }
        if (userId == null) {
            throw new IllegalArgumentException("用户Id不能为空");
        }

        Map<String, Object> param = new HashMap<>();
        param.put("username", username);
        param.put("userId", userId);
        UserDO userDO = userInfoDao.queryUserByCondition(param);
        if (userDO == null) {
            return null;
        }

        param = new HashMap<>();
        param.put("userId", userDO.getId());
        UserDetailDO userDetailDO = userDetailDao.queryUserDetailByCondition(param);
        if (userDetailDO == null) {
            throw new IllegalArgumentException("用户详情查询失败");
        }

        UserDetail userDetail = new UserDetail();
        userDetail.setAddress(userDetailDO.getAddress());
        userDetail.setNickName(userDetailDO.getNickName());
        userDetail.setPhone(userDetailDO.getPhone());
        return new User(userDO.getId(), userDO.getUsername(), userDetail)
    }
}

上述用户信息查询代码是我在工作中遇到的一个真实的例子的简化改编，这种“流水账”似的代码在工程开发中比比皆是，造成代码流水账的原因往往是二次扩展时采取在代码的原有基础上进一步堆叠逻辑的方式，让方法的进一步熵增，逐渐混沌，导致一个方法几百上千行，失去维护价值。

描述目的与动机

基于控制流编程，首先是找到一个系统行为的控制流。将系统行为翻译为控制流，这是第一步。如何将一个系统行为翻译成为一段控制流。这其中其实分为两种模式：正向拆解、逆向还原。

正向拆解

正向拆解比较好理解，我们只需要对系统行为进行合理的推演，再根据过往的经验，总结出一段控制流程即可。比如还是这个例子：用户信息的查询行为，根据数据查询的通用模版，分为前置校验、查询、后置校验、返回结果几个步骤，我们可以得到用户查询行为的控制流：查询条件校验 -> 查询用户基本信息 -> 根据用户基本信息查询用户详细信息 -> 结果校验 -> 返回。

逆向还原

逆向还原稍微复杂一点，非常考验程序员的抽象总结能力，即给你一段冗长混沌的流水账过程代码，对其中的控制流进行总结和提取，这种情况一般发生在对一段“散发着陈年香气”的老代码进行重构的时候。但万变不离其宗，依旧是对代码进行整体分析，对动机一致、目的一致的段落进行提取，抽象为控制流节点。将整段又臭又长的代码总结为几个关键步骤，组合成为控制流。

套用这个方法，可以通过控制流构建对于上述冗长代码进行可读性上的进行极大优化：

public class UserService {

    @Autowired
    private UserInfoDAO userInfoDao;

    @Autowired
    private UserDetailDAO userDetailDao;

    // ----------- 系统行为 -----------

    public User queryUserDetail(User queryCondition) {
        // 1. 参数校验
        validateQueryCondition(queryCondition);
        // 2. 查询用户基本信息
        UserDO userDO = queryUserInfo(queryCondition.getUsername(), queryCondition.getUserId());
        // 3. 查询用户详细信息
        UserDetailDO userDetailDO = queryUserDetail(userDO.getId());
        // 4. 校验查询结果
        validateQueryResult(userDetailDO);
        // 5. 返回查询结果
        return buildUserResult(userDO.getId(), userDO.getUsername(), userDetailDO);
    }

    // ------------ 私有方法：步骤实现细节 -----------

    private void validateQueryCondition(User queryCondition) {
        String username = queryCondition.getUsername();
        String userId = queryCondition.getUserId();
        if (username == null) {
            throw new IllegalArgumentException("用户名不能为空");
        }
        if (userId == null) {
            throw new IllegalArgumentException("用户Id不能为空");
        }
    }

    private UserDO queryUserInfo(String name, String userId) {
        Map<String, Object> param = new HashMap<>();
        param.put("username", name);
        param.put("userId", userId);
        UserDO userDO = userInfoDao.queryUserByCondition(param);
        if (userDO == null) {
            throw new IllegalArgumentException("用户详情查询失败");
        }
        return userDO;
    }

    private UserDetailDO queryUserDetail(String userId) {
        Map<String, Object> param = new HashMap<>();
        param.put("userId", userId);
        return userDetailDao.queryUserDetailByCondition(param);
    }

    private void validateQueryResult(UserDetailDO userDetail) {
        if (userDetail == null) {
            throw new IllegalArgumentException("用户详情查询失败");
        }
    }

    private User buildUserResult(String id, String username, UserDetailDO userDetailDO) {
        UserDetail userDetail = new UserDetail();
        userDetail.setAddress(userDetailDO.getAddress());
        userDetail.setNickName(userDetailDO.getNickName());
        userDetail.setPhone(userDetailDO.getPhone());
        return new User(userDetail);
    }
}

上述代码看似只是抽了几个方法抽象，实则不然，深挖这背后的动机，这其实隐含着解构过程的思想。为什么声明式编程比命令式编程更加具有优势，究其本质就是其面向目的而不是过程的宗旨，这不仅仅是避免了复杂的过程带来的副作用，而且增加了代码整体的可读性。而此处我们将过程细节进行分类封装于以目的命名的方法中，而在主流程中只留下各种以目的作为命名的方法的编排，使得系统行为的控制流程得以凸显，能够让代码读者迅速抓取整段代码前后逻辑步骤。这其实和声明式编程的内核不谋而合。

以上，我们可以得到提高代码可读性一个很重要的技巧：以描述目的和动机的方式解构过程，而不是盲目堆叠过程

藏在暗处的维护隐患

但仅此而已吗，只是做了几个方法的拆分就足够吗。此时我们只要往代码的长尾运维角度进行思索，就能立刻找到破绽——“流程怎么进行扩展呢？”。目前我们控制流实现方式存在一个很大的隐患：控制流节点的实现依赖于源码细节。

这一点几乎是致命的，由于控制流节点只描述目的和动机，过程的实现方式必然不止一种，假如后期运维时需要对控制流节点的过程进行二次扩展，就会立刻回到堆叠过程的混沌状态。关于这一点，控制流的第二特性：细节无关原则给出了解法。

细节无关原则

早在三四十年前，当面向对象编程还没有兴起的时候，那时的程序员都是采用面向过程的C语言进行技术研发。对于一段程序的控制流来说，想要实现细节无关原则是一件极其困难的事情。缺少了面向对象的多态特性，接口概念的缺失让一段控制代码无可避免的会依赖于源码细节。而正是由于面向对象的一系列编程语言的出现让控制流脱离源码细节成为了可能。这其中的关键秘诀就是依赖反转。

在面向过程编程的时代，控制流的特性就是控制流的方向和实现细节的依赖方向是相同的。而不幸的是，我们第一版的控制流的依赖状态也是控制流程和实现细节的依赖方向吻合，也就是说，我们的初版代码依旧没有摆脱面向过程编程的思想桎梏。

但别忘了，我们可是使用的java这一面向对象编程的语言利器，我们完全可以通过多态将这种依赖关系进行反转。

利用依赖反转实现细节无关原则，体现到代码上如下所示：

public class UserService {

    @Autowired
    private UserInfoQueryRepository userInfoQueryRepository;

    @Autowired
    private UserDetailQueryRepository userDetailQueryRepository;

    @Autowired
    private UserQueryValidator userQueryValidator;

    // ----------- 系统行为 -----------

    public User queryUserDetail(User queryCondition) {
        // 1. 参数校验
        validateQueryCondition(queryCondition);
        // 2. 查询用户基本信息
        User user = queryUserInfo(queryCondition.getUsername(), queryCondition.getPassword());
        // 3. 查询用户详细信息
        UserDetail userDetail = queryUserDetail(user.getId());
        // 4. 校验查询结果
        validateQueryResult(userDetail);
        // 5. 返回查询结果
        return new User(userDetail);
    }

    // ------------ 私有方法：步骤实现细节 -----------

    private void validateQueryCondition(User queryCondition) {
        userQueryValidator.validateQueryCondition(queryCondition);
    }

    private User queryUserInfo(String userId, String userName) {
        User user = userInfoQueryRepository.findUser(userId, userName);
        if (Objects.isNull(user)) {
            throw new IllegalArgumentException("用户详情查询失败");
        }
        return user;
    }

    private UserDetail queryUserDetail(String userId) {
        return userDetailQueryRepository.findByUserId(userId);
    }

    private void validateQueryResult(UserDetail userDetail) {
        userQueryValidator.validateUserDetail(userDetail);
    }
}

这段代码里面我利用多态做了两件事：

1. 将校验逻辑抽象为Validator接口，其背后的动机就是将系统中出现的所有校验逻辑内聚至一处单独管理，以此封装所有的校验细节并将细节脱离于控制流，提升系统核心流程的整洁度。但其实是否需要这样做见仁见智，很多时候过度设计并不见得是一件好事。在校验逻辑不会过于复杂且修改频率较低的情况下，保留控制流对于校验逻辑细节的强依赖其实无伤大雅。
2. 将DAO封装为Repository仓储层，其背后的动机相较于第一点其实更加复杂一点，除了IO逻辑内聚之外，更重要的是对设备无关原则的遵循。

关于设备无关原则，这里展开来多说一点。

为什么UNIX操作系统会将IO设备设计成插件形式呢，因为自20世纪50年代末期以来，我们学到了一个重要经验：程序应该与设备无关。这个经验从何而来呢？因为一度所有程序都是设备相关的，但是后来我们逐渐发现其实真正需要的事情是在不同的设备上实现同样的功能。

——《架构整洁之道》

为什么我一定坚持DAO不能直接侵入系统的核心运行逻辑，因为DAO是外部存储源在业务系统中的集成层，其中避免不了存在和存储源相关的定制化操作逻辑，且这些操作逻辑不包含系统的任何领域信息。直接集成DAO相当于直接依赖于特定的存储设备的源码细节，不仅违背了设备无关原则，且由于缺乏领域信息，所以在调用DAO的时候还要使用大量的硬编码将领域信息翻译为查询操作。

举个例子：

private UserDO queryUserInfo(String name, String userId) {
    Map<String, Object> param = new HashMap<>();
    param.put("username", name);
    param.put("userId", userId);
    UserDO userDO = userInfoDao.queryUserByCondition(param);
    if (userDO == null) {
        throw new IllegalArgumentException("用户详情查询失败");
    }
    return userDO;
}

以上代码将查询参数put到map中的操作就是在将领域信息翻译构建为关系型数据库的查询操作。

因此，以设备无关原则作为出发点，同时考虑留落系统领域信息，仓储层在系统中应该作为外部存储的准入标准而存在。我们通过分析系统IO交互诉求在仓储层中构建具体的、包含动机和目的的访问接口，外部存储必须实现仓储层以集成到系统的核心领域中。

举个例子：

public interface UserInfoQueryRepository {
    /**
     * 根据userId、userName查询用户信息
     * @param userId user id
     * @param userName user name
     * @return user info
     */
    User findUser(String userId, String userName);
}

public class UserInfoQueryMysqlRepository implements UserInfoQueryRepository {

    private UserInfoDao userInfoDao;

    private UserModelConverter modelConverter;

    @Override
    public User findUser(String userId, String userName) {
        Map<String, Object> param = new HashMap<>();
        param.put("username", userName);
        param.put("userId", userId);
        UserDO userDO = userInfoDao.queryUserByCondition(param);
        if (userDO == null) {
            throw new IllegalArgumentException("用户详情查询失败");
        }
        return modelConverter.convert(userDO);
    }
}

以上代码将系统的用户信息查询诉求抽象为了repository的方法，规定的入参和出参，以此在仓储层留落领域信息，如果需要通过关系型数据库实现用户信息查询功能，就应该实现该仓储层接口，于此封装存储过程的源码细节，而不是直接将源码细节耦合在系统核心领域中。这样的话后期如果我们需要扩展用户信息的IO方式，比如从缓存中获取，可以非常轻松的进行扩展并替换核心领域中的存储来源。

所以仓储层是由其存在于系统中并扮演关键性角色的价值的，但很可惜的是，我在工作中接触的很多工程系统都没有认真构建仓储层，导致后期扩展出现困难，以至于加一个缓存需要大刀阔斧的对系统核心流程进行重构。

这里扯远了，我们回到正题上来，通过多态进行依赖反转，我们使得源码细节脱离了控制流的实现，这样做有什么好处呢？好处就是脱离了控制流实现的源码也可以通过控制流进行过程解构，比如脱离了控制流的Validator、Repository可以分别提炼控制流，以此面对后续可能出现的能力扩展，举个例子，如果Repository层需要进行多级缓存实现用户信息查询功能，我们如何做控制流拆解，如下列代码所示：

public class UserInfoQueryRepositoryImpl implements UserInfoQueryRepository {
    /**
     * mysql store
     */
    private UserInfoQueryMysqlRepository userInfoQueryMysqlRepository;
    /**
     * local cache store
     */
    private UserInfoQueryLocalCacheRepository userInfoQueryLocalCacheRepository;
    /**
     * redis store
     */
    private UserInfoQueryRedisRepository userInfoQueryRedisRepository;

    @Override
    public User findUser(String userId, String userName) {
        // 1. 在各存储源中查询用户信息
        User user = findUserFromMultilevelCache(Arrays.asList(
                userInfoQueryLocalCacheRepository,
                userInfoQueryRedisRepository,
                userInfoQueryMysqlRepository
        ), userId, userName);
        
        // 2. 校验查询结果
        validateResult(user);
        
        // 3. 返回结果
        return user;
    }

    private User findUserFromMultilevelCache(List<UserInfoQueryRepository> repositories, String userId, String userName) {
        for (UserInfoQueryRepository repository : repositories) {
            User user = repository.findUser(userId, userName);
            if (Objects.nonNull(user)) {
                return user;
            }
        }
        return null;
    }
    
    private void validateResult(User user) {
        if (Objects.isNull(user)) {
            throw new IllegalArgumentException("结果查询失败");
        }
    }
}

控制流对于过程的解构其实就是一个递归的过程，逐步将长流程解构为一个个独立存在，保证复用性的流程子节点。

以上，我们可以得到提高代码可读性一个很重要的技巧：依赖反转，细节无关。

见微知著：流程编排

我们在满足了“描述目的和动机”、“细节无关原则”的控制流实现基础上再深入的思考一层，其实控制流的流程节点本身何尝不是一种细节，只要是细节就有破除硬编码形态、灵活化的余地。此时我们自然而然就会想到流程节点可以通过动态标准化编排的方式出现在系统行为中，而不是直接以硬编排的方式毫无标准规范的留落于方法的实现类。

于是基于流程编排的系统构建方式便浮现出来。基于流程编排，我们可以对控制流的流程节点进行标准化，规范入参、出参、上下文，同时规范流程节点之间的数据流动格式以及流程的触发逻辑。以此实现流程的可配置化，甚至是可视化。

基于流程编排，用户信息的查询逻辑可能就变成了如下所示：

public class UserService {

    private ProcessorFactory processorFactory;

    private ProcessorChainBuilder processorChainBuilder;

    private ChainInvoker chainInvoker;

    // ----------- 系统行为 -----------

    public User queryUserDetail(User queryCondition) {
        ProcessorChain<User, User> processorChain = processorChainBuilder
                .process(processorFactory.get("queryConditionValidateProcessor"))
                .process(processorFactory.get("queryUserInfoProcessor"))
                .process(processorFactory.get("queryUserDetailProcessor"))
                .process(processorFactory.get("queryResultValidateProcessor"))
                .build();

        return chainInvoker.invoke(queryCondition, processorChain);
    }
}

当然，还有更多更好的编排方式，比如基于xml配置化或者页面可视化配置。

关于流程编排多说一点，流程编排是一套非常重的系统构建体系，是否选择使用流程编排要经过深思熟虑的考量，不是所有系统，所有应用场景都适合流程编排，比如上述颗粒度细化到方法实现层面的流程编排非常容易落入过度设计的陷阱之中，反而无故增加系统复杂度，加重了运维负担。流程编排最适用的应用方式我认为是业务用例维度的，即系统行为的组合场景下使用，并且该用例有着较为明显的控制流程，不需要经过研发人员耗费大量精力寻找流程节点之间的边界，比如电商平台的商家入驻、网站的用户注册等流程化明显的业务用例。

写在最后

上述的所有内容涉及到了4种代码的组织方式：

• 过程堆叠模式
• 基于目的和动机描述的控制流模式
• 基于目的和动机描述并且细节无关的控制流模式
• 基于流程编排的控制流模式

对于这四种代码组织方式应该辩证看待，不是说后一种方式就比前一种好，细节无关的控制流就一定优于细节相关的控制流，因为系统复杂度随着代码过程的抽象和拆解增加了，而系统的复杂度的增加不一定就意味着可读性的提升，两者不是正相关关系，而是非线性的：随着系统复杂度的增加可读性会提升，但随着系统复杂度达到一个阈值，复杂度继续增加时可读性反而降低了。

对于简单的方法，过程堆叠无伤大雅；如果一个方法的过程堆叠到了几百行，可以试试对过程基于动机和目的进行过程拆解；如果扩展频率很高，试着用依赖反转对细节进行抽象和封装；如果说系统的业务用例流程化明显，不妨采用流程编排的方式构建系统。

我们对于系统代码组织的方式其实并不固定，但唯一不变的宗旨是对高可读性代码的追求。

以上。