🔥
Hono 치트시트

초경량·초고속 멀티 런타임 웹 표준 프레임워크 완벽 가이드: 시스템 요구사양, Cloudflare Workers/Bun/Node.js 환경 구축, 스마트 라우터 & Context 생명주기, Zod 스키마 검증, Hono RPC 엔드투엔드 타입 세이프티, 미들웨어 및 엣지 스트리밍
#hono#typescript#cloudflare-workers#bun#nodejs#edge-computing#web-standards#rest-api#zod#rpc최종 업데이트: 2026-10-09
Hono 치트시트 핵심 명령어 및 실전 가이드

## 1. 필수 사전 설치 요건 & 개발 환경 구성 (Prerequisites)

### 💻 시스템 설치 및 실행 요구사양 (System Requirements)

| 항목 | 최소 사양 (Minimum) | 권장 사양 (Recommended) | 참고 및 비고 |
| :--- | :--- | :--- | :--- |
| **운영체제 (OS)** | Linux, macOS, Windows 10/11 (WSL2 권장) | Ubuntu 22.04 LTS, macOS (Apple Silicon), Windows 11 | 모든 현대적 OS 지원 |
| **CPU** | 1 코어 이상 | 2 코어 ~ 4 코어 이상 | TypeScript 트랜스파일 및 번들링 |
| **메모리 (RAM)** | 512 MB 이상 (서버리스 128MB 지원) | 2 GB ~ 4 GB 이상 | 초경량 프레임워크 (번들 크기 < 14KB) |
| **디스크 (Storage)** | 200 MB 이상의 여유 공간 | 1 GB 이상의 SSD | node_modules 및 캐시 공간 |
| **네트워크 / 런타임** | Node.js 18.14.1+, Bun 1.0+, Deno 1.30+ | Bun 1.1+ 또는 Node.js 22 LTS, Cloudflare Workers | Web Fetch API 표준 준수 런타임 |

Hono(호노 - 일본어로 '불꽃(炎)'을 뜻함)는 Web Fetch API(`Request`, `Response`, `Headers`) 표준을 엄격히 준수하여 **어디서나(Anywhere)** 실행되는 초경량·초고속 웹 프레임워크입니다. Express나 Fastify와 달리 Node.js 전용 C++ 바인딩에 의존하지 않으므로 **Cloudflare Workers, Deno, Bun, Fastly, AWS Lambda, Node.js** 등 모든 자바스크립트 런타임에서 동일한 코드로 구동됩니다.

---

### 🟢 1. 지원 런타임 버전 확인 및 설치

Hono를 실행하기 위한 자바스크립트/타입스크립트 런타임을 준비합니다.

```bash
# 옵션 A: Bun 사용 시 (초고속 권장 - Bun은 네이티브 TS 및 Hono 지원이 매우 뛰어남)
curl -fsSL https://bun.sh/install | bash
bun -v # 1.0.0 이상 확인

# 옵션 B: Node.js 사용 시 (LTS 18.14.1 이상, 권장: Node.js 20.x 또는 22.x LTS)
node -v
npm -v

# Node 버전 관리자(fnm)를 통한 최신 LTS 설치
fnm install --lts
fnm use lts-latest
```

---

### 🛠️ 2. `create-hono` 스타터를 통한 프로젝트 생성

공식 스캐폴딩 도구인 `create-hono`를 사용하면 사용할 런타임(Cloudflare Workers, Bun, Node.js 등)에 맞는 최적화된 템플릿을 대화형으로 생성할 수 있습니다:

```bash
# 1. create-hono 대화형 CLI 실행
npm create hono@latest my-hono-app
# 또는 Bun 사용 시:
# bun create hono my-hono-app

# 2. 터미널 프롬프트 안내에 따라 원하는 런타임 선택:
# ? Target directory: my-hono-app
# ? Which template do you want to use?
#   cloudflare-workers (권장: 글로벌 엣지 서버리스)
#   bun (권장: 초고속 로컬/컨테이너 백엔드)
#   nodejs (기존 Node.js 생태계 호환)
#   deno

# 3. 디렉토리 이동 및 의존성 설치
cd my-hono-app
npm install  # (Bun 템플릿의 경우: bun install)
```

