vi
new
0
Avatar
Duong Nguyen @arya.it
4 0 4
Đã đăng vào khoảng 10 giờ trước 16 phút đọc
12

[Vibe Coding Thực Chiến #04] Giải Phẫu Kiến Trúc EzyPlatform: Hiểu Đúng Bộ Khung Xương Để "Chỉ Huy" AI Chuẩn Đét!

Tác giả: Lee
Series: Vibe Coding Thực Chiến Cùng EzyPlatform (#04)
Hạ tầng thực nghiệm: VPS Ubuntu 22.04 LTS (157.66.47.xxx) | Domain: https://1576647xxx-admin.interdata.io.vn
Bộ công cụ: VS Code + Extension youngmonkeys.ezyarticle + Claude Code CLI / ChatGPT Codex

Ở bài viết số #03, chúng ta đã cùng nhau làm chủ Framework Prompt 3 Tầng và kỹ thuật mớm ngữ cảnh bằng file RULES.md, giúp AI sinh code chuẩn chỉ và né sạch tình trạng "nồi lẩu thập cẩm" spaghetti.

Thế nhưng, sau khi có trong tay những câu prompt xịn sò, rất nhiều bạn lại vướng phải một rào cản tâm lý khác:

"AI sinh ra một đống file code tách rời meta.json, content.html, head.html, foot.html... rồi hệ thống bên dưới lắp ghép chúng lại như thế nào? Tại sao sửa code xong F5 lại không thấy đổi? Muốn dùng chung thanh Header/Footer giữa các trang thì cấu hình ở đâu?"

Nếu không hiểu được kiến trúc của hệ thống mà bạn đang tương tác, việc Vibe Coding sẽ chẳng khác nào "người mù lái xe" — bạn chỉ biết bấm ga và cầu nguyện cho chiếc xe chạy đúng hướng. Đến khi gặp lỗi xung đột layout hay lỗi định tuyến (routing), bạn sẽ hoàn toàn bất lực vì không biết AI đã đặt code sai ở tầng nào!

Hôm nay, mình sẽ cùng bạn "mổ xẻ và giải phẫu" toàn bộ kiến trúc của EzyPlatform. Hiểu thấu đáo bộ khung xương này, bạn sẽ từ một người "thử may rủi với AI" trở thành một Kỹ sư chỉ huy thực thụ: chỉ tay vào đúng file, sửa đúng dòng và ép AI phục vụ chính xác mục tiêu của dự án!

1. Bức tranh tổng thể: EzyPlatform được cấu tạo như thế nào?

Khác với các hệ thống CMS truyền thống bằng PHP (như WordPress) thường bị phình to và tiêu tốn tài nguyên, hay các framework JavaScript fullstack (như Next.js) đòi hỏi setup Node server phức tạp, EzyPlatform được xây dựng trên triết lý Micro-modular cực kỳ tinh gọn chạy trên nền tảng EzyFox Java Ecosystem.

Dưới đây là sơ đồ giải phẫu 4 tầng kiến trúc cốt lõi của nền tảng:

Giải phẫu kiến trúc tổng thể EzyPlatform Sơ đồ 4 tầng kiến trúc: Presentation Layer (Thymeleaf), Plugin Ecosystem, Dual API Gateway và EzyFox Java Core Engine.

4 tầng kiến trúc bạn cần nắm rõ:

  1. Tầng Trình Diễn & Theme Engine (Presentation Layer):
    • Sử dụng Thymeleaf — công cụ Server-Side Rendering (SSR) kinh điển trong thế giới Java Enterprise, cho tốc độ render trang HTML siêu tốc mà không cần nạp cả "núi" node_modules.
    • Đi kèm theme Freestyle linh hoạt: Cho phép bạn cấu hình Empty Layout để toàn quyền kiểm soát 100% thẻ HTML của trang web mà không sợ bị giao diện mặc định chèn đè.
  2. Hệ Sinh Thái Module & Plugin Cốt Lõi (Plugin Ecosystem):
    • EzyPlatform hoạt động theo cơ chế cắm-rút (pluggable). Các tính năng đều được module hóa thành các plugin độc lập:
      • EzyArticle: Quản lý bài viết, trang tĩnh, đồng bộ file từ VS Code lên VPS theo thời gian thực.
      • EzySupport: Quản lý chứng chỉ SSL Let's Encrypt, cấu hình tên miền tự động.
      • GraphQL & Media: Xử lý lưu trữ tài nguyên tĩnh, kiêm MCP Server kết nối trực tiếp với AI.
  3. Cổng Giao Tiếp Dữ Liệu Kép (Data & API Gateway):
    • Trang bị song song cả 2 cổng: REST API (/api/v1/...) cho các tác vụ CRUD thông thường và GraphQL Endpoint (/graphql) cho các truy vấn dữ liệu động phức tạp.
  4. Nền Tảng Cốt Lõi (Core Engine & Storage):
    • Chạy trên nền Java Core của EzyFox. Toàn bộ hệ thống chạy êm ru trên con VPS Ubuntu 2 CPU / 4GB RAM (157.66.47.xxx) với mức tiêu thụ RAM chưa tới 500MB!

2. Thực địa VPS: Cấu trúc Template Explorer trên máy chủ

Để thấy rõ kiến trúc này hoạt động ngoài đời thực, hãy cùng SSH vào VPS và mở giao diện quản trị Admin:

Cấu trúc Template Explorer trên VPS So sánh song song: Thư mục vật lý trên VPS Ubuntu và cây thư mục được Template Explorer nhận diện trong trang Admin.

Khi bạn dùng extension youngmonkeys.ezyarticle trên VS Code, mỗi trang web bạn tạo ra sẽ nằm trong một thư mục riêng biệt tại pages/[slug]/:

# Cấu trúc thư mục trang chuẩn trên máy chủ VPS 157.66.47.xxx
pages/example-page/
├── content.html    # Thân trang (Nội dung chính hiển thị)
├── foot.html       # Script JavaScript và logic tương tác
├── head.html       # CSS Framework, Font và Meta tags
└── meta.json       # Metadata điều hướng, slug, title và layout

Bất cứ khi nào bạn nhấn Ctrl + S lưu file trong VS Code, extension sẽ đóng gói và bắn một request qua REST API lên máy chủ. Trình duyệt Template Explorer tại https://1576647xxx-admin.interdata.io.vn sẽ lập tức cập nhật cây thư mục chỉ sau 1–2 giây!

3. "Bộ Tứ Trụ" EzyArticle: Tại sao lại sinh ra như dành riêng cho AI?

Đây là phần thú vị nhất của kiến trúc EzyPlatform dưới góc nhìn Vibe Coding!

Nhiều anh em từng thắc mắc: "Tại sao không gộp chung vào 1 file .html duy nhất như bình thường, hoặc dùng file .jsx như React mà lại phải chia thành 4 file tách biệt?"

Câu trả lời nằm ở nguyên lý Single Responsibility (Đơn nhiệm): Chia nhỏ để khóa chặt phạm vi tác động của AI!

Bộ Tứ Trụ EzyArticle và cơ chế ghép trang Thymeleaf Bộ Tứ Trụ: meta.json (Bộ não), content.html (Thân thể), head.html (Phục trang), foot.html (Hệ thần kinh) được Thymeleaf tự động lắp ghép.

3.1. meta.json — "Bộ Não" điều phối cấu hình

File này quyết định định danh của trang web trong cơ sở dữ liệu và hệ thống định tuyến (Routing).

Bóc tách cấu trúc file meta.json Chi tiết các trường quan trọng trong meta.json và ý nghĩa kỹ thuật.

Nội dung một file meta.json chuẩn mực:

{
  "id": 1,
  "slug": "khoa-hoc-vibe-coding",
  "title": "Khóa Học Vibe Coding Thực Chiến Cùng EzyPlatform",
  "summary": "Học lập trình thực chiến cùng AI từ con số 0.",
  "pageType": "PAGE",
  "contentType": "HTML",
  "status": "DRAFT",
  "metadata": {
    "layout": "empty"
  }
}
  • slug: Đường dẫn URL truy cập trên trình duyệt (ví dụ: /pages/khoa-hoc-vibe-coding).
  • pageType: Có 2 giá trị then chốt:
    • "PAGE": Trang web độc lập, có đường dẫn URL riêng để người dùng truy cập.
    • "FRAGMENT": Khối giao diện con (Header/Footer/Banner) dùng để nhúng vào trang khác.
  • status: "DRAFT" (chỉ xem được trong chế độ Preview có token bí mật) hoặc "PUBLISHED" (công khai ra Internet).
  • "layout": "empty": Báo cho Thymeleaf Engine biết rằng trang này sử dụng layout trống, không cần chèn các thanh menu mặc định của theme.

3.2. content.html — "Thân Xác" giao diện (UI Component)

Đây là nơi chứa toàn bộ mã nguồn HTML của giao diện người dùng.

[!IMPORTANT] Quy tắc vàng: Trong file content.html, bạn TUYỆT ĐỐI KHÔNG được viết các thẻ bao ngoài như <!DOCTYPE html>, <html>, <head>, <body>. Bạn chỉ được viết các thẻ component nội dung như <section>, <header>, <div>, <main>.

Lý do: Khi render, Thymeleaf sẽ tự động bọc content.html vào khung xương trang chuẩn của hệ thống. Nếu AI sinh thêm các thẻ <html> hay <body>, trang web sẽ bị lỗi cú pháp đúp khung (Invalid Nested DOM) khiến giao diện bị vỡ tan tành!

3.3. head.html — "Phục Trang" (CSS & Tài nguyên nạp trước)

Chứa toàn bộ các liên kết CDN CSS (Tailwind CSS, Font Awesome), Google Fonts và các thẻ <style> tùy biến:

<!-- Nạp Tailwind CSS CDN -->
<script src="https://cdn.tailwindcss.com"></script>

<!-- Nạp Google Font Inter -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700;800&display=swap" rel="stylesheet">

<style>
  body { font-family: 'Inter', sans-serif; }
</style>

Tất cả các thẻ trong head.html sẽ được hệ thống tự động tiêm (inject) vào đúng vị trí thẻ <head> của trang HTML cuối cùng.

3.4. foot.html — "Hệ Thần Kinh" (JavaScript & Logic tương tác)

Chứa các đoạn mã JavaScript thuần (Vanilla JS), các event listener xử lý sự kiện click, accordion, modal hoặc animation:

<script>
  document.addEventListener("DOMContentLoaded", () => {
    console.log("Page loaded successfully on VPS!");
  });
</script>

Hệ thống sẽ nạp foot.html ngay trước thẻ đóng </body>. Điều này đảm bảo toàn bộ cây DOM trong content.html đã được trình duyệt tải xong xuôi thì mã JavaScript mới thực thi, tránh 100% lỗi kinh điển TypeError: Cannot read property of null.

4. Cơ chế Page Fragments: Tái sử dụng Header, Footer mà không cần copy-paste

Một vấn đề nhức nhối khi xây dựng website nhiều trang là: Nếu trang nào AI cũng sinh lại Header và Footer, khi cần đổi logo hay thêm một mục menu, bạn sẽ phải đi sửa từng trang một!

EzyPlatform giải quyết triệt để vấn đề này bằng cơ chế Page Fragments:

Cơ chế Page Fragments trong EzyArticle Mô hình DRY: Tách Header và Footer thành Fragment dùng chung, hàng trăm trang con tự động thừa kế.

Cách thức hoạt động:

  1. Bạn tạo một thư mục fragment, ví dụ: fragments/common-header/ với file meta.json có "pageType": "FRAGMENT".
  2. Trong layout của Theme Freestyle, bạn khai báo vị trí chèn fragment bằng cú pháp Thymeleaf:
    <!-- Nhúng Header dùng chung -->
<div th:replace="~{ezyarticle/fragments/common-header :: content}"></div>

<!-- Vùng hiển thị nội dung động của trang con -->
<main th:replace="~{ezyarticle/pages/current-page :: content}"></main>

<!-- Nhúng Footer dùng chung -->
<div th:replace="~{ezyarticle/fragments/common-footer :: content}"></div>
  3. Khi ra lệnh cho AI: Từ nay, bạn chỉ cần ra lệnh cho AI: "Tạo cho tôi phần nội dung chính (Hero Section & Bảng giá) của trang /bang-gia". AI chỉ sinh mã nguồn cho đúng vùng content.html, phần Header và Footer sẽ tự động hiển thị hoàn hảo!

5. Cổng giao tiếp dữ liệu kép: REST API & GraphQL Endpoint

Để chuẩn bị cho việc kết nối dữ liệu thật ở các bài viết tiếp theo, bạn cần hiểu 2 "cửa ngõ" giao tiếp dữ liệu của EzyPlatform:

Cổng giao tiếp dữ liệu kép: REST API vs GraphQL So sánh 2 cổng kết nối: REST API phục vụ tác vụ chuẩn và GraphQL Endpoint làm bệ phóng kết nối AI qua MCP.

Tiêu chí Cổng REST API (/api/v1/...) Cổng GraphQL (/graphql)
Mục đích chính Đồng bộ file, CRUD tiêu chuẩn, upload media Truy vấn dữ liệu động, quan hệ đa bảng
Bên sử dụng Extension VS Code, form submit AI Assistant, Mobile App, MCP Server
Cơ chế xác thực Header admin_access_token Bearer Token / API Key
Khả năng mở rộng Endpoint cố định cho từng resource Truy vấn chính xác trường cần lấy, 0 byte dư thừa

Đặc biệt, cổng GraphQL chính là "vũ khí tối thượng" giúp chúng ta thiết lập MCP Server (Model Context Protocol) ở Bài #08: cho phép Claude hoặc Codex tự đọc schema database trên VPS và tự viết câu truy vấn chính xác 100%!

6. 3 bẫy lỗi kinh điển về kiến trúc & Cách né trong 1 nốt nhạc 😡

Trong quá trình làm việc với kiến trúc này, 90% anh em dev sẽ vấp phải 3 bẫy lỗi sau:

Bẫy lỗi #1: Bị đúp Header/Footer (Double Layout Conflict) 😣

  • Hiện tượng: Trang web của bạn vừa có thanh menu do AI viết, vừa xuất hiện thêm thanh menu mặc định của theme Freestyle màu xám đè lên trên.
  • Nguyên nhân: Theme Freestyle mặc định có layout chứa sẵn menu hệ thống. Bạn chưa báo cho EzyPlatform biết là trang này muốn dùng layout trắng (Empty Layout).
  • Cách né (Recommend 👍):
    • Trong meta.json, bắt buộc khai báo "metadata": { "layout": "empty" }.
    • Trên Admin EzyPlatform: Vào menu Theme > Freestyle Settings, đảm bảo layout mặc định được gán về Empty Layout.

Bẫy lỗi #2: Đặt nhầm pageType: "FRAGMENT" khiến trang "mất tích" 😡

  • Hiện tượng: Sync code lên VPS thành công nhưng khi vào đường dẫn https://1576647xxx-admin.interdata.io.vn/pages/[slug] thì nhận về lỗi 404 Not Found.
  • Nguyên nhân: AI vô tình gán "pageType": "FRAGMENT" trong file meta.json. Vì là Fragment nên hệ thống chỉ coi nó là một khối phụ để nhúng, không tạo đường dẫn URL truy cập độc lập.
  • Cách né (Lưu ý ⚠️):
    • Luôn kiểm tra file meta.json: Nếu là trang web độc lập, giá trị bắt buộc phải là "pageType": "PAGE".

Bẫy lỗi #3: Lỗi cache template khiến F5 không cập nhật mã mới ⚠️

  • Hiện tượng: Bạn vừa sửa code trên VS Code, lưu file thành công nhưng ra trình duyệt F5 mỏi tay giao diện vẫn y như cũ.
  • Nguyên nhân: Thymeleaf có cơ chế cache template compiled để tối ưu hiệu năng trên server production.
  • Cách né (Bí kíp 💡):
    • Mở file content.html trong VS Code, bấm chuột phải chọn EzyArticle: Preview Page. Extension sẽ tự động đính kèm token preview mới để ép server bypass cache và nạp thẳng mã nguồn mới nhất!

7. Cheatsheet Kiến Trúc & Cấu Hình Mẫu meta.json Chuẩn Đét 📋

Lưu lại bảng cấu hình này vào bookmark để đối chiếu mỗi khi bắt đầu một trang mới trong dự án:

{
  "id": 0,
  "slug": "ten-trang-viet-thuong-khong-dau",
  "title": "Tiêu Đề Trang Hiển Thị Trên Trình Duyệt & SEO",
  "summary": "Mô tả ngắn gọn về trang web dùng cho thẻ meta description",
  "featuredImageName": "",
  "pageType": "PAGE",
  "contentType": "HTML",
  "status": "DRAFT",
  "metadata": {
    "layout": "empty"
  }
}

Bảng tóm tắt phân vai cho AI (Đưa thẳng vào RULES.md):

  • Khi cần sửa nút bấm, form, bảng giá, giao diện: ➔ Chỉ sửa content.html.
  • Khi cần nạp thêm thư viện icon, font chữ, CSS framework: ➔ Chỉ sửa head.html.
  • Khi cần viết hàm click, logic tính toán, modal popup: ➔ Chỉ sửa foot.html.
  • Khi cần đổi tiêu đề trang, đường dẫn URL, layout: ➔ Chỉ sửa meta.json.

8. Tổng kết & Kỳ tiếp theo

Vibe Coding không có nghĩa là biến lập trình viên thành người "mù công nghệ". Ngược lại, khi bạn đã nắm vững Bộ Tứ Trụ, cơ chế Thymeleaf Assembly và luồng dữ liệu của EzyPlatform, bạn sẽ có toàn quyền kiểm soát hệ thống trong lòng bàn tay!

🎯 3 điểm cốt lõi cần nhớ từ bài viết này:

  1. Kiến trúc Micro-modular: EzyPlatform tách biệt rạch ròi giữa Core Java, Plugin và Presentation Layer giúp hệ thống siêu nhẹ và an toàn tuyệt đối.
  2. Bộ Tứ Trụ: meta.json (Bộ não), content.html (Thân xác), head.html (Phục trang), foot.html (Hệ thần kinh) là thiết kế hoàn hảo để phân lập phạm vi sinh code cho AI.
  3. Page Fragments & Dual Gateway: Tái sử dụng Header/Footer để code không bị trùng lặp, sẵn sàng mở rộng qua REST và GraphQL.

Ở bài viết tiếp theo, khi toàn bộ nền móng kiến trúc đã thông suốt, chúng ta sẽ bắt tay vào hành động thực tế:

👉 [Vibe Coding Thực Chiến #05] Website Đầu Tiên Trong 5 Phút: Quy Trình Sync Siêu Tốc Từ VS Code Lên VPS Production!

Chúng ta sẽ cùng nhau thực chiến tạo một Landing Page hoàn chỉnh từ con số 0, tận hưởng cảm giác code xong bấm Preview là thấy ngay trên server thật chỉ trong 5 phút!

💬 Góc thảo luận: Anh em thích kiểu kiến trúc tách bạch 4 file độc lập như EzyArticle hơn, hay thích kiểu nhồi chung cả HTML/CSS/JS vào một file Component duy nhất (như React JSX/Vue SFC)? Ưu và nhược điểm anh em thấy là gì? Hãy để lại bình luận bên dưới nhé!

Đừng quên bấm Upvote 👍 và Bookmark (Clip) 🔖 để lưu lại bộ tài liệu giải phẫu kiến trúc này nhé. Hẹn gặp lại anh em ở Bài #05!

AI architecture Coding Java

All rights reserved

Mục lục


Viblo
Hãy đăng ký một tài khoản Viblo để nhận được nhiều bài viết thú vị hơn.
Đăng kí