Նախագծի ճարտարապետություն

01Շերտեր՝ յուրաքանչյուր մաս ունի մեկ գործ

Պատկերացրեք ռեստորան։ Մատուցողն ընդունում է պատվերը (HTTP շերտ), խոհարարը որոշում է՝ ինչպես պատրաստել (բիզնես շերտ), պահեստը պահում է մթերքները (տվյալների շերտ)։ Մատուցողը երբեք չի եփում, իսկ խոհարարը երբեք չի խոսում հաճախորդների հետ։ Կոդում՝ կոնտրոլլերները կամ route handler-ները վերլուծում են հարցումը և վերադարձնում պատասխան, սերվիսները կամ use case-երը կիրառում են բիզնես կանոնները, ռեպոզիտորիաները կամ ORM մոդելները կարդում և գրում են տվյալները։ Կախվածություններն ուղղված են դեպի ներս՝ կոնտրոլլերը գիտի սերվիսի մասին, սերվիսը՝ տվյալների շերտի, բայց բիզնես տրամաբանությունը ոչինչ չգիտի HTTP-ի մասին։ Դա նույն տրամաբանությունը դարձնում է վերաօգտագործելի API-ից, CLI հրամանից, queue job-ից կամ թեստից։

• Ներկայացում (presentation)՝ կոնտրոլլերներ, հարցման վալիդացիա, պատասխանի ձևավորում։
• Հավելված (application)՝ սերվիսներ կամ use case-եր, որոնք համակարգում են առաջադրանքը (PlaceOrder, RefundPayment)։
• Դոմեն՝ էնտիտիներ, value object-ներ և կանոններ (Money, OrderStatus-ի անցումներ)։
• Ենթակառուցվածք (infrastructure)՝ տվյալների բազա, հերթեր, վճարային gateway-ներ, email պրովայդերներ։

02Սերվիսներ, use case-եր և DTO-ներ

Սերվիսը խմբավորում է մեկ դոմենի հետ կապված գործողությունները (OrderService)։ Use case-ը, կամ action-ը, մեկ գործողություն է հստակ անունով (PlaceOrder)։ Երկուսն էլ ընդունում են պարզ մուտքային տվյալներ և վերադարձնում պարզ արդյունք։ Այդ մուտքը DTO է՝ Data Transfer Object, փոքր, տիպավորված օբյեկտ, որը ճշգրիտ նկարագրում է այն դաշտերը, որոնք գործողությունն ընդունում է։ DTO-ները թույլ չեն տալիս հարցման «հում» զանգվածներին թափանցել բիզնես տրամաբանության մեջ և պայմանագիրը դարձնում են ակնհայտ։ Վալիդացրեք եզրերին՝ ստուգեք կառուցվածքն ու տիպերը այնտեղ, որտեղ տվյալները մտնում են համակարգ (HTTP հարցում, webhook, CSV import, հաղորդագրություն հերթից), իսկ ներսում արդեն վստահեք DTO-ին։ Բիզնես կանոնները, օրինակ՝ «չեղարկված պատվերը չի կարող վճարվել», միևնույն է ապրում են դոմենում, որովհետև դրանք մուտքի կառուցվածքի մասին չեն։

1// Edge: validate and map to a DTO
2export const CreateOrderSchema = z.object({
3  branchId: z.string().uuid(),
4  items: z.array(z.object({ productId: z.string().uuid(), qty: z.number().int().min(1) })).min(1),
5});
6export type CreateOrderDto = z.infer<typeof CreateOrderSchema>;
7 
8// Use case: business logic only, no HTTP
9export class PlaceOrder {
10  constructor(private orders: OrderRepository, private pricing: PricingService) {}
11 
12  async execute(companyId: string, dto: CreateOrderDto) {
13    const quote = await this.pricing.quote(companyId, dto.items);
14    return this.orders.create({ companyId, branchId: dto.branchId, ...quote });
15  }
16}

03Թղթապանակների կառուցվածք՝ ըստ դոմենի, ոչ թե ըստ ֆայլի տիպի