---

### ⚙️ 3. 런타임별 패키지 구성 및 실행 진입점

Hono는 웹 표준 인터페이스를 가지므로 런타임별 진입점 어댑터만 다를 뿐, 애플리케이션 코드는 100% 동일합니다:

#### A. Cloudflare Workers 환경 (`wrangler`)
```bash
# Cloudflare Workers 로컬 개발 서버 구동
npx wrangler dev

# Cloudflare 전 세계 엣지 네트워크로 원클릭 배포
npx wrangler deploy
```

#### B. Bun 환경
```bash
# Bun 네이티브 고속 개발 서버 실행 (핫 리로드)
bun --watch src/index.ts
```

#### C. Node.js 환경 (`@hono/node-server`)
Node.js는 네이티브 Web Fetch 서버가 아니므로 `@hono/node-server` 어댑터를 사용합니다:
```bash
# Node.js용 서버 어댑터 및 TypeScript 실행기 설치
npm install @hono/node-server
npm install -D tsx typescript @types/node

# 개발 서버 실행
npx tsx watch src/index.ts
```

---

### 📦 4. 필수 의존성 패키지 설치 (`Zod` 및 유효성 검사기)

타입 안전한 REST API 구축을 위해 Zod 유효성 검사기 및 클라이언트 라이브러리를 설치합니다:

```bash
# Zod 유효성 검증 미들웨어
npm install @hono/zod-validator zod

# 프론트엔드 End-to-End RPC 클라이언트를 위한 패키지 (Hono 코어에 포함되어 있음)
# import { hc } from 'hono/client'
```

---

## 2. Hono 멘탈 모델 & 아키텍처 다이어그램 (Mental Model & Architecture)

### 💡 Hono 핵심 동작 원리 (웹 표준과 초고속 정규표현식 라우팅)

```
[클라이언트 요청]
       │  (HTTP Request)
       ▼
┌────────────────────────────────────────────────────────┐
│  런타임 추상화 계층 (Runtime Adapters)                   │
│  Cloudflare Workers / Bun / Node.js / Deno / AWS Lambda│
└────────────────────────────────────────────────────────┘
       │  Web Standard Request 변환
       ▼
┌────────────────────────────────────────────────────────┐
│  RegExpRouter (선형 정규표현식 기반 초고속 라우트 매칭)   │
│  Trie 트리 탐색 대비 메모리 절약 & O(1)에 근접한 속도    │
└────────────────────────────────────────────────────────┘
       │
       ▼
┌────────────────────────────────────────────────────────┐
│  미들웨어 파이프라인 (Onion Model - 양파 껍질 구조)     │
│  1. cors() ──────────► 2. logger() ──► 3. bearerAuth() │
│      │                     │               │           │
│      ▼                     ▼               ▼           │
│  [핸들러 실행] c.req ──► 비즈니스 로직 ──► c.json(...) │
│      ▲                     ▲               ▲           │
│      │                     │               │           │
│  1. 응답 헤더 추가 ◄── 2. 경과 시간 로깅 ◄─┘           │
└────────────────────────────────────────────────────────┘
       │
       ▼
[클라이언트 응답 (Web Standard Response)]
```

### 🔑 핵심 구성 요소
1. **Context (`c`)**: 단일 요청-응답 수명주기 전체를 캡슐화한 핵심 객체입니다. `c.req`(요청 파싱), `c.text()`, `c.json()`, `c.env`(엣지 환경변수 및 KV/D1 바인딩), `c.set()` / `c.get()`(미들웨어 간 상태 전달)을 제공합니다.
2. **RegExpRouter**: Hono가 직접 개발한 라우팅 엔진으로, 수십 개의 라우트 패턴을 단 하나의 거대한 정규표현식으로 합성하여 매칭하므로 JavaScript 엔진의 C++ 정규식 최적화 혜택을 100% 누립니다.
3. **Multi-Runtime Fetch Handlers**: `export default app`을 선언하면 Cloudflare Workers와 Bun이 자동으로 네이티브 fetch 이벤트 리스너로 인식하여 구동됩니다.

