一、準備
今天是2024年1月24日,雖然天氣比較寒冷,但是我的精神狀態感覺越來越好,於是就把kbnet整體架構中的dapi程序架構弄出來了,至此,kbnet程序架構整理完畢。
因爲前些時日微軟已經正式發佈.net8,所以dapi程序架構也升級了上來,從.net6升級到.net8對於asp.net core webapi項目幾乎屬於無感式升級,所以不用有過多擔心。
廢話不多說,如下繼續......
二、程序架構
三、程序架構信息
一、解決方案 1.方案名稱:kbnet代指產品或項目名稱,xaas表示解決方案爲服務程序(如saas\paas),dapi表示爲服務程序中的數據服務,d即data首字母縮寫。 2.隸屬關係:kbnet.xaas.dapi位於view->papi->dapi末尾位置,是數據存儲的核心節點,專職負責與關係型數據庫的交互。 3.介紹信息: a.本程序主要負責業務數據的持久化存儲、以及增刪改查操作,不涉及業務層面的邏輯處理。 b.本程序基於kbgress進行設計研發,且結構清晰,因此僅需按照程序架構、項目信息和編碼規範,便可以實現高效能的程序開發。 c.本程序架構以提供webapi服務爲基準,軟件即服務。 d.本程序可以訪問不同的數據庫實例,但僅限於對單個數據庫實例進行交互作業,不允許跨多個數據庫實例操作。 e.... 二、項目信息 1.基礎項目 1.1.kbnet.xaas.dapi a.項目簡介:該項目是啓動項目,主要負責程序的初始化工作,以及API的定義、使用、權鑑、轉發和管理等。 b.項目結構:無 c.規則規範: 1)在項目中不允許編寫業務相關代碼。 2)程序初始化相關功能應在kbnet.xaas.services項目中實現,確保本項目作爲啓動項目的純粹性。 3)程序初始化不僅包含自身的初始化,也包含kbnet.xaas.services項目對接kbgress功能的初始化。 4)Controllers文件夾中所有的類,必須以xxxxController進行命名。 5)xxxxController類中的方法僅允許對參數進行驗證,不允許處理業務邏輯運算。 7)權鑑和安全功能,首先由中間件攔截請求,通過kbnet.xaas.services項目轉發kbgress.client,最終由kbgress.client實現,並返回結果。 d.引用關係: 1.類庫引用: 1)Newtonsoft.Json 2.項目引用: 1)kbnet.xaas.models 2)kbnet.xaas.common 3)kbnet.xaas.services 4)kbnet.xaas.xxxx.core.repositories 5)kbnet.xaas.xxxx.models.inner 6)kbnet.xaas.xxxx.models.data e.其他信息:無 1.2.kbnet.xaas.common a.項目簡介:該項目是通用項目,主要定義一些功能性的類,比如工具類、網絡類、本地類、驗證類等通用型的類。 b.項目結構:無 c.規則規範: 1)不允許在此類中定義業務相關的功能類。 d.引用關係: 1.類庫引用: 1)Newtonsoft.Json 2.項目引用: 1)kbnet.xaas.models e.其他信息:無 1.3.kbnet.xaas.services a.項目簡介:該項目是基礎服務項目,一方面負責爲xxxx項目提供基礎服務,另一方面負責與kbgress對接,即通過與kbgress對接實現xxxx項目所需的基礎服務。 b.項目結構: 1)項目引用的SDK由“Microsoft.NET.Sdk”改爲“Microsoft.NET.Sdk.Web”。注意,此次項目輸出類型會變成“控制檯應用程序”,應該回“類庫”。 c.規則規範: 1)此項目負責中間件的定義與實現。 2)此項目負責令牌、權限、安全的驗證。 3)此項目管理請求流量的控制與統計。 4)此項目管理配置文件的解讀與更新。 5)此項目管理請求的定義和維護、以及分發和轉發。 6)此項目管理分佈式計算與存儲的接口定義和調用。 7)此項目負責日誌和消息記錄與發送。 8)此項目負責運維狀態的記錄和通信。 9)此項目負責服務治理相關的事項。 d.引用關係: 1.類庫引用: 1)Newtonsoft.Json 2.項目引用: 1)kbnet.xaas.models 2)kbnet.xaas.common e.其他信息:無 1.4.kbnet.xaas.models a.項目簡介:該項目是基礎模型項目,主要定義通用的基礎模型類,因此它不引用任何項目和第三方類庫,僅提供基礎模型類給其他項目引用和使用。 b.項目結構:無 c.規則規範: 1)不允許引用其他項目和第三方類庫。 d.引用關係: 1.類庫引用:無 2.項目引用:無 e.其他信息:無 1.5.kbnet.xaas.tests a.項目簡介:該項目是測試項目,主要用於編寫業務功能的測試類和執行順序。測試至關重要,既是對自己負責,也是對協同者負責。 b.項目結構: 1)本項目是一個控制檯程序,所有測試代碼均自己動手編碼,不依賴任何第三方測試類庫和工具。 c.規則規範: 1)測試以目錄劃分順序、層級和範圍,以目錄名稱創建並命名xxxxTest類,且繼承抽象類BaseTest,實現抽象方法ExecTest。 2)Program啓動類,調用以項目命名的頂級xxxxTest類的ExecTest方法,通過層級關係實現所有xxxxTest類的測試。 3)已經測試過,不需要再測試的xxxxTest類,只需要在上級的ExecTest方法中註釋掉即可,或者把自身的ExecTest方法中的內容註釋掉。 4)多個xxxxTest類之間的執行順序,由程序員依據業務實際需求自行控制。 5)爲避免給數據庫留下無用的測試數據,應本着測試結束後,數據庫中無測試數據爲原則。 d.引用關係: 1.類庫引用: 1)Newtonsoft.Json 2.項目引用: 1)kbnet.xaas.models 2)kbnet.xaas.common 3)kbnet.xaas.services 4)kbnet.xaas.xxxx.core.repositories 5)kbnet.xaas.xxxx.core.services 6)kbnet.xaas.xxxx.models.data 7)kbnet.xaas.xxxx.models.inner 8)kbnet.xaas.xxxx.api.cache 9)kbnet.xaas.xxxx.api.local e.其他信息:無 2.模塊項目 2.1.Core項目 2.1.1.kbnet.xaas.xxxx.core.repositories a.項目簡介:數據倉庫項目,主要以面向對象的思維負責數據的讀寫與運算,它位於業務層(papi)與數據層中間,起着連接與隔離的雙層含義。 b.項目結構:無 c.規則規範: 1)所有類均以xxxxRepository形式命名,即以Repository結尾。 2)以xxxx命名的類文件是業務對象,該文件中編寫的方法均與業務對象xxxx直接相關,與數據庫無關。實際文件中的方法會包含多個輔助對象的方法,此時方法命名應注意區分,通常採用“輔助對象名_方法名”的形式。 3)倘若對數據庫涉及大於一次的增加、刪除和修改操作的方法,需要把業務邏輯控制留在本項目中,不允許推到services項目中實現。並且需要開啓TrasactionScope事務控制,確保ACID原則。 4)利用partial關鍵字,在xxxxRepository類文件中,定義相同名稱和繼承關係的兩個xxxxRepository類代碼塊,使用partial修飾,實現在一個塊中寫公有方法,另一個塊寫私有方法。 5)原則上不允許通過拼接字符串的方式編寫SQL腳本,如果必須盡心拼接SQL的場景,一定一定一定要嚴格控制SQL注入攻擊,嚴格進行關鍵字驗證。 6)一定要寫明業務邏輯執行邏輯說明註釋,寫不明白說明註釋需進行嚴肅考覈。 7)業務功能絕對會改變,因此一定不要過度抽象,並且要儘可能的留出擴展接口。 8)所有類均繼承BaseRepository基礎類。 d.引用關係: 1.類庫引用: 1)Newtonsoft.Json 2.項目引用: 1)kbnet.xaas.models 2)kbnet.xaas.common 3)kbnet.xaas.services 4)kbnet.xaas.xxxx.core.services 5)kbnet.xaas.xxxx.core.entities 6)kbnet.xaas.xxxx.models.data 7)kbnet.xaas.xxxx.models.inner 8)kbnet.xaas.xxxx.models.converter 9)kbnet.xaas.xxxx.api.cache 10)kbnet.xaas.xxxx.api.local e.其他信息:無 2.1.2.kbnet.xaas.xxxx.core.services a.項目簡介:數據服務項目,主要面向數據庫結構進行數據的讀寫操作,即一個xxxxService類文件對應一張數據表。 b.項目結構:無 c.規則規範: 1)所有類均以xxxxService形式命名,即以Service結尾。 2)原則上禁止一切以拼接字符串的方式編寫SQL,如果必須盡心拼接SQL的場景,一定一定一定要嚴格控制SQL注入攻擊,嚴格進行關鍵字驗證。 3)儘量使用linq和lambda表達式方式編寫數據庫查詢。 4)原則上方法內只允許實現一條增加或刪除或更改的SQL腳本,如果執行多條請在repositories項目中使用TrasactionScope做事務控制。批量操作除外。 5)對於編寫SQL腳本的需求場景,除SQL關鍵字以外,不允許直接寫數據表字段,應該使用nameof方法間接實現,主要規避數據表字段名稱改變後,程序中遺漏修改。 6)對象類的默認值一定要嚴格管控,尤其是在程序升級更新時,避免弄髒數據。 7)對於編寫的SQL腳本一定要做嚴格的性能測試,找出並優化掉低效耗時的腳本。 8)作爲數據服務項目,數據安全是基礎,儘可能不要因爲技術能力不足給數據庫服務器製造性能壓力,確保其平穩運行。 9)所有類均繼承BaseService基礎類。 d.引用關係: 1.類庫引用: 1)Newtonsoft.Json 2.項目引用: 1)kbnet.xaas.models 2)kbnet.xaas.common 3)kbnet.xaas.services 4)kbnet.xaas.xxxx.core.entities 5)kbnet.xaas.xxxx.models.data 6)kbnet.xaas.xxxx.models.inner e.其他信息:無 2.1.3.kbnet.xaas.xxxx.core.entities a.項目簡介:數據實體項目,此項目中的類和代碼,主要使用ORM工具依據數據庫結構自動生成,切勿隨意改動。 b.項目結構:無 c.規則規範:無 d.引用關係: 1.類庫引用: 1)Microsoft.EntityFrameworkCore 2)Microsoft.EntityFrameworkCore.Design 3)Microsoft.EntityFrameworkCore.SqlServer 4)Microsoft.EntityFrameworkCore.Tools 2.項目引用:無 e.其他信息: 1)類庫引用中僅引用SqlServer數據庫的類庫,倘若使用其他廠商的數據庫,通過nuget搜索EntityFrameworkCore,便可在查詢結果中找到其他廠商的類庫文件,如Oracle\MySql\Postgresql等。 2)如何使用Scaffold-DbContext工具 .NET Core CLI使用方法:dotnet ef dbcontext scaffold "Data Source=(localdb)\MSSQLLocalDB;Initial Catalog=Chinook" Microsoft.EntityFrameworkCore.SqlServer Visual Studio使用方法:Scaffold-DbContext 'Data Source=(localdb)\MSSQLLocalDB;Initial Catalog=Chinook' Microsoft.EntityFrameworkCore.SqlServer 2.2.API項目 2.2.1.kbnet.xaas.xxxx.api.cache a.項目簡介:緩存服務項目,此項目主要負責與文件服務器進行交互,實現數據的高速讀寫。 b.項目結構: 1)Memcached文件夾表示使用memcached服務器進行數據的緩存。 2)Redis文件夾表示使用Redis服務器進行數據的緩存。 3)MyMemory文件夾表示使用框架自帶的集合把數據緩存到服務器內存中。 c.規則規範: 1)本項目僅限於爲dapi提供數據的緩存服務,如果對緩存數據設計的等級較高,不建議直接連接Redis服務器,而是在中間建立專門與Redis服務器通訊的服務程序。 2)使用MyMemory緩存數據時,數據會隨着dapi服務的啓停而銷燬。 3)設計編碼時,一定要將業務類和功能類做區分與管理,提升和改進代碼,確保高可讀性與質量。 d.引用關係: 1.類庫引用: 1)Newtonsoft.Json 2.項目引用: 1)kbnet.xaas.common 2)kbnet.xaas.models 3)kbnet.xaas.services 4)kbnet.xaas.xxxx.models.data e.其他信息:無 2.2.2.kbnet.xaas.xxxx.api.local a.項目簡介:本地服務項目,此項目主要負責計算機硬盤裏文件的讀寫與維護,比如Sqlite數據庫文件、LiteDB、數據文件、文本文件等。 b.項目結構: 1)DataJson文件夾表示負責讀寫與維護數據爲Json格式的文件。 2)DataSqlite文件夾表示負責讀寫與維護Sqlite數據庫文件。 3)DataText文件夾表示負責讀寫與維護數據爲純文本的文件。 4)... c.規則規範: 1)本項目僅限於爲dapi提供本地化文件存儲服務,因此,每一種類型文件均需在配置文件中,設置讀寫與維護規則。 2)本地文件的存儲管理,如文件大小、保留時長、刪除條件、更新步驟、是否會被誤刪或覆蓋掉、文件存儲位置等。 3)設計編碼時,一定要將業務類和功能類做區分與管理,提升和改進代碼,確保高可讀性與質量。 d.引用關係: 1.類庫引用: 1)Newtonsoft.Json 2)Microsoft.Data.Sqlite 2.項目引用: 1)kbnet.xaas.common 2)kbnet.xaas.models 3)kbnet.xaas.services 4)kbnet.xaas.xxxx.models.data e.其他信息: 1)在.netcore中,使用Microsoft.Data.Sqlite不包含SqliteDataAdapter類,意味着DataSet不可用。倘若想使用可以繼續使用舊的System.Data.Sqlite,但是不建議使用。 2.3.Models項目 2.3.1.kbnet.xaas.xxxx.models.data a.項目簡介:數據模型項目,此項目定義的模型類,專門用於與papi傳輸結構化數據。 b.項目結構: 1)Cache文件夾定義緩存服務數據模型類。 2)Local文件夾定義本地服務數據模型類。 3)Dms文件夾定義數據服務的模型類。 4)... c.規則規範: 1)所有模型類均以xxxxDModel形式命名,即DModel結尾。 2)模型類和屬性均需註釋說明其用意。 3)屬性默認值必須註釋解釋清楚。 4)項目以文件夾方式將數據模型類分割管理,目的是爲了清晰化目錄結構,因此,切勿在項目內部跨文件夾相互引用。 5)Dms文件夾中的數據模型類需繼承自kbnet.xaas.models項目的DataBaseModel類。 d.引用關係: 1.類庫引用:無 2.項目引用: 1)kbnet.xaas.models e.其他信息:無 2.3.2.kbnet.xaas.xxxx.models.inner a.項目簡介:自用模型項目,此項目定義的模型類,僅作用於dapi項目內部使用,不允許對外輸出。 b.項目結構: 1)Cache文件夾定義緩存服務內部模型類。 2)Common文件夾定義通用內部模型類。 3)Data文件夾定義數據服務內部模型類。 4)Local文件夾定義本地服務內部模型類。 5)... c.規則規範: 1)所有模型類均以xxxxIModel形式命名,即IModel結尾。 2)不同項目間的模型類存放在自己的文件夾中,原則上不允許在項目A調用項目B的模型類,實際操作中按照項目的規模、複雜度和難度自行掌控。 3)模型類和屬性均需註釋說明其用意。 4)屬性默認值必須註釋解釋清楚。 5)所有模型類需繼承自kbnet.xaas.models項目的BaseModel類。 d.引用關係: 1.類庫引用:無 2.項目引用: 1)kbnet.xaas.models e.其他信息:無 2.3.3.kbnet.xaas.xxxx.models.converter a.項目簡介:模型轉換器項目,負責模型類對象轉換,爲了各項目保持代碼的純粹性和可讀性、可複用性、可維護性,不允許在core和api項目中編寫模型對象轉換代碼,尤其在項目repostories中。 b.項目結構:無 c.規則規範: 1)類命名:xxxxConverter。 2)方法命名:inner轉換爲data,xxxx_IM2DM()。data轉換爲inner,xxxx_DM2IM()。 3)方法命名:data轉換爲orm,xxxx_DM2OM()。orm轉換爲data,xxxx_OM2DM()。 4)方法命名:倘若模型轉換的是集合(如List,Dictionary等),方法名錶示爲xxxx_XX2XX_List()。 5)轉換操作:在轉換前,必須做非空判斷,避免出現空指針異常。 6)... d.引用關係: 1.類庫引用:無 2.項目引用: 1)kbnet.xaas.models 2)kbnet.xaas.common 3)kbnet.xaas.xxxx.models.data 4)kbnet.xaas.xxxx.models.inner e.其他信息:無 三、配置規則 1.說明信息: 配置規則需要通過kbgress.web設置和定義好,然後下載到本地,或配置好綁定關係,程序在啓動時從kbgress直接讀取。 2.規則類別: 2.1.系統信息 a.系統所屬產品ID:xxxxxxxxxxxxxxxx。 b.系統所屬程序ID:xxxxxxxxxxxxxxxx。 c.系統所屬線路ID:xxxxxxxxxxxxxxxx。 c.系統ID:xxxxxxxxxxxxxxxx。 d.系統版本:v1.0.0。 e.系統狀態:可用、不可用/升級中、等待升級。 2.2.安全權限 a.令牌信息 b.權限信息 c.IP信息 d.腳本攻擊:xss或csrf等。 2.3.日誌信息 a.是否上傳雲端:0或1。 2.4.消息信息 2.5.緩存信息 2.6.本地信息 2.7.數據庫信息 2.8.服務信息 a.狀態: 1.心跳:頻率(5s)。 b.流量: 1.app信息: a)最大允許連接數:0。 b)最大連接數:0。 c)拒絕連接數:0。 d)當前連接數:0。 2.api信息: a)最大時耗(毫秒):以天爲單位。 b)最小時耗(毫秒):以天爲單位。 c)請求數量(10分鐘):以10分鐘爲單位。 d)流量上限(0表示不限流量,次數/每秒):0。 e)最大流量(分鐘):0。 f)拒絕次數(分鐘):0。 g)重試次數(0-3):調用鏈路中api時。 h)是否熔斷(0或1):被調用服務或api故障時。 2.9.DCS信息 a.主要依據業務對象的粒度和時間,定位目標數據庫和數據表。 2.10.硬件信息 a.操作系統:xxxxxxxxxxxxxxx。 b.內存容量:xxxxxxxxxxxxxxx。 c.硬盤信息:xxxxxxxxxxxxxxx。 d.CPU信息:xxxxxxxxxxxxxxx。 e.網絡信息:xxxxxxxxxxxxxxx。 四、編碼規範 1.編碼流程: a.主流程:是指程序對關係型數據庫(Oracle\MSSQL\MySql\Postgresql等)的操作。 1.kbnet.xaas.dapi:此項目是程序的啓動項目,定義了外界可以調用訪問的WebApi方法。 2.kbnet.xaas.xxxx.core.repositories:業務對象倉庫項目,以業務對象形式定義和提供數據操作方法,項目中類不與數據表一一對應。 3.kbnet.xaas.xxxx.core.services:數據對象服務項目,以數據對象形式定義和提供數據操作方法,項目中類與數據表一一對應。 4.kbnet.xaas.xxxx.core.entities:EntityFrameworkCore的ORM項目,負責ORM映射轉換。 b.輔流程: 1.緩存流程:是指程序從緩存數據庫(Memcached\Redis等)中讀寫數據。 a)緩存主指kbnet.xaas.xxxx.api.cache項目。 b)repostories\services項目都可以調用本項目公開的方法。 2.本地流程:是指程序從本地數據庫(Sqlite)或文件中讀寫數據。 a)本地主指kbnet.xaas.xxxx.api.local項目。 b)repostories\services項目都可以調用本項目公開的方法。 2.編碼規範: 由於各團隊有自己的編碼規範,所以此處便不公開了。 3.測試流程: a.測試分爲單元測試和案例測試,前者主要對單個功能進行測試,後者模擬現實業務操作進行測試。 b.按照項目類別將測試對象分爲二類,第一類api\repositories\services項目方法的測試,第三類cache\local項目方法的測試。 c.在所有測試項目中,api和repositories項目測試是必須執行的,其他項目按實際需要自行決定。 d.... 4.測試規範: a.所有成員都必須按照規定對自己編寫的代碼測試,經驗證明幾乎沒有程序員可以編寫出零BUG的方法代碼。 b.測試不僅是對自己編寫的代碼負責,也是對協同開發的成員負責。 c.凡是因未測試引發的問題,皆由自己負責。 d.... 5.發佈部署: a.部署方式:依據實際情況,程序分爲兩種部署方式。 第一種方式,單線路環境,暫停對外提供服務,更新部署程序,影響使用。 第二種方式,多線路環境,對半暫停線路,一半一半的更新程序,不影響使用(無感更新)。 6.常用單詞: 1)查詢:select\get\find\query 2)增加:insert\add\new\create 3)更新:update\modify\edit 4)刪除:delete\remove 5)對象:info,item\items,list,all 6)條件:id,code,name,isDelete,isActive,isVisible,typeId,parentId,ownerId,userId\memberId,companyId 7)時間:date,time,year\month\day,hour\minute\seconds,milliseconds 8)分頁:page\pages,count,index,num\no,size,total 9)表格:table\row\column\cell 10)集合:first\last,previous\current\next,above\below,before\after,exist,contains,max\min,sum,average,top,sort,asc\desc 11)庫表:master\slave,sync\async,lock\unlock,isInit,isMain,versionNo 12)倉庫:level層級,dimension維度,granularity粒度,measure度量\metric指標(特殊的度量),scale尺度(度量單位),field字段,caliber口徑 13)詞對:start\stop,key\value,upload\download,import\export,encode\decode,encrypt/decrypt,split\join,go\back 14)比較:+Plus,-Minus,*Multiply,/Divide,%Mod,=Equal,!=NotEqual,>GreatThan,>=GreatOrEqual,<LessThan,<=LessOrEqual,&BinAnd,|BinOr,^BinXor,<<BinShiftLeft,>>BinShiftRight 15)其他:save,build,batch,copy,set,valid,gen(erate),parse,by,or,in,cut,result 五、注意事項 1.三方服務:嚴禁擅自引用第三方服務的行爲,尤其是在線服務,不論是商業、開源、或其他形式的服務,避免造成程序和產品的依賴性、穩定性、不可控性等風險和問題。 2.自律習慣:軟件產品或項目以更好的服務用戶和客戶爲宗旨,因此,嚴禁在開發中以鍛鍊自己技術的思想和行爲編寫不可控或效率低劣的代碼。 3.自律習慣:團隊成員需按照解決方案類型的程序架構進行設計與編碼,不可以自我主觀意念破壞編碼流程與規範。 4.成本警鐘:由於軟件設計研發是一門純腦力勞動,所以一定要時不時的給自己敲一下警鐘,測算一下時間週期、團隊規模、成員能力等各方面的成本,堅決要避免一根筋的苦思冥想鑽牛角尖。 5.... 六、總結 本文既是對解決方案的介紹,也是編程規範的定義。然而上述內容並不是完全不變的,在實戰過程中,如遇到特殊場景,需要與規則制定者或架構師商議,更改或制定合適的規則規範。 依照上述內容便可完成DAPI項目中功能的設計、開發、測試、發佈等工作。
四、總結
終於在春節前把kbnet架構搞完,算是了結了我一樁大心事。軟件編程技術變化之快可謂日新月異,最讓程序員提心吊膽和驚魂的就是學不完、跟不上,因爲那樣意味着淘汰出局。在技術積累與探索發現中領悟到,唯有以不變應萬變之法纔可以確保自己不會被淘汰出局,即構建自己的架構體系,技術、知識、能力等,形成架構體系後,便可以把凌亂的東西分門別類的歸納起來,過時落後的清理出去。
有了這一整套程序架構,便可以基於此,進行各種軟件的設計與研發,十幾年的技術鑽研,算是有個交代了。
接下來,就會基於這套框架進行kbgress的設計與研發,想知道kbgress是什麼軟件?可以理解爲它是這套程序框架的基礎設施服務軟件,提供網關服務、安全服務、負載均衡服務、分佈式計算與存儲服務等功能,一句話使開發人員能夠使用kbnet專注軟件產品功能開發,其他保障性需求它來提供服務。