Xây dựng Web API siêu nhẹ với Hono và Cloudflare Workers: Định tuyến Type-safe, Middleware và Serverless Edge

Development tutorial - IT technology blog
Development tutorial - IT technology blog

API chạy cả tháng, không ai gọi — vẫn mất tiền server

Tưởng tượng bạn viết một API nhỏ cho internal tool của team: nhận webhook, xử lý dữ liệu, trả về JSON. Không phức tạp, chỉ vài endpoint. Nhưng để deploy, bạn cần một server chạy 24/7, cài Node.js, cấu hình Nginx, lo SSL, lo update bảo mật… Và cuối tháng vẫn trả tiền VPS dù traffic thực tế chỉ vài trăm request.

Mình đã làm đúng vậy gần 3 năm. Một cái VPS $5/tháng để chạy một Express app mà tổng request trong tháng chưa đến 10,000. Hiệu quả không? Không. Có cách khác không? Có.

Vấn đề cốt lõi: Express + VPS không phải lúc nào cũng đúng công cụ

Express.js ra đời từ thời server vẫn là máy chủ vật lý. Mô hình một process Node.js xử lý tất cả request vẫn hợp lý với web app lớn — khi bạn cần database connection pool, session management, middleware stack đầy đủ. Với những thứ đó, Express làm tốt.

Nhưng với API nhỏ — webhook handler, proxy đơn giản, auth service, rate limiter — mô hình “server luôn chạy” tạo ra mấy vấn đề thực tế:

  • Idle cost không nhỏ: Server không làm gì vẫn tốn RAM, CPU, và tiền.
  • Scaling thủ công: Traffic tăng đột biến bạn phải tự lo thêm instance, load balancer.
  • Địa lý cố định: Server ở Singapore nhưng user ở Mỹ — latency cao hơn cần thiết.
  • Overhead vận hành: Update OS, monitor process crash, backup — tất cả do bạn tự lo.

Các lựa chọn thay thế: Lambda, Vercel Functions hay Cloudflare Workers?

Giải pháp đơn giản nhất: chỉ trả tiền khi code thực sự chạy. Serverless functions làm điều đó — nhưng mỗi platform xử lý khác nhau và trade-off cũng khác:

  • AWS Lambda: Mạnh, flexible, nhưng cold start có thể lên đến 1-2 giây với Node.js. Cấu hình IAM, VPC, API Gateway phức tạp hơn nhiều so với nhu cầu thực tế.
  • Vercel/Netlify Functions: Đơn giản hơn, tích hợp tốt với frontend. Nhưng giới hạn execution time (10 giây trên free plan) và request vẫn đi về một region cố định.
  • Cloudflare Workers: Chạy trên V8 isolates thay vì Node.js process. Cold start dưới 5ms. Deploy trên 300+ PoP toàn cầu. Free plan 100,000 request/ngày.

Điểm khiến Cloudflare Workers khác hẳn hai cái còn lại: nó không dùng Node.js runtime mà dùng V8 isolates — cùng engine với Chrome nhưng khởi động trong vài millisecond thay vì vài trăm ms. Đánh đổi là không có đầy đủ Node.js API (fs, net không dùng được), nhưng với Web API thông thường điều đó hiếm khi quan trọng.

Hono: Framework nhẹ nhất cho Web API hiện đại

Hono (tiếng Nhật: 炎 — ngọn lửa) là web framework được thiết kế từ đầu cho edge runtime: Cloudflare Workers, Deno, Bun, và cả Node.js. API quen thuộc giống Express nhưng type-safe hơn, nhẹ hơn (~14KB), và không cần viết adapter riêng cho từng platform.

Điểm mình thích nhất: Hono không giả vờ bạn đang ở Node.js. Nó dùng Web Standard APIs — Request, Response, Headers — chuẩn web mà browser, Deno, Bun đều hiểu ngay.

Khởi tạo dự án

# Tạo project mới với template Cloudflare Workers
npm create hono@latest my-api
# Chọn: cloudflare-workers

cd my-api
npm install

Cấu trúc thư mục ban đầu:

my-api/
├── src/
│   └── index.ts       # Entry point
├── wrangler.toml      # Cloudflare Workers config
├── package.json
└── tsconfig.json

Định tuyến cơ bản và Type-safe Response

File src/index.ts:

import { Hono } from 'hono'

const app = new Hono()

// Route đơn giản
app.get('/', (c) => c.text('Hello from Edge!'))

// Route với path parameter — type-safe
app.get('/users/:id', (c) => {
  const id = c.req.param('id')  // TypeScript biết `id` là string
  return c.json({ userId: id, status: 'active' })
})

// Route nhận POST body
app.post('/webhooks/github', async (c) => {
  const payload = await c.req.json()
  const event = c.req.header('X-GitHub-Event')

  if (event === 'push') {
    console.log('Push to:', payload.repository?.full_name)
  }

  return c.json({ received: true }, 200)
})