---

## 3. [초보자 1단계] 헬로월드 및 기초 라우팅 (Hello World & Basic Routing)

단일 파일로 바로 실행 가능한 Hono 최소 애플리케이션입니다.

### 📝 `src/index.ts` (완전한 실행 코드)

```typescript
import { Hono } from 'hono';

// 1. Hono 인스턴스 초기화
const app = new Hono();

// 2. 루트 경로 GET 요청 핸들러 (c.text() 응답)
app.get('/', (c) => {
  return c.text('🔥 Hello, Hono! Welcome to Modern Web Development.');
});

// 3. JSON 응답 및 상태 코드 제어 (c.json())
app.get('/api/health', (c) => {
  return c.json(
    {
      status: 'ok',
      uptime: process.uptime ? process.uptime() : 'edge-runtime',
      timestamp: new Date().toISOString(),
    },
    200
  );
});

// 4. 경로 파라미터(Path Parameter) 조회 (c.req.param())
app.get('/api/users/:id', (c) => {
  const userId = c.req.param('id');
  return c.json({
    message: '사용자 조회 성공',
    userId: Number(userId),
    username: `dev_user_${userId}`,
  });
});

// 5. 쿼리 파라미터(Query Parameter) 조회 (c.req.query())
app.get('/api/search', (c) => {
  const query = c.req.query('q') || '';
  const page = Number(c.req.query('page') || '1');
  const limit = Number(c.req.query('limit') || '10');

  return c.json({
    searchQuery: query,
    pagination: { page, limit },
    results: [
      { id: 1, title: `${query} 관련 기술 아티클` },
      { id: 2, title: `${query} 실전 프로덕션 팁` },
    ],
  });
});

// 6. POST 요청 본문(JSON Body) 파싱 (await c.req.json())
app.post('/api/articles', async (c) => {
  const body = await c.req.json<{ title: string; content: string }>();

  // 201 Created 응답 및 커스텀 헤더 설정
  c.header('X-Created-By', 'Hono-Engine');
  return c.json(
    {
      success: true,
      createdArticle: {
        id: Math.floor(Math.random() * 1000) + 1,
        title: body.title,
        content: body.content,
        createdAt: new Date().toISOString(),
      },
    },
    201
  );
});

// Bun 또는 Cloudflare Workers 환경을 위한 기본 익스포트
export default app;

// Node.js 환경에서 직접 실행할 경우 아래 주석을 해제하여 구동:
// import { serve } from '@hono/node-server';
// serve({ fetch: app.fetch, port: 3000 }, (info) => {
//   console.log(`🚀 Hono Server running on http://localhost:${info.port}`);
// });
```

---

### 💻 실행 및 `curl` 테스트 검증

```bash
# [실행] Bun 환경인 경우:
bun --watch src/index.ts

# [실행] Node.js 환경인 경우:
npx tsx watch src/index.ts

# -------------------------------------------------------------
# [테스트 1] 헬로월드 텍스트 요청
curl http://localhost:3000/
# 출력:
# 🔥 Hello, Hono! Welcome to Modern Web Development.

# [테스트 2] 경로 파라미터 조회
curl http://localhost:3000/api/users/42
# 출력:
# {"message":"사용자 조회 성공","userId":42,"username":"dev_user_42"}

# [테스트 3] 쿼리스트링 검색
curl "http://localhost:3000/api/search?q=hono&page=1"
# 출력:
# {"searchQuery":"hono","pagination":{"page":1,"limit":10},"results":[{"id":1,"title":"hono 관련 기술 아티클"},{"id":2,"title":"hono 실전 프로덕션 팁"}]}

# [테스트 4] POST JSON 생성
curl -X POST http://localhost:3000/api/articles \
  -H "Content-Type: application/json" \
  -d '{"title": "Hono 도입 가이드", "content": "14KB 미만의 가벼운 프레임워크"}'
