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