Xây dựng REST API siêu nhẹ, Type-Safe với Hono và TypeScript: Từ Cloudflare Workers đến Node.js

Programming tutorial - IT technology blog
Programming tutorial - IT technology blog

Bối cảnh: Sự chuyển dịch sang Edge-First API

Trong nhiều năm, Express luôn là lựa chọn mặc định của tôi khi xây dựng các backend service. Nhưng kiến trúc serverless đã làm thay đổi hoàn toàn cuộc chơi. Triển khai Express bên trong AWS Lambda hoặc Cloud Run thường đồng nghĩa với việc phải vật lộn với các container bundle nặng tới 40MB, thư mục node_modules cồng kềnh, và thời gian cold start kéo dài hơn 600ms. Tệ hơn nữa, việc cố gắng tích hợp kiểu dữ liệu TypeScript nghiêm ngặt vào các middleware kế thừa của Express luôn tạo cảm giác như đang đối đầu với chính framework này.

Khi đội ngũ của chúng tôi chuyển các microservice đòi hỏi độ trễ thấp sang mạng edge, các tech stack Node truyền thống đã không còn theo kịp. Hono giải quyết trực tiếp vấn đề này. Được xây dựng hoàn toàn dựa trên các Web Standard hiện đại (Fetch, Request, Response), Hono có thể chạy trên hầu như mọi môi trường JavaScript: Cloudflare Workers, Fastly Compute, Deno, Bun, AWS Lambda, và Node.js tiêu chuẩn.

Toàn bộ thư viện nặng chưa đầy 14KB sau khi minified và không có bất kỳ dependency bên ngoài nào. RegExpRouter nổi bật của nó biên dịch các mẫu định tuyến thành biểu thức chính quy để phân giải đường dẫn trong tích tắc (microseconds). Khi kết hợp với TypeScript, Hono mang lại khả năng type safety toàn diện (end-to-end) cùng một RPC client mạnh mẽ. Thay vì phát hiện lỗi sai lệch hợp đồng API (API contract) trên môi trường production, trình biên dịch của bạn sẽ bắt lỗi ngay lập tức.

Cài đặt: Khởi tạo dự án đa Runtime (Multi-Runtime)

Hono cung cấp một công cụ CLI khởi tạo có tên là create-hono với các preset đã được kiểm nghiệm thực tế. Tôi khuyên bạn nên bắt đầu với template Cloudflare Workers. Mã nguồn xây dựng theo hướng edge-first có thể chuyển sang Node.js rất mượt mà. Ngược lại, việc gỡ bỏ các API đặc thù của Node (như fs hay stream gốc) để chạy trên các isolate ở edge lại vô cùng gian nan.

Bước 1: Khởi tạo dự án

npm create hono@latest hono-edge-api
cd hono-edge-api
npm install

Bước 2: Cài đặt thư viện Validation và Node Adapter

Tiếp theo, cài đặt Zod cùng middleware validator chính thức của Hono. Thêm adapter cho server Node dưới dạng development dependency để bạn có thể chạy cùng một codebase trong môi trường container truyền thống:

npm install zod @hono/zod-validator
npm install @hono/node-server @types/node -D

Đảm bảo rằng file tsconfig.json của bạn hướng tới các tính năng ECMAScript hiện đại và bật tính năng kiểm tra kiểu nghiêm ngặt (strict type checking):

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "skipLibCheck": true,
    "types": ["@cloudflare/workers-types"]
  }
}

Cấu hình: Định tuyến rõ ràng và triển khai kép

Bí quyết để giữ cho service của bạn có thể chuyển đổi linh hoạt giữa Cloudflare Workers và Node.js rất đơn giản: tách biệt các route ứng dụng khỏi listener của runtime.

1. Định nghĩa Schema và Domain Type

Bắt đầu với tầng dữ liệu. Định nghĩa các quy tắc xác thực request và suy luận kiểu TypeScript bằng Zod trong file src/schemas.ts:

import { z } from 'zod';

export const CreateArticleSchema = z.object({
  title: z.string().min(5, 'Tiêu đề phải chứa ít nhất 5 ký tự'),
  slug: z.string().regex(/^[a-z0-9-]+$/, 'Slug phải an toàn cho URL (dạng kebab-case)'),
  content: z.string().min(20, 'Nội dung phải chứa ít nhất 20 ký tự'),
  published: z.boolean().default(false),
});

export type CreateArticleInput = z.infer<typeof CreateArticleSchema>;

export interface Article extends CreateArticleInput {
  id: string;
  createdAt: string;
}

2. Xây dựng Router chính

Tập hợp các route handler trong src/app.ts. Hono tích hợp sẵn các middleware cho security headers, CORS và ghi log, vì vậy bạn không cần các package bên thứ ba như Helmet hay Morgan:

import { Hono } from 'hono';
import { cors } from 'hono/cors';
import { secureHeaders } from 'hono/secure-headers';
import { zValidator } from '@hono/zod-validator';
import { CreateArticleSchema, Article } from './schemas';

const articles = new Map<string, Article>();