export default app

Thêm Middleware: Authentication, CORS và Logging

Built-in middleware là điểm mạnh của Hono — không cần npm install thêm package nào. Ví dụ với Bearer token auth, CORS và logging:

import { Hono } from 'hono'
import { bearerAuth } from 'hono/bearer-auth'
import { logger } from 'hono/logger'
import { cors } from 'hono/cors'

const app = new Hono()

// Global middleware — áp dụng cho tất cả routes
app.use('*', logger())
app.use('*', cors({
  origin: ['https://yourdomain.com'],
  allowMethods: ['GET', 'POST', 'PUT', 'DELETE'],
}))

// Protected routes — chỉ áp dụng cho /api/*
app.use('/api/*', bearerAuth({ token: 'your-secret-token' }))

app.get('/api/data', (c) => {
  return c.json({ message: 'Protected data', timestamp: Date.now() })
})

// Public route — không cần auth
app.get('/health', (c) => c.json({ ok: true }))

export default app

Biến môi trường và Secrets

Secrets trong Cloudflare Workers không giống Node.js — không có file .env truyền thống. Thay vào đó, dùng Wrangler để set trực tiếp:

# Set secret qua CLI (nhập value khi được hỏi)
npx wrangler secret put API_SECRET_KEY

# wrangler.toml — khai báo biến thông thường (không phải secret)
[vars]
ENVIRONMENT = "production"

Truy cập trong code với type-safe bindings:

// Khai báo kiểu cho environment bindings
type Bindings = {
  API_SECRET_KEY: string
  ENVIRONMENT: string
}

const app = new Hono<{ Bindings: Bindings }>()

app.get('/config', (c) => {
  // c.env có type đầy đủ — IDE gợi ý đúng tên biến
  return c.json({ environment: c.env.ENVIRONMENT })
})

Chia route theo module khi project lớn hơn

// src/routes/users.ts
import { Hono } from 'hono'

const users = new Hono()

users.get('/', (c) => c.json({ users: [] }))
users.get('/:id', (c) => c.json({ id: c.req.param('id') }))
users.post('/', async (c) => {
  const body = await c.req.json()
  return c.json({ created: true, data: body }, 201)
})

export default users
// src/index.ts — mount các sub-router
import { Hono } from 'hono'
import users from './routes/users'
import webhooks from './routes/webhooks'

const app = new Hono()

app.route('/users', users)       // /users, /users/:id
app.route('/webhooks', webhooks) // /webhooks/github, /webhooks/stripe

export default app

Test local và Deploy

# Chạy local với hot reload
npx wrangler dev
# API chạy tại http://localhost:8787

# Deploy lên Cloudflare (lần đầu cần login)
npx wrangler login
npm run deploy

# Output:
# ✅ Deployed to: https://my-api.your-username.workers.dev

Trước khi deploy, mình hay dùng Wrangler dev để test local rồi copy response vào toolcraft.app/vi/tools/developer/json-formatter để format và kiểm tra cấu trúc JSON — tiện hơn nhiều so với đọc raw trong terminal hay cài extension. Đặc biệt khi response lồng nhau nhiều tầng, format rõ ràng giúp debug nhanh hơn hẳn.

Toàn bộ quá trình deploy mất khoảng 10-15 giây. Không cần cấu hình server, không cần lo SSL (tự động qua Cloudflare), không cần setup Nginx hay PM2.

Kết quả thực tế: Từ VPS $5/tháng xuống gần $0

Sau khi chuyển vài internal API từ VPS sang Cloudflare Workers, mình thấy vài điểm khác ngay:

  • Free plan 100,000 request/ngày — đủ cho hầu hết internal tool và webhook handler nhỏ
  • Latency giảm với user ở nhiều region vì request được xử lý tại PoP gần nhất
  • Zero maintenance: không lo update OS, không lo process crash lúc 3 giờ sáng
  • Deploy và rollback chỉ một lệnh, Cloudflare giữ lịch sử deployment

Nhưng có trường hợp Cloudflare Workers không phải lựa chọn phù hợp. Nếu API cần kết nối Postgres với connection pooling phức tạp, cần long-running process, hay cần filesystem access — bạn vẫn cần server truyền thống. Với webhook handler, proxy API, auth service, rate limiter thì ngược lại — gọn hơn nhiều so với một VPS chạy 24/7 đang nhàn rỗi.

Điểm bắt đầu thực tế nhất: lấy một webhook handler đang chạy trên VPS, port nó sang Hono, deploy lên Cloudflare Workers. 2-3 giờ là xong, và cái VPS kia sẽ thành thứ bạn tự hỏi sao mình giữ lâu vậy.

Share: