Phân tầng mô-đun

Đầu vào là mã đã viết xong — một tệp, một mảnh diff. Đầu ra là một phán quyết: tệp có nằm trong phạm vi hay không, quy tắc đã xuất bản nào nổ, nổ trên specifier nào, ứng với mã luật nào, và cửa nào còn mở đủ để giấu đúng cái lỗi ấy. Mô-đun này không chọn bố cục nào cả. Nó từ chối một bố cục, và nó phải chỉ được ra đúng specifier mà nó từ chối.

Luật

Luật nói về đường nối giữa các năng lực: một lần import được phép gọi tên cái gì, và một năng lực được phép nói gì về chính nó. Một lần import gọi tên tệp khai báo ký hiệu, không bao giờ gọi tên một thư mục tái xuất hộ; và bên trong một năng lực, import đi bằng đường tương đối chứ không vòng qua alias công khai của chính năng lực đó.

Luật có năm mã. Hai mã có quy tắc giữ. Nguồn xuất đúng hai quy tắc trong rules và đúng hai trong recommended, hai danh sách khớp nhau, và cả hai đều đòi mức error. Ba mã còn lại không có gì giữ.

Một trong ba mã đó bị bỏ ra một cách cố ý và nguồn nói thẳng điều đó: muốn biết một mô-đun được import là năng lực anh em hay là con lồng bên trong thì phải có đồ thị mô-đun, mà quy tắc đọc từng tệp một thì không thấy. Đó là hình dạng thật thà của ranh giới này — cả hai quy tắc đều là xử lý chuỗi thuần trên một specifier, vừa là lý do chúng được để ở mức error mà không cần ngân sách báo nhầm, vừa là lý do mọi thứ cần tới tệp thứ hai đều nằm ngoài tầm với.

Luật máy đã xuất bản

LAYERING-3 (một mô-đun năng lực import mô-đun của năng lực anh em thay vì nối dây ở composition root), LAYERING-4 (composition root là nơi duy nhất biết toàn cục) và LAYERING-5 (bề mặt công khai của một năng lực là những tệp nó có ý cho người khác import) không có quy tắc nào giữ. Chúng là chưa được cưỡng chế chứ không phải đã được bao phủ, và một lần chạy xanh không nói gì về cả ba.

LAYERING-5 đáng được ghi chú gắt nhất, vì nó trông như đã được giữ mà thật ra không. must-deep-module-import giữ nửa bên gọi: không ai được import một barrel qua alias. Không gì giữ nửa bên khai báo: viết một index.ts tái xuất cả thư mục thì không bị báo, và một khi tệp đó tồn tại thì mọi đường tương đối và mọi đường không-alias tới nó đều hợp lệ. Quy tắc làm cho barrel bất tiện để với tới, chứ không làm cho barrel không thể viết ra. Ai đọc bảng trên rồi kết luận “đã cấm được barrel” là đã đọc sai một mức.

Đọc một diff

1. Quyết định phạm vi trước mọi thứ khác, và ghi lại. Với no-self-module-alias, một tệp mà đường dẫn không chứa /src/modules/, /src/features/ hay /src/tests/ sẽ nhận bộ thăm rỗng — ngoài phạm vi không có nghĩa là tệp đã qua, mà có nghĩa quy tắc không tồn tại với tệp đó. must-deep-module-import không bao giờ đọc context.filename nên nó có phạm vi ở khắp nơi.
2. Kiểm các miễn trừ. Một export { X } cục bộ không có source thì bị bỏ qua. Một specifier không phải string — template literal, nguồn tính toán ra — cũng bị bỏ qua. Một tệp ở composition root, ngoài mọi cây năng lực, được no-self-module-alias thả hoàn toàn.
3. Đọc các nút. Với cả hai quy tắc chỉ có ba vị trí specifier tĩnh: ImportDeclaration, ExportNamedDeclaration có source, và ExportAllDeclaration. Mọi dạng động đều nằm ngoài tầm với ngay từ cấu tạo, nên hãy đọc dạng nút trước khi đọc chuỗi.
4. Xuất một khối cho mỗi phát hiện. Một specifier có thể mang hai phát hiện: một barrel tự trỏ bị cả hai quy tắc báo, độc lập với nhau.
5. Viết dòng cửa mở mỗi khi có một cửa mở đủ sức giấu đúng cái lỗi ấy. Một phán quyết silent là một kết quả thật và phải được báo cáo. “Cổng xanh” và “quy tắc đã nhìn” là hai câu khác nhau, và chỉ một trong hai là bằng chứng.
6. Đừng báo cái mà không quy tắc nào canh. Ba trong năm mã không có máy giữ; một phán quyết nói khác đi là nói sai về mô-đun này.

