“整潔架構(gòu)”和商家前端的重構(gòu)之路

原創(chuàng) 陳子煜 得物技術(shù)

1. 背景

團(tuán)隊歸屬于后方業(yè)務(wù)支撐部門,組內(nèi)的項目都以pc中后臺應(yīng)用為主。對比移動端應(yīng)用,代碼庫比較龐大,業(yè)務(wù)邏輯也相對復(fù)雜。在持續(xù)的迭代過程中,我們發(fā)現(xiàn)當(dāng)前的代碼倉庫仍然有不少可以優(yōu)化的點:

  • 可以減弱對ui框架的依賴

21年前端平臺決定技術(shù)棧統(tǒng)一遷移到React生態(tài),后續(xù)平臺的基礎(chǔ)建設(shè)也都圍繞React展開,這就使得商家使用Vue生態(tài)做開發(fā)的系統(tǒng)面臨技術(shù)棧遷移的難題,將業(yè)務(wù)邏輯和UI框架節(jié)藕變得異常重要。

  • 代碼風(fēng)格可以更加統(tǒng)一

隨著代碼量和團(tuán)隊成員的增加,應(yīng)用里風(fēng)格迥異的代碼也越來越多。為了能夠持續(xù)迅速的進(jìn)行迭代,團(tuán)隊急需一套統(tǒng)一的頂層代碼架構(gòu)設(shè)計方案。

  • 可以集成自動化測試用例

隨著業(yè)務(wù)變得越來越復(fù)雜,在迅速的迭代過程中團(tuán)隊需要頻繁地對功能進(jìn)行回歸,因此我們對于自動化單測用例的訴求也變的越來越強(qiáng)烈。

為了完成以上的優(yōu)化,四組對現(xiàn)有的應(yīng)用架構(gòu)做了一次重構(gòu),而重構(gòu)的核心就是整潔架構(gòu)。

2. 整潔架構(gòu)(The Clean Architecture)

整潔架構(gòu)(The clean architecture)是由 Robert C. Martin (Uncle Bob)在2012年提出的一套代碼組織的理念,其核心主要是依據(jù)各部分代碼作用的不同將其拆分成不同的層次,在各層次間制定了明確的依賴原則,以達(dá)到以下目的:

  1. 與框架無關(guān):無論是前端代碼還是服務(wù)端代碼,其邏輯本身都應(yīng)該是獨立的,不應(yīng)該依賴于某一個第三方框架或工具庫。一套獨立的代碼可以把第三方框架等作為工具使用。
  2. 可測試:代碼中的業(yè)務(wù)邏輯可以在不依賴ui、數(shù)據(jù)庫、服務(wù)器的情況下進(jìn)行測試
  3. 和ui無關(guān):代碼中的業(yè)務(wù)邏輯不應(yīng)該和ui做強(qiáng)綁定。比如把一個web應(yīng)用切換成桌面應(yīng)用,業(yè)務(wù)邏輯不應(yīng)該受到影響。
  4. 和數(shù)據(jù)庫無關(guān):無論數(shù)據(jù)庫用的是mysql還是mongodb,無論其怎么變,都不該影響到業(yè)務(wù)邏輯。
  5. 和外部服務(wù)無關(guān):無論外部服務(wù)怎么變,都不影響到使用該服務(wù)的業(yè)務(wù)邏輯。


    image.png

為了實現(xiàn)以上目的,整潔架構(gòu)把應(yīng)用劃分成了entities、use cases、interface adapters(MVC、MVP等)、Web/DB等至少四層。這套架構(gòu)除了分層之外,在層與層之間還有一個非常明確的依賴關(guān)系,外層的邏輯依賴內(nèi)層的邏輯。

Entity

entities封裝了企業(yè)級的業(yè)務(wù)邏輯和規(guī)則。entities沒有什么固定的形式,無論是一個對象也好,是一堆函數(shù)的集合也好,唯一的標(biāo)準(zhǔn)就是能夠被企業(yè)的各個應(yīng)用所復(fù)用。

Use Case

entities封裝了企業(yè)里最通用的一部分邏輯,而應(yīng)用各自的業(yè)務(wù)邏輯就都封裝在use case里面。日常開發(fā)中最常見的對于某個模型的crud操作就屬于usecase這一層。

