Xây codebase dùng chung cho team Laravel

CV ghi một dòng: "Xây dựng codebase để team có thể tái sử dụng, kiến trúc thư mục code (modular, thêm lớp service giữa controller và model)". Interviewer sẽ hỏi dồn vào đúng dòng đó, và câu hỏi khó nhất không phải "anh chia thư mục thế nào" mà là "làm sao anh biết team thật sự dùng lại, chứ không phải copy-paste rồi sửa?" và "chỗ nào anh đã trừu tượng hoá quá sớm?".

Bài này đi từ cấu trúc thư mục → cách ép tuân thủ bằng máy → chỗ nó gãy. Bối cảnh xuyên suốt: LMS micro-learning, Laravel 12 + Livewire, một repo monolith, team 4 – 7 developer (có fresher), release 2 – 3 lần/tuần.

Thuật ngữ dùng trong bài

Môi trường kiểm chứng. Mọi output trong bài chạy thật trên Laravel 12.64.0 + PHP 8.3.33 + PHPUnit 11.5.56 + Composer (container laravel-app). Lab dựng ở /tmp/lab bên trong container: copy code project, symlink vendor/, database SQLite riêng — không đụng chiennn_commerce_postgres và không đụng source project thật. Số đo thời gian chạy trên máy dev qua Docker — đọc tỉ lệ, đừng đọc số tuyệt đối.

Modular monolith giải quyết bài toán gì (so với chỉ thêm Service layer)

Câu hỏi đầu tiên interviewer hay hỏi ngược lại: "Laravel đã có sẵn app/Models, app/Http/Controllers; anh thêm app/Services là xong rồi, tách module để làm gì cho mệt?". Trả lời đúng phải thấy được: hai thứ đó cắt codebase theo hai chiều khác nhau, không thay thế nhau.

• Service layer cắt ngang — theo vai trò kỹ thuật: controller / service / model. Nó trả lời câu "logic này để ở tầng nào".
• Module cắt dọc — theo mảng nghiệp vụ: Learning / Billing / Reporting. Nó trả lời câu "code này của ai, và ai được phép gọi".

Thêm Service layer mà vẫn để cấu trúc phẳng thì bạn đã trả lời câu thứ nhất và bỏ trống câu thứ hai. Hậu quả không thấy ngay lúc 20 file, nó hiện ra ở khoảng 100 file trở đi.

Bốn bài toán Service layer một mình không giải được

Điểm cần nói rõ khi phỏng vấn: module không thay thế service layer. Service layer vẫn nằm nguyên bên trong mỗi module (modules/Learning/Services/). Module chỉ thêm đúng một thứ mà cấu trúc phẳng không có: một ranh giới có tên, có chủ, và ép được bằng máy.

Cái giá phải trả, và khi nào đừng tách

Khi nào KHÔNG tách module. App dưới ~30 – 40 class service, team 1 – 3 người, chỉ một mảng nghiệp vụ, hoặc domain còn đang thay đổi mỗi tuần → cứ để cấu trúc Laravel mặc định + service layer. Ngưỡng nên tách là khi một trong ba dấu hiệu xuất hiện: (1) hai người trở lên thường xuyên sửa đè lên nhau trong cùng một thư mục; (2) không ai dám xoá một file vì không biết ai đang dùng; (3) bắt đầu có nhu cầu "phần này giao cho team khác/tách ra sau này". Tách vì "kiến trúc cho đẹp" mà chưa có dấu hiệu nào là trừu tượng hoá quá sớm — đúng cái lỗi mục 3 nói.

Câu trả lời một câu: "Service layer giải quyết chuyện logic nằm ở tầng nào; module giải quyết chuyện logic thuộc về ai và ai được gọi nó. Tôi cần cái thứ hai vì team 4 – 7 người có fresher, và vì tôi muốn luật ranh giới do CI giữ chứ không do tôi nhớ lúc review."

1. Nó là gì / chạy thế nào

1.1. "Codebase dùng chung" gồm ba tầng, đừng gộp làm một

Câu hỏi "xây codebase dùng chung thế nào" thật ra là ba câu hỏi khác nhau, chi phí khác hẳn nhau:

