1 
2سال‌ها انتخاب فریم‌ورک وب JavaScript به معنای پذیرش یک سازش بود: Express جهانی اما کند و وابسته به Node بود، Fastify سریع اما فقط Node، Next.js کامل اما سنگین. وقتی رنتایم‌های edge — Cloudflare Workers، Deno Deploy، Bun، Vercel Edge — آمدند، آن فریم‌ورک‌ها محدودیت‌های خود را نشان دادند.
3 
4[Hono](https://hono.dev) (در ژاپنی به معنی "شعله" 🔥) پاسخ مدرن است. فریم‌ورکی کمتر از ۱۴KB، کاملاً روی Web Standards (`Request`، `Response`، `fetch`) ساخته شده، که هر جا یک رنتایم JavaScript باشد اجرا می‌شود. همان کد بدون تغییر روی Cloudflare Workers، Bun، Deno، Node.js، Vercel، Netlify و AWS Lambda مستقر می‌شود.
5 
6## چرا Hono
7 
81. **عملکرد.** `RegExpRouter` تمام الگوهای مسیر را در یک regex کامپایل می‌کند. بنچمارک‌ها از ۴۰۰٫۰۰۰ ops/ثانیه فراتر می‌روند.
92. **قابلیت حمل.** Web Standards یعنی صفر وابستگی به Node.
103. **DX TypeScript-first.** پارامترهای مسیر به‌عنوان literal type استنتاج می‌شوند، کلاینت RPC امن از نظر نوع end-to-end.
11 
12```mermaid
13graph LR
14    Client[Client] -->|Request| App[app.fetch]
15    App --> MW1[Middleware 1]
16    MW1 --> MW2[Middleware 2]
17    MW2 --> Router[RegExpRouter]
18    Router --> Handler[Route Handler]
19    Handler --> Context[c.json / c.text]
20    Context -->|Response| Client
21    App -.->|deploy| CF[Cloudflare Workers]
22    App -.->|deploy| Bun[Bun]
23    App -.->|deploy| Deno[Deno]
24    App -.->|deploy| Node[Node.js]
25    App -.->|deploy| Vercel[Vercel]
26```
27 
28## شروع
29 
30```bash
31npm create hono@latest my-api
32cd my-api
33npm install
34npm run dev
35```
36 
37```typescript
38// src/index.ts
39import { Hono } from 'hono'
40 
41const app = new Hono()
42 
43app.get('/', (c) => c.text('Hello Hono!'))
44 
45export default app
46```
47 
48روی Cloudflare Workers همین کافی است. روی Bun: `Bun.serve({ fetch: app.fetch, port: 3000 })`. روی Node: `serve({ fetch: app.fetch })` از `@hono/node-server`.
49 
50## مسیریابی
51 
52```typescript
53import { Hono } from 'hono'
54 
55const app = new Hono()
56 
57app.get('/', (c) => c.text('Home'))
58app.get('/posts/:id', (c) => {
59  const id = c.req.param('id')
60  return c.json({ id })
61})
62app.get('/posts/:id/comments/:commentId', (c) => {
63  const { id, commentId } = c.req.param()
64  return c.json({ id, commentId })
65})
66app.get('/files/*', (c) => c.text('Wildcard'))
67app.post('/posts', async (c) => {
68  const body = await c.req.json()
69  return c.json({ created: body }, 201)
70})
71```
72 
73### گروه‌بندی مسیرها
74 
75```typescript
76// routes/posts.ts
77import { Hono } from 'hono'
78 
79const posts = new Hono()
80posts.get('/', (c) => c.json({ posts: [] }))
81posts.get('/:id', (c) => c.json({ id: c.req.param('id') }))
82export default posts
83 
84// src/index.ts
85import { Hono } from 'hono'
86import posts from './routes/posts'
87 
88const app = new Hono()
89app.route('/posts', posts)
90```
91 
92## شیء Context
93 
94```typescript
95app.post('/echo', async (c) => {
96  const userAgent = c.req.header('User-Agent')
97  const page = c.req.query('page')
98  const body = await c.req.json()
99  const env = c.env
100 
101  c.set('requestId', crypto.randomUUID())
102  const id = c.get('requestId')
103 
104  c.header('X-Request-Id', id)
105  c.status(200)
106  return c.json({ userAgent, page, body, id })
107})
108```
109 
110## میان‌افزار: مدل پیازی
111 
112```typescript
113import { Hono } from 'hono'
114import { logger } from 'hono/logger'
115import { cors } from 'hono/cors'
116import { secureHeaders } from 'hono/secure-headers'
117 
118const app = new Hono()
119 
120app.use('*', logger())
121app.use('*', secureHeaders())
122app.use('/api/*', cors({ origin: 'https://spinny.dev' }))
123 
124app.use('*', async (c, next) => {
125  const start = performance.now()
126  await next()
127  c.header('X-Response-Time', `${performance.now() - start}ms`)
128})
129```
130 
131### میان‌افزارهای داخلی
132 
133| میان‌افزار | کاربرد |
134|-----------|---------|
135| `logger` | لاگ ساختاریافته متد، مسیر، وضعیت، مدت |
136| `cors` | CORS قابل پیکربندی بر اساس origin، متدها، هدرها |
137| `csrf` | محافظت CSRF مبتنی بر origin |
138| `secureHeaders` | تنظیم CSP، HSTS، X-Frame-Options |
139| `bearerAuth` / `basicAuth` | احراز هویت Bearer/Basic آماده |
140| `jwt` | تأیید/امضای JWT با `jose` |
141| `etag` | تولید ETag و مدیریت ۳۰۴ |
142| `cache` | کش از طریق Web Cache API |
143| `compress` | gzip/deflate روی پاسخ |
144| `bodyLimit` | رد body بالاتر از آستانه |
145| `timing` | هدر Server-Timing برای پروفایلینگ |
146 
147### میان‌افزار سفارشی امن از نظر نوع
148 
149```typescript
150import { createMiddleware } from 'hono/factory'
151 
152type AuthVars = { userId: string; role: 'user' | 'admin' }
153 
154export const requireAuth = createMiddleware<{ Variables: AuthVars }>(
155  async (c, next) => {
156    const token = c.req.header('Authorization')?.replace('Bearer ', '')
157    if (!token) return c.json({ error: 'Unauthorized' }, 401)
158 
159    const payload = await verifyJwt(token)
160    c.set('userId', payload.sub)
161    c.set('role', payload.role)
162    await next()
163  }
164)
165 
166app.get('/me', requireAuth, (c) => {
167  const userId = c.var.userId
168  return c.json({ userId })
169})
170```
171 
172## اعتبارسنجی با Zod
173 
174```typescript
175import { Hono } from 'hono'
176import { zValidator } from '@hono/zod-validator'
177import { z } from 'zod'
178 
179const createPost = z.object({
180  title: z.string().min(1).max(200),
181  body: z.string().min(1),
182  tags: z.array(z.string()).default([]),
183})
184 
185app.post(
186  '/posts',
187  zValidator('json', createPost),
188  (c) => {
189    const data = c.req.valid('json')
190    return c.json({ ok: true, post: data }, 201)
191  }
192)
193```
194 
195## RPC: کلاینت امن از نظر نوع end-to-end
196 
197```typescript
198// server.ts
199import { Hono } from 'hono'
200import { zValidator } from '@hono/zod-validator'
201import { z } from 'zod'
202 
203const app = new Hono()
204  .get('/posts/:id', (c) =>
205    c.json({ id: c.req.param('id'), title: 'Hello' })
206  )
207  .post(
208    '/posts',
209    zValidator('json', z.object({ title: z.string(), body: z.string() })),
210    (c) => c.json({ ok: true }, 201)
211  )
212 
213export type AppType = typeof app
214export default app
215```
216 
217```typescript
218// client.ts
219import { hc } from 'hono/client'
220import type { AppType } from './server'
221 
222const client = hc<AppType>('https://api.spinny.dev')
223 
224const res = await client.posts[':id'].$get({ param: { id: '42' } })
225if (res.ok) {
226  const data = await res.json()
227  console.log(data.title)
228}
229 
230const created = await client.posts.$post({
231  json: { title: 'سلام', body: 'Hono یک شعله است' },
232})
233```
234 
235### تمایز کد وضعیت
236 
237```typescript
238.get('/posts/:id', (c) => {
239  const post = findPost(c.req.param('id'))
240  if (!post) return c.json({ error: 'not found' }, 404)
241  return c.json({ post }, 200)
242})
243```
244 
245```typescript
246const res = await client.posts[':id'].$get({ param: { id } })
247if (res.status === 404) {
248  const { error } = await res.json()
249}
250if (res.status === 200) {
251  const { post } = await res.json()
252}
253```
254 
255## روترها و عملکرد
256 
257| روتر | نقاط قوت | چه زمانی استفاده شود |
258|--------|-----------|-------------|
259| `RegExpRouter` | حداکثر سرعت، regex کامپایل‌شده | پیش‌فرض برای اکثر APIها |
260| `TrieRouter` | از همه الگوها پشتیبانی می‌کند | الگوهای پیچیده‌ای که RegExp مدیریت نمی‌کند |
261| `SmartRouter` | بهترین را خودکار انتخاب می‌کند | پیش‌فرض پیشنهادی |
262| `LinearRouter` | ثبت فوق‌سریع | ورکرهای یک‌بار مصرف، cold start حیاتی |
263| `PatternRouter` | حداقل بسته (<15KB) | محدودیت‌های شدید اندازه |
264 
265```typescript
266import { Hono } from 'hono'
267import { LinearRouter } from 'hono/router/linear-router'
268 
269const app = new Hono({ router: new LinearRouter() })
270```
271 
272## استقرار چندرنتایم
273 
274### Cloudflare Workers
275 
276```typescript
277import { Hono } from 'hono'
278 
279type Bindings = { MY_KV: KVNamespace; DB: D1Database }
280const app = new Hono<{ Bindings: Bindings }>()
281 
282app.get('/cache/:key', async (c) => {
283  const value = await c.env.MY_KV.get(c.req.param('key'))
284  return c.json({ value })
285})
286 
287export default app
288```
289 
290استقرار: `npx wrangler deploy`.
291 
292### Bun
293 
294```typescript
295import { Hono } from 'hono'
296const app = new Hono()
297app.get('/', (c) => c.text('Bun + Hono'))
298 
299Bun.serve({ fetch: app.fetch, port: 3000 })
300```
301 
302### Node.js
303 
304```typescript
305import { serve } from '@hono/node-server'
306import { Hono } from 'hono'
307 
308const app = new Hono()
309app.get('/', (c) => c.text('Node + Hono'))
310 
311serve({ fetch: app.fetch, port: 3000 })
312```
313 
314### Deno
315 
316```typescript
317import { Hono } from 'jsr:@hono/hono'
318const app = new Hono()
319app.get('/', (c) => c.text('Deno + Hono'))
320Deno.serve(app.fetch)
321```
322 
323### Vercel
324 
325```typescript
326// api/[[...route]].ts
327import { Hono } from 'hono'
328import { handle } from 'hono/vercel'
329 
330const app = new Hono().basePath('/api')
331app.get('/hello', (c) => c.json({ msg: 'Hello from Vercel' }))
332 
333export const GET = handle(app)
334export const POST = handle(app)
335```
336 
337## مثال عملی: REST API با احراز هویت و DB
338 
339```typescript
340import { Hono } from 'hono'
341import { jwt } from 'hono/jwt'
342import { logger } from 'hono/logger'
343import { cors } from 'hono/cors'
344import { zValidator } from '@hono/zod-validator'
345import { z } from 'zod'
346 
347type Bindings = { DB: D1Database; JWT_SECRET: string }
348type Variables = { jwtPayload: { sub: string } }
349 
350const app = new Hono<{ Bindings: Bindings; Variables: Variables }>()
351 
352app.use('*', logger())
353app.use('/api/*', cors({ origin: 'https://spinny.dev', credentials: true }))
354 
355const auth = (c: any, next: any) =>
356  jwt({ secret: c.env.JWT_SECRET })(c, next)
357 
358const api = app.basePath('/api')
359 
360api.get('/posts', async (c) => {
361  const { results } = await c.env.DB
362    .prepare('SELECT id, title, created_at FROM posts ORDER BY created_at DESC LIMIT 50')
363    .all()
364  return c.json({ posts: results })
365})
366 
367api.post(
368  '/posts',
369  auth,
370  zValidator('json', z.object({
371    title: z.string().min(1).max(200),
372    body: z.string().min(1),
373  })),
374  async (c) => {
375    const { title, body } = c.req.valid('json')
376    const userId = c.var.jwtPayload.sub
377    const result = await c.env.DB
378      .prepare('INSERT INTO posts (title, body, author_id) VALUES (?, ?, ?) RETURNING id')
379      .bind(title, body, userId)
380      .first<{ id: number }>()
381    return c.json({ id: result?.id }, 201)
382  }
383)
384 
385api.onError((err, c) => {
386  console.error(err)
387  return c.json({ error: 'Internal error' }, 500)
388})
389 
390export type AppType = typeof api
391export default app
392```
393 
394## تست
395 
396```typescript
397import { describe, it, expect } from 'vitest'
398import app from '../src/index'
399 
400describe('GET /api/posts', () => {
401  it('فهرست پست‌ها را برمی‌گرداند', async () => {
402    const res = await app.request('/api/posts')
403    expect(res.status).toBe(200)
404    const body = await res.json()
405    expect(body.posts).toBeInstanceOf(Array)
406  })
407})
408```
409 
410## بهترین شیوه‌ها
411 
412### ۱. تعاریف مسیر را زنجیره‌ای کنید
413 
414```typescript
415const app = new Hono()
416  .get('/posts', handler1)
417  .post('/posts', handler2)
418  .get('/posts/:id', handler3)
419```
420 
421### ۲. نوع را خروجی بدهید، نه پیاده‌سازی را
422 
423کلاینت باید `AppType` را وارد کند.
424 
425### ۳. یک روتر برای هر دامنه
426 
427زیراپ برای `posts`، `users`، `webhooks`.
428 
429### ۴. اعتبارسنجی در مرز، همیشه
430 
431هر ورودی خارجی باید از `zValidator` عبور کند.
432 
433### ۵. به bindings تکیه کنید، نه به کلاینت‌های جهانی
434 
435در Cloudflare از طریق `c.env` به KV/D1/R2 دسترسی پیدا کنید.
436 
437### ۶. قبل از بهینه‌سازی روتر اندازه‌گیری کنید
438 
439`SmartRouter` پیش‌فرض برای ۹۵٪ موارد مناسب است.
440 
441## نتیجه‌گیری
442 
443Hono در سال ۲۰۲۶ به استاندارد عملی برای ساخت APIهای آماده edge در TypeScript تبدیل شده است.
444 
445> **چک‌لیست شروع:**
446>
447> - [x] `npm create hono@latest` و قالب رنتایم خود را انتخاب کنید
448> - [x] مسیرها را با زنجیره تعریف کنید (`.get(...).post(...)`)
449> - [x] `logger`، `cors`، `secureHeaders` را به‌عنوان میان‌افزار جهانی اضافه کنید
450> - [x] هر ورودی را با `@hono/zod-validator` اعتبارسنجی کنید
451> - [x] `AppType` را خروجی دهید و API را با کلاینت `hc` امن از نظر نوع مصرف کنید
452> - [x] تست‌ها را با `app.request()` بنویسید — بدون نیاز به سرور HTTP
453> - [x] با `wrangler deploy` (CF)، `vercel deploy` یا باندلر رنتایم خود مستقر کنید
454