export const app = new Hono()
  .use('*', secureHeaders())
  .use('*', cors({
    origin: ['https://itfromzero.com'],
    allowMethods: ['GET', 'POST', 'PUT', 'DELETE'],
  }))
  .get('/api/health', (c) => {
    return c.json({
      status: 'healthy',
      runtime: typeof crypto !== 'undefined' && 'subtle' in crypto ? 'edge-compatible' : 'standard',
      timestamp: new Date().toISOString(),
    });
  })
  .get('/api/articles', (c) => {
    return c.json(Array.from(articles.values()));
  })
  .post('/api/articles', zValidator('json', CreateArticleSchema), async (c) => {
    const validatedData = c.req.valid('json');
    const newArticle: Article = {
      id: crypto.randomUUID(),
      ...validatedData,
      createdAt: new Date().toISOString(),
    };
    
    articles.set(newArticle.id, newArticle);
    return c.json(newArticle, 201);
  });

export type AppType = typeof app;

3. Cấu hình Entry Point cho Cloudflare Workers

Cloudflare Workers yêu cầu ứng dụng của bạn phải là một default export dạng ES module. Giữ file src/index.ts gọn gàng chỉ trong hai dòng:

import { app } from './app';

export default app;

4. Thêm Server Adapter cho Node.js

Để chạy cùng một API này bên trong một container Docker tiêu chuẩn hoặc máy ảo, hãy bọc router của bạn bằng @hono/node-server trong src/node-server.ts:

import { serve } from '@hono/node-server';
import { app } from './app';

const port = Number(process.env.PORT) || 3000;

console.log(`Đang khởi chạy Node adapter trên port ${port}...`);

serve({
  fetch: app.fetch,
  port,
});

Bây giờ, hãy cấu hình các script trong package.json để chạy cả hai môi trường song song trong quá trình phát triển:

{
  "scripts": {
    "dev:edge": "wrangler dev",
    "deploy:edge": "wrangler deploy",
    "dev:node": "tsx watch src/node-server.ts",
    "start:node": "node dist/node-server.js"
  }
}

Kiểm thử & Khả năng quan sát (Observability)

Sau khi đã hoàn thiện định tuyến và xác thực dữ liệu, bạn có thể kiểm tra các ràng buộc payload, kiểm tra response header và đo đạc thời gian thực thi.

1. Contract Testing với Hono Client (RPC)

RPC client của Hono (hc) loại bỏ sự cần thiết của việc tạo stub OpenAPI hoặc duy trì các interface client dư thừa. Bằng cách import AppType đã export vào Vitest, các lệnh gọi kiểm thử của bạn sẽ được định kiểu hoàn toàn:

import { test, expect } from 'vitest';
import { testClient } from 'hono/testing';
import { app } from './src/app';

test('POST /api/articles từ chối dữ liệu không hợp lệ và chấp nhận payload hợp lệ', async () => {
  const client = testClient(app);

  // Payload không hợp lệ: Zod sẽ trả về HTTP 400 Bad Request
  const invalidRes = await client.api.articles.$post({
    json: {
      title: 'Lỗi',
      slug: 'NOT_SAFE!',
      content: 'Quá ngắn',
      published: false,
    },
  });
  expect(invalidRes.status).toBe(400);

  // Payload hợp lệ: trả về HTTP 201 Created cùng ID được tạo tự động
  const validRes = await client.api.articles.$post({
    json: {
      title: 'Xây dựng Edge API',
      slug: 'building-edge-apis',
      content: 'Hướng dẫn thực hành khám phá các kiến trúc điện toán biên hiện đại.',
      published: true,
    },
  });
  expect(validRes.status).toBe(201);
  const data = await validRes.json();
  expect(data.id).toBeDefined();
});

2. Smoke Test nhanh qua Terminal

Khởi động worker cục bộ bằng lệnh npm run dev:edge (mặc định tại cổng 8787) và kiểm tra trực tiếp các endpoint bằng cURL:

# 1. Kiểm tra health và runtime
curl -i http://localhost:8787/api/health

# 2. Kích hoạt phản hồi 400 khi thiếu các trường dữ liệu
curl -i -X POST http://localhost:8787/api/articles \
  -H "Content-Type: application/json" \
  -d '{"title": "Ngắn"}'

# 3. Tạo một bài viết hợp lệ
curl -i -X POST http://localhost:8787/api/articles \
  -H "Content-Type: application/json" \
  -d '{"title": "TypeScript trên Edge", "slug": "typescript-edge", "content": "Hướng dẫn đầy đủ về cách viết serverless API chuẩn type-safe.", "published": true}'

3. Thu thập dữ liệu đo từ xa (Telemetry) và Timing Header trên Edge

Tốc độ định tuyến dưới một mili-giây sẽ chẳng có ý nghĩa gì nếu các tác vụ phía sau bị nghẽn. Hãy thêm một middleware đo thời gian gọn nhẹ để ghi lại thời lượng xử lý request và trả về qua header chuẩn Server-Timing:

app.use('*', async (c, next) => {
  const start = performance.now();
  await next();
  const elapsed = (performance.now() - start).toFixed(2);
  
  c.header('Server-Timing', `total;dur=${elapsed}`);
  console.log(`[HTTP] ${c.req.method} ${c.req.path} -> ${c.res.status} (${elapsed}ms)`);
});

Trên Cloudflare Workers, thời gian cold start giảm xuống dưới 5ms với thời gian thực thi trung vị (median) dưới 2ms đối với các route được cache hoặc lưu trong bộ nhớ. Bạn có được một codebase duy nhất, chuẩn type-safe, chạy mượt mà từ môi trường phát triển cục bộ, container Docker cho đến mạng lưới edge trên toàn cầu.

Share: