Optimizely CMS 12 Headless với Next.js và .NET 8 API

Giới thiệu

Trong nhiều năm, các nhà phát triển Optimizely CMS (trước đây là Episerver) đã dựa vào các template Razor và kết xuất phía máy chủ (SSR) để cung cấp nội dung web. Mặc dù kiến trúc này mạnh mẽ, nhưng web hiện đại đòi hỏi tốc độ, sự linh hoạt và trải nghiệm phát triển tuyệt vời như được tìm thấy trong các framework frontend như Next.js. Bài viết này khám phá sự chuyển đổi chiến lược từ kiến trúc Razor nguyên khối sang cách tiếp cận Headless, tận dụng sức mạnh của Next.js và Optimizely Content Delivery API. Chúng tôi sẽ hướng dẫn chi tiết về việc triển khai cốt lõi và các thực tiễn tốt nhất để đảm bảo quá trình chuyển đổi diễn ra suôn sẻ.

Hướng dẫn từng bước

1. Kích hoạt Content Delivery API

Đầu tiên, hãy đảm bảo instance Optimizely CMS 12 của bạn được cấu hình để hiển thị nội dung qua JSON. Cài đặt package EPiServer.ContentDeliveryApi.Cms và cấu hình nó trong Startup.cs.

// Ginbok.Web/Startup.cs
public void ConfigureServices(IServiceCollection services)
{
    services.AddContentDeliveryApi()
            .AddContentApiFullHtml()
            .AddContentApiSearch();
}

2. Tạo Custom API Controllers

Đối với các trang phức tạp như Trang chủ (Homepage), các endpoint REST tiêu chuẩn có thể yêu cầu nhiều request (chatty). Hãy tạo một controller tùy chỉnh để tổng hợp dữ liệu, giảm thiểu các lần round-trip cho frontend Next.js.

// Ginbok.Web/Controllers/Api/HomepageController.cs
[Route("api/[controller]")]
[ApiController]
public class HomepageController : ControllerBase {
    [HttpGet("data")]
    public IActionResult GetData() {
        var startPage = _contentLoader.Get<SiteStartPage>(ContentReference.StartPage);
        return Ok(new {
            Title = startPage.PageTitle,
            HeroImage = _urlResolver.GetUrl(startPage.HeroImage)
        });
    }
}

3. Triển khai Truy vấn Dữ liệu trong Next.js

Trong ứng dụng Next.js của bạn, sử dụng một hàm fetch bất đồng bộ để truy xuất nội dung từ CMS. Sử dụng tùy chọn revalidate để tận dụng Incremental Static Regeneration (ISR).

// frontend/lib/api.ts
export async function getHomepageData() {
    const res = await fetch(`${process.env.CMS_URL}/api/homepage/data`, {
        next: { revalidate: 600 } // Tái xác thực (Revalidate) mỗi 10 phút
    });
    if (!res.ok) throw new Error('Lỗi khi truy xuất dữ liệu');
    return res.json();
}

Các Lỗi Thường Gặp & Giải Pháp

Vi phạm Chính sách CORS (CORS Policy Violations): Bảo mật trình duyệt sẽ chặn các request nếu CORS không được cấu hình.
- Giải pháp: Thêm [EnableCors("AllowNextJsFrontend")] vào các controller của bạn và định nghĩa chính sách trong Startup.cs cho phép origin của Next.js.
Thiếu Bảo mật Nội dung (Missing Content Security): API có thể trả về 401/403 cho các request ẩn danh.
- Giải pháp: Đảm bảo rằng nhóm "Everyone" có quyền "Read" (Đọc) đối với các node khởi đầu của bạn, hoặc triển khai OAuth/OpenID Connect để truy xuất an toàn.
URL Bản Nháp so với Bản Đã Xuất Bản: Cố gắng truy xuất một slug tồn tại nhưng chưa được xuất bản (published).
- Giải pháp: Luôn kiểm tra thuộc tính Status trong CMS và đảm bảo API của bạn lọc theo VersionStatus.Published.

Thực Tiễn Tốt Nhất

Nên: Sử dụng các interface TypeScript để ánh xạ các model CMS, đảm bảo an toàn kiểu dữ liệu (type safety) trên toàn bộ stack.
Nên: Triển khai việc ghi nhật ký (logging) mạnh mẽ trong tiện ích API của bạn (ví dụ: sử dụng pino hoặc winston) để theo dõi các lỗi truy xuất.
Không nên: Truy xuất toàn bộ nội dung nếu bạn chỉ cần dữ liệu tóm tắt. Giữ cho payload JSON của bạn gọn nhẹ để đạt hiệu suất tối ưu tại edge.

Xác Minh

Để xác minh quá trình di chuyển, điều hướng đến môi trường local Next.js của bạn (thường là http://localhost:3000). Kiểm tra tab mạng (network tab) để đảm bảo các request đang truy cập api.ginbok.com và trả về 200 OK với cấu trúc JSON mong đợi.

Các Bước Tiếp Theo

Khi nền tảng đã được thiết lập, hãy cân nhắc tích hợp Optimizely Graph để truy vấn nâng cao hoặc Cloudflare Workers để cache các phản hồi API của bạn tại edge.