must-deep-module-import — LAYERING-1

Nó báo cái gì. barrel — một specifier gọi tên một năng lực và không tệp nào. @modules/ai thay vì @modules/ai/ai-invoke.service. Mỗi specifier phạm luật là một lần báo.

Nó phát hiện bằng gì. Thăm ImportDeclaration, cùng với ExportNamedDeclaration và ExportAllDeclaration khi node.source tồn tại. Đọc node.source.value và thoát trừ khi typeof là string. Tìm mục đầu tiên trong mảng ALIASES ba phần tử mà specifier startsWith tiền tố của nó: @modules/, @features/, @tests/. Cắt tiền tố ra, báo ngay khi phần còn lại rỗng, ngược lại tách phần còn lại theo / và so parts.length với barrelDepth bằng 1 — hoặc bằng 2 khi alias là metaAware (chỉ @modules/) và parts[0] nằm trong Set ba tên META_ROOTS: platform, lib, integrations. parts.length <= barrelDepth thì báo. Nó không bao giờ đọc context.filename.

Nó không thấy gì. Nó đếm số đoạn, không bao giờ đếm cái mà đoạn cuối trỏ tới. @modules/ai/index là hai đoạn nên đi lọt — gọi thẳng tên tệp barrel là đường đi lọt sạch sẽ nhất qua chính quy tắc sinh ra để cấm barrel. @modules/ai/services khi services/ có index.ts cũng là khe hở đó và là dạng hay gặp hơn nhiều: với một quy tắc không bao giờ phân giải gì, một thư mục barrel lồng bên trong không phân biệt nổi với một tệp. @modules/ai/ tách ra ["ai", ""] — hai đoạn, và đoạn rỗng không bao giờ được kiểm. @modules//ai và @modules/./ai là cùng một phép đếm. Một specifier tương đối không có tiền tố alias nào, nên một barrel liên năng lực gọi bằng đường tương đối là vô hình. ALIASES và META_ROOTS mỗi thứ là ba tên viết tay: thêm một alias thứ tư hay một thư mục nhóm thứ tư là có ngay một cây không được cưỡng chế, im lặng, không tín hiệu nào. Và nhận biết thư mục nhóm chỉ thuộc về @modules/, nên dưới @features/ và @tests/ một thư mục nhóm bị coi là năng lực và mọi barrel dưới nó đi lọt.

Ranh giới. Quy tắc này phán về hình dạng của một specifier. Chuyện specifier đó có trỏ ngược về chính năng lực của tệp đang import hay không là LAYERING-2. Chuyện barrel có được phép viết ra hay không thì không gì giữ.

no-self-module-alias — LAYERING-2

Nó báo cái gì. self — một tệp nằm trong năng lực ai mà với tay lấy @modules/ai/.... Đó là năng lực nói chuyện với chính mình qua cửa trước của mình. Mỗi specifier phạm luật là một lần báo.