# 출력 (HTTP 201 Created):
# {"success":true,"createdArticle":{"id":782,"title":"Hono 도입 가이드","content":"14KB 미만의 가벼운 프레임워크","createdAt":"2026-10-09T08:30:00.000Z"}}
```

---

## 4. [2단계] 핵심 기능 & 실무 아키텍처 (Core Features & Middleware)

엔터프라이즈 환경에서 필수적인 **모듈식 라우팅**, **내장 미들웨어**, **Zod 유효성 검사** 및 **Context 변수 공유** 패턴입니다.

### 🧩 1. 모듈식 라우터 분리 (`app.route()`)

거대한 애플리케이션을 도메인별 하위 라우터로 깔끔하게 분리할 수 있습니다:

```typescript
// src/routes/posts.ts
import { Hono } from 'hono';

export const postRouter = new Hono()
  .get('/', (c) => c.json([{ id: 1, title: '첫 번째 게시글' }]))
  .get('/:id', (c) => c.json({ id: c.req.param('id'), title: '상세 게시글' }))
  .delete('/:id', (c) => c.json({ message: `게시글 ${c.req.param('id')} 삭제 완료` }));
```

```typescript
// src/index.ts
import { Hono } from 'hono';
import { postRouter } from './routes/posts';

const app = new Hono();

// '/api/posts' 프리픽스로 하위 라우터 마운트
app.route('/api/posts', postRouter);

export default app;
```

---

### 🛡️ 2. 필수 내장 미들웨어 파이프라인

Hono는 외부 의존성 없이 프레임워크 자체에 고성능 미들웨어를 내장하고 있습니다:

```typescript
import { Hono } from 'hono';
import { logger } from 'hono/logger';
import { cors } from 'hono/cors';
import { prettyJSON } from 'hono/pretty-json';
import { secureHeaders } from 'hono/secure-headers';
import { bearerAuth } from 'hono/bearer-auth';

const app = new Hono();

// 1. HTTP 요청 로깅 미들웨어 (요청 메서드, 경로, 응답 코드, 응답 시간 표시)
app.use('*', logger());

// 2. 보안 HTTP 응답 헤더 자동 추가 (HSTS, X-Content-Type-Options 등)
app.use('*', secureHeaders());

// 3. CORS(교차 출처 리소스 공유) 헤더 설정
app.use(
  '/api/*',
  cors({
    origin: ['https://example.com', 'http://localhost:5173'],
    allowMethods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
    allowHeaders: ['Content-Type', 'Authorization'],
    maxAge: 86400,
  })
);

// 4. JSON 응답 들여쓰기 포맷팅 (쿼리에 ?pretty 추가 시 활성화)
app.use('*', prettyJSON());

// 5. 관리자 전용 경로 Bearer 토큰 인증 미들웨어
const ADMIN_API_TOKEN = 'secret-production-token-12345';
app.use('/api/admin/*', bearerAuth({ token: ADMIN_API_TOKEN }));

app.get('/api/admin/dashboard', (c) => {
  return c.json({ systemStatus: 'All Systems Operational', secretValue: 9999 });
});
```

---

### 🎯 3. Zod 기반 엔드투엔드 유효성 검증 (`@hono/zod-validator`)

`zValidator`를 사용하면 요청 본문(`json`), 쿼리스트링(`query`), 경로 파라미터(`param`), 헤더(`header`)를 검증하고, **검증을 통과한 데이터의 타입을 자동으로 추론**합니다:

```typescript
import { Hono } from 'hono';
import { zValidator } from '@hono/zod-validator';
import { z } from 'zod';

const app = new Hono();

// 1. Zod 스키마 정의
const CreateUserSchema = z.object({
  email: z.string().email({ message: '올바른 이메일 형식을 입력하세요.' }),
  password: z.string().min(8, { message: '비밀번호는 최소 8자 이상이어야 합니다.' }),
  age: z.number().int().min(14, { message: '14세 이상만 가입 가능합니다.' }).optional(),
});

const UserQuerySchema = z.object({
  role: z.enum(['admin', 'member', 'guest']).default('member'),
});

// 2. 라우트에 zValidator 미들웨어 연결
app.post(
  '/api/v1/users',
  zValidator('json', CreateUserSchema, (result, c) => {
    // 유효성 검증 실패 시 사용자 정의 에러 응답
    if (!result.success) {
      return c.json(
        {
          success: false,
          errors: result.error.issues.map((issue) => ({
            field: issue.path.join('.'),
            message: issue.message,
          })),
        },
        400
      );
    }
  }),
  async (c) => {
    // 3. 검증 완료된 데이터 획득 (완벽한 TypeScript 자동완성 제공)
    const validData = c.req.valid('json');

    console.log(`신규 가입 요청 이메일: ${validData.email}`);

    return c.json(
      {
        success: true,
        user: {
          id: 101,
          email: validData.email,
          age: validData.age ?? null,
        },
      },
      201
    );
  }
);
```

---

### 📦 4. 커스텀 미들웨어 및 Context 상태 공유 (`c.set` & `c.get`)

타입 안전하게 미들웨어에서 인증된 사용자 정보를 저장하고 후속 핸들러에서 꺼내 쓰는 패턴입니다:

```typescript
import { Hono } from 'hono';

// 1. Context에 저장할 Variables 타입 인터페이스 정의
interface AppVariables {
  Variables: {
    currentUser: {
      userId: string;
      role: 'admin' | 'user';
    };
    requestId: string;
  };
}

// 2. 제네릭으로 AppVariables 전달
const app = new Hono<AppVariables>();

// 3. 커스텀 인증 및 요청 ID 주입 미들웨어
app.use('*', async (c, next) => {
  const reqId = crypto.randomUUID();
  c.set('requestId', reqId);

  // 헤더에서 토큰 검증 시뮬레이션
  const authHeader = c.req.header('Authorization');
  if (authHeader?.startsWith('Bearer admin-key')) {
    c.set('currentUser', { userId: 'admin_01', role: 'admin' });
  } else {
    c.set('currentUser', { userId: 'guest_99', role: 'user' });
  }

  // 다음 핸들러로 제어권 위임 (필수: await next())
  await next();

  // 후처리 (응답 헤더에 요청 ID 첨부)
  c.header('X-Request-Id', reqId);
});

// 4. 비즈니스 로직 핸들러에서 타입 안전하게 꺼내기
app.get('/api/profile', (c) => {
  const user = c.get('currentUser'); // { userId: string; role: 'admin' | 'user' } 자동 추론
  const reqId = c.get('requestId');

  return c.json({
    requestId: reqId,
    profile: {
      id: user.userId,
      role: user.role,
      accessedAt: new Date().toISOString(),
    },
  });
});
```

---

## 5. [3단계] 실무 응용 & 고급 패턴 (Advanced Production Patterns)

### 🚀 1. Hono RPC: 프론트엔드-백엔드 간 End-to-End 타입 세이프티

Hono RPC를 사용하면 백엔드 코드 생성기(tRPC나 GraphQL Code Generator 등) 없이도 **백엔드 라우트 타입만 익스포트**하여 프론트엔드에서 완전한 타입 자동완성을 누릴 수 있습니다:

#### 1) 백엔드 (`server.ts`)
```typescript
import { Hono } from 'hono';
import { zValidator } from '@hono/zod-validator';
import { z } from 'zod';

const postSchema = z.object({
  title: z.string().min(2),
  content: z.string(),
});

// 메서드 체이닝을 유지하여 라우트 인스턴스 생성
const apiRoutes = new Hono()
  .get('/items', (c) => {
    return c.json([
      { id: 1, name: 'Cloudflare Worker' },
      { id: 2, name: 'Hono Framework' },
    ]);
  })
  .post('/items', zValidator('json', postSchema), (c) => {
    const { title, content } = c.req.valid('json');
    return c.json({ id: 3, title, content, success: true }, 201);
  });