Փոքր հավելվածները կարող են խմբավորել ըստ տիպի՝ բոլոր կոնտրոլլերները մեկ թղթապանակում, բոլոր մոդելները՝ մյուսում։ Մոտ քսան ֆիչերից հետո դա ցավոտ է դառնում, որովհետև մեկ փոփոխությունը դիպչում է իրարից հեռու հինգ թղթապանակի։ Ըստ դոմենի խմբավորումը, որը երբեմն կոչվում է feature folders կամ մոդուլներ, պատվերների մասին ամեն ինչ պահում է միասին։ Յուրաքանչյուր մոդուլ բացում է փոքր հանրային մակերես (սերվիս, մի քանի տիպ) և թաքցնում մնացածը։ Ընդհանուր, cross-cutting կոդը (auth, լոգավորում, գումարի հետ աշխատող helper-ներ) գնում է shared կամ core թղթապանակ։ Laravel-ում կարող եք պահել ֆրեյմվորքի թղթապանակները և Models-ի ու Services-ի ներսում ավելացնել դոմենային ենթաթղթապանակներ, NestJS-ում մոդուլներն այս մոտեցմանը բնականորեն համապատասխանում են։

1src/
2  modules/
3    orders/
4      orders.controller.ts
5      orders.service.ts
6      dto/create-order.dto.ts
7      orders.module.ts
8    menu/
9    loyalty/
10  shared/
11    auth/  logging/  money/
12  config/
13    env.ts

04Առանձին API-ներ վեբի, մոբայլի և ադմինի համար

Մեկ բեքենդը հաճախ ունի երեք լսարան։ Հանրային կայքին, մոբայլ հավելվածին և ադմին վահանակին պետք են պատասխանի տարբեր կառուցվածքներ, տարբեր auth (cookie սեսիա, թոքեն կամ աշխատակցի մուտք 2FA-ով), տարբեր rate limit-ներ և տարբեր թողարկման ցիկլեր՝ մոբայլ հավելվածի տարբերակը կարող է մեկ տարի ապրել հեռախոսներում, ուստի նրա API-ն պետք է մնա հետադարձ համատեղելի։ Լավ պատերն է յուրաքանչյուր ալիքի համար առանձին route խմբեր կամ կոնտրոլլերներ, որոնք կանչում են նույն սերվիսները։ Հաճախորդի այն ֆունկցիաները, որոնք վեբի և մոբայլի համար նույնական են, կարելի է սահմանել մեկ անգամ և միացնել երկու prefix-ների տակ։ Ադմինի endpoint-ներն ապրում են իրենց սեփական խմբում՝ ավելի խիստ թույլտվություններով և audit լոգավորմամբ։ Մոբայլ API-ն տարբերակավորեք բացահայտ (v1, v2), որպեսզի կարողանաք այն անվտանգ զարգացնել։

05Մոնոռեպոներ, կոնֆիգուրացիա և միջավայր

Մոնոռեպոն մի քանի հավելված և փաթեթ պահում է մեկ ռեպոզիտորիայում՝ api, web, admin, mobile, գումարած ընդհանուր փաթեթներ, ինչպիսիք են տիպերը, API client-ը, UI կոմպոնենտները կամ ESLint կոնֆիգը։ pnpm workspaces-ը փաթեթները լոկալ կապում է իրար, իսկ Turborepo-ն (կամ Nx-ը) առաջադրանքները գործարկում է կախվածությունների հերթականությամբ և քեշավորմամբ, այնպես որ վերակառուցվում և թեստավորվում է միայն փոփոխվածը։ Կոնֆիգուրացիան պետք է հետևի twelve-factor կանոնին՝ կոդը ամենուր նույնն է, տարբերվում է միջավայրը։ Միջավայրի փոփոխականները կարդացեք մեկ անգամ՝ գործարկման պահին, վալիդացրեք սխեմայով և անմիջապես ձախողվեք (fail fast), եթե ինչ-որ բան բացակայում է։ Երբեք commit մի արեք .env ֆայլեր, փոխարենը commit արեք .env.example՝ placeholder արժեքներով։

1# pnpm-workspace.yaml
2packages:
3  - "apps/*"
4  - "packages/*"
5 
6# turbo.json
7{
8  "tasks": {
9    "build": { "dependsOn": ["^build"], "outputs": ["dist/**", ".next/**"] },
10    "test": { "dependsOn": ["^build"] },
11    "lint": {}
12  }
13}

06Ինչպես ճարտարապետությունը առողջ պահել ժամանակի ընթացքում