Interface Adapter

這一層類似于膠水層,需要負(fù)責(zé)內(nèi)圈的entity和use case同外圈的external interfaces之間的數(shù)據(jù)轉(zhuǎn)化。需要把外層服務(wù)的數(shù)據(jù)轉(zhuǎn)化成內(nèi)層entity和usecase可以消費的數(shù)據(jù),反之亦然。如上面圖上畫的,這一層有時候可能很簡單(一個轉(zhuǎn)化函數(shù)), 有時候可能復(fù)雜到包含一整個MVC/MVP的架構(gòu)。

External Interfaces

我們需要依賴的外部服務(wù),第三方框架,以及需要糊的頁面UI都?xì)w屬在這一層。這一層完全不感知內(nèi)圈的任何邏輯,所以無論這一層怎么變(ui變化),都不應(yīng)該影響到內(nèi)圈的應(yīng)用層邏輯(usecase)和企業(yè)級邏輯(entity)。

依賴原則

在整潔架構(gòu)的原始設(shè)計中,并不是強(qiáng)制一定只能寫這么四層,根據(jù)業(yè)務(wù)的需要還可以拆分的更細(xì)。不過無論怎么拆,都需要遵守前面提到的從外至內(nèi)的依賴原則。即entity作為企業(yè)級的通用邏輯,不能依賴任何模塊。而外層的ui等則可以使用usecase、entity。

3. 重構(gòu)

前面介紹了當(dāng)前代碼庫目前的一些具體問題,而整潔架構(gòu)的理念正好可以幫助我們優(yōu)化代碼可維護(hù)性。

作為前端,我們的業(yè)務(wù)邏輯不應(yīng)該依賴視圖層(ui框架及其生態(tài)),同時應(yīng)當(dāng)保證業(yè)務(wù)邏輯的獨立性和可復(fù)用性(usecase & entity)。最后,作為數(shù)據(jù)驅(qū)動的端應(yīng)用,要保證應(yīng)用視圖渲染和業(yè)務(wù)邏輯等不受數(shù)據(jù)變動的影響(adapter & entity)。

根據(jù)以上的思考,我們對“整潔架構(gòu)”做了如下落地。

Entities

對于前端應(yīng)用來說,在entity層我們只需要將服務(wù)端的生數(shù)據(jù)做一層簡單的抽象,生成一個貧血對象給后續(xù)的渲染和交互邏輯使用。


interface IRawOrder {
  amount: number
  barCode: string
  orderNo: string
  orderType: string
  skuId: number
  deliveryTime: number
  orderTime: number
  productImg: string
  status: number
}

export default function buildMakeOrder({
  formatTimestamp,
  formatImageUrl,
}: {
  formatTimestamp: (timestamp: number, format?: string) => string
  formatImageUrl: (
    image: string,
    config?: { width: number; height: number },
  ) => string
}) {
  return function makeOrder(raw?: IRawOrder) {
    if (!raw || !raw.orderNo) {
       Monitor.warn('臟數(shù)據(jù)')
       return null;
    }
    return {
      amount: raw.amount,
      barCode: raw.barCode,
      orderNo: raw.orderNo,
      orderType: raw.orderType,
      skuId: raw.skuId,
      status: raw.status,
      statusDescription: selectStatusDescription(raw.status),
      deliveryTime: formatTimestamp(raw.deliveryTime),
      orderTime: formatTimestamp(raw.orderTime),
      productImg: formatImageUrl(raw.productImg),
    }
  }
}

function selectStatusDescription(status: number): string {
  switch (status) {
    case 0:
      return '待支付'
    case 1:
      return '待發(fā)貨'
    case 2:
      return '待收貨'
    case 3:
      return '已完成'
    default:
      return ''
  }
}

以上是商家后臺訂單模型的entity工廠函數(shù),工廠主要負(fù)責(zé)對服務(wù)端返回的生數(shù)據(jù)進(jìn)行加工處理,讓其滿足渲染層和邏輯層的要求。除了抽象數(shù)據(jù)之外,可以看到在entity工廠還對數(shù)據(jù)進(jìn)行了校驗,將臟數(shù)據(jù)、不符合預(yù)期的數(shù)據(jù)全部處理掉或者進(jìn)行兜底(具體操作要看業(yè)務(wù)場景)。