flowchart TB
  T1["Tầng 1 — trong một module
trait, scope, Blade component, helper
Chi phí đổi: sửa 1 file, review 5 phút"]
  T2["Tầng 2 — giữa các module, cùng repo
Contracts + DTO + service container
Chi phí đổi: 1 MR, CI chạy lại, cả team pull"]
  T3["Tầng 3 — giữa nhiều repo
package Composer nội bộ + version
Chi phí đổi: tag version, n repo bump, n lần deploy"]
  T1 --> T2 --> T3
  N["Càng xuống dưới, đổi càng đắt
→ chỉ xuống khi đã đau thật"]
  T3 -.-> N

Sai lầm hay gặp của lead mới: nhảy thẳng lên tầng 3 ("tách package cho pro") khi cả công ty mới có một repo. Lúc đó mỗi lần sửa một dòng helper phải: commit package → tag → bump version ở app → chạy composer update → deploy. Đổi lấy được gì? Không gì cả, vì chỉ có một người dùng nó.

1.2. Cấu trúc thư mục: module là một thư mục có service provider riêng

Không cần package bên ngoài. Laravel đã có sẵn đủ thứ: PSR-4 của Composer + một service provider cho mỗi module.

app/                      # code khung: Providers, Exceptions, base class
modules/
  Learning/
    Contracts/            # CỬA TRƯỚC — module khác chỉ được import từ đây
      EnrollmentReader.php
    Data/                 # CỬA TRƯỚC — DTO đi qua ranh giới
      EnrollmentData.php
    Domain/               # ruột: Eloquent model, business object
    Services/             # nghiệp vụ nhiều bước
    Http/                 # Controller, Livewire component, FormRequest
    Providers/LearningServiceProvider.php
    routes/web.php
    resources/views/
    database/migrations/
    tests/
  Billing/
  Reporting/

Service provider của module chỉ có đúng ngần này — không có gì thông minh hơn:

<?php

namespace Modules\Learning\Providers;

use Illuminate\Support\ServiceProvider;

class LearningServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        $this->loadRoutesFrom(__DIR__."/../routes/web.php");
        $this->loadViewsFrom(__DIR__."/../resources/views", "learning");
        $this->loadMigrationsFrom(__DIR__."/../database/migrations");
    }
}

Hai chỗ khai báo, làm một lần rồi thôi:

// composer.json
"autoload": {
    "psr-4": {
        "App\\": "app/",
        "Modules\\": "modules/"
    }
}

// bootstrap/providers.php  (Laravel 11+)
return [
    App\Providers\AppServiceProvider::class,
    Modules\Learning\Providers\LearningServiceProvider::class,
];

Chạy thật trong lab — route, view namespace và migration của module đều được nhận:

$ composer dump-autoload
Generated optimized autoload files containing 8106 classes

$ php artisan route:list --path=learning
  GET|HEAD  learning/ping  learning.ping › modules/Learning/routes/web.php

$ php artisan tinker --execute="echo view('learning::ping')->render();"
pong from module

$ php artisan migrate:status | grep learning
  2026_01_01_000000_learning_demo ......................... Pending

Đây là toàn bộ "framework module" mà team cần. Khoảng 15 dòng code. Câu hỏi interviewer hay gài: "sao không dùng nwidart/laravel-modules?" — trả lời ở mục 4 (Trade-off): package đó thêm generator, cấu hình, cách đặt tên riêng và một lớp phải nâng cấp mỗi lần Laravel lên major. Đổi lại nó thay thế đúng 15 dòng trên.

1.3. Một request đi qua những tầng nào

sequenceDiagram
  autonumber
  participant U as Browser / Livewire
  participant C as Controller / Livewire component
  participant FR as FormRequest (validate)
  participant S as Service / Action
  participant M as Eloquent model
  participant EV as Event + Listener (queue)

  U->>C: POST /enroll
  C->>FR: rules() + authorize()
  FR-->>C: dữ liệu đã sạch
  C->>S: EnrollStudent::handle(EnrollmentData)
  S->>M: transaction: insert + update
  M-->>S: Enrollment
  S->>EV: StudentEnrolled (dispatch sau commit)
  S-->>C: EnrollmentData
  C-->>U: redirect / render
  EV-->>EV: gửi mail, cập nhật báo cáo — worker chạy

Quy ước ngắn gọn dán ở đầu CONTRIBUTING.md, và đây cũng là checklist review:

Luật "service không được đụng request()" nghe khô khan nhưng chính nó làm code dùng lại được: cùng một EnrollStudent gọi được từ controller web, từ Livewire, từ artisan command import Excel, và từ test — không cần giả lập HTTP request.

1.4. Cái gì đáng đưa vào "core dùng chung", cái gì không

Câu chốt khi bị hỏi "team anh có base class không": "Có, nhưng chỉ base class ép ràng buộc (strict model, format lỗi, tenant scope), không có base class gom nghiệp vụ. Base nghiệp vụ là chỗ cả team đổ code vào rồi không ai dám xoá."

1.5. Ranh giới thật: Contracts + container binding

Module Billing cần biết một khoá học có bao nhiêu sinh viên đang học. Hai cách viết:

// CÁCH SAI — Billing thò tay vào ruột Learning
use Modules\Learning\Domain\Enrollment;   // model của module khác

$count = Enrollment::where("course_id", $id)->where("status", "active")->count();

Hỏng ở chỗ: ngày Learning đổi cột status thành bảng riêng, Billing gãy mà người sửa Learning không hề biết. Grep "ai đang dùng bảng này" thì ra 30 chỗ rải khắp repo.

// CÁCH ĐÚNG — Learning mở một cửa trước
namespace Modules\Learning\Contracts;

interface EnrollmentReader
{
    public function countActive(int $courseId): int;
}

// Learning tự làm phần ruột
namespace Modules\Learning\Services;

class EloquentEnrollmentReader implements EnrollmentReader
{
    public function countActive(int $courseId): int
    {
        return Enrollment::where("course_id", $courseId)->active()->count();
    }
}

// LearningServiceProvider::register()
$this->app->bind(EnrollmentReader::class, EloquentEnrollmentReader::class);

// Billing chỉ type-hint interface, không biết Learning dùng bảng nào
namespace Modules\Billing\Domain;

class InvoiceBuilder
{
    public function __construct(private EnrollmentReader $enrollments) {}
}

Được gì cụ thể: đổi cách lưu bên Learning → sửa một class; test InvoiceBuilder → nhét fake vào container, không cần seed bảng enrollment; và quan trọng nhất — grep EnrollmentReader ra đúng danh sách người phụ thuộc.

Mất gì: thêm một file interface cho mỗi cửa. Nên chỉ mở cửa khi có module khác thật sự cần — không phải viết interface cho mọi service.

1.5.1. Cửa trước trả gì, nhận gì

Ví dụ ở trên trả về int nên chưa lộ vấn đề. Câu hỏi thật là khi cửa phải trả về cả một bản ghi — lúc đó trả thẳng Eloquent model hay trả DTO? Chốt trước, giải thích sau:

Vì sao không trả model: chữ ký hàm tự làm thủng ranh giới

Lý do mạnh nhất không phải "DTO sạch hơn", mà là chính dòng use trong file interface:

namespace Modules\Learning\Contracts;

use Modules\Learning\Domain\Enrollment;   // <-- ngay dòng này

interface EnrollmentReader
{
    public function find(int $id): Enrollment;   // Billing buộc phải import Enrollment
}

Billing type-hint Enrollment ở chỗ nhận giá trị → architecture test ở mục 1.6 bắt ngay, vì use Modules\Learning\Domain\... xuất hiện trong file của Billing. Tức là cửa trước mở ra đúng cái ruột mà nó định giấu. Cửa trả model là cửa không có cánh.

Viết đúng thì cửa không import Domain\ một dòng nào:

namespace Modules\Learning\Data;

final readonly class EnrollmentSummary
{
    public function __construct(
        public int $id,
        public int $courseId,
        public int $studentId,
        public string $status,
    ) {}
}

// Contracts\EnrollmentReader — không có use Domain\...
public function countActive(int $courseId): int;        // scalar đủ thì đừng đẻ DTO
/** @return list<EnrollmentSummary> */
public function summaries(array $courseIds): array;

Parameter: luật đối xứng, nhưng khác một chỗ

// SAI — Learning phải import model của Billing để khai interface của chính mình
public function enroll(Invoice $invoice, Student $student): void;

// SAI — nhận Builder/Collection/Request: lộ trạng thái query và tầng HTTP ra ngoài
public function search(Builder $query): array;

// SAI — array không type: Larastan mù, gõ sai key trả null âm thầm
public function enroll(array $payload): int;

// ĐÚNG — id thô, hoặc DTO do chính Learning định nghĩa
public function enroll(EnrollmentData $data): int;      // trả id, KHÔNG trả model vừa tạo

Khác biệt so với return: DTO tham số vẫn thuộc module sở hữu cửa (Learning), không phải bên gọi. Learning công bố hình dạng dữ liệu nó chịu nhận; Billing import Modules\Learning\Data\EnrollmentData. Nếu để Billing tự định nghĩa DTO rồi ném sang thì hướng phụ thuộc lộn ngược — Learning phải biết Billing.

Khi nào gộp tham số thành DTO:

// Bom nổ chậm: 5 tham số, 2 bool, gọi sai thứ tự vẫn chạy được
enroll(int $courseId, int $studentId, bool $trial, bool $notify, ?string $note)

// Gộp: named arguments + readonly, sai kiểu là IDE đỏ ngay
enroll(new EnrollmentData(courseId: 10, studentId: 3, trial: true))

Validate vẫn phải nằm trong module sở hữu. DTO có type không thay thế được validate nghiệp vụ (khoá học còn chỗ không, sinh viên có bị khoá không). Đây là trust boundary (ranh giới tin cậy — chỗ dữ liệu từ bên ngoài đi vào), không được bỏ vì "bên gọi chắc đã check rồi".

Khi DTO bí: đổi hình dạng cửa, đừng trả model

Màn hình báo cáo cần lọc + sắp xếp + phân trang theo cột của module khác thì DTO không cứu được — không lọc trong SQL được nữa (chính là bảng "Mất gì ở mức C" ở mục 1.9). Lối thoát không phải là trả model ra, mà là để cửa nhận tiêu chí thay vì trả dữ liệu:

// Learning giữ SQL trong ruột nó; Billing chỉ mô tả cái nó muốn
public function search(EnrollmentCriteria $criteria): PaginatedResult;

Chốt để trả lời phỏng vấn: "Cửa trả scalar nếu đủ, còn lại trả readonly DTO. Không trả Eloquent model, lý do không phải cho sạch mà vì chữ ký hàm buộc bên gọi import model của module khác — đúng thứ architecture test đang cấm. Tham số cũng vậy, và DTO tham số do bên sở hữu cửa định nghĩa để hướng phụ thuộc không lộn ngược. Ngoại lệ là User vì nó là shared kernel. Cần lọc/sắp xếp xuyên module thì đổi cửa thành nhận tiêu chí, chứ không mở ruột ra."

1.6. Ép tuân thủ bằng máy, không bằng lời nhắc trong review

Quy ước chỉ nằm trong tài liệu thì 3 tháng sau là tài liệu sai. Ba lớp chặn, chạy trong CI:

flowchart LR
  A["git push"] --> B["Pint
--test
format code"]
  B --> C["Larastan level 6
bắt type, null, method không tồn tại"]
  C --> D["Architecture test
ranh giới module"]
  D --> E["PHPUnit
nghiệp vụ"]
  E --> F["Merge được"]
  B -->|"fail"| X["pipeline đỏ
không ai phải nhắc trong review"]
  C -->|"fail"| X
  D -->|"fail"| X

Lớp thứ ba — architecture test — là thứ ít team làm nhất mà lại rẻ nhất. Nó là một test PHPUnit thuần, không boot app, chạy hết 9 ms:

<?php

namespace Tests\Architecture;

use PHPUnit\Framework\TestCase;
use RecursiveDirectoryIterator as Dir;
use RecursiveIteratorIterator as Walk;

class ModuleBoundaryTest extends TestCase
{
    /** Module chỉ được gọi module khác qua lớp công khai: Contracts\ hoặc Data\ */
    public function test_modules_only_depend_on_public_layers(): void
    {
        $root = dirname(__DIR__, 2)."/modules";
        $violations = [];

        foreach (new Walk(new Dir($root, Dir::SKIP_DOTS)) as $file) {
            if ($file->getExtension() !== "php") continue;
            $self = explode("/", substr($file->getPathname(), strlen($root) + 1))[0];
            preg_match_all("/^use\s+Modules\\\\(\w+)\\\\([\w\\\\]+);/m", file_get_contents($file), $m, PREG_SET_ORDER);
            foreach ($m as [$line, $target, $rest]) {
                if ($target === $self || preg_match("/^(Contracts|Data)\\\\/", $rest)) continue;
                $violations[] = str_replace("$root/", "", $file->getPathname())."  =>  ".trim($line);
            }
        }

        $this->assertSame([], $violations, "Module gọi thẳng vào ruột module khác:\n".implode("\n", $violations));
    }
}

Chạy thật với một vi phạm cố ý (Billing import model của Learning):

$ php vendor/bin/phpunit tests/Architecture/ModuleBoundaryTest.php
PHPUnit 11.5.56 by Sebastian Bergmann and contributors.
F                                                          1 / 1 (100%)
Time: 00:00.017, Memory: 10.00 MB

1) Tests\Architecture\ModuleBoundaryTest::test_modules_only_depend_on_public_layers
Module gọi thẳng vào ruột module khác:
Billing/Domain/InvoiceBuilder.php  =>  use Modules\Learning\Domain\Enrollment;

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

Sau khi đổi sang use Modules\Learning\Contracts\EnrollmentReader;:

$ php vendor/bin/phpunit tests/Architecture/ModuleBoundaryTest.php
.                                                          1 / 1 (100%)
Time: 00:00.009, Memory: 10.00 MB
OK (1 test, 1 assertion)

27 dòng, không thêm dependency nào. Có package làm việc này đẹp hơn (pestphp/pest-plugin-arch, deptrac) — đáng thêm khi số luật vượt quá 5 – 6 và bắt đầu cần whitelist ngoại lệ. Trước đó thì một file test là đủ, và nó không bao giờ vỡ khi Laravel lên version mới.

1.7. Base model: bật strict cho cả team bằng một dòng

Việc dùng chung có giá trị nhất không phải là class tiện ích, mà là ràng buộc bật một lần cho toàn bộ code. Model::shouldBeStrict() bật ba chốt cùng lúc. Chạy thật:

// app/Providers/AppServiceProvider::boot()
Model::shouldBeStrict(! $this->app->isProduction());

$ php strict.php     # Laravel 12.64.0, SQLite lab
1) Illuminate\Database\LazyLoadingViolationException: Attempted to lazy load [lessons]
   on model [TmpCourse] but lazy loading is disabled.
2) Illuminate\Database\Eloquent\MissingAttributeException: The attribute [title] either
   does not exist or was not retrieved for model [TmpCourse].
3) Illuminate\Database\Eloquent\MassAssignmentException: Add fillable property
   [khong_co_trong_fillable] to allow mass assignment on [TmpCourse].

Ba lỗi này bắt được đúng ba thói quen hay gặp của dev mới: N+1, select() thiếu cột rồi đọc bừa, và nhét thẳng $request->all() vào create().

Bẫy 1 — strict mode không bắt khi query trả về đúng 1 dòng. Đọc source Laravel 12 (Eloquent/Builder.php, hàm hydrate):

$model = $instance->newFromBuilder($item);

if (count($items) > 1) {                                   // <-- điều kiện ở đây
    $model->preventsLazyLoading = Model::preventsLazyLoading();
}

Tức là lazy load trên kết quả một dòng không bị chặn (hợp lý: một dòng thì không có N+1). Hệ quả thực tế: dev test local với 1 bản ghi thấy "chạy ngon", lên staging có 3 bản ghi thì nổ LazyLoadingViolationException. Lab xác nhận đúng như vậy: 1 course → im lặng; 2 course → ném exception.

Bẫy 2 — Laravel 12 có automaticallyEagerLoadRelationships(), bật lên là strict mode câm. Chạy thật, bật cả hai cùng lúc:

$ php autoload_eager.php
OK - khong nem exception
So query chay: 2
  - select * from "tmp_courses"
  - select * from "tmp_lessons" where "tmp_lessons"."tmp_course_id" in (1, 2, 3)

Laravel tự gom thành eager load nên không còn vi phạm để mà ném. Nghe thì hay, nhưng ở codebase dùng chung phải chọn một triết lý: hoặc để dev thấy lỗi và tự viết with() (nhìn được truy vấn), hoặc để framework tự gom (êm hơn, nhưng dev không bao giờ học được và không kiểm soát được thứ tự truy vấn). Team tôi chọn cách 1 cho dev/staging vì đội có fresher — mục tiêu là dạy, không phải giấu.

1.8. Khi nào mới tách package Composer nội bộ

Tách khi repo thứ hai cần cùng một đoạn code (ví dụ: LMS Laravel và một dịch vụ NestJS-đi-kèm-PHP-worker dùng chung cách ký JWT, cùng format mã sinh viên). Lúc phát triển, dùng path repository để không phải đẩy lên server:

// composer.json của app
"repositories": [
    { "type": "path", "url": "packages/support" }
],
"require": { "onschool/support": "@dev" }

// packages/support/composer.json — auto-discovery
{
    "name": "onschool/support",
    "autoload": { "psr-4": { "OnSchool\\Support\\": "src/" } },
    "extra": {
        "laravel": {
            "providers": ["OnSchool\\Support\\SupportServiceProvider"]
        }
    }
}

$ composer update onschool/support
  - Installing onschool/support (dev-main bdd26d3): Symlinking from packages/support

$ php artisan package:discover
  onschool/support ...................................... DONE

$ php artisan tinker --execute="echo Str::maSinhVien(42);"
SV000042

Bẫy 3 — CI chạy composer install --no-scripts thì package nội bộ chết âm thầm. Đúng lỗi tôi gặp trong lab: cài xong, class có, autoload có, nhưng service provider chưa được discover → macro không tồn tại → BadMethodCallException: Method Illuminate\Support\Str::maSinhVien does not exist ngay lúc chạy, không phải lúc build. Nếu pipeline dùng --no-scripts (nhiều team bật để tránh script lạ chạy trong CI) thì phải gọi tay php artisan package:discover trong Dockerfile, hoặc khai thẳng provider vào bootstrap/providers.php.

1.9. Model dùng chung (User) — tách module hay không, và Eloquent mất gì

Đây là câu hỏi đầu tiên mọi người vấp khi chia module, vì User là thứ module nào cũng cần: Billing cần email để gửi hoá đơn, Learning cần biết ai đang học, Reporting cần tên để in báo cáo. Câu hỏi đi kèm luôn là: "tách ra rồi thì có còn $invoice->user->email nữa không?"

Trả lời ngắn: Eloquent không hề biết khái niệm "module". Nó phân giải quan hệ bằng tên class đầy đủ (FQN) và khoá ngoại — namespace nằm ở đâu không liên quan. Cái làm mất relationship không phải việc tách thư mục, mà là luật do chính mình đặt ra ở mục 1.5 (cấm import ruột module khác) cộng với architecture test ở mục 1.6 thi hành nó.

Chạy thật: quan hệ xuyên module vẫn hoạt động

Lab khai báo Modules\Identity\Domain\User và Modules\Billing\Domain\Invoice ở hai namespace khác nhau, rồi eager load:

// modules/Billing/Domain/Invoice.php
public function user(): BelongsTo
{
    return $this->belongsTo(\Modules\Identity\Domain\User::class, 'user_id');
}

Invoice::with('user:id,name,email')->where('status', 'unpaid')->get();

### 1. belongsTo xuyên module (Billing -> Identity) + eager load
class Invoice : Modules\Billing\Domain\Invoice
class User    : Modules\Identity\Domain\User
số query      : 2
  SQL: select * from "invoices" where "status" = ?
  SQL: select "id", "name", "email" from "users" where "users"."id" in (1, 2, 3, 4, 5)
đọc được      : u1@test.vn

Và whereHas — thứ đắt giá nhất — vẫn gom được về một câu SQL, tức là lọc theo cột của User mà không phải bê dữ liệu về PHP:

### 2. whereHas + join xuyên module — lọc theo cột của User trong 1 câu SQL
số query : 1
SQL      : select * from "invoices" where exists (select * from "users"
           where "invoices"."user_id" = "users"."id" and "email" like ?)
kết quả  : 1 hoá đơn (user_id=3)

Ba mức tách — chọn mức nào

Mức A không phải chọn cho lười — nó đúng lý thuyết. Thực thể mà mọi module đều phải tham chiếu chính là định nghĩa của shared kernel (phần lõi chia sẻ có chủ ý). Ép nó thành module thường là ép sai hình. Tiện lợi kèm theo: architecture test ở mục 1.6 chỉ quét use Modules\..., nên App\Models\User tự động hợp lệ, không phải viết thêm một dòng whitelist nào.

Cái đáng tách là hành vi, không phải bảng

Bệnh thật của User không phải "nằm sai thư mục" mà là phình: mỗi module nhét thêm vài method, ba năm sau User.php 800 dòng, đụng vào là sợ. Cách chữa: mỗi module giữ bảng mở rộng của riêng nó, quan hệ trỏ một chiều từ module vào User.

// modules/Billing/Domain/BillingProfile.php   — bảng billing_profiles
class BillingProfile extends Model
{
    public function user(): BelongsTo            // Billing -> User: được phép
    {
        return $this->belongsTo(User::class, 'user_id');
    }
}

Chú ý: User không có method billingProfile(). Billing tự query từ phía nó. Nếu thật sự cần viết $user->billingProfile cho gọn, Laravel có sẵn đường chính thống để module gắn quan hệ vào model của người khác mà không sửa file User.php — doc yêu cầu luôn ghi rõ tên khoá:

// modules/Billing/Providers/BillingServiceProvider::boot()
User::resolveRelationUsing('billingProfile', fn (User $u) =>
    $u->hasOne(BillingProfile::class, 'user_id', 'id')
);

### 4. resolveRelationUsing — module tự gắn quan hệ vào User, không sửa User.php
$u1->billingProfile->tax_code = MST-001
eager load được luôn : 2 query

Giá của resolveRelationUsing: quan hệ chỉ tồn tại lúc chạy, nên IDE không gợi ý và Larastan không nhìn thấy → phải khai @property-read trong PHPDoc của User, tức là User vẫn phải biết tên module. Mặc định nên để quan hệ một chiều (chỉ BillingProfile->user()) cho dễ đọc; dùng resolveRelationUsing khi viết package thật sự.

Nếu vẫn chọn mức C — giá phải trả, đo trong lab

Ở mức C, Billing không được biết class User nữa, nên phải tự làm lại việc mà with() vẫn làm hộ: lấy danh sách id → gọi Contract → ghép dữ liệu vào. Chỉ cần quên bước "gọi một lần cho cả danh sách" là N+1 quay lại ngay:

// ĐÚNG — gọi Contract một lần cho cả danh sách rồi tự ghép
$invoices = Invoice::where('status', 'unpaid')->get();
$users = $userReader->findMany($invoices->pluck('user_id')->all());
$invoices->each(fn ($i) => $i->setAttribute('user_data', $users[$i->user_id] ?? null));

// SAI — hỏi từng dòng
$invoices->each(fn ($i) => $i->setAttribute('user_data', $userReader->find($i->user_id)));

### 3. Mức C (cấm import model) — thay eager load bằng 2 query + hydrate
ĐÚNG  (findMany) : 2 query
SAI   (find/dòng): 6 query  <-- N+1 quay lại
thay whereHas    : 2 query, phải bê 2 bước sang PHP

Hai dòng giữa là lý do thật khiến mức C sập ở dự án có màn hình báo cáo. Khi nào mức C đáng? Khi bảng users sắp nằm ở database khác — lúc đó join vốn đã không còn, trả giá sớm là hợp lý.

Bốn cái bẫy phải biết trước khi di chuyển User

Bẫy 1 — polymorphic lưu nguyên FQN vào database. Đây là bẫy chết người nhất khi đổi namespace, vì hỏng ở dữ liệu chứ không phải ở code:

### 5. Polymorphic — FQN trong DB vs enforceMorphMap
CHƯA morph map, cột notable_type lưu:
  Modules\Identity\Domain\User
SAU enforceMorphMap:
  user
model chưa đăng ký -> ClassMorphViolationException:
  No morph map defined for model [Modules\Billing\Domain\Invoice].

đọc ngược morph alias: Relation::getMorphedModel('user') = Modules\Identity\Domain\User
dữ liệu cũ còn FQN   : Modules\Identity\Domain\User <-- phải UPDATE khi bật morph map

// AppServiceProvider::boot() — dùng enforceMorphMap, KHÔNG dùng morphMap
Relation::enforceMorphMap([
    'user'    => \Modules\Identity\Domain\User::class,
    'invoice' => \Modules\Billing\Domain\Invoice::class,
]);

Khác nhau một chữ nhưng quan trọng: morphMap() gặp model chưa khai thì im lặng ghi FQN vào database; enforceMorphMap() ném ClassMorphViolationException ngay — hỏng lúc test, không hỏng lúc 3 giờ sáng. Dòng cuối của output là phần hay bị quên: bật morph map không sửa dữ liệu cũ, phải có migration UPDATE ... SET notable_type = 'user' WHERE notable_type = '...' cho mọi bảng morph (notifications, activity_log, media, comments…).

Bẫy 2 — job đang nằm trong queue giữ FQN cũ. SerializesModels không lưu cả model, nó lưu một ModelIdentifier — và trong đó có tên class:

### 6. Job trong queue giữ FQN của model — bẫy khi đổi namespace
O:36:"Modules\Billing\Jobs\SendInvoiceMail":1:{s:4:"user";
  O:45:"Illuminate\Contracts\Database\ModelIdentifier":5:{
    s:5:"class";s:28:"Modules\Identity\Domain\User";s:2:"id";i:1; ... }}

Deploy đổi namespace trong lúc queue còn hàng → worker bốc job cũ lên → ClassNotFoundException, job rơi vào failed_jobs. Cách xử lý: để queue cạn trước khi deploy, hoặc giữ một class rỗng ở namespace cũ class_alias() sang tên mới trong một release, release sau mới xoá.

Bẫy 3 — config/auth.php trỏ thẳng tên class. 'model' => App\Models\User::class. Đổi chỗ mà quên sửa thì ở máy dev vẫn chạy (config chưa cache), chết sau php artisan config:cache trên production. Grep User::class trước khi di chuyển: config/auth.php, policy, Route::model binding, factory, seeder.

Bẫy 4 — thứ tự migration và khoá ngoại. invoices.user_id có FK trỏ users.id nên bảng users phải được tạo trước. Module nạp theo thứ tự trong bootstrap/providers.php, mà thứ tự đó dễ bị sửa nhầm khi thêm module. Cách rẻ nhất là giữ migration create_users_table ở database/migrations gốc, không đẩy vào module — đúng tinh thần "shared kernel".

Chốt để trả lời phỏng vấn: "Không tách User thành module thường — nó là shared kernel, để ở app/Models, ai cũng import được. Cái tách là hành vi: mỗi module giữ bảng profile riêng và quan hệ đi một chiều vào User, nên User không phình. Tách module không làm mất relationship Eloquent — Eloquent chỉ cần tên class. Cái mất là do luật mình tự đặt: cấm import thì mất luôn whereHas và orderBy xuyên bảng, và đó mới là thứ đắt. Chỉ trả giá đó khi users sắp sang database khác."

2. Lợi ích

Điểm hay để nói trong phỏng vấn: lợi ích lớn nhất không phải tiết kiệm dòng code, mà là giảm số quyết định mà mỗi dev phải tự nghĩ ra. Fresher không phải chọn "validate ở đâu", "transaction đặt ở đâu", "đặt tên file thế nào" — những chỗ đó đã có một đường mòn.

3. Tác hại / hạn chế

3.1. Cái giá thật: viết chậm hơn, nhiều file hơn — và phiên bản rẻ

Câu team hay kêu, và đúng tới đâu. Không né:

Chỗ hay hiểu sai, và nó đổi toàn bộ phép tính

Luật "chỉ gọi qua Contracts\" áp dụng ở ranh giới, không áp dụng trong ruột module. Trong một module vẫn viết Laravel bình thường: controller → model → Blade, Eloquent thẳng, không DTO, không interface.

flowchart LR
  A["Việc hằng ngày"] --> B["Trong 1 module
~80-90% số task"]
  A --> C["Xuyên module
~10-20% số task"]
  B --> D["Eloquent thẳng
Không DTO, không interface
KHÔNG chậm dòng nào"]
  C --> E["Contracts + DTO
Chậm ở đây thôi"]

Nếu team thấy chậm ở mọi feature thì luật đang bị áp dụng sai chỗ: viết interface cho mọi service, DTO cho mọi hàm. Đó là trừu tượng hoá quá sớm (dòng đầu bảng trên), không phải modular monolith. Số phần trăm ở trên là ước lượng minh hoạ cho một LMS cỡ vừa — đo bằng cách đếm số MR đụng từ 2 module trở lên trong một sprint.

Khi nào cái giá này KHÔNG đáng — nói thẳng

• Team ≤ 3 người, ai cũng biết hết codebase → đừng làm, grep là đủ.
• Domain còn đổi mô hình hàng tuần → vẽ ranh giới sai thì DTO sai theo, sửa đắt gấp đôi. Chờ ổn định.
• Không có architecture test canh → trả tiền mà không nhận hàng: luật không có máy canh thì 2 tháng sau không còn tồn tại.
• App gần như không có màn hình báo cáo / join xuyên bảng → vẫn dùng được, nhưng lợi ích nhỏ hơn nhiều.

Phiên bản rẻ: leo thang, đừng nhảy thẳng lên đỉnh

Hai cách cắt chi phí mà không bỏ luật:

1. Stub generator. Một lệnh artisan sinh sẵn interface + implementation + DTO + dòng binding. "Nhiều file" biến thành "một lệnh" — cái đắt là số khái niệm phải nhớ, không phải số file trên đĩa.
2. DTO viết tay 8 dòng, đừng thêm package. final readonly class + constructor property promotion là đủ. Chỉ kéo spatie/laravel-data vào khi thật sự cần cast + validation + dựng từ Request ở nhiều chỗ; dưới mức đó nó là dependency thừa.

"Code trông khó đọc" — nó không mất đi, nó đổi chỗ

Đổi này chỉ lời khi câu hỏi thứ hai được hỏi thường xuyên — tức là team đông, code sống lâu, nhiều người sửa chéo nhau. Team nhỏ ít khi hỏi câu đó, nên áp luật vào là lỗ. Đây cũng là câu trả lời thẳng thắn nên nói trong phỏng vấn, thay vì kể lợi ích một chiều.

Một nỗi lo phổ biến nhưng sai chỗ: "chia nhiều module làm app chậm"

Đo thật trong lab — thêm 30 module, mỗi module một service provider có loadRoutesFrom + loadViewsFrom, lấy median 10 lần bootstrap:

Chênh lệch nằm trong nhiễu đo. Nói cách khác: số module gần như không phải là thứ làm chậm app; cái làm chậm là số route lớn chưa cache, autoload chưa -o, và query. Đây là kiểu số liệu nên có sẵn khi phỏng vấn — nó biến "em nghĩ là…" thành "em đo rồi".

Ghi rõ giới hạn của phép đo: đây là bootstrap CLI (artisan), provider rỗng, máy dev chạy Docker. Provider thật có đăng ký binding, event, policy thì tốn hơn; nhưng bậc độ lớn vẫn là vài ms cho vài chục module — chưa verify trên môi trường production có OPcache + preload.

4. Trade-off

4.1. Gom code chung tới mức nào

flowchart LR
  A["Copy-paste
(0 chi phí, 2 chỗ lệch nhau)"] --> B["Gom trong 1 module
trait / scope / component"]
  B --> C["Contracts giữa module
(cùng repo)"]
  C --> D["Package Composer
(nhiều repo, có version)"]
  D --> E["Service riêng qua HTTP
(deploy riêng)"]
  R["Rule of three:
lần 1, 2 cứ copy — lần 3 mới gom"] -.-> B
  S["Chỉ sang D khi có repo thứ 2 thật
Chỉ sang E khi cần scale/deploy riêng"] -.-> D

4.2. Các cặp chọn lựa hay bị hỏi

5. Khó khăn khi vận hành thực tế

6. Case thực tế và cách xử lý

Case 1 — Hàm tính điểm bị copy 3 chỗ, sửa 1 chỗ, báo cáo lệch

Hiện tượng: điểm hiển thị cho sinh viên là 7,5; export Excel ra 7,8; dashboard giảng viên lại ra 7,5 nhưng xếp loại sai.

flowchart TB
  R["Yêu cầu: làm tròn 0,25 thay vì 0,5"] --> A["Sửa ở Livewire component (màn sinh viên)"]
  R --> B["Quên: ExportGradesJob"]
  R --> C["Quên: ReportController"]
  A --> X["3 kết quả khác nhau cho cùng một sinh viên"]
  B --> X
  C --> X

Xử lý từng bước:

1. Chặn máu trước: tìm hết bản sao — grep -rn "round(" --include=*.php | grep -i diem. Chọn một bản đúng theo quy chế, sửa 2 bản còn lại cho khớp, deploy. Chưa refactor gì cả.
2. Gom (lần thứ 3 rồi, đủ điều kiện): đưa vào một chỗ duy nhất — Modules\Learning\Domain\GradeCalculator, method final, không có tham số $mode.
3. Test theo bảng quy chế: data provider với các mốc 7,124 / 7,125 / 7,375… Test này là tài liệu quy chế bằng code.
4. Chặn tái phát: thêm một luật vào architecture test — cấm chuỗi round( trong Http/ và trong Job; muốn tính điểm thì gọi GradeCalculator.
5. Đóng vòng: ADR 15 dòng "quy tắc làm tròn điểm nằm ở đâu và vì sao", link trong README module.

Chỗ dễ trả lời sai khi phỏng vấn: nhảy ngay vào "em tạo service dùng chung". Câu trả lời tốt phải có bước 1 (sửa lệch dữ liệu trước) và bước 4 (chặn bằng máy, không bằng lời dặn).

Case 2 — BaseService phình thành 900 dòng

Hiện tượng: mọi service extends BaseService. Method create(array $data, array $options = []) có 7 nhánh if ($options['skip_...']). Sửa cho module Billing thì test module Learning đỏ.

Xử lý:

1. Đếm thật xem con nào dùng gì: grep -rn "parent::" modules/ | sort | uniq -c. Thường ra kết quả: 80% method của base chỉ 1 – 2 con dùng.
2. Phần nhiều con dùng và không có if (ví dụ ghi audit log) → chuyển thành trait hoặc event listener, không phải kế thừa.
3. Phần có $options → tách thành action riêng cho từng nghiệp vụ: EnrollStudent, TransferStudent, CancelEnrollment. Trùng vài dòng — chấp nhận, vì chúng sẽ phân hoá tiếp.
4. Làm dần: mỗi sprint kéo 1 – 2 service ra khỏi base; base teo dần rồi xoá. Không làm một MR "refactor toàn bộ" — loại MR đó không ai review nổi và không rollback được.

Dấu hiệu để biết khi nào một base class bắt đầu hỏng (dùng luôn làm tiêu chí review): tham số $options/$flags xuất hiện; con phải override rồi không gọi parent::; base phải instanceof con để rẽ nhánh.

Case 3 — Deadline gấp, dev import thẳng model module khác

Hiện tượng: MR gấp trước ngày khai giảng, Billing import Modules\Learning\Domain\Enrollment. Pipeline đỏ ở job architecture test (output thật ở mục 1.6).

Xử lý — và đây là chỗ thể hiện vai trò lead:

1. Không tắt test. Cho phép một đường hợp lệ: Learning thêm method vào EnrollmentReader (5 phút), Billing dùng interface.
2. Nếu thật sự không kịp: thêm một dòng ngoại lệ có hạn vào file luật, kèm comment // TODO(#1234) gỡ trước 30/09 và issue thật. Ngoại lệ phải nhìn thấy được, không phải @phpstan-ignore rải rác.
3. Retro: nếu tháng nào cũng phải xin ngoại lệ ở cùng một ranh giới → ranh giới đó vẽ sai, gộp hai module lại. Ranh giới là giả thuyết, không phải điều răn.

Case 4 — Package nội bộ chạy ở máy dev, chết trên production

Hiện tượng: deploy xong, trang thanh toán 500 hàng loạt: BadMethodCallException: Method Illuminate\Support\Str::maSinhVien does not exist. Ở máy dev chạy hoàn toàn bình thường.

Nguyên nhân (đã dựng lại trong lab): image production build bằng composer install --no-dev --no-scripts. --no-scripts chặn luôn package:discover → service provider của package không được đăng ký → macro không tồn tại. Class thì vẫn autoload được nên static analysis không bắt.

Xử lý:

1. Ngay lúc đó: rollback bằng đổi upstream (blue-green), không debug trên production.
2. Sửa gốc: thêm php artisan package:discover --ansi vào Dockerfile ngay sau composer install; hoặc khai thẳng provider vào bootstrap/providers.php — rõ ràng hơn auto-discovery, và đây là cách tôi ưu tiên cho package nội bộ.
3. Chặn tái phát: smoke test sau deploy gọi một route dùng macro đó; job CI build image rồi chạy php artisan about + smoke test trên chính image sắp deploy, không phải trên máy dev.

Bài học đáng nói trong phỏng vấn: lỗi không nằm ở code, nằm ở khác biệt giữa môi trường build và môi trường dev. Mọi thứ "tự động" (auto-discovery, cache, symlink) đều là chỗ hai môi trường có thể lệch nhau.

Case 5 — Bật strict model cho codebase đang chạy

Hiện tượng: bật Model::shouldBeStrict() cho cả 3 môi trường, hôm sau production ném LazyLoadingViolationException ở màn hình danh sách lớp — chỗ mà dev test local (1 lớp) không hề thấy lỗi (bẫy count($items) > 1 ở mục 1.7).

Xử lý:

1. Production không ném exception: Model::shouldBeStrict(! app()->isProduction()).
2. Production vẫn muốn biết → ghi log thay vì ném:

   Model::handleLazyLoadingViolationUsing(function ($model, $relation) {
       Log::warning("lazy_load", ["model" => $model::class, "relation" => $relation]);
   });

   Có số liệu thật để biết chỗ nào đáng sửa trước, mà người dùng không thấy lỗi.
3. Seed dữ liệu dev phải có nhiều dòng cho mỗi bảng chính — nếu không, cả strict mode lẫn mắt người đều không thấy N+1.
4. Bật dần theo model: dùng Model::preventLazyLoading() toàn cục sau khi đã dọn xong danh sách trong log, đừng bật một phát rồi tắt vì "ồn quá".

7. Câu hỏi phụ interviewer hay hỏi tiếp

Trả lời trong 60 giây (bản dùng khi phỏng vấn)

"Repo là một monolith chia module: mỗi module một thư mục, một service provider tự nạp route, view, migration — tổng cộng khoảng 15 dòng framework, không thêm dependency. Module chỉ gọi nhau qua Contracts và DTO, và luật đó do một test kiến trúc 27 dòng canh, không phải do em nhắc trong review. Trong module thì tách controller → service/action → model; service không đụng request nên gọi lại được từ Livewire, command và test.

Thứ dùng chung em chỉ giữ loại ép ràng buộc — base model bật shouldBeStrict, format lỗi, tenant scope — không giữ base class gom nghiệp vụ, vì loại đó luôn phình thành 900 dòng với một đống $options. Code chỉ được gom khi xuất hiện lần thứ ba, và chỉ tách thành package Composer khi có repo thứ hai thật sự cần.

Bẫy em đã gặp: composer install --no-scripts làm package nội bộ không được discover → 500 trên production dù dev chạy tốt; và strict mode không bắt lazy load khi query trả về đúng một dòng — nên seed dev phải nhiều dòng, còn production thì log thay vì ném lỗi."

Đọc tiếp: Tối ưu Laravel (N+1, eager loading), Blade nhận gì — Model, array hay Collection (DTO qua ranh giới view), Pint + static analysis (hai lớp chặn đầu trong CI).