Nó phát hiện bằng gì. Đọc context.filename || context.getFilename() một lần lúc create và đổi \ thành /. Duyệt cùng mảng ALIASES theo thứ tự khai báo, lấy lastIndexOf của từng root — /src/modules/, /src/features/, /src/tests/ — và root đầu tiên tìm thấy thì thắng. Tách phần đuôi đường dẫn theo / để suy ra khoá tự thân: bình thường là [parts[0]], hoặc ["<nhóm>/<tên>", "<tên>"] khi alias là metaAware, parts[0] là một thư mục nhóm và còn ít nhất hai đoạn. Không root nào khớp thì trả về bộ thăm rỗng. Còn lại thì thăm cùng ba loại nút, đòi specifier startsWith đúng tiền tố alias đó, và báo khi phần còn lại === key hoặc startsWith(key + "/") với bất kỳ khoá nào.

Nó không thấy gì. @modules//ai/x và @modules/./ai/x để lại phần còn lại là "/ai/x" và "./ai/x", không khớp key cũng không khớp key + "/". Với vào một năng lực khác bằng đường tương đối — ../../billing/billing.service từ trong modules/ai/ — là một lần vượt ranh giới không có alias nào để báo, mà quy tắc chỉ soi những specifier có tiền tố alias. Một cây năng lực đặt ở apps/api/modules/, src/module/, hay bất kỳ đường dẫn nào không chứa đúng cặp đoạn /src/modules/ thì không tìm thấy root và không được kiểm chút nào; hình dạng thư mục là thứ rẻ nhất trong một kho mã để đổi, mà ở đây nó chịu lực. Một tệp viết thẳng ở src/modules/platform/config.ts cho ra khoá tự thân ["platform/config.ts", "config.ts"] — tên tệp nằm ở chỗ đáng lẽ là tên năng lực — và vì không specifier nào mang đuôi .ts, quy tắc tắt hẳn với tệp đó trong khi trông vẫn như đang bật. Khoá ngắn dưới thư mục nhóm không mang tên nhóm, nên từ trong modules/platform/exceptions/ một import tới @modules/exceptions/... thật sự khác vẫn bị báo là tự trỏ: quy tắc bắn vào mã đúng, và thói quen nó dạy người đọc là cuộn qua nó. Còn một lần tự trỏ đi vòng qua tệp thứ ba tái xuất hộ thì là hai dòng import đều đúng khi đọc riêng, và không quy tắc một-tệp nào thấy được vòng đó.

Ranh giới. Quy tắc này suy ra năng lực từ đường dẫn, nên nó chỉ đúng đúng bằng mức mà bố cục thư mục còn giống lúc nó được viết ra. Chuyện specifier có gọi tên một barrel hay không là LAYERING-1.

Cách phát hiện

Cả hai đều là một-tệp và chỉ-chuỗi. Không quy tắc nào phân giải một import, chạm vào hệ tệp, đọc một kiểu, hay biết được đoạn cuối của một specifier là tệp, là thư mục, hay chẳng là gì cả.

Lối thoát hợp lệ

Đã đóng — người đọc có thể tưởng những cách viết này đi lọt, và chúng không lọt.

Còn mở — mù đã xuất xưởng. Một phán quyết không được phép nói rằng những chỗ này đã được phán.

Mọi cửa còn mở ở trên là khe hở của quy tắc, không bao giờ là quyền được viết như vậy của luật. Mã đi lọt vẫn là mã sai.

Đầu vào

Ngoài ra không đọc gì khác. Cả hai quy tắc đều khai schema: [] nên không nhận tuỳ chọn nào; không có cấu hình nào để một kho mã thêm một alias, thêm một thư mục nhóm, hay dời một root.

Quy tắc