有一點需要注意的是,在設(shè)計entity的時候(尤其是基礎(chǔ)entity)需要考慮復(fù)用性。舉個例子,在上面orderEntity的基礎(chǔ)上,我們通過簡單的組合就可以生成一個虛擬商品訂單entity:

import { makeOrder } from '@/entities'

export default function buildMakeVirtualOrder() {
  return function makeVirtualOrder(raw?: IRawPresaleOrder) {
     const order = makeOrder(raw)

     if(! order || !raw.virtualOrderType) {
         Monitor.warn('臟數(shù)據(jù)')
         return null
     }

     return {
         ...order,
         virtualOrderType: raw.virtualOrderType,
         virtualOrderDesc: selectVirtualOrderDesc(raw.virtualOrderType)
     }
  }
}

如此一來,我們就通過entity層達(dá)到了2個目的:

  1. 把前端的邏輯和服務(wù)端接口數(shù)據(jù)隔離開,無論服務(wù)端怎么變,前端后續(xù)的渲染、業(yè)務(wù)代碼不需要變,我們只需要變更entitiy工廠函數(shù);并且經(jīng)過entity層處理過后,所有流入后續(xù)渲染&交互邏輯的數(shù)據(jù)都是可靠的;對于部分異常數(shù)據(jù),前端應(yīng)用可以第一時間發(fā)現(xiàn)并報警。
  2. 通過對業(yè)務(wù)模型進(jìn)行抽象,實現(xiàn)了模塊間的組合、復(fù)用。另外,抽象出的entity對代碼的維護(hù)性也有非常大的幫助,開發(fā)者可以非常直觀的知道所使用的entity所包含的所有字段。

Usecase

usecase這一層即是圍繞entity展開的一系列crud操作,以及為了頁面渲染做的一些聯(lián)動(通過ui store實現(xiàn))。由于當(dāng)前架構(gòu)的原因(沒有bff層),usecase還可能承擔(dān)部分微服務(wù)串聯(lián)的工作。

舉個例子,商家后臺訂單頁面在渲染前有一堆準(zhǔn)備邏輯:

  1. 根據(jù)route的query參數(shù)以及一些商家類型參數(shù)來決定默認(rèn)選中哪個tab

  2. 根據(jù)是國內(nèi)商家還是境外商家,調(diào)用對應(yīng)的供應(yīng)商接口來更新供應(yīng)商下拉框

現(xiàn)在大致的實現(xiàn)是:

{
    mounted() {
        const { subType } = this.$route.query
        /*
            7-15行處理了幾種分支鏈路場景下對subType的賦值問題
        */
        if (Number(subType) === 0 || subType) {
          this.subType = subType.toString()
        } else {
          if (this.user.merchant.typeId === 4) {
            this.subType = this.tabType.cross
          } else {
            this.subType = this.tabType.ordinarySpot
          }
        }

        /*
            getAllLogisticsCarrier有沒有對subType賦值呢?光看這段代碼完全不確定
        */
        this.getAllLogisticsCarrier()
        /*
            21-22行又多出來一個分支需要對subType進(jìn)行再次賦值
        */
        if (this.isPersonPermission && !this.crossUser) {
          this.subType = this.tabType.warehouse
        }
    },

    getAllLogisticsCarrier() {
        let getCarrier = API.getAllLogisticsCarrier
        if (this.crossUser) {
          getCarrier = API.getOrderShipAllLogistics
        }

        getCarrier({}).then(res => {
          if (res.code === 200) {
            const options = []

            .......... // 給options賦值

            this.options2 = options

          }
        })
    },
}

我們能看到7-15、24-125行對this.subType進(jìn)行了賦值。但由于我們無法確定20行的函數(shù)是否也對this.subType進(jìn)行了賦值,所以光憑mounted函數(shù)的代碼我們并不能完全確定subType的值究竟是什么,需要跳轉(zhuǎn)到getAllLogisticsCarrier函數(shù)確認(rèn)。這段代碼在這里已經(jīng)做了簡化,實際的代碼像getAllLogisticsCarrier這樣的調(diào)用還有好幾個,要想搞清楚邏輯就得把所有函數(shù)全看一遍,代碼的可讀性一般。同時,由于函數(shù)都封裝在ui組件里,因此要想給函數(shù)覆蓋單測的話也需要一些改造。

