本文檔收集了這些年來我們使用Katana定義的最佳實踐和準則。
項目中定義和共享準則和最佳實踐的優(yōu)點：
1. 當(dāng)做一件事有多種相同的方法時，選擇一種方法并保持一致可以讓每個人立即了解事情是如何工作的，以及如何向應(yīng)用程序或庫引入更改，即使他們并不熟悉代碼庫。
2.?通過遵循共享的模式，我們可以在假設(shè)某些事情是以特定的方式完成的情況下實現(xiàn)工具。
3.?在審查Pull請求時，可以利用指導(dǎo)方針來提供有效的反饋。
4.指南所保留的統(tǒng)一的書面知識，新手們可以領(lǐng)先一步。
Guidelines
使用管理器來封裝邏輯
為了實現(xiàn)代碼的盡可能高的模塊化和可重用性，我們定義了對象，我們稱之為Manager。Manager負責(zé)處理業(yè)務(wù)邏輯的特定部分。例如，健身應(yīng)用可能需要一個登錄管理器、一個計劃生成器，甚至需要更通用的邏輯來執(zhí)行API調(diào)用或跟蹤用戶指標。
依賴容器負責(zé)啟動這些管理器，并將它們暴露給Katana的Side Effects。以下是創(chuàng)建管理器時需要遵循的一些指導(dǎo)方針:?
1.管理者是“被動的”，他們被Katana的?Side Effects所調(diào)用，他們不應(yīng)該以任何方式與武士刀交互(也就是說，他們不能分派)
2.管理器既不能訪問存儲getState，也不能訪問分派
3.管理器不應(yīng)該包含狀態(tài)。函數(shù)執(zhí)行計算所需的所有信息都作為參數(shù)傳遞。
4.管理者可能需要使用其他管理者來實現(xiàn)他們的部分邏輯。我們稱這些下屬管理者為依賴關(guān)系。在初始化管理器時，依賴項應(yīng)該作為參數(shù)傳遞。
在命名約定方面，作為管理器的類應(yīng)該使用Manager后綴命名。舉個具體的例子，Login不是一個有效的管理器名，而LoginManager是。
Event Observers
Katana?提供了一個攔截器，可以用來觀察以下事件:
1.狀態(tài)變化，
2.一個狀態(tài)更新器或一個副作用已經(jīng)被發(fā)送，
3.通知是否已經(jīng)被發(fā)布
有時這是不夠的，我們需要觀察外部世界，并把我們從這個觀察中得到的信息帶回Katana的世界。正如指南(1)中所討論的，管理器是應(yīng)用程序的被動成員，因此它們不能分派。為了解決這個特定的用例，我們引入了event observers。這些類是由依賴容器創(chuàng)建和擁有的，它們唯一且唯一的職責(zé)是監(jiān)聽來自外部世界(例如，F(xiàn)irebase、Websockets等等)的事件，并在這個事件之后在Katana世界中分派一些東西。
雖然分開管理者(Manager)和Observers?可能看起來很奇怪，但這實際上有助于保持每個部分的簡單和一致。對于簡單的情況使用管理器，對于更復(fù)雜的情況使用event observer。
在命名約定方面，作為eventtobservers的類應(yīng)該使用Observer后綴命名。舉個具體的例子，HealthKit不是一個有效的觀察者名，而HealthKitObserver是。
Avoid complex Side Effects(避免復(fù)雜的Side Effects)
在編寫應(yīng)用程序的邏輯時，可能會創(chuàng)建一些高度靈活的Side Effects，這些Side Effects需要多個輸入(即，實現(xiàn)Side Effects的結(jié)構(gòu)有幾個參數(shù))，并根據(jù)這些輸入實現(xiàn)不同的東西。
邏輯被封裝在分組的、可重用的函數(shù)中。這意味著您應(yīng)該盡量使Side Effects簡單，并盡可能接近管理器功能和分派的簡單鏈接。
關(guān)于在另一個Side Effects中發(fā)送一個Side Effects，應(yīng)該盡可能避免，因為這會使整個邏輯更加難以遵循。如果您最終處于這種情況，請嘗試查看您的代碼，并考慮更多地利用管理員。
Leverage encapsulation, modularisation and visibility modifiers(利用封裝、模塊化和可見性修飾符)
應(yīng)用程序是由相互協(xié)作的獨立邏輯部分組成的。在編寫應(yīng)用程序邏輯時，應(yīng)該創(chuàng)建名稱空間(模塊)，反映這些名稱空間中的劃分和組狀態(tài)更新器以及Side Effects。
Documentation
文檔是應(yīng)用程序中非常重要的部分。擁有出色的文檔，其他開發(fā)人員可以輕松進入您的代碼庫，并更快地提高生產(chǎn)力。
上面一條準則定義了邏輯模塊的公共接口的概念。在將該準則應(yīng)用于代碼時，還應(yīng)確保正確記錄了“公共接口”。好的文檔應(yīng)包括：
1.功能/副作用/狀態(tài)更新程序的功能說明
2.參數(shù)說明
3.前提條件（如果有）
4.在編寫代碼時所做的假設(shè)
5.代碼無法輕易推斷出的任何其他信息，這些信息在使用代碼或需要更改代碼時都非常有用
Project files structure (項目文件結(jié)構(gòu))
ProjectName
? ? |-- Logic
? ? ? ? ? |-- AppDependenciesContainer.swift
? ? ? ? ? |-- Home
? ? ? ? ? ? ? ? |-- HomeDispatchable.swift? // side effects and state updaters? ? ? ?
? ? ? ? ? |-- Login
? ? ? ? ? ? ? ? |-- LoginDispatchable.swift // side effects and state updaters
? ? ? ? ? ? ? ? |-- LoginManager.swift
? ? ? ? ? |-- PlanGenerator
? ? ? ? ? ? ? ? |-- PlanGeneratorDispatchable.swift // side effects and state updaters
? ? ? ? ? ? ? ? |-- PlanGeneratorModels.swift
? ? ? ? ? ? ? ? |-- PlanGeneratorManager.swift
? ? |-- UI
? ? ? ? ? |-- Login
? ? ? ? ? ? ? ? |-- LoginVC.swift
? ? ? ? ? ? ? ? |-- LoginView.swift?
? ? ? ? ? |-- Home
? ? ? ? ? ? ? ? |-- HomeVC.swift
? ? ? ? ? ? ? ? |-- HomeView.swift? ?
? ? ? ? ? ? ? ? |-- HomeVM.swift
? ? |-- State
? ? ? ? ? |-- AppState.swift? ?
如您所見，主文件夾包含3個主文件夾：邏輯，UI和狀態(tài)。
邏輯文件夾包含應(yīng)用程序的所有邏輯（狀態(tài)更新程序，副作用和管理器）以及依賴項容器。
即使所有邏輯都在一個文件中（例如Home.swift，它具有與Home視圖控制器嚴格相關(guān)的副作用），也應(yīng)該將該文件包含在文件夾中以方便搜索，而不必猜測它是文件夾還是文件夾。一份文件。總體邏輯應(yīng)包含副作用，狀態(tài)更新程序，管理器和與邏輯相關(guān)的模型。
State文件夾包含該狀態(tài)一部分的所有結(jié)構(gòu)。請注意，遵循?準則（4），您可能希望將狀態(tài)與邏輯共同定位，以對代碼實施某種信息隱藏技術(shù)（即，將某些變量設(shè)為私有或文件私有）。這是唯一允許的例外。
