0

App nằm dưới base path của hệ thống khác: route, link cũ, theme và những thứ nhỏ dễ vỡ

Trình thiết kế báo cáo mình làm phải chạy được ở hai nơi:

  1. Bên trong một web app lớn, ở một đường dẫn con như /apps/report/. Server của web app đó phục vụ trang, chèn thẻ <base href="/apps/report/"> và cấu hình vào HTML.
  2. Như một file HTML độc lập, gửi cho khách xem demo, mở thẳng từ ổ đĩa hoặc một host tĩnh bất kỳ, không có server nào phía sau.

Phiên bản đầu dùng hash route (/#/reports/42) cho cả hai, vì nó chạy được ở mọi nơi. Rồi đến lượt người dùng thật:

  • Link chia sẻ trông như .../apps/report/#/reports/42, khác hẳn mọi link khác trong hệ thống.
  • Sau khi đăng nhập, app đưa người dùng về đường dẫn lưu sẵn, và ai đó nhận ra đường dẫn lưu sẵn có thể là bất kỳ thứ gì.
  • Người dùng chọn giao diện tối, tải lại trang, quay về giao diện sáng.

Bài này đi qua từng chuyện.

Hai chế độ, hai kiểu route

Bên trong hệ thống chủ File độc lập
Ai phục vụ trang Server của hệ thống chủ Không ai (mở file) hoặc host tĩnh
Server trả trang cho mọi đường dẫn con? Có (cấu hình được) Không
Kiểu route Theo đường dẫn: /apps/report/reports/42 Theo hash: index.html#/reports/42

Hash route tồn tại vì một lý do: khi không có server nào trả trang cho /reports/42, trình duyệt chỉ có thể mở file gốc, và phần sau dấu # không bao giờ được gửi lên server. Khi đã có server chủ phục vụ trang cho mọi đường dẫn con, route theo đường dẫn cho link sạch, đồng bộ với phần còn lại của hệ thống.

// Đường dẫn gốc lấy từ thẻ <base href> mà server chủ chèn vào, không gõ cứng
function basePath(): string {
  const path = new URL(document.baseURI).pathname;      // "/apps/report/"
  return path.endsWith('/') ? path.slice(0, -1) : path; // "/apps/report"
}

const router = MODE === 'standalone'
  ? createHashRouter(routes)
  : createBrowserRouter(routes, { basename: basePath() || '/' });

Không gõ cứng /apps/report trong code. Hệ thống chủ có thể được cài ở một đường dẫn khác cho từng khách hàng (/portal/apps/report, /apps/report), và thẻ <base> là thứ duy nhất biết đúng.

Thẻ <base> còn một tác dụng phụ quan trọng: mọi đường dẫn tương đối (ảnh, file JS chia nhỏ) đều tính từ nó. Build bằng Vite với base: './' thì asset luôn được tìm đúng chỗ, dù trang được phục vụ ở đường dẫn nào.

Link cũ dạng #/ không được chết

Đổi từ hash route sang route theo đường dẫn, những link #/reports/42 người dùng đã lưu, đã gửi qua email vẫn phải mở được. Chuyển một lần, thay thế trong lịch sử:

function LegacyHashRedirect() {
  const navigate = useNavigate();
  useEffect(() => {
    const hash = window.location.hash;                      // "#/reports/42"
    if (MODE !== 'standalone' && hash.startsWith('#/')) {
      navigate(hash.slice(1), { replace: true });           // → /apps/report/reports/42
    }
  }, [navigate]);
  return null;
}

replace: true để nút Back không đưa người dùng về link cũ, rồi lại bị chuyển tiếp, rồi lại Back, vòng lặp.

Quay lại sau khi đăng nhập: chỉ về route của chính app

Luồng quen thuộc: người dùng mở một link sâu, chưa đăng nhập, app lưu lại đường dẫn đó, đưa đi đăng nhập, xong quay về. Chỗ nguy hiểm là "quay về" một đường dẫn đọc từ bộ nhớ hoặc từ tham số URL. Nếu không kiểm, ai đó có thể gửi link khiến người dùng bị đưa sang một trang khác sau khi đăng nhập (lỗi open redirect).

import { matchPath } from 'react-router-dom';

const APP_ROUTES = ['/', '/reports', '/reports/:id', '/settings'];

function safeReturnTo(saved: string | null): string {
  if (!saved || !saved.startsWith('/') || saved.startsWith('//')) return '/'; // "//evil.com" là URL ngoài
  const path = saved.split('?')[0];
  return APP_ROUTES.some((pattern) => matchPath(pattern, path)) ? saved : '/';
}

Chỉ những đường dẫn khớp với route có thật của app mới được mở. Mọi thứ khác về trang chủ của app.

Dev server phải giống server chủ

Trên máy dev không có server của hệ thống chủ. Nếu dev server chỉ phục vụ trang thô, bạn sẽ dev ở một môi trường không có thẻ <base>, không có cấu hình, và mọi bug về đường dẫn chỉ lộ ra khi đã lên môi trường thật.

Mình viết một plugin Vite nhỏ, chỉ chạy khi vite dev, để đóng vai server chủ:

function hostShell(devConfig: object): Plugin {
  return {
    name: 'host-shell',
    apply: 'serve', // chỉ dev, không bao giờ vào bản build
    transformIndexHtml(html) {
      return html.replace(
        '<head>',
        '<head><base href="/"><script>window.APP_CONFIG = ' + JSON.stringify(devConfig) + '</script>',
      );
    },
  };
}

Thêm vào đó là trả trang cho mọi route của app (history fallback; Vite đã làm sẵn nếu trang của bạn là index.html, tên khác thì cần thêm một middleware nhỏ). Kết quả: npm run dev mở ra là chạy được với dữ liệu demo, không cần bật thêm gì.

Và test cho chính những thứ này: mỗi route mở được ở đúng đường dẫn của nó, link #/ cũ được chuyển, đăng nhập xong về đúng chỗ, mở thẳng một đường dẫn sâu vẫn ra trang.

Theme phải sống qua lần tải lại trang

Lưu lựa chọn theme vào localStorage thì ai cũng biết. Hai chỗ dễ sai:

const KEY = 'report.theme';

export function readTheme(): 'light' | 'dark' {
  try {
    return localStorage.getItem(KEY) === 'dark' ? 'dark' : 'light';
  } catch {
    return 'light'; // chế độ ẩn danh, bộ nhớ bị chặn: vẫn chạy được
  }
}

Chỗ thứ nhất: localStorage có thể ném lỗi (trình duyệt chặn bộ nhớ, chế độ riêng tư). Không bọc try là app trắng trang chỉ vì không đọc được theme.

Chỗ thứ hai nằm ở test. Test "chọn tối rồi mount lại component, vẫn là tối" xanh, nhưng nó chỉ chứng minh lựa chọn còn trong bộ nhớ của module, chưa chứng minh nó được đọc lại từ localStorage. Mô phỏng một lần tải trang thật bằng cách nạp lại module:

it('trang mới đọc lại theme đã lưu', async () => {
  localStorage.setItem('report.theme', 'dark');
  vi.resetModules();                                  // như mở trang mới: module được nạp lại từ đầu
  const { readTheme } = await import('./theme');
  expect(readTheme()).toBe('dark');
});

Hai cái bẫy giao diện nhỏ khi nhúng vào hệ thống khác

Control "giống thư viện" nhưng thực ra là của trình duyệt. Component Select của thư viện UI mình dùng thực chất bọc <select> gốc của trình duyệt. Danh sách xổ ra là của trình duyệt, nên nó không theo giao diện tối. Đổi sang component Dropdown tự vẽ thì danh sách theo đúng theme.

Danh sách xổ ra bị header dính đè. Bảng báo cáo có header dính ở trên khi cuộn (z-index: 2), còn danh sách xổ ra của bộ lọc mặc định chỉ có z-index: 1. Danh sách mở ra nằm dưới header, mất mấy lựa chọn đầu. Sửa bằng một con số z-index cao hơn cho đúng danh sách đó, kèm một dòng giải thích vì sao, để người sau không hạ nó xuống.


Thử ngay: mở app của bạn ở một đường dẫn sâu (copy link một trang con, dán vào tab mới) và bấm F5. Nếu ra trang 404 của server, app của bạn đang thiếu history fallback ở môi trường đó. Rồi tìm chỗ xử lý "quay lại sau khi đăng nhập" và xem nó có kiểm đường dẫn không.

Bài sau là bài cuối của series: E2E với Playwright cho luồng thật, và cách trị test chập chờn mà không che bug. App của bạn dùng hash route hay route theo đường dẫn, và vì sao? Comment chia sẻ nhé.

P.S. Mấy quyết định ở bài này (route nào cho chế độ nào, đọc cấu hình từ đâu) mình hay soát cùng skill frontend-dev-patterns trong PrimeKit, bộ skill mình tự làm, nắm các mẫu React và TypeScript hiện đại như route, tải lười, Suspense. Cài bằng npx @lovehlmmm/primekit init, rồi gõ /pk:frontend-dev-patterns kèm câu hỏi. App của bạn sống trong hệ thống nào thì chỉ bạn biết, phần đó vẫn phải tự chốt.


Series khác của mình


All rights reserved

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í