為了解決問題,我們將這部分邏輯都拆分到usecase層:

// prepare-order-page.ts
import { tabType } from '@/constants'

interface IParams {
  subType?: number
  merchantType: number
  isCrossUser: boolean
  isPersonPermission: boolean
}

/*
    做依賴倒置主要是為了方便后續(xù)的單測和復(fù)用
*/
export default function buildPrepareOrderPage({
  queryLogisticsCarriers,
}: {
  queryLogisticsCarriers: () => Promise<{ carriers: ICarrires }>
}) {
  return async function prepareOrderPage(params: IParams) {
    const activeTab = selectActiveTab(params)

    const { carriers } = queryLogisticsCarriers(params.isCrossUser)

    return {
      activeTab,
      carriers,
    }
  }
}

function selectActiveTab({
  subType,
  isCrossUser,
  isPersonPermission,
  merchantType,
}: IParams) {
  if (isPersonPermission && !isCrossUser) {
    return tabType.warehouse
  }

  if (Number(subType) === 0 || subType) {
    return subType.toString()
  }

  if (merchantType === 4) {
    return tabType.cross
  }

  return tabType.ordinarySpot
}
// query-logistics-carriers
export default function buildQueryLogisticsCarriers({
  fetchAllLogisticsCarrier,
  fetchOrderShipAllLogistics,
}: {
  fetchAllLogisticsCarrier: () => Promise<{ data: {carriers: ICarrires }}>
  fetchOrderShipAllLogistics: () => Promise<{ data: {carriers: ICarrires }}>
}) {
  return async function queryLogisticsCarriers(isCrossUser: boolean) {
    if (isCrossUser) {
      return fetchAllLogisticsCarrier()
    }

    return fetchOrderShipAllLogistics()
  }
}

// index.vue
{
    mounted() {
        const {activeTab, carriers} = prepareOrderPage(params)

        this.subType = activeTab;
        this.options = buildCarrierOptions(carriers) // 將carries轉(zhuǎn)換成下拉框option
    }
}

首先,可以看到所有usecase一定是一個純函數(shù),不會存在副作用的問題。

其次,prepareOrderPage usecase專門為訂單頁定制,拆分后一眼就能看出來訂單頁的準(zhǔn)備工作需要干決定選中的tab和拉取供應(yīng)商列表兩件事情。而另一個拆分出來的queryLogisticsCarriers則是封裝了商家后臺跨境、國內(nèi)兩種邏輯,后續(xù)無論跨境還是國內(nèi)的邏輯如何變更,其影響范圍被限制在了queryLogisticsCarriers函數(shù),我們需要對其進(jìn)行功能回歸;而對于prepareOrderPage來說,queryLogisticsCarriers只是() => Promise<{ carriers: ICarrires }>的一個實現(xiàn)而已,其內(nèi)部調(diào)用queryLogisticsCarriers的邏輯完全不受影響,不需要進(jìn)行回歸。

最后,而由于我們做了依賴倒置,我們可以非常容易的給usecase覆蓋單測:


import buildPrepareOrderPage from '@/utils/create-goods';

function init() {
  const queryLogisticsCarriers = jest.fn();

  const prepareOrderPage = buildPrepareOrderPage({ queryLogisticsCarriers });

  return {
    prepareOrderPage,
    queryLogisticsCarriers,
  };
}

describe('訂單頁準(zhǔn)備邏輯', () => {
  it('當(dāng)用戶是國內(nèi)商家且在入倉白名單上,在打開訂單頁時,默認(rèn)打開入倉tab', async () => {
    const { prepareOrderPage } = init();
    const params = {
        merchantType: 2
        isCrossUser: false
        isPersonPermission: true
    }

    const { activeTab } = await prepareOrderPage(params)

    expect(activeTab).toEqual({tabType.warehouse});
  });

   it('當(dāng)用戶是跨境商家,在打開訂單頁時,默認(rèn)打開跨境tab', async () => {
    const { prepareOrderPage } = init();
    const params = {
        merchantType: 4
        isCrossUser: true
        isPersonPermission: true
    }

    const { activeTab } = await prepareOrderPage(params)

    expect(activeTab).toEqual({tabType.cross});
  });

  ......
});

