“整洁架构” 和商家前端的重构之路

,团队归属于后方业务支撑部门，组内的项目都以 pc 中后台应用为主。对比移动端应用，代码库比较庞大，业务逻辑也相对复杂。在持续的迭代过程中，我们发现当前的代码仓库仍然有不少可以优化的点：,21 年前端平台决定技术栈统一迁移到 React 生态，后续平台的基础建设也都围绕 React 展开，这就使得商家使用 Vue 生态做开发的系统面临技术栈迁移的难题，将业务逻辑和 UI 框架节藕变得异常重要。,随着代码量和团队成员的增加，应用里风格迥异的代码也越来越多。为了能够持续迅速的进行迭代，团队急需一套统一的顶层代码架构设计方案。,随着业务变得越来越复杂，在迅速的迭代过程中团队需要频繁地对功能进行回归，因此我们对于自动化单测用例的诉求也变的越来越强烈。,为了完成以上的优化，四组对现有的应用架构做了一次重构，而重构的核心就是整洁架构。,整洁架构 (The clean architecture) 是由 Robert C. Martin (Uncle Bob) 在 2012 年提出的一套代码组织的理念，其核心主要是依据各部分代码作用的不同将其拆分成不同的层次，在各层次间制定了明确的依赖原则，以达到以下目的：,为了实现以上目的，整洁架构把应用划分成了 entities、use cases、interface adapters (MVC、MVP 等)、Web/DB 等至少四层。这套架构除了分层之外，在层与层之间还有一个非常明确的依赖关系，外层的逻辑依赖内层的逻辑。,entities 封装了企业级的业务逻辑和规则。entities 没有什么固定的形式，无论是一个对象也好，是一堆函数的集合也好，唯一的标准就是能够被企业的各个应用所复用。,entities 封装了企业里最通用的一部分逻辑，而应用各自的业务逻辑就都封装在 use case 里面。日常开发中最常见的对于某个模型的 crud 操作就属于 usecase 这一层。,这一层类似于胶水层，需要负责内圈的 entity 和 use case 同外圈的 external interfaces 之间的数据转化。需要把外层服务的数据转化成内层 entity 和 usecase 可以消费的数据，反之亦然。如上面图上画的，这一层有时候可能很简单 (一个转化函数)， 有时候可能复杂到包含一整个 MVC/MVP 的架构。,我们需要依赖的外部服务，第三方框架，以及需要糊的页面 UI 都归属在这一层。这一层完全不感知内圈的任何逻辑，所以无论这一层怎么变 (ui 变化)，都不应该影响到内圈的应用层逻辑 (usecase) 和企业级逻辑 (entity)。,在整洁架构的原始设计中，并不是强制一定只能写这么四层，根据业务的需要还可以拆分的更细。不过无论怎么拆，都需要遵守前面提到的从外至内的依赖原则。即 entity 作为企业级的通用逻辑，不能依赖任何模块。而外层的 ui 等则可以使用 usecase、entity。,前面介绍了当前代码库目前的一些具体问题，而整洁架构的理念正好可以帮助我们优化代码可维护性。,作为前端，我们的业务逻辑不应该依赖视图层 (ui 框架及其生态)，同时应当保证业务逻辑的独立性和可复用性 (usecase & entity)。最后，作为数据驱动的端应用，要保证应用视图渲染和业务逻辑等不受数据变动的影响 (adapter & entity)。,根据以上的思考，我们对 “整洁架构” 做了如下落地。,对于前端应用来说，在 entity 层我们只需要将服务端的生数据做一层简单的抽象，生成一个贫血对象给后续的渲染和交互逻辑使用。,以上是商家后台订单模型的 entity 工厂函数，工厂主要负责对服务端返回的生数据进行加工处理，让其满足渲染层和逻辑层的要求。除了抽象数据之外，可以看到在 entity 工厂还对数据进行了校验，将脏数据、不符合预期的数据全部处理掉或者进行兜底 (具体操作要看业务场景)。,有一点需要注意的是，在设计 entity 的时候 (尤其是基础 entity) 需要考虑复用性。举个例子，在上面 orderEntity 的基础上，我们通过简单的组合就可以生成一个虚拟商品订单 entity：,如此一来，我们就通过 entity 层达到了两个目的：,usecase 这一层即是围绕 entity 展开的一系列 crud 操作，以及为了页面渲染做的一些联动 (通过 ui store 实现)。由于当前架构的原因 (没有 bff 层)，usecase 还可能承担部分微服务串联的工作。,举个例子，商家后台订单页面在渲染前有一堆准备逻辑：,现在大致的实现是：,我们能看到 7-15、24-125 行对 this.subType 进行了赋值。但由于我们无法确定 20 行的函数是否也对 this.subType 进行了赋值，所以光凭 mounted 函数的代码我们并不能完全确定 subType 的值究竟是什么，需要跳转到 getAllLogisticsCarrier 函数确认。这段代码在这里已经做了简化，实际的代码像 getAllLogisticsCarrier 这样的调用还有好几个，要想搞清楚逻辑就得把所有函数全看一遍，代码的可读性一般。同时，由于函数都封装在 ui 组件里，因此要想给函数覆盖单测的话也需要一些改造。,为了解决问题，我们将这部分逻辑都拆分到 usecase 层：,首先，可以看到所有 usecase 一定是一个纯函数，不会存在副作用的问题。,其次，prepareOrderPage usecase 专门为订单页定制，拆分后一眼就能看出来订单页的准备工作需要干决定选中的 tab 和拉取供应商列表两件事情。而另一个拆分出来的 queryLogisticsCarriers 则是封装了商家后台跨境、国内两种逻辑，后续无论跨境还是国内的逻辑如何变更，其影响范围被限制在了 queryLogisticsCarriers 函数，我们需要对其进行功能回归；而对于 prepareOrderPage 来说，queryLogisticsCarriers 只是 () => Promise<{ carriers: ICarrires }> 的一个实现而已，其内部调用 queryLogisticsCarriers 的逻辑完全不受影响，不需要进行回归。,最后，而由于我们做了依赖倒置，我们可以非常容易的给 usecase 覆盖单测：,单测除了进行功能回归之外，它的描述 (demo 里使用了 Given-When-Then 的格式，由于篇幅的原因，关于单测的细节在后续的文章再进行介绍) 对于了解代码的逻辑非常非常非常有帮助。由于单测和代码逻辑强行绑定的缘故，我们甚至可以将单测描述当成一份实时更新的业务文档。,除了方便写单测之外，在通过 usecase 拆分完成之后，ui 组件真正成为了只负责 “ui” 和监听用户交互行为的组件，这为我们后续的 React 技术栈迁移奠定了基础；通过 usecase 我们也实现了很不错的模块化，对于使用比较多的一些 entity，他的 crud 操作可以通过独立的 usecase 具备了在多个页面甚至应用间复用的能力。,上面 usecase 例子中的 fetchAllLogisticsCarrier 就是一个 adapter，这一层起到的作用是将外部系统返回的数据转化成 entity，并以一种统一的数据格式返回回来。,这一层很核心的一点即是可以依赖 entity 的工厂函数，将接口返回的数据转化成前端自己设计的模型数据，保证流入 usecase 和 ui 层的数据都是经过处理的 “干净数据”。除此之外，通常在这一层我们会用一种固定的数据格式返回数据，比如例子中的 {success: boolean, data?: any}。这样做主要是为了抹平对接多个系统带来的差异性，同时减少多人协作时的沟通成本。,通过 Adapter + entity 的组合，我们基本形成了前端应用和后端服务之间的防腐层，使得前端可以在完全不清楚接口定义的情况下完成 ui 渲染、usecase 等逻辑的开发。在服务端产出定义后，前端只需要将实际接口返回适配到自己定义的模型 (通过 entity) 即可。这一点对前端的测试周提效非常非常非常重要，因为防腐层的存在，我们可以在测试周完成需求评审之后根据 prd 的内容设计出业务模型，并以此完成需求开发，在真正进入研发周后只需要和服务端对接完成 adapter 这一层的适配即可。,在实践过程中，我们发现在对接同一个系统的时候 (对商家来说就是 stark 服务) 各个 adapter 对于异常的处理几乎一模一样 (上述的 11-15 行)，我们可以通过 Proxy 对其进行抽离实现复用。当然，后续我们也完全有机会根据接口定义来自动生成 adapter。,在经过前面的拆分之后，无论咱们的 UI 层用 React 还是 Vue 来写，要做的工作都很简单了：,由于 entity 已经做了过滤和适配处理，所以在 ui 层我们可以放心大胆的用，不需要再写一堆莫名其妙的判断逻辑。另外由于 entity 是由前端自己定义的模型，无论开发过程中服务端接口怎么变，受影响的都只有 entity 工厂函数，ui 层不会受到影响。,最后，在 ui 层我们还剩下令人头痛的技术栈迁移问题。整个团队目前使用 vue 的项目有 10 个，按迭代频率和项目规模迁移的方案可以分为两类：,通过整洁架构我们形成了统一的编码规范，在前端应用标准化的道路上迈下了坚实的一步。可以预见的是整个标准化的过程会非常漫长，我们会陆续往标准中增加新的规范使其更加完善，短期内在规划中的有：