// 최상위 앱에 마운트
const app = new Hono().route('/api', apiRoutes);

// 클라이언트를 위한 라우트 타입 익스포트
export type AppType = typeof apiRoutes;
export default app;
```

#### 2) 프론트엔드 React/Next.js (`client.ts`)
```typescript
import { hc } from 'hono/client';
import type { AppType } from './server'; // 백엔드 타입만 임포트 (런타임 번들 크기 0B)

// 백엔드 API 클라이언트 생성
const client = hc<AppType>('http://localhost:3000/api');

async function main() {
  // 1. GET 요청 (반환값 타입이 { id: number; name: string }[] 로 자동 추론됨)
  const res = await client.items.$get();
  const items = await res.json();
  console.log('아이템 목록:', items);

  // 2. POST 요청 (요청 바디 인자가 { title: string; content: string } 로 타입 검사됨)
  const postRes = await client.items.$post({
    json: {
      title: '새로운 글 작성',
      content: 'Hono RPC는 매우 강력합니다.',
    },
  });

  if (postRes.status === 201) {
    const created = await postRes.json();
    console.log(`생성 성공! ID: ${created.id}`);
  }
}
```

---

### 🌊 2. 엣지 스트리밍 & Server-Sent Events (SSE)

Hono는 Web Streams API를 활용하여 OpenAI/Claude AI 스트리밍 응답이나 실시간 알림 SSE를 완벽히 지원합니다:

```typescript
import { Hono } from 'hono';
import { streamText, streamSSE } from 'hono/streaming';

const app = new Hono();

// 1. 대용량 텍스트 / AI 응답 토큰 단위 청크 스트리밍
app.get('/api/ai/stream', (c) => {
  return streamText(c, async (stream) => {
    const message = '인공지능 LLM이 생성한 실시간 응답 텍스트 토큰입니다... ';
    for (const char of message.split('')) {
      await stream.write(char);
      await stream.sleep(40); // 40ms 지연 시뮬레이션
    }
  });
});

// 2. 실시간 Server-Sent Events (SSE) 푸시 알림
app.get('/api/notifications/sse', (c) => {
  return streamSSE(c, async (stream) => {
    let count = 1;
    while (count <= 5) {
      await stream.writeSSE({
        data: JSON.stringify({ message: `서버 상태 핑 알림 #${count}`, time: Date.now() }),
        event: 'ping',
        id: String(count),
      });
      await stream.sleep(1000); // 1초 간격 전송
      count++;
    }
  });
});
```

---

### ☁️ 3. Cloudflare Workers 생태계 연동 (D1 SQL & KV 바인딩)

Cloudflare Workers의 환경변수, Secrets, D1(서버리스 SQLite), KV(글로벌 캐시)를 타입 안전하게 다루는 방법입니다:

```typescript
// wrangler.jsonc 설정 예시:
// "kv_namespaces": [{ "binding": "CACHE_KV", "id": "xxxx" }],
// "d1_databases": [{ "binding": "DB", "database_name": "prod-db", "database_id": "xxxx" }]

import { Hono } from 'hono';

// 1. Cloudflare 바인딩 환경변수 타입 인터페이스 정의
interface Env {
  Bindings: {
    API_SECRET_KEY: string;
    CACHE_KV: KVNamespace;
    DB: D1Database;
  };
}

const app = new Hono<Env>();

// 2. D1 데이터베이스 조회 및 KV 캐싱 패턴
app.get('/api/products/:id', async (c) => {
  const productId = c.req.param('id');
  const cacheKey = `product:${productId}`;

  // Step 1: KV 글로벌 캐시 확인
  const cached = await c.env.CACHE_KV.get(cacheKey, 'json');
  if (cached) {
    return c.json({ source: 'cache', data: cached });
  }

  // Step 2: D1 SQL 데이터베이스 쿼리 실행 (Prepared Statement)
  const product = await c.env.DB.prepare('SELECT id, name, price, stock FROM products WHERE id = ?')
    .bind(productId)
    .first();

  if (!product) {
    return c.json({ error: '상품을 찾을 수 없습니다.' }, 404);
  }

  // Step 3: KV에 60초간 캐시 저장 (TTL)
  await c.env.CACHE_KV.put(cacheKey, JSON.stringify(product), { expirationTtl: 60 });

  return c.json({ source: 'database', data: product });
});
```

---

### 🚨 4. 전역 예외 처리 & HTTP 표준 에러 핸들링

```typescript
import { Hono } from 'hono';
import { HTTPException } from 'hono/http-exception';