1. Danh tính của một quy tắc là tên đã công bố của nó. Không có mã số riêng cho quy tắc; cái tên đó mới là chuỗi build in ra, là chuỗi dòng tắt cảnh báo mang theo, và là chuỗi mọi cuộc trao đổi về một lỗi dùng tới.
2. Mỗi quy tắc giữ đúng một mã luật, và không mã nào bị hai quy tắc cùng giữ.
3. Cả hai quy tắc đều là meta.type: "problem" và đều ở mức error trong recommended.
4. Cả hai chỉ thấy ba vị trí specifier tĩnh: ImportDeclaration, ExportNamedDeclaration có source, ExportAllDeclaration. Mọi dạng động nằm ngoài tầm với ngay từ cấu tạo.
5. must-deep-module-import quyết định bằng số đoạn, không bao giờ bằng thứ mà đoạn cuối trỏ tới. Mọi câu nói về “tệp” trong thông điệp của nó là câu của luật, không phải điều nó đo được.
6. no-self-module-alias suy ra năng lực từ đường dẫn, nên nó chỉ đúng đúng bằng mức mà bố cục thư mục còn giống lúc nó được viết ra.
7. Không root nào khớp thì trả bộ thăm rỗng, nên một tệp ngoài cây không bị kiểm một nửa.
8. Mọi cửa còn mở là khe hở của quy tắc, không bao giờ là quyền được viết như vậy của luật. Mã đi lọt vẫn là mã sai.

Ngoại lệ

Ngoại lệ ở đây là những miễn trừ đã nằm sẵn trong nguồn, không phải chỗ để lách.

• Thư mục nhóm. platform, lib, integrations được coi là chỗ chứa năng lực chứ không phải một năng lực. Điều này thả @modules/platform/exceptions khỏi việc bị đọc thành “năng lực kèm tệp” — nó đúng là một barrel — và thả một tệp nằm trong thư mục đó thành hai khoá tự thân, tên dài và tên ngắn. Đây là ngoại lệ đắt nhất của mô-đun: danh sách là đóng, và mọi cửa mở nó sở hữu đều bắt nguồn từ chỗ danh sách đó thiếu hoặc thừa một cái tên.
• Tệp ngoài mọi cây năng lực. Composition root và mọi tệp không thuộc năng lực nào được no-self-module-alias thả hoàn toàn. Đây là đúng chứ không phải lỏng: một tệp không thuộc năng lực nào thì không thể import chính năng lực của nó.
• export { X } không có nguồn. Chỉ tái xuất có source mới được kiểm; một export { X } cục bộ không phải là một lần import và được thả khỏi cả hai quy tắc.
• LAYERING-3 không có quy tắc, một cách cố ý. Nguồn nói thẳng: phân biệt năng lực anh em với con lồng bên trong cần đồ thị mô-đun. Kho nào muốn cưỡng chế thì phải viết nó thành một cổng duyệt cây, không phải một quy tắc đọc từng tệp rồi đoán.
• Mức đề nghị là error, nhưng chỉ khi đo trước. Nguồn ghi rõ cả hai được đo ở mức nợ bằng không trong kho tham chiếu. Một kho áp dụng chúng vào cây có sẵn sẽ không ở mức đó, vì barrel là mặc định của phần lớn mã nguồn. Đo trước, hạ xuống warn kèm con số, rồi mới đốt dần.

Ngoài những điều trên, không quy tắc nào khai một tuỳ chọn, một danh sách trắng hay một lối tắt theo tệp. Lối ra duy nhất còn lại là dòng tắt cảnh báo, và mô-đun này không cấp lối ra đó; dòng đó đã được ghi ở trên như một cửa còn mở, không phải như một ngoại lệ.

Đầu ra

Một khối cho mỗi phát hiện:

rule:      <must-deep-module-import | no-self-module-alias>
code:      <LAYERING-1 | LAYERING-2>
file:      <path as the rule normalized it, or "not read" for LAYERING-1>
alias:     <@modules/ | @features/ | @tests/ | none matched>
self keys: <derived capability keys, or "none: file is outside every root">
segments:  <parts.length vs barrelDepth, for LAYERING-1>
message:   <barrel | self>
verdict:   <fires | silent: hatch <name from the Open table>>

Một tệp sạch xuất đúng một khối với message: none và verdict: silent: no hatch — every static specifier was read and none matched. Một tệp ngoài phạm vi của no-self-module-alias xuất self keys: none: file is outside every root cùng verdict: silent: no visitor installed, và đó không phải là một lần qua.

Ví dụ đã giải