單測除了進(jìn)行功能回歸之外,它的描述(demo里使用了Given-When-Then的格式,由于篇幅的原因,關(guān)于單測的細(xì)節(jié)在后續(xù)的文章再進(jìn)行介紹)對于了解代碼的邏輯非常非常非常有幫助。由于單測和代碼邏輯強(qiáng)行綁定的緣故,我們甚至可以將單測描述當(dāng)成一份實時更新的業(yè)務(wù)文檔。

除了方便寫單測之外,在通過usecase拆分完成之后,ui組件真正成為了只負(fù)責(zé)“ui”和監(jiān)聽用戶交互行為的組件,這為我們后續(xù)的React技術(shù)棧遷移奠定了基礎(chǔ);通過usecase我們也實現(xiàn)了很不錯的模塊化,對于使用比較多的一些entity,他的crud操作可以通過獨立的usecase具備了在多個頁面甚至應(yīng)用間復(fù)用的能力。

Adapter

上面usecase例子中的fetchAllLogisticsCarrier就是一個adapter,這一層起到的作用是將外部系統(tǒng)返回的數(shù)據(jù)轉(zhuǎn)化成entity,并以一種統(tǒng)一的數(shù)據(jù)格式返回回來。

這一層很核心的一點即是可以依賴entity的工廠函數(shù),將接口返回的數(shù)據(jù)轉(zhuǎn)化成前端自己設(shè)計的模型數(shù)據(jù),保證流入usecase和ui層的數(shù)據(jù)都是經(jīng)過處理的“干凈數(shù)據(jù)”。除此之外,通常在這一層我們會用一種固定的數(shù)據(jù)格式返回數(shù)據(jù),比如例子中的 {success: boolean, data?: any}。這樣做主要是為了抹平對接多個系統(tǒng)帶來的差異性,同時減少多人協(xié)作時的溝通成本。


type Request = (url: string, params: Record<string, any>) => Promise<any>;
import makeCarrier from '@/entities/makeCarrier'


export default function buildFetchAllLogisticsCarrier({request}: {request: Request}) {
  return async function fetchAllLogisticsCarrier() {
    // TODO: 異常處理
    const response = await request('/fakeapi', info)

    if (!response || !resposne.code === 200) {
        return { 
            success: false
        }
    }

    return {
      success: true,
      data: {
          carriers: response.list?.map(makeCarrier)
      }
    }
  }
}

通過Adapter + entity的組合,我們基本形成了前端應(yīng)用和后端服務(wù)之間的防腐層,使得前端可以在完全不清楚接口定義的情況下完成ui渲染、usecase等邏輯的開發(fā)。在服務(wù)端產(chǎn)出定義后,前端只需要將實際接口返回適配到自己定義的模型(通過entity)即可。這一點對前端的測試周提效非常非常非常重要,因為防腐層的存在,我們可以在測試周完成需求評審之后根據(jù)prd的內(nèi)容設(shè)計出業(yè)務(wù)模型,并以此完成需求開發(fā),在真正進(jìn)入研發(fā)周后只需要和服務(wù)端對接完成adapter這一層的適配即可。

在實踐過程中,我們發(fā)現(xiàn)在對接同一個系統(tǒng)的時候(對商家來說就是stark服務(wù))各個adapter對于異常的處理幾乎一模一樣(上述的11-15行),我們可以通過Proxy對其進(jìn)行抽離實現(xiàn)復(fù)用。當(dāng)然,后續(xù)我們也完全有機(jī)會根據(jù)接口定義來自動生成adapter。

UI

在經(jīng)過前面的拆分之后,無論咱們的UI層用React還是Vue來寫,要做的工作都很簡單了:

  1. 監(jiān)聽交互事件并調(diào)用對應(yīng)的usecase來進(jìn)行響應(yīng)

  2. 通過usecase來獲取entity數(shù)據(jù)進(jìn)行渲染

