Trong thế giới phát triển phần mềm hiện đại, việc quản lý các tác vụ phức tạp, bất đồng bộ và cần độ bền bỉ cao luôn là một thách thức. Tin vui là Vercel vừa công bố sự hỗ trợ của Workflow SDK (phiên bản 5) dành cho TanStack Start, hứa hẹn mở ra một kỷ nguyên mới cho việc xây dựng các trình xử lý workflow siêu bền bỉ, đáng tin cậy! 🚀
1. Thiết Lập Dự Án & Cấu Hình 🛠️
Tạo Dự Án & Cài Đặt Thư Viện
Để bắt đầu, hãy khởi tạo một dự án TanStack Start và cài đặt gói workflow:
bash npx @tanstack/cli create my-workflow-app cd my-workflow-app npm i workflow
Cấu Hình Vite
Workflow SDK sử dụng một plugin Vite đặc biệt để chuyển đổi các chỉ thị workflow và step. Bạn cần thêm workflow() vào tệp vite.config.ts của mình.
> ⚠️ Lưu ý Quan trọng: Plugin workflow() bắt buộc phải được liệt kê đầu tiên trong mảng plugins. Điều này đảm bảo rằng các biến đổi "use workflow" và "use step" được xử lý trước khi bất kỳ plugin nào khác can thiệp vào các tệp của bạn, tránh xung đột không đáng có.
```typescript // vite.config.ts import { defineConfig } from "vite"; import { workflow } from "workflow/vite";
export default defineConfig({ plugins: [ workflow(), // ...các plugin tanstackStart(), nitro() và các plugin khác hiện có ], }); ```
2. Định Nghĩa Workflow và Các Bước (Steps) 🏗️
Workflows đóng vai trò điều phối, trong khi các bước (steps) chứa logic nghiệp vụ thực tế. Cả hai đều được định nghĩa bằng các chỉ thị chuỗi cụ thể.
Tạo các định nghĩa workflow và step của bạn trong src/workflows/user-signup.ts:
```typescript // src/workflows/user-signup.ts import { sleep, FatalError } from "workflow";
// ========================================== // WORKFLOW (Bộ Điều Phối) // ========================================== export async function handleUserSignup(email: string) { "use workflow";
const user = await createUser(email); await sendWelcomeEmail(user); // Tạm dừng thực thi 5 giây mà không tiêu tốn tài nguyên máy chủ await sleep("5s"); await sendOnboardingEmail(user); return { userId: user.id, status: "onboarded" }; }
// ========================================== // STEPS (Logic Nghiệp Vụ) // ========================================== async function createUser(email: string) { "use step";
console.log(Creating user with email: ${email}); // Toàn quyền truy cập Node.js (cơ sở dữ liệu, API, v.v.) return { id: crypto.randomUUID(), email }; }
async function sendWelcomeEmail(user: { id: string; email: string }) { "use step";
console.log(Sending welcome email to user: ${user.id}); if (Math.random() < 0.3) { // Các lỗi không được xử lý sẽ tự động kích hoạt tính năng thử lại (retry) theo mặc định throw new Error("Retryable!"); } }
async function sendOnboardingEmail(user: { id: string; email: string }) { "use step";
if (!user.email.includes("@")) { // Ném ra FatalError để bỏ qua thử lại và thất bại ngay lập tức throw new FatalError("Invalid Email"); } console.log(Sending onboarding email to user: ${user.id}); } ```
Các Khái Niệm Chính Cần Nắm Rõ:
* "use workflow": Định nghĩa hàm điều phối (orchestrator function). * "use step": Định nghĩa các khối thực thi độc lập. Khi được gọi bên trong một workflow, các bước này được đưa vào hàng đợi để chạy trên một yêu cầu riêng biệt trong khi workflow tạm dừng. * sleep(duration): Tạm dừng việc thực thi workflow (trong vài giây, giờ, ngày hoặc tháng) mà không tiêu tốn tài nguyên tính toán hoạt động. Đây là một tính năng cực kỳ hữu ích cho các tác vụ hẹn giờ dài hạn. * Xử Lý Lỗi: * Các lỗi tiêu chuẩn không được xử lý sẽ tự động kích hoạt cơ chế thử lại (retry). * Ném ra một FatalError sẽ bỏ qua các lần thử lại và dừng thực thi ngay lập tức. Hãy cân nhắc kỹ khi sử dụng điều này để đảm bảo logic ứng dụng của bạn là chính xác.
3. Tạo Bộ Xử Lý Route 🌐
Để kích hoạt workflow của bạn, hãy thiết lập một bộ xử lý route API. Workflows có thể được bắt đầu từ các route API hoặc bất kỳ ngữ cảnh phía máy chủ nào.
```typescript // src/routes/api/signup.ts import { createFileRoute } from "@tanstack/react-router"; import { json } from "@tanstack/react-start"; import { start } from "workflow/api"; import { handleUserSignup } from "../../workflows/user-signup";
export const Route = createFileRoute("/api/signup")({ server: { handlers: { POST: async ({ request }) => { const { email } = await request.json(); // Thực thi bất đồng bộ và không chặn phản hồi của ứng dụng await start(handleUserSignup, [email]); return json({ message: "User signup workflow started" }); }, }, }, }); ```
4. Phát Triển & Khả Năng Quan Sát Tại Chỗ 👀
Chạy Ứng Dụng
Khởi động máy chủ phát triển: bash npm run dev
Kích Hoạt Workflow
Gửi yêu cầu POST tới endpoint API của bạn: bash curl -X POST --json '{\"email\":\"[email protected]\"}' http://localhost:3000/api/signup
Giám Sát và Kiểm Tra Các Lần Chạy
Workflow SDK cung cấp các công cụ tích hợp để kiểm tra và gỡ lỗi các lần chạy workflow:
* Giao Diện Web (Bảng Điều Khiển Khả Năng Quan Sát): Mở tại http://localhost:3456 bash npx workflow web * Giao Diện Thiết Bị Đầu Cuối CLI: bash npx workflow inspect runs
5. Triển Khai Sản Phẩm 🚀
Các ứng dụng Workflow SDK được tối ưu hóa để triển khai trên Vercel mà không cần cấu hình ban đầu. Đây là một lợi thế lớn cho các nhà phát triển đã quen thuộc với nền tảng này.
> ⚡ Tối Ưu Chi Phí Cực Kỳ Quan Trọng: > Bạn bắt buộc phải bật Fluid Compute trên Vercel trước khi triển khai. Workflow dựa vào các quy trình bền bỉ, chạy dài, và Fluid Compute giúp tối ưu hóa việc sử dụng tài nguyên serverless. Điều này đảm bảo rằng bạn chỉ phải trả tiền cho thời gian thực thi hoạt động thực sự chứ không phải toàn bộ thời lượng của workflow, giúp tiết kiệm đáng kể chi phí khi xử lý các tác vụ có độ trễ cao. Đừng bỏ qua bước này nếu bạn muốn tối ưu hóa hiệu quả tài chính!