Đầu vào. src/modules/ai/ai-invoke.service.ts:

import { Injectable } from "@nestjs/common"
import { AiService } from "@modules/ai"
import { BillingService } from "@modules/billing"
 
export * from "@modules/platform"
 
@Injectable()
export class AiInvokeService {
  constructor(
    private readonly ai: AiService,
    private readonly billing: BillingService,
  ) {}
}

Tệp nằm dưới /src/modules/, nên no-self-module-alias tìm thấy root và suy ra khoá tự thân ["ai"]. must-deep-module-import có phạm vi ở khắp nơi và không bao giờ đọc đường dẫn.

rule:      must-deep-module-import
code:      LAYERING-1
file:      not read
alias:     @modules/
self keys: n/a
segments:  1 vs barrelDepth 1
message:   barrel
verdict:   fires

rule:      no-self-module-alias
code:      LAYERING-2
file:      src/modules/ai/ai-invoke.service.ts
alias:     @modules/
self keys: ["ai"]
segments:  n/a
message:   self
verdict:   fires

Hai khối đó là cùng một dòng, @modules/ai. Chúng là hai phép kiểm độc lập tình cờ đồng ý với nhau.

rule:      must-deep-module-import
code:      LAYERING-1
file:      not read
alias:     @modules/
self keys: n/a
segments:  1 vs barrelDepth 1
message:   barrel
verdict:   fires

Đó là @modules/billing. Còn export * from "@modules/platform" được thăm như một ExportAllDeclaration, và platform là một thư mục nhóm đứng một mình:

rule:      must-deep-module-import
code:      LAYERING-1
file:      not read
alias:     @modules/
self keys: n/a
segments:  1 vs barrelDepth 2
message:   barrel
verdict:   fires

@nestjs/common không khớp tiền tố alias nào nên không bao giờ bị soi tới.

Đã sửa. Alias tự trỏ đổi thành đường tương đối, mỗi import liên năng lực gọi tên tệp khai báo, và dòng tái xuất gọi tên một tệp nằm dưới thư mục nhóm:

import { Injectable } from "@nestjs/common"
import { AiService } from "./ai.service"
import { BillingService } from "@modules/billing/billing.service"
 
export * from "@modules/platform/exceptions/domain.exception"
 
@Injectable()
export class AiInvokeService {
  constructor(
    private readonly ai: AiService,
    private readonly billing: BillingService,
  ) {}
}

Có một cửa mở sống sót qua lần sửa này. Thêm một dòng nữa là đường nối biến mất mà không phát hiện nào nổ:

import { BillingRepository } from "../billing/billing.repository"

rule:      no-self-module-alias
code:      LAYERING-2
file:      src/modules/ai/ai-invoke.service.ts
alias:     none matched
self keys: ["ai"]
segments:  n/a
message:   none
verdict:   silent: hatch reaching into another capability relatively — no alias prefix, so neither rule inspects the specifier and the boundary crossing is invisible

Sự im lặng đó không phải là tuân thủ. Cũng dòng import ấy viết thành @modules/billing/billing.repository thì vượt đúng cái ranh giới đó và đọc lên y hệt với mắt người; chỉ có cách đánh vần là khác.

Phạm vi

Mô-đun này ghi lại phần cưỡng chế của hai quy tắc thuộc một luật back-end, không ghi lại luật. Nó không phán chuyện một barrel có được phép viết ra hay không — nửa bên khai báo của LAYERING-5 không có máy giữ — cũng không phán chuyện một năng lực đáng lẽ phải được nối dây ở composition root thay vì import thẳng, tức LAYERING-3 và LAYERING-4, hai mã không gì giữ và thuộc về một cổng duyệt cây mà mô-đun này không chứa. Nó không gọi tên sản phẩm, công ty hay kho mã nào. Tên quy tắc, định danh thông điệp, tiền tố alias và tên thư mục mà các quy tắc so khớp là những định danh có xuất xưởng và được chép lại nguyên văn; miễn trừ đó không phủ thêm gì khác.