const app = new Hono();

// 특정 비즈니스 로직에서 HTTPException 발생
app.get('/api/protected', (c) => {
  const token = c.req.header('Authorization');
  if (!token) {
    throw new HTTPException(401, { message: '인증 토큰이 누락되었습니다.' });
  }
  return c.text('접근 승인 완료');
});

// 1. 404 Not Found 전역 핸들러
app.notFound((c) => {
  return c.json(
    {
      error: 'Not Found',
      message: `요청하신 경로 [${c.req.method} ${c.req.path}]를 찾을 수 없습니다.`,
      statusCode: 404,
    },
    404
  );
});

// 2. 500 전역 에러 핸들러 (모든 비정상 예외 포획)
app.onError((err, c) => {
  console.error(`[서버 에러 발생] ${err.message}`, err.stack);

  if (err instanceof HTTPException) {
    return err.getResponse();
  }

  return c.json(
    {
      error: 'Internal Server Error',
      message: '서버 내부 처리 중 예기치 않은 오류가 발생했습니다.',
      statusCode: 500,
    },
    500
  );
});
```

---

## 6. Hono 핵심 API & 미들웨어 퀵 레퍼런스 (Cheat Sheet Quick Reference)

### 📌 `c.req` 요청 파싱 주요 메서드

| 메서드 / 프로퍼티 | 설명 | 사용 예시 |
| :--- | :--- | :--- |
| `c.req.param(name)` | 경로 파라미터 값 추출 (`:id`) | `const id = c.req.param('id');` |
| `c.req.query(name)` | 쿼리스트링 파라미터 단일 값 추출 | `const q = c.req.query('q');` |
| `c.req.queries(name)` | 동일 키의 다중 쿼리 파라미터 배열 추출 | `const tags = c.req.queries('tags');` |
| `c.req.header(name)` | 특정 요청 헤더 값 추출 | `const auth = c.req.header('Authorization');` |
| `await c.req.json()` | JSON 형식의 요청 본문 파싱 | `const body = await c.req.json();` |
| `await c.req.text()` | 일반 텍스트 본문 파싱 | `const text = await c.req.text();` |
| `await c.req.formData()`| Multipart/UrlEncoded 폼 데이터 파싱 | `const form = await c.req.formData();` |
| `c.req.valid(target)` | `zValidator` 등으로 검증된 타입 안전 데이터 | `const data = c.req.valid('json');` |

### 📤 `c` 응답 헬퍼 메서드

| 메서드 | 반환 Content-Type | 설명 |
| :--- | :--- | :--- |
| `c.text(text, status?)` | `text/plain; charset=UTF-8` | 문자열 텍스트 응답 |
| `c.json(object, status?)`| `application/json; charset=UTF-8` | JSON 객체 직렬화 응답 |
| `c.html(htmlString, status?)` | `text/html; charset=UTF-8` | HTML 문서 렌더링 응답 |
| `c.redirect(url, status?)` | `Location` 헤더 포함 | 기본 302 리다이렉트 응답 |
| `c.notFound()` | `text/plain` (404) | 404 Not Found 빠른 반환 |
| `c.header(key, value)` | - | 응답 헤더 추가/설정 |
| `c.status(statusCode)` | - | HTTP 응답 상태 코드 변경 |

### 🛠️ 공식 내장 미들웨어 요약

| 미들웨어 함수 | 패키지 경로 | 주요 역할 |
| :--- | :--- | :--- |
| `logger()` | `hono/logger` | 터미널 요청/응답 실시간 로깅 |
| `cors(options)` | `hono/cors` | Cross-Origin 리소스 공유 헤더 제어 |
| `secureHeaders()` | `hono/secure-headers` | OWASP 권장 보안 헤더 자동 주입 |
| `bearerAuth(options)` | `hono/bearer-auth` | Bearer 토큰 간이 인증 검증기 |
| `basicAuth(options)` | `hono/basic-auth` | HTTP 기본 인증(Base64) 미들웨어 |
| `jwt(options)` | `hono/jwt` | JWT 토큰 검증 및 페이로드 추출 |
| `prettyJSON()` | `hono/pretty-json` | JSON 들여쓰기 가독성 개선 |
| `compress()` | `hono/compress` | Gzip/Deflate 응답 압축 |
| `etag()` | `hono/etag` | HTTP ETag 캐시 식별자 자동 생성 |
| `timeout(ms)` | `hono/timeout` | 요청 시간 초과 시 504 반환 |

---

## 7. 실무 주의사항 & 프로덕션 체크리스트 (Gotchas & Production Checklist)

### ⚠️ 자주 발생하는 실수 & 트러블슈팅

1. **미들웨어에서 `await next()` 누락 주의**:
   - 잘못된 예: `app.use('*', (c, next) => { console.log('start'); next(); });`
   - 해결책: Hono 미들웨어는 비동기 프로미스를 반환하므로 반드시 `await next()`를 호출해야 후속 핸들러의 응답이 보장되며, 응답 후처리(경과 시간 측정 등)가 정상 작동합니다.

2. **Context(`c`) 비동기 핸들러 수명주기 주의**:
   - `c` 객체는 HTTP 요청이 종료되는 즉시 가비지 컬렉션의 대상이 되거나 메모리 풀로 반환될 수 있습니다. `setTimeout`이나 백그라운드 태스크에서 `c.req`를 나중에 비동기로 읽으려고 하면 에러가 발생합니다. 백그라운드 작업이 필요하다면 Cloudflare의 `c.executionCtx.waitUntil(promise)`를 사용하세요.

3. **엣지 런타임의 Node.js 네이티브 API 제약**:
   - Cloudflare Workers 환경에서는 Node.js의 C++ 네이티브 애드온(`.node`), 로컬 파일시스템 동기 I/O(`fs.readFileSync`), 운영체제 소켓(`net`, `dgram`) 등을 직접 쓸 수 없습니다. `wrangler.jsonc`에 `compatibility_flags = ["nodejs_compat"]` 설정을 추가하여 지원되는 Node 표준 라이브러리(`Buffer`, `crypto` 등)를 확인하세요.

---

### 📋 프로덕션 배포 체크리스트 (Edge & Serverless)

- [ ] **보안 헤더 활성화**: `app.use('*', secureHeaders())`를 최상단에 마운트하여 XSS 및 Clickjacking 방지 조치 완료.
- [ ] **엄격한 CORS 설정**: 프로덕션에서는 `origin: '*'` 대신 신뢰할 수 있는 도메인 리스트를 명시.
- [ ] **Zod 런타임 스키마 검증**: 모든 클라이언트 입력(`body`, `query`, `param`)에 `zValidator`를 적용하여 잘못된 파라미터 사전 차단.
- [ ] **전역 에러 핸들러 구성**: `app.onError` 및 `app.notFound`를 작성하여 민감한 시스템 스택트레이스가 사용자에게 노출되지 않도록 마스킹.
- [ ] **Hono RPC 인터페이스 관리**: 프론트엔드와 공유하는 `export type AppType = typeof routes;`가 최신 상태로 유지되는지 확인.
- [ ] **번들 크기 및 트리쉐이킹 검증**: 불필요한 거대 Node 라이브러리를 임포트하지 않고 Web Fetch 표준 라이브러리를 우선 사용.
💬
Hono 치트시트

의견 및 질문

댓글 수정

댓글 삭제