Ճարտարապետությունը քայքայվում է մեկ «կարճ ճանապարհով» ամեն անգամ։ Պաշտպանեք այն կանոններով, որոնք ստուգում են գործիքները՝ lint կանոններ կամ dependency-cruiser, որոնք արգելում են մի մոդուլին ներմուծել մյուսի ներքին մասերը, TypeScript strict ռեժիմ և թեստեր սերվիսների մակարդակում։ Երբ մեծ ընտրություն եք կատարում, գրեք ճարտարապետական կարճ նշումներ (ADR՝ Architecture Decision Record), որպեսզի հաջորդ մարդը իմանա՝ ինչու։ Սկսեք որպես մոդուլային մոնոլիթ՝ մեկ deploy արվող հավելված մոդուլների մաքուր սահմաններով։ Հետագայում սերվիսների բաժանելը հեշտ է, եթե սահմանները մաքուր են, և գրեթե անհնար, եթե՝ ոչ։ Ռեֆակտորինգ արեք անընդհատ, փոքր քայլերով, այլ ոչ թե պլանավորեք մեկ մեծ վերագրում։

07Սահմանների պահպանում գործիքներով, ոչ թե բարի մտադրություններով

Wiki-ի դիագրամը չի կանգնեցնի երեկոյան 6-ին հոգնած developer-ին, որը import է անում մեկ այլ մոդուլի ներքին repository-ն։ Ձախողվող CI ստուգումը՝ կկանգնեցնի։ TypeScript-ում dependency-cruiser-ը ստուգում է import-ի կանոնները ամբողջ նախագծում, իսկ Nx-ը workspace-երի համար ունի enforce-module-boundaries lint կանոն։ PHP-ում Deptrac-ը սահմանում է շերտեր և թույլատրված dependency-ներ, իսկ Pest-ի architecture test-երը կանոնները ձևակերպում են որպես test-եր, օրինակ՝ «controller-ները չեն կարող օգտագործել DB facade-ը»։ Լավ առաջին կանոնների հավաքածուն փոքր է․ մոդուլները կարող են import անել մեկ այլ մոդուլի միայն public entry ֆայլը, domain կոդը չի կարող import անել HTTP կամ framework class-ներ, shared կոդը չի կարող import անել մոդուլներից։ Կանոնները CI-ին ավելացրեք warning mode-ով, ուղղեք առկա խախտումները, ապա անցեք error-ի։ Յուրաքանչյուր նոր կանոն պետք է նկարագրի իրական խնդիր, որ ունեցել եք, ոչ թե տեսական մաքրության նպատակ։

1// .dependency-cruiser.cjs
2module.exports = {
3  forbidden: [
4    {
5      name: 'no-cross-module-internals',
6      comment: 'Import other modules only through their index.ts',
7      severity: 'error',
8      from: { path: '^src/modules/([^/]+)/' },
9      to: {
10        path: '^src/modules/[^/]+/',
11        pathNot: ['^src/modules/$1/', '^src/modules/[^/]+/index[.]ts$'],
12      },
13    },
14    { name: 'shared-stays-generic', severity: 'error', from: { path: '^src/shared/' }, to: { path: '^src/modules/' } },
15  ],
16};

08Domain modelling․ invariant-ներ, aggregate-ներ և state machine-ներ

Invariant-ը կանոն է, որը միշտ պետք է ճիշտ լինի․ պատվերի total-ը հավասար է իր տողերի գումարին, refund արված պատվերը չի կարող վճարվել։ Aggregate-ը օբյեկտների խումբ է, որը միասին պաշտպանում է այդպիսի կանոնները, օրինակ՝ պատվերն իր տողերով, և այն փոխվում է միայն իր սեփական method-ներով, երբեք՝ մեկ այլ տեղից տողի գրառումն ուղղակի խմբագրելով։ Status դաշտերը այն տեղն են, որտեղ թաքնված են bug-երի մեծ մասը, ուստի մոդելավորեք դրանք որպես բացահայտ state machine-ներ՝ թույլատրված անցումների աղյուսակ և մեկ function, որը կիրառում է դրանք։ Այդ դեպքում «կարելի՞ է refund անել չեղարկված պատվերը» հարցն ունի մեկ պատասխան մեկ տեղում, և կարող եք test անել յուրաքանչյուր զույգ։ Միավորեք սա value object-ների հետ գումարի (ամբողջ թիվ minor unit-ներով գումարած արժույթ) և քանակների համար, և bug-երի շատ դասեր, օրինակ՝ float-ի կլորացումը կամ բացասական stock-ը, անհետանում են կառուցվածքով։