由于entity已經(jīng)做了過濾和適配處理,所以在ui層我們可以放心大膽的用,不需要再寫一堆莫名其妙的判斷邏輯。另外由于entity是由前端自己定義的模型,無論開發(fā)過程中服務(wù)端接口怎么變,受影響的都只有entity工廠函數(shù),ui層不會受到影響。

最后,在ui層我們還剩下令人頭痛的技術(shù)棧遷移問題。整個團(tuán)隊目前使用vue的項目有10個,按迭代頻率和項目規(guī)模遷移的方案可以分為兩類:

  • 迭代頻繁的大應(yīng)用:主要包括代碼行數(shù)較多、邏輯較為復(fù)雜的幾個中大型應(yīng)用。這些應(yīng)用想要一把梭直接完成遷移成本極高,但同時每個迭代又有相當(dāng)?shù)男枨蟆;谶@種情況,對于這三個應(yīng)用我們采取了微前端的方式進(jìn)行遷移。每個應(yīng)用分別起一個對應(yīng)的React應(yīng)用,對于新頁面以及部分邏輯已經(jīng)完全和ui解藕遷移成本不高的業(yè)務(wù),都由React應(yīng)用來承接,最后通過module federation的方式實現(xiàn)融合。
  • 迭代不頻繁的小應(yīng)用:剩下的應(yīng)用均是復(fù)雜度不高的小應(yīng)用,這部分應(yīng)用迭代的需求不多,以維護(hù)為主。因此我們的方案是對現(xiàn)有邏輯進(jìn)行整潔架構(gòu)重構(gòu),在ui和邏輯分層之后直接對ui層進(jìn)行替換完成遷移。

4. 后續(xù)

通過整潔架構(gòu)我們形成了統(tǒng)一的編碼規(guī)范,在前端應(yīng)用標(biāo)準(zhǔn)化的道路上邁下了堅實的一步??梢灶A(yù)見的是整個標(biāo)準(zhǔn)化的過程會非常漫長,我們會陸續(xù)往標(biāo)準(zhǔn)中增加新的規(guī)范使其更加完善,短期內(nèi)在規(guī)劃中的有:

  • 單測即文檔:上面提到了usecase通過依賴倒置來配合單測落地,后續(xù)團(tuán)隊期望將一些業(yè)務(wù)邏輯的實現(xiàn)細(xì)則通過單測的描述來進(jìn)行沉淀,解決業(yè)務(wù)文檔實時性的問題。
  • 完善監(jiān)控體系:前端常遇到的3種異常包括 代碼邏輯異常、性能瓶頸(渲染卡頓、內(nèi)存不足等)、數(shù)據(jù)導(dǎo)致異常。對于數(shù)據(jù)異常,我們可以在entity層映射的過程中加入對異常數(shù)據(jù)的埋點上報來填補(bǔ)目前監(jiān)控的空白。(代碼邏輯異常通過sentry已經(jīng)監(jiān)控,性能監(jiān)控對于中后臺應(yīng)用不需要)

后續(xù)在標(biāo)準(zhǔn)逐漸穩(wěn)定之后,我們也期望基于穩(wěn)定的規(guī)范進(jìn)行一些工程化的實踐(比如根據(jù)mooncake文檔自動生成adapter層、基于usecase實現(xiàn)功能開關(guān)等),敬請期待。

參考鏈接:

The Clean Architecturehttps://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html

Module Federation:https://webpack.js.org/concepts/module-federation/

Anti-corruption Layer patternhttps://docs.microsoft.com/en-us/azure/architecture/patterns/anti-corruption-layer

*文/陳子煜

關(guān)注得物技術(shù),每周一三五晚18:30更新技術(shù)干貨
要是覺得文章對你有幫助的話,歡迎評論轉(zhuǎn)發(fā)點贊~

?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成,瀏覽時請結(jié)合常識與多方信息審慎甄別。
平臺聲明:文章內(nèi)容(如有圖片或視頻亦包括在內(nèi))由作者上傳并發(fā)布,文章內(nèi)容僅代表作者本人觀點,簡書系信息發(fā)布平臺,僅提供信息存儲服務(wù)。

相關(guān)閱讀更多精彩內(nèi)容

友情鏈接更多精彩內(nèi)容