1type OrderStatus = 'draft' | 'placed' | 'paid' | 'fulfilled' | 'cancelled' | 'refunded';
2 
3const allowed: Record<OrderStatus, OrderStatus[]> = {
4  draft: ['placed', 'cancelled'],
5  placed: ['paid', 'cancelled'],
6  paid: ['fulfilled', 'refunded'],
7  fulfilled: ['refunded'],
8  cancelled: [],
9  refunded: [],
10};
11 
12export function transition(order: Order, to: OrderStatus): Order {
13  if (!allowed[order.status].includes(to)) {
14    throw new DomainError('Cannot move order from ' + order.status + ' to ' + to);
15  }
16  return { ...order, status: to, version: order.version + 1 };
17}

09Ինչպես են մոդուլները շփվում․ ուղղակի կանչեր, event-ներ և read model-ներ

Մոդուլները պետք է համագործակցեն՝ առանց միմյանց ներսը իմանալու։ Օգտագործեք մեկ այլ մոդուլի public service-ի ուղղակի կանչ, երբ պատասխանն անմիջապես պետք է, օրինակ՝ checkout-ը pricing-ից գնանշում է խնդրում։ Օգտագործեք domain event, երբ ինչ-որ բան տեղի է ունեցել, և մյուսները կարող են արձագանքել, օրինակ՝ OrderPaid-ը գործարկում է loyalty միավորներ, անդորրագրի email և stock-ի շարժ․ order մոդուլին պետք չէ իմանալ, թե ով է լսում։ Մեկ process-ի ներսում event-ները կարող են dispatch արվել commit-ից հետո, իսկ երբ listener-ներն ապրում են մեկ այլ process-ում, գրեք դրանք outbox-ի մեջ նույն transaction-ում։ Խուսափեք նրանից, որ երկու մոդուլ գրեն նույն աղյուսակում, քանի որ այդ դեպքում ոչ մեկը չի տիրապետում կանոններին։ Հաշվետվությունները, որոնց պետք են տվյալներ շատ մոդուլներից, հատուկ դեպք են․ կառուցեք read model՝ denormalised աղյուսակ, որը թարմացվում է event-ներից կամ գիշերային job-ով, ամեն մոդուլի աղյուսակները join անող մեկ հսկա query-ի փոխարեն։

• Command՝ «արա սա» մեկ սեփականատիրոջը, կարող է ձախողվել, պատասխան է պետք։
• Event՝ «սա տեղի ունեցավ», զրո կամ ավելի listener, անցյալ ժամանակով անուն։
• Read model՝ query-ների համար օպտիմալացված պատճեն, eventually consistent, վերակառուցվում է source of truth-ից։

10Legacy համակարգերի փոփոխում․ seam-եր, strangler fig և anti-corruption layer-ներ

Big-bang rewrite-երը սովորաբար ձախողվում են․ հին համակարգը շարունակում է փոխվել, իսկ նորը հետապնդում է այն։ Strangler fig pattern-ը համակարգը փոխարինում է կտոր առ կտոր։ Առջևում դրեք routing շերտ, օրինակ՝ reverse proxy կամ նոր app-ի router-ը, միաժամանակ տեղափոխեք մեկ endpoint կամ էկրան, իսկ մնացածն ուղարկեք հին կոդին, մինչև ոչինչ չմնա։ Ռիսկային կոդին ձեռք տալուց առաջ գրեք characterization test-եր, որոնք գրանցում են, թե այն ինչ է անում այսօր, նույնիսկ եթե այդ վարքը սխալ է թվում, որպեսզի refactoring-ը փոխի կառուցվածքը, ոչ թե արդյունքները։ Երբ նոր կոդը պետք է շփվի legacy model-ի կամ տարօրինակ անուններով ու կանոններով արտաքին ERP-ի հետ, մեջտեղում դրեք anti-corruption layer՝ թարգմանիչ, որը նրանց հասկացությունները քարտեզագրում է ձերի վրա, որպեսզի նրանց խառնաշփոթը չթափանցի ձեր domain։ Feature flag-երը թույլ են տալիս traffic-ը փոխել աստիճանաբար և rollback անել ակնթարթորեն։