戰(zhàn)：構(gòu)建類型安全的TypeScript后端API)
1. 先搞清楚 Hono 和 Zod 到底能幫你解決什么實(shí)際問題如果你正在用 TypeScript 寫后端 API或者處理任何需要接收外部輸入比如 HTTP 請求、表單、配置文件的場景那么 Hono 和 Zod 這兩個(gè)庫的組合值得你花時(shí)間了解一下。它們解決的不是“從零到一”造輪子的問題而是“如何更穩(wěn)、更快、更省心地寫生產(chǎn)級(jí)代碼”的問題。Hono 是一個(gè)輕量、快速、面向邊緣計(jì)算的 Web 框架。它最直接的價(jià)值是在 Node.js、Deno、Bun 甚至 Cloudflare Workers 等運(yùn)行時(shí)上都能提供一致且高性能的 HTTP 服務(wù)開發(fā)體驗(yàn)。你不用再為不同平臺(tái)寫適配代碼一套邏輯可以跑在多個(gè)環(huán)境。Zod 則是一個(gè)以 TypeScript 為核心的運(yùn)行時(shí)數(shù)據(jù)驗(yàn)證庫。它的核心能力是讓你用一套語法同時(shí)定義數(shù)據(jù)的類型給 TypeScript 編譯器看和驗(yàn)證規(guī)則在運(yùn)行時(shí)檢查數(shù)據(jù)。這解決了后端開發(fā)里一個(gè)老大難問題我定義了一個(gè)User接口但客戶端傳過來的數(shù)據(jù)真的符合這個(gè)接口嗎Zod 讓你能明確地回答“是”或“否”并給出清晰的錯(cuò)誤信息。把這兩個(gè)結(jié)合起來你得到的是一個(gè)“類型安全貫穿始終”的開發(fā)流程從定義 API 接口的輸入輸出類型到實(shí)際接收請求時(shí)驗(yàn)證數(shù)據(jù)再到業(yè)務(wù)邏輯中使用這些數(shù)據(jù)TypeScript 的智能提示和錯(cuò)誤檢查會(huì)一直陪伴你極大減少因數(shù)據(jù)格式錯(cuò)誤導(dǎo)致的運(yùn)行時(shí) Bug。2. 環(huán)境準(zhǔn)備別急著寫代碼先把跑道鋪好在開始任何“Mini Project”之前確保你的開發(fā)環(huán)境是就緒的。這聽起來像廢話但我見過太多人卡在第一步不是因?yàn)楣ぞ唠y用而是因?yàn)榘姹緦Σ簧匣蛘甙芾砥鳑]選對。2.1 選擇你的運(yùn)行時(shí)和包管理器Hono 支持多運(yùn)行時(shí)但對于學(xué)習(xí)和本地開發(fā)我建議從Node.js或Bun開始。Node.js 生態(tài)最廣Bun 則啟動(dòng)更快、內(nèi)置了測試運(yùn)行器和包管理器。Node.js: 確保版本在 18.x 或以上?？梢杂胣ode -v檢查。Bun: 如果你追求極速的安裝和啟動(dòng)體驗(yàn)可以試試 Bun。它的包管理器是內(nèi)置的。包管理器: npm 或 yarn 都可以。用 Bun 的話它的bun install命令兼容 npm。2.2 初始化項(xiàng)目并安裝核心依賴打開終端創(chuàng)建一個(gè)新目錄并初始化項(xiàng)目。這里以使用 npm 和 Node.js 為例mkdir learn-hono-zod cd learn-hono-zod npm init -y接下來安裝核心依賴。注意我們安裝的是生產(chǎn)依賴因?yàn)?Hono 和 Zod 本身就是運(yùn)行時(shí)需要的庫。npm install hono zod同時(shí)安裝 TypeScript 和相關(guān)的類型定義作為開發(fā)依賴npm install -D typescript types/node然后初始化 TypeScript 配置。使用npx來運(yùn)行當(dāng)前項(xiàng)目下的tscnpx tsc --init生成的tsconfig.json文件我建議至少修改或確認(rèn)以下幾項(xiàng)這對于現(xiàn)代 Node.js 開發(fā)和獲得更好的類型檢查體驗(yàn)很重要{ compilerOptions: { target: ES2022, module: ESNext, moduleResolution: node, esModuleInterop: true, strict: true, skipLibCheck: true, outDir: ./dist, rootDir: ./src }, include: [src/**/*], exclude: [node_modules] }關(guān)鍵點(diǎn)解釋“target”: “ES2022”: 使用較新的 ECMAScript 標(biāo)準(zhǔn)能用到更多現(xiàn)代語法。“module”: “ESNext”和“moduleResolution”: “node”: 配合 Hono 的 ESM 風(fēng)格導(dǎo)入。“strict”: true:強(qiáng)烈建議開啟。嚴(yán)格的類型檢查是使用 TypeScript 和 Zod 的最大意義所在?！皁utDir”和“rootDir”: 將源代碼放在src目錄編譯輸出到dist目錄保持項(xiàng)目結(jié)構(gòu)清晰。2.3 配置開發(fā)腳本和熱重載為了方便開發(fā)在package.json中添加一些腳本。我們使用tsx或ts-node來直接運(yùn)行 TypeScript 文件避免手動(dòng)編譯。這里推薦tsx它速度更快。npm install -D tsx然后在package.json的“scripts”部分添加{ “scripts”: { “dev”: “tsx watch src/index.ts”, “start”: “tsx src/index.ts”, “build”: “tsc” } }現(xiàn)在運(yùn)行npm run dev就會(huì)啟動(dòng)一個(gè)監(jiān)聽模式的服務(wù)當(dāng)你修改src/index.ts文件時(shí)服務(wù)會(huì)自動(dòng)重啟。3. 第一個(gè) Hono 應(yīng)用從 “Hello World” 到基礎(chǔ)路由讓我們先拋開 Zod感受一下 Hono 的簡潔。在src目錄下創(chuàng)建index.ts文件。3.1 創(chuàng)建應(yīng)用實(shí)例并定義路由// src/index.ts import { Hono } from ‘hono’ // 1. 創(chuàng)建 Hono 應(yīng)用實(shí)例 const app new Hono() // 2. 定義第一個(gè)路由GET / app.get(‘/’, (c) { // c 是 Context 對象包含了請求和響應(yīng)的所有信息 return c.text(‘Hello Hono!’) }) // 3. 定義帶參數(shù)的路由GET /hello/:name app.get(‘/hello/:name’, (c) { // 從路徑參數(shù)中獲取 name const name c.req.param(‘name’) return c.text(Hello, ${name}!) }) // 4. 定義處理 JSON 和查詢參數(shù)的路由 app.get(‘/api/user’, (c) { // 從查詢字符串中獲取參數(shù)例如 /api/user?id123activetrue const id c.req.query(‘id’) const isActive c.req.query(‘a(chǎn)ctive’) ‘true’ // 返回 JSON 響應(yīng) return c.json({ userId: id, active: isActive, message: ‘User data fetched (without validation for now)’ }) }) // 5. 啟動(dòng)服務(wù)器監(jiān)聽 3000 端口 export default { port: 3000, fetch: app.fetch } console.log(‘Server is running on http://localhost:3000’)現(xiàn)在運(yùn)行npm run dev打開瀏覽器訪問http://localhost:3000/- 看到 “Hello Hono!”http://localhost:3000/hello/TypeScript- 看到 “Hello, TypeScript!”http://localhost:3000/api/user?id456activetrue- 看到 JSON 響應(yīng)。你已經(jīng)有了一個(gè)能處理基本路由的 HTTP 服務(wù)。Hono 的 API 非常直觀app.get(‘/path’, handler)。handler函數(shù)接收一個(gè)Context對象 (c)通過它你能訪問請求 (c.req) 和構(gòu)造響應(yīng) (c.json(),c.text())。3.2 處理 POST 請求和請求體現(xiàn)代 API 離不開接收數(shù)據(jù)。我們來創(chuàng)建一個(gè)處理用戶注冊的 POST 接口。// 在 src/index.ts 中繼續(xù)添加 app.post(‘/api/register’, async (c) { try { // 嘗試解析 JSON 格式的請求體 const body await c.req.json() // 暫時(shí)直接使用沒有驗(yàn)證 console.log(‘Received registration data:’, body) // 模擬處理邏輯 const newUser { id: Date.now(), …body } return c.json({ success: true, user: newUser }, 201) // 201 Created } catch (error) { // 如果請求體不是合法的 JSON會(huì)在這里捕獲錯(cuò)誤 return c.json({ success: false, error: ‘Invalid JSON body’ }, 400) } })用 curl 或 Postman 測試一下curl -X POST http://localhost:3000/api/register \ -H “Content-Type: application/json” \ -d ‘{“username”: “alice”, “email”: “aliceexample.com”}’你會(huì)收到一個(gè) 201 響應(yīng)。但是這里有個(gè)嚴(yán)重問題我們完全信任了客戶端傳來的數(shù)據(jù)。如果客戶端傳了{(lán)“username”: 123, “email”: “not-an-email”}甚至{“admin”: true}我們的代碼也會(huì)照單全收。這就是運(yùn)行時(shí) Bug 的溫床。接下來Zod 就該上場了。4. 引入 Zod為你的數(shù)據(jù)穿上“防彈衣”Zod 的核心是Schema模式。你可以為任何數(shù)據(jù)結(jié)構(gòu)定義一個(gè) Schema然后用它來驗(yàn)證未知的數(shù)據(jù)。4.1 定義第一個(gè) Schema用戶注冊在src目錄下創(chuàng)建一個(gè)schemas文件夾然后創(chuàng)建user.schema.ts文件。將數(shù)據(jù)驗(yàn)證的邏輯與路由處理分離是一個(gè)好習(xí)慣。// src/schemas/user.schema.ts import { z } from ‘zod’; // 1. 定義用戶注冊數(shù)據(jù)的 Schema export const registerUserSchema z.object({ // username 必須是字符串長度在3到20個(gè)字符之間 username: z.string().min(3).max(20), // email 必須是有效的郵箱格式 email: z.string().email(), // age 是可選的數(shù)字如果提供則必須在18歲以上 age: z.number().int().positive().min(18).optional(), // tags 是一個(gè)字符串?dāng)?shù)組最多10個(gè)元素 tags: z.array(z.string()).max(10).optional(), }); // 2. 從 Schema 推斷出 TypeScript 類型 export type RegisterUserInput z.infertypeof registerUserSchema;看我們只用一套語法就同時(shí)完成了兩件事運(yùn)行時(shí)驗(yàn)證規(guī)則username是字符串且長度在 3-20 之間email必須符合郵箱格式等。靜態(tài)類型定義RegisterUserInput這個(gè)類型可以直接用在我們的業(yè)務(wù)邏輯函數(shù)參數(shù)上享受完整的 TypeScript 提示和檢查。4.2 在 Hono 路由中使用 Zod 驗(yàn)證現(xiàn)在回到src/index.ts改造我們的/api/register路由。// src/index.ts import { Hono } from ‘hono’ import { zValidator } from ‘hono/zod-validator’ // 需要安裝這個(gè)中間件 import { registerUserSchema, type RegisterUserInput } from ‘./schemas/user.schema’ const app new Hono() // … 之前的其他路由 … // 安裝驗(yàn)證中間件 npm install hono/zod-validator // 使用 zValidator 中間件處理 POST 請求 app.post( ‘/api/register’, // zValidator 中間件第一個(gè)參數(shù) ‘json’ 表示從請求體解析 JSON // 第二個(gè)參數(shù)是我們的 Schema zValidator(‘json’, registerUserSchema), async (c) { // 如果程序執(zhí)行到這里說明請求體數(shù)據(jù)已經(jīng)通過了 Zod 驗(yàn)證 // c.req.valid(‘json’) 可以獲取到類型安全且已驗(yàn)證的數(shù)據(jù) const validatedData: RegisterUserInput c.req.valid(‘json’) console.log(‘Validated registration data:’, validatedData) // 現(xiàn)在你可以放心地使用 validatedData 了它的類型是 RegisterUserInput // TypeScript 知道 validatedData.username 是 string validatedData.age 是 number | undefined // 模擬業(yè)務(wù)邏輯 const newUser { id: Date.now(), …validatedData } return c.json({ success: true, user: newUser }, 201) } )這個(gè)流程的威力在于自動(dòng)驗(yàn)證如果客戶端發(fā)送的數(shù)據(jù)不符合 SchemazValidator中間件會(huì)自動(dòng)返回一個(gè)400 Bad Request響應(yīng)并附上 Zod 生成的、非常清晰的錯(cuò)誤信息指出是哪個(gè)字段、違反了哪條規(guī)則。你不需要寫任何try-catch來處理驗(yàn)證邏輯。類型安全在路由處理器內(nèi)部c.req.valid(‘json’)返回的數(shù)據(jù)類型就是RegisterUserInput。你在寫業(yè)務(wù)代碼時(shí)編輯器會(huì)提供完整的自動(dòng)補(bǔ)全并且不可能錯(cuò)誤地訪問一個(gè)不存在的屬性。用錯(cuò)誤的數(shù)據(jù)測試一下curl -X POST http://localhost:3000/api/register \ -H “Content-Type: application/json” \ -d ‘{“username”: “ab”, “email”: “invalid-email”}’ # username太短email格式錯(cuò)誤你會(huì)得到一個(gè)結(jié)構(gòu)化的錯(cuò)誤響應(yīng)類似{ “success”: false, “issues”: [ {“path”: [“username”], “message”: “String must contain at least 3 character(s)”}, {“path”: [“email”], “message”: “Invalid email”} ] }4.3 處理更復(fù)雜的嵌套數(shù)據(jù)和文件上傳Zod 的能力遠(yuǎn)不止于此。假設(shè)我們有一個(gè)創(chuàng)建博客文章的接口包含標(biāo)題、內(nèi)容、標(biāo)簽數(shù)組和一個(gè)可選的元數(shù)據(jù)對象。// src/schemas/post.schema.ts import { z } from ‘zod’; const metaSchema z.object({ isDraft: z.boolean().default(false), visibility: z.enum([‘public’, ‘private’, ‘unlisted’]).default(‘public’), scheduledFor: z.string().datetime().optional(), // ISO 8601 日期字符串 }); export const createPostSchema z.object({ title: z.string().min(5).max(100), content: z.string().min(1), tags: z.array(z.string().max(15)).max(5), // 最多5個(gè)標(biāo)簽每個(gè)標(biāo)簽最多15字符 meta: metaSchema.optional(), // 可選的嵌套對象 }); export type CreatePostInput z.infertypeof createPostSchema;在路由中使用它// src/index.ts import { createPostSchema } from ‘./schemas/post.schema’; app.post(‘/api/posts’, zValidator(‘json’, createPostSchema), async (c) { const postData c.req.valid(‘json’); // 類型為 CreatePostInput // … 保存到數(shù)據(jù)庫等邏輯 … return c.json({ success: true, postId: 123 }); } )對于文件上傳Hono 也提供了方便的處理方式結(jié)合 Zod 可以驗(yàn)證文件類型和大小。// 假設(shè)我們只接受單張圖片上傳 import { z } from ‘zod’; const uploadAvatarSchema z.object({ avatar: z.instanceof(File) // 驗(yàn)證是 File 對象 .refine((file) file.size 5 * 1024 * 1024, ‘File size must be less than 5MB’) // 驗(yàn)證大小 .refine((file) [‘image/jpeg’, ‘image/png’, ‘image/gif’].includes(file.type), ‘Unsupported file type’), }); app.post(‘/api/upload-avatar’, zValidator(‘form’, uploadAvatarSchema), // 注意這里是 ‘form’ async (c) { const { avatar } c.req.valid(‘form’); // 處理 avatar 文件… return c.json({ success: true }); } )5. 構(gòu)建 Mini Project一個(gè)簡單的待辦事項(xiàng) API現(xiàn)在我們把所有知識(shí)串聯(lián)起來構(gòu)建一個(gè)具備 CRUD創(chuàng)建、讀取、更新、刪除功能的待辦事項(xiàng) API。這將涉及路由分組、更復(fù)雜的 Schema 驗(yàn)證以及狀態(tài)管理為了簡單我們用內(nèi)存數(shù)組。5.1 定義數(shù)據(jù)模型和 Schema// src/schemas/todo.schema.ts import { z } from ‘zod’; // 創(chuàng)建待辦事項(xiàng)的 Schema export const createTodoSchema z.object({ title: z.string().min(1, “Title cannot be empty”).max(200), description: z.string().max(1000).optional(), completed: z.boolean().default(false), }); // 更新待辦事項(xiàng)的 Schema (通常所有字段都是可選的) export const updateTodoSchema createTodoSchema.partial(); // .partial() 使所有字段變?yōu)榭蛇x // 從創(chuàng)建 Schema 推斷類型 export type CreateTodoInput z.infertypeof createTodoSchema; export type UpdateTodoInput z.infertypeof updateTodoSchema; // 我們應(yīng)用內(nèi)部使用的 Todo 類型包含數(shù)據(jù)庫生成的 id export interface Todo extends CreateTodoInput { id: number; createdAt: Date; updatedAt: Date; }5.2 使用 Hono 的路由分組Hono 支持路由分組讓代碼組織更清晰。我們?yōu)樗?api/todos相關(guān)的路由創(chuàng)建一個(gè)組。// src/routes/todos.ts import { Hono } from ‘hono’; import { zValidator } from ‘hono/zod-validator’; import { createTodoSchema, updateTodoSchema, type CreateTodoInput, type UpdateTodoInput, type Todo } from ‘../schemas/todo.schema’; // 創(chuàng)建一個(gè)專門的路由實(shí)例 const todosApp new Hono(); // 內(nèi)存存儲(chǔ)僅用于演示生產(chǎn)環(huán)境請用數(shù)據(jù)庫 let todos: Todo[] []; let currentId 1; // 1. 獲取所有待辦事項(xiàng) todosApp.get(‘/’, (c) { return c.json({ todos }); }); // 2. 根據(jù)ID獲取單個(gè)待辦事項(xiàng) todosApp.get(‘/:id’, (c) { const id Number(c.req.param(‘id’)); if (isNaN(id)) { return c.json({ error: ‘Invalid ID format’ }, 400); } const todo todos.find(t t.id id); if (!todo) { return c.json({ error: ‘Todo not found’ }, 404); } return c.json({ todo }); }); // 3. 創(chuàng)建新的待辦事項(xiàng) todosApp.post(‘/’, zValidator(‘json’, createTodoSchema), (c) { const data: CreateTodoInput c.req.valid(‘json’); const newTodo: Todo { …data, id: currentId, createdAt: new Date(), updatedAt: new Date(), }; todos.push(newTodo); return c.json({ todo: newTodo }, 201); } ); // 4. 更新待辦事項(xiàng) todosApp.patch(‘/:id’, zValidator(‘json’, updateTodoSchema), (c) { const id Number(c.req.param(‘id’)); if (isNaN(id)) { return c.json({ error: ‘Invalid ID format’ }, 400); } const updates: UpdateTodoInput c.req.valid(‘json’); const index todos.findIndex(t t.id id); if (index -1) { return c.json({ error: ‘Todo not found’ }, 404); } // 更新找到的待辦事項(xiàng) todos[index] { …todos[index], …updates, updatedAt: new Date(), // 更新修改時(shí)間 }; return c.json({ todo: todos[index] }); } ); // 5. 刪除待辦事項(xiàng) todosApp.delete(‘/:id’, (c) { const id Number(c.req.param(‘id’)); if (isNaN(id)) { return c.json({ error: ‘Invalid ID format’ }, 400); } const initialLength todos.length; todos todos.filter(t t.id ! id); if (todos.length initialLength) { return c.json({ error: ‘Todo not found’ }, 404); } return c.json({ success: true }); }); export default todosApp;5.3 在主應(yīng)用中掛載路由回到src/index.ts將待辦事項(xiàng)路由掛載到主應(yīng)用上。// src/index.ts import { Hono } from ‘hono’; import { zValidator } from ‘hono/zod-validator’; import { registerUserSchema } from ‘./schemas/user.schema’; import todosApp from ‘./routes/todos’; // 導(dǎo)入路由 const app new Hono(); // 掛載待辦事項(xiàng)路由所有 /api/todos 開頭的請求都會(huì)由 todosApp 處理 app.route(‘/api/todos’, todosApp); // 你之前定義的其他路由… app.get(‘/’, (c) c.text(‘Todo API is running!’)); app.post(‘/api/register’, zValidator(‘json’, registerUserSchema), (c) { … }); // … 其他路由和服務(wù)器導(dǎo)出 export default { port: 3000, fetch: app.fetch, };現(xiàn)在你的 API 就擁有了完整的待辦事項(xiàng)功能GET /api/todos– 獲取列表GET /api/todos/:id– 獲取單個(gè)POST /api/todos– 創(chuàng)建數(shù)據(jù)會(huì)被自動(dòng)驗(yàn)證PATCH /api/todos/:id– 更新數(shù)據(jù)會(huì)被自動(dòng)驗(yàn)證DELETE /api/todos/:id– 刪除5.4 測試你的 API使用 curl、Postman 或任何 HTTP 客戶端進(jìn)行測試。# 1. 創(chuàng)建待辦事項(xiàng) curl -X POST http://localhost:3000/api/todos \ -H “Content-Type: application/json” \ -d ‘{“title”: “Learn Hono”, “description”: “Build a mini project”}’ # 2. 獲取所有待辦事項(xiàng) curl http://localhost:3000/api/todos # 3. 更新待辦事項(xiàng) (標(biāo)記為完成) curl -X PATCH http://localhost:3000/api/todos/1 \ -H “Content-Type: application/json” \ -d ‘{“completed”: true}’ # 4. 刪除待辦事項(xiàng) curl -X DELETE http://localhost:3000/api/todos/1嘗試發(fā)送錯(cuò)誤數(shù)據(jù)看看 Zod 的驗(yàn)證是否生效curl -X POST http://localhost:3000/api/todos \ -H “Content-Type: application/json” \ -d ‘{“title”: “”}’ # 標(biāo)題為空應(yīng)該返回400錯(cuò)誤6. 進(jìn)階與生產(chǎn)化考量這個(gè) Mini Project 跑通了但離一個(gè)健壯的生產(chǎn)應(yīng)用還有距離。下面是一些你接下來可以深入探索的方向和避坑點(diǎn)。6.1 錯(cuò)誤處理中間件目前我們的錯(cuò)誤處理分散在各個(gè)路由中。Hono 支持自定義中間件進(jìn)行全局錯(cuò)誤處理。// src/index.ts const app new Hono(); // 全局錯(cuò)誤處理中間件 app.onError((err, c) { console.error(err); // 可以根據(jù) err 的類型返回不同的狀態(tài)碼和消息 if (err.message.includes(‘Validation’)) { return c.json({ error: ‘Request validation failed’, details: err.message }, 400); } // 默認(rèn)返回 500 內(nèi)部服務(wù)器錯(cuò)誤 return c.json({ error: ‘Internal server error’ }, 500); }); // 之后的路由如果拋出錯(cuò)誤都會(huì)被這個(gè)中間件捕獲 app.get(‘/error’, (c) { throw new Error(‘Something went wrong!’); });6.2 環(huán)境變量與配置永遠(yuǎn)不要將敏感信息如數(shù)據(jù)庫連接字符串、API 密鑰硬編碼在代碼中。使用dotenv和 Zod 可以很好地管理環(huán)境變量。npm install dotenv npm install -D types/node # 如果之前沒裝的話創(chuàng)建.env文件DATABASE_URL“postgresql://user:passlocalhost:5432/mydb” PORT3000 NODE_ENV“development”創(chuàng)建src/config.tsimport { z } from ‘zod’; import { config } from ‘dotenv’; config(); // 加載 .env 文件中的變量到 process.env const envSchema z.object({ DATABASE_URL: z.string().url(), PORT: z.coerce.number().int().positive().default(3000), // coerce 將字符串轉(zhuǎn)為數(shù)字 NODE_ENV: z.enum([‘development’, ‘production’, ‘test’]).default(‘development’), }); // 驗(yàn)證并導(dǎo)出環(huán)境變量 const env envSchema.safeParse(process.env); if (!env.success) { console.error(‘? Invalid environment variables:’, env.error.format()); process.exit(1); } export const config env.data;然后在index.ts中使用import { config } from ‘./config’; export default { port: config.PORT, fetch: app.fetch, };這樣做的好處是應(yīng)用啟動(dòng)時(shí)會(huì)立即檢查所有必需的環(huán)境變量是否正確而不是在運(yùn)行時(shí)才崩潰。6.3 連接數(shù)據(jù)庫內(nèi)存數(shù)組只是演示。真實(shí)項(xiàng)目需要連接數(shù)據(jù)庫。以 Prisma ORM 和 PostgreSQL 為例npm install prisma prisma/client npx prisma init這會(huì)創(chuàng)建prisma/schema.prisma文件。定義你的Todo模型然后運(yùn)行npx prisma migrate dev創(chuàng)建數(shù)據(jù)庫表。最后在你的路由中導(dǎo)入PrismaClient實(shí)例來操作數(shù)據(jù)庫。6.4 測試為你的路由編寫測試。Hono 應(yīng)用本身就是一個(gè)fetch兼容的對象可以直接用測試框架調(diào)用。// test/todos.test.ts import { describe, it, expect, beforeEach } from ‘vitest’; // 或 jest import app from ‘../src/index’; describe(‘Todos API’, () { beforeEach(() { // 清空內(nèi)存數(shù)據(jù)或重置測試數(shù)據(jù)庫 }); it(‘should create a todo’, async () { const res await app.request(‘/api/todos’, { method: ‘POST’, headers: { ‘Content-Type’: ‘a(chǎn)pplication/json’ }, body: JSON.stringify({ title: ‘Test Todo’ }), }); expect(res.status).toBe(201); const body await res.json(); expect(body.todo.title).toBe(‘Test Todo’); }); });6.5 部署Hono 應(yīng)用可以輕松部署到各種平臺(tái)Node.js 服務(wù)器: 使用serve或node直接運(yùn)行編譯后的文件。Bun: 使用bun run src/index.ts。Cloudflare Workers: 這是 Hono 的強(qiáng)項(xiàng)幾乎無需修改代碼。Vercel/Netlify: 作為 Serverless Function 部署。部署時(shí)確保運(yùn)行npm run build生成dist目錄如果配置了的話并設(shè)置好生產(chǎn)環(huán)境的環(huán)境變量。7. 常見問題與排查思路在實(shí)際操作中你可能會(huì)遇到以下問題TypeScript 編譯錯(cuò)誤 “找不到模塊 ‘hono’ 或其相應(yīng)的類型聲明”檢查: 確保npm install hono成功并且node_modules中存在types/honoHono 自帶類型通常不需要單獨(dú)安裝。檢查tsconfig.json中的“moduleResolution”: “node”。中間件zValidator不生效或者c.req.valid是undefined檢查: 確認(rèn)安裝了hono/zod-validator包。確認(rèn)中間件使用順序正確zValidator必須在路由處理函數(shù)之前。檢查導(dǎo)入路徑是否正確。Zod 驗(yàn)證通過了但業(yè)務(wù)邏輯里類型還是any或報(bào)錯(cuò)檢查: 確保你使用了c.req.valid(‘json’)而不是原始的c.req.json()。c.req.valid()的返回值類型是由 Schema 推斷出來的。如果問題依舊檢查z.infertypeof yourSchema是否正確定義和導(dǎo)出。應(yīng)用運(yùn)行正常但修改代碼后熱重載不生效檢查: 確認(rèn)package.json中的dev腳本使用的是tsx watch或nodemonts-node。檢查文件是否保存在src目錄下并且tsx監(jiān)聽的是正確的入口文件。部署到邊緣環(huán)境如 Cloudflare Workers時(shí)報(bào)錯(cuò)檢查: 邊緣環(huán)境可能不支持某些 Node.js 原生模塊如fs,path。確保你的代碼和依賴特別是數(shù)據(jù)庫驅(qū)動(dòng)兼容邊緣運(yùn)行時(shí)。Hono 的官方文檔有針對各運(yùn)行時(shí)的具體指南。這個(gè)組合的核心優(yōu)勢在于它通過類型安全將很多運(yùn)行時(shí)錯(cuò)誤提前到了編譯時(shí)和請求驗(yàn)證時(shí)。我建議你在自己的項(xiàng)目中從一個(gè)小模塊開始實(shí)踐比如先給一個(gè)用戶注冊接口加上 Zod 驗(yàn)證體會(huì)一下它帶來的信心和開發(fā)效率的提升。當(dāng)你習(xí)慣了這種“先定義契約再寫邏輯”的模式后就很難再回到那種對輸入數(shù)據(jù)提心吊膽的編碼方式了。 Hono與Zod實(shí)戰(zhàn)：構(gòu)建類型安全的TypeScript后端API
1. 先搞清楚 Hono 和 Zod 到底能幫你解決什么實(shí)際問題如果你正在用 TypeScript 寫后端 API或者處理任何需要接收外部輸入比如 HTTP 請求、表單、配置文件的場景那么 Hono 和 Zod 這兩個(gè)庫的組合值得你花時(shí)間了解一下。它們解決的不是“從零到一”造輪子的問題而是“如何更穩(wěn)、更快、更省心地寫生產(chǎn)級(jí)代碼”的問題。Hono 是一個(gè)輕量、快速、面向邊緣計(jì)算的 Web 框架。它最直接的價(jià)值是在 Node.js、Deno、Bun 甚至 Cloudflare Workers 等運(yùn)行時(shí)上都能提供一致且高性能的 HTTP 服務(wù)開發(fā)體驗(yàn)。你不用再為不同平臺(tái)寫適配代碼一套邏輯可以跑在多個(gè)環(huán)境。Zod 則是一個(gè)以 TypeScript 為核心的運(yùn)行時(shí)數(shù)據(jù)驗(yàn)證庫。它的核心能力是讓你用一套語法同時(shí)定義數(shù)據(jù)的類型給 TypeScript 編譯器看和驗(yàn)證規(guī)則在運(yùn)行時(shí)檢查數(shù)據(jù)。這解決了后端開發(fā)里一個(gè)老大難問題我定義了一個(gè)User接口但客戶端傳過來的數(shù)據(jù)真的符合這個(gè)接口嗎Zod 讓你能明確地回答“是”或“否”并給出清晰的錯(cuò)誤信息。把這兩個(gè)結(jié)合起來你得到的是一個(gè)“類型安全貫穿始終”的開發(fā)流程從定義 API 接口的輸入輸出類型到實(shí)際接收請求時(shí)驗(yàn)證數(shù)據(jù)再到業(yè)務(wù)邏輯中使用這些數(shù)據(jù)TypeScript 的智能提示和錯(cuò)誤檢查會(huì)一直陪伴你極大減少因數(shù)據(jù)格式錯(cuò)誤導(dǎo)致的運(yùn)行時(shí) Bug。2. 環(huán)境準(zhǔn)備別急著寫代碼先把跑道鋪好在開始任何“Mini Project”之前確保你的開發(fā)環(huán)境是就緒的。這聽起來像廢話但我見過太多人卡在第一步不是因?yàn)楣ぞ唠y用而是因?yàn)榘姹緦Σ簧匣蛘甙芾砥鳑]選對。2.1 選擇你的運(yùn)行時(shí)和包管理器Hono 支持多運(yùn)行時(shí)但對于學(xué)習(xí)和本地開發(fā)我建議從Node.js或Bun開始。Node.js 生態(tài)最廣Bun 則啟動(dòng)更快、內(nèi)置了測試運(yùn)行器和包管理器。Node.js: 確保版本在 18.x 或以上?？梢杂胣ode -v檢查。Bun: 如果你追求極速的安裝和啟動(dòng)體驗(yàn)可以試試 Bun。它的包管理器是內(nèi)置的。包管理器: npm 或 yarn 都可以。用 Bun 的話它的bun install命令兼容 npm。2.2 初始化項(xiàng)目并安裝核心依賴打開終端創(chuàng)建一個(gè)新目錄并初始化項(xiàng)目。這里以使用 npm 和 Node.js 為例mkdir learn-hono-zod cd learn-hono-zod npm init -y接下來安裝核心依賴。注意我們安裝的是生產(chǎn)依賴因?yàn)?Hono 和 Zod 本身就是運(yùn)行時(shí)需要的庫。npm install hono zod同時(shí)安裝 TypeScript 和相關(guān)的類型定義作為開發(fā)依賴npm install -D typescript types/node然后初始化 TypeScript 配置。使用npx來運(yùn)行當(dāng)前項(xiàng)目下的tscnpx tsc --init生成的tsconfig.json文件我建議至少修改或確認(rèn)以下幾項(xiàng)這對于現(xiàn)代 Node.js 開發(fā)和獲得更好的類型檢查體驗(yàn)很重要{ compilerOptions: { target: ES2022, module: ESNext, moduleResolution: node, esModuleInterop: true, strict: true, skipLibCheck: true, outDir: ./dist, rootDir: ./src }, include: [src/**/*], exclude: [node_modules] }關(guān)鍵點(diǎn)解釋“target”: “ES2022”: 使用較新的 ECMAScript 標(biāo)準(zhǔn)能用到更多現(xiàn)代語法。“module”: “ESNext”和“moduleResolution”: “node”: 配合 Hono 的 ESM 風(fēng)格導(dǎo)入。“strict”: true:強(qiáng)烈建議開啟。嚴(yán)格的類型檢查是使用 TypeScript 和 Zod 的最大意義所在?！皁utDir”和“rootDir”: 將源代碼放在src目錄編譯輸出到dist目錄保持項(xiàng)目結(jié)構(gòu)清晰。2.3 配置開發(fā)腳本和熱重載為了方便開發(fā)在package.json中添加一些腳本。我們使用tsx或ts-node來直接運(yùn)行 TypeScript 文件避免手動(dòng)編譯。這里推薦tsx它速度更快。npm install -D tsx然后在package.json的“scripts”部分添加{ “scripts”: { “dev”: “tsx watch src/index.ts”, “start”: “tsx src/index.ts”, “build”: “tsc” } }現(xiàn)在運(yùn)行npm run dev就會(huì)啟動(dòng)一個(gè)監(jiān)聽模式的服務(wù)當(dāng)你修改src/index.ts文件時(shí)服務(wù)會(huì)自動(dòng)重啟。3. 第一個(gè) Hono 應(yīng)用從 “Hello World” 到基礎(chǔ)路由讓我們先拋開 Zod感受一下 Hono 的簡潔。在src目錄下創(chuàng)建index.ts文件。3.1 創(chuàng)建應(yīng)用實(shí)例并定義路由// src/index.ts import { Hono } from ‘hono’ // 1. 創(chuàng)建 Hono 應(yīng)用實(shí)例 const app new Hono() // 2. 定義第一個(gè)路由GET / app.get(‘/’, (c) { // c 是 Context 對象包含了請求和響應(yīng)的所有信息 return c.text(‘Hello Hono!’) }) // 3. 定義帶參數(shù)的路由GET /hello/:name app.get(‘/hello/:name’, (c) { // 從路徑參數(shù)中獲取 name const name c.req.param(‘name’) return c.text(Hello, ${name}!) }) // 4. 定義處理 JSON 和查詢參數(shù)的路由 app.get(‘/api/user’, (c) { // 從查詢字符串中獲取參數(shù)例如 /api/user?id123activetrue const id c.req.query(‘id’) const isActive c.req.query(‘a(chǎn)ctive’) ‘true’ // 返回 JSON 響應(yīng) return c.json({ userId: id, active: isActive, message: ‘User data fetched (without validation for now)’ }) }) // 5. 啟動(dòng)服務(wù)器監(jiān)聽 3000 端口 export default { port: 3000, fetch: app.fetch } console.log(‘Server is running on http://localhost:3000’)現(xiàn)在運(yùn)行npm run dev打開瀏覽器訪問http://localhost:3000/- 看到 “Hello Hono!”http://localhost:3000/hello/TypeScript- 看到 “Hello, TypeScript!”http://localhost:3000/api/user?id456activetrue- 看到 JSON 響應(yīng)。你已經(jīng)有了一個(gè)能處理基本路由的 HTTP 服務(wù)。Hono 的 API 非常直觀app.get(‘/path’, handler)。handler函數(shù)接收一個(gè)Context對象 (c)通過它你能訪問請求 (c.req) 和構(gòu)造響應(yīng) (c.json(),c.text())。3.2 處理 POST 請求和請求體現(xiàn)代 API 離不開接收數(shù)據(jù)。我們來創(chuàng)建一個(gè)處理用戶注冊的 POST 接口。// 在 src/index.ts 中繼續(xù)添加 app.post(‘/api/register’, async (c) { try { // 嘗試解析 JSON 格式的請求體 const body await c.req.json() // 暫時(shí)直接使用沒有驗(yàn)證 console.log(‘Received registration data:’, body) // 模擬處理邏輯 const newUser { id: Date.now(), …body } return c.json({ success: true, user: newUser }, 201) // 201 Created } catch (error) { // 如果請求體不是合法的 JSON會(huì)在這里捕獲錯(cuò)誤 return c.json({ success: false, error: ‘Invalid JSON body’ }, 400) } })用 curl 或 Postman 測試一下curl -X POST http://localhost:3000/api/register \ -H “Content-Type: application/json” \ -d ‘{“username”: “alice”, “email”: “aliceexample.com”}’你會(huì)收到一個(gè) 201 響應(yīng)。但是這里有個(gè)嚴(yán)重問題我們完全信任了客戶端傳來的數(shù)據(jù)。如果客戶端傳了{(lán)“username”: 123, “email”: “not-an-email”}甚至{“admin”: true}我們的代碼也會(huì)照單全收。這就是運(yùn)行時(shí) Bug 的溫床。接下來Zod 就該上場了。4. 引入 Zod為你的數(shù)據(jù)穿上“防彈衣”Zod 的核心是Schema模式。你可以為任何數(shù)據(jù)結(jié)構(gòu)定義一個(gè) Schema然后用它來驗(yàn)證未知的數(shù)據(jù)。4.1 定義第一個(gè) Schema用戶注冊在src目錄下創(chuàng)建一個(gè)schemas文件夾然后創(chuàng)建user.schema.ts文件。將數(shù)據(jù)驗(yàn)證的邏輯與路由處理分離是一個(gè)好習(xí)慣。// src/schemas/user.schema.ts import { z } from ‘zod’; // 1. 定義用戶注冊數(shù)據(jù)的 Schema export const registerUserSchema z.object({ // username 必須是字符串長度在3到20個(gè)字符之間 username: z.string().min(3).max(20), // email 必須是有效的郵箱格式 email: z.string().email(), // age 是可選的數(shù)字如果提供則必須在18歲以上 age: z.number().int().positive().min(18).optional(), // tags 是一個(gè)字符串?dāng)?shù)組最多10個(gè)元素 tags: z.array(z.string()).max(10).optional(), }); // 2. 從 Schema 推斷出 TypeScript 類型 export type RegisterUserInput z.infertypeof registerUserSchema;看我們只用一套語法就同時(shí)完成了兩件事運(yùn)行時(shí)驗(yàn)證規(guī)則username是字符串且長度在 3-20 之間email必須符合郵箱格式等。靜態(tài)類型定義RegisterUserInput這個(gè)類型可以直接用在我們的業(yè)務(wù)邏輯函數(shù)參數(shù)上享受完整的 TypeScript 提示和檢查。4.2 在 Hono 路由中使用 Zod 驗(yàn)證現(xiàn)在回到src/index.ts改造我們的/api/register路由。// src/index.ts import { Hono } from ‘hono’ import { zValidator } from ‘hono/zod-validator’ // 需要安裝這個(gè)中間件 import { registerUserSchema, type RegisterUserInput } from ‘./schemas/user.schema’ const app new Hono() // … 之前的其他路由 … // 安裝驗(yàn)證中間件 npm install hono/zod-validator // 使用 zValidator 中間件處理 POST 請求 app.post( ‘/api/register’, // zValidator 中間件第一個(gè)參數(shù) ‘json’ 表示從請求體解析 JSON // 第二個(gè)參數(shù)是我們的 Schema zValidator(‘json’, registerUserSchema), async (c) { // 如果程序執(zhí)行到這里說明請求體數(shù)據(jù)已經(jīng)通過了 Zod 驗(yàn)證 // c.req.valid(‘json’) 可以獲取到類型安全且已驗(yàn)證的數(shù)據(jù) const validatedData: RegisterUserInput c.req.valid(‘json’) console.log(‘Validated registration data:’, validatedData) // 現(xiàn)在你可以放心地使用 validatedData 了它的類型是 RegisterUserInput // TypeScript 知道 validatedData.username 是 string validatedData.age 是 number | undefined // 模擬業(yè)務(wù)邏輯 const newUser { id: Date.now(), …validatedData } return c.json({ success: true, user: newUser }, 201) } )這個(gè)流程的威力在于自動(dòng)驗(yàn)證如果客戶端發(fā)送的數(shù)據(jù)不符合 SchemazValidator中間件會(huì)自動(dòng)返回一個(gè)400 Bad Request響應(yīng)并附上 Zod 生成的、非常清晰的錯(cuò)誤信息指出是哪個(gè)字段、違反了哪條規(guī)則。你不需要寫任何try-catch來處理驗(yàn)證邏輯。類型安全在路由處理器內(nèi)部c.req.valid(‘json’)返回的數(shù)據(jù)類型就是RegisterUserInput。你在寫業(yè)務(wù)代碼時(shí)編輯器會(huì)提供完整的自動(dòng)補(bǔ)全并且不可能錯(cuò)誤地訪問一個(gè)不存在的屬性。用錯(cuò)誤的數(shù)據(jù)測試一下curl -X POST http://localhost:3000/api/register \ -H “Content-Type: application/json” \ -d ‘{“username”: “ab”, “email”: “invalid-email”}’ # username太短email格式錯(cuò)誤你會(huì)得到一個(gè)結(jié)構(gòu)化的錯(cuò)誤響應(yīng)類似{ “success”: false, “issues”: [ {“path”: [“username”], “message”: “String must contain at least 3 character(s)”}, {“path”: [“email”], “message”: “Invalid email”} ] }4.3 處理更復(fù)雜的嵌套數(shù)據(jù)和文件上傳Zod 的能力遠(yuǎn)不止于此。假設(shè)我們有一個(gè)創(chuàng)建博客文章的接口包含標(biāo)題、內(nèi)容、標(biāo)簽數(shù)組和一個(gè)可選的元數(shù)據(jù)對象。// src/schemas/post.schema.ts import { z } from ‘zod’; const metaSchema z.object({ isDraft: z.boolean().default(false), visibility: z.enum([‘public’, ‘private’, ‘unlisted’]).default(‘public’), scheduledFor: z.string().datetime().optional(), // ISO 8601 日期字符串 }); export const createPostSchema z.object({ title: z.string().min(5).max(100), content: z.string().min(1), tags: z.array(z.string().max(15)).max(5), // 最多5個(gè)標(biāo)簽每個(gè)標(biāo)簽最多15字符 meta: metaSchema.optional(), // 可選的嵌套對象 }); export type CreatePostInput z.infertypeof createPostSchema;在路由中使用它// src/index.ts import { createPostSchema } from ‘./schemas/post.schema’; app.post(‘/api/posts’, zValidator(‘json’, createPostSchema), async (c) { const postData c.req.valid(‘json’); // 類型為 CreatePostInput // … 保存到數(shù)據(jù)庫等邏輯 … return c.json({ success: true, postId: 123 }); } )對于文件上傳Hono 也提供了方便的處理方式結(jié)合 Zod 可以驗(yàn)證文件類型和大小。// 假設(shè)我們只接受單張圖片上傳 import { z } from ‘zod’; const uploadAvatarSchema z.object({ avatar: z.instanceof(File) // 驗(yàn)證是 File 對象 .refine((file) file.size 5 * 1024 * 1024, ‘File size must be less than 5MB’) // 驗(yàn)證大小 .refine((file) [‘image/jpeg’, ‘image/png’, ‘image/gif’].includes(file.type), ‘Unsupported file type’), }); app.post(‘/api/upload-avatar’, zValidator(‘form’, uploadAvatarSchema), // 注意這里是 ‘form’ async (c) { const { avatar } c.req.valid(‘form’); // 處理 avatar 文件… return c.json({ success: true }); } )5. 構(gòu)建 Mini Project一個(gè)簡單的待辦事項(xiàng) API現(xiàn)在我們把所有知識(shí)串聯(lián)起來構(gòu)建一個(gè)具備 CRUD創(chuàng)建、讀取、更新、刪除功能的待辦事項(xiàng) API。這將涉及路由分組、更復(fù)雜的 Schema 驗(yàn)證以及狀態(tài)管理為了簡單我們用內(nèi)存數(shù)組。5.1 定義數(shù)據(jù)模型和 Schema// src/schemas/todo.schema.ts import { z } from ‘zod’; // 創(chuàng)建待辦事項(xiàng)的 Schema export const createTodoSchema z.object({ title: z.string().min(1, “Title cannot be empty”).max(200), description: z.string().max(1000).optional(), completed: z.boolean().default(false), }); // 更新待辦事項(xiàng)的 Schema (通常所有字段都是可選的) export const updateTodoSchema createTodoSchema.partial(); // .partial() 使所有字段變?yōu)榭蛇x // 從創(chuàng)建 Schema 推斷類型 export type CreateTodoInput z.infertypeof createTodoSchema; export type UpdateTodoInput z.infertypeof updateTodoSchema; // 我們應(yīng)用內(nèi)部使用的 Todo 類型包含數(shù)據(jù)庫生成的 id export interface Todo extends CreateTodoInput { id: number; createdAt: Date; updatedAt: Date; }5.2 使用 Hono 的路由分組Hono 支持路由分組讓代碼組織更清晰。我們?yōu)樗?api/todos相關(guān)的路由創(chuàng)建一個(gè)組。// src/routes/todos.ts import { Hono } from ‘hono’; import { zValidator } from ‘hono/zod-validator’; import { createTodoSchema, updateTodoSchema, type CreateTodoInput, type UpdateTodoInput, type Todo } from ‘../schemas/todo.schema’; // 創(chuàng)建一個(gè)專門的路由實(shí)例 const todosApp new Hono(); // 內(nèi)存存儲(chǔ)僅用于演示生產(chǎn)環(huán)境請用數(shù)據(jù)庫 let todos: Todo[] []; let currentId 1; // 1. 獲取所有待辦事項(xiàng) todosApp.get(‘/’, (c) { return c.json({ todos }); }); // 2. 根據(jù)ID獲取單個(gè)待辦事項(xiàng) todosApp.get(‘/:id’, (c) { const id Number(c.req.param(‘id’)); if (isNaN(id)) { return c.json({ error: ‘Invalid ID format’ }, 400); } const todo todos.find(t t.id id); if (!todo) { return c.json({ error: ‘Todo not found’ }, 404); } return c.json({ todo }); }); // 3. 創(chuàng)建新的待辦事項(xiàng) todosApp.post(‘/’, zValidator(‘json’, createTodoSchema), (c) { const data: CreateTodoInput c.req.valid(‘json’); const newTodo: Todo { …data, id: currentId, createdAt: new Date(), updatedAt: new Date(), }; todos.push(newTodo); return c.json({ todo: newTodo }, 201); } ); // 4. 更新待辦事項(xiàng) todosApp.patch(‘/:id’, zValidator(‘json’, updateTodoSchema), (c) { const id Number(c.req.param(‘id’)); if (isNaN(id)) { return c.json({ error: ‘Invalid ID format’ }, 400); } const updates: UpdateTodoInput c.req.valid(‘json’); const index todos.findIndex(t t.id id); if (index -1) { return c.json({ error: ‘Todo not found’ }, 404); } // 更新找到的待辦事項(xiàng) todos[index] { …todos[index], …updates, updatedAt: new Date(), // 更新修改時(shí)間 }; return c.json({ todo: todos[index] }); } ); // 5. 刪除待辦事項(xiàng) todosApp.delete(‘/:id’, (c) { const id Number(c.req.param(‘id’)); if (isNaN(id)) { return c.json({ error: ‘Invalid ID format’ }, 400); } const initialLength todos.length; todos todos.filter(t t.id ! id); if (todos.length initialLength) { return c.json({ error: ‘Todo not found’ }, 404); } return c.json({ success: true }); }); export default todosApp;5.3 在主應(yīng)用中掛載路由回到src/index.ts將待辦事項(xiàng)路由掛載到主應(yīng)用上。// src/index.ts import { Hono } from ‘hono’; import { zValidator } from ‘hono/zod-validator’; import { registerUserSchema } from ‘./schemas/user.schema’; import todosApp from ‘./routes/todos’; // 導(dǎo)入路由 const app new Hono(); // 掛載待辦事項(xiàng)路由所有 /api/todos 開頭的請求都會(huì)由 todosApp 處理 app.route(‘/api/todos’, todosApp); // 你之前定義的其他路由… app.get(‘/’, (c) c.text(‘Todo API is running!’)); app.post(‘/api/register’, zValidator(‘json’, registerUserSchema), (c) { … }); // … 其他路由和服務(wù)器導(dǎo)出 export default { port: 3000, fetch: app.fetch, };現(xiàn)在你的 API 就擁有了完整的待辦事項(xiàng)功能GET /api/todos– 獲取列表GET /api/todos/:id– 獲取單個(gè)POST /api/todos– 創(chuàng)建數(shù)據(jù)會(huì)被自動(dòng)驗(yàn)證PATCH /api/todos/:id– 更新數(shù)據(jù)會(huì)被自動(dòng)驗(yàn)證DELETE /api/todos/:id– 刪除5.4 測試你的 API使用 curl、Postman 或任何 HTTP 客戶端進(jìn)行測試。# 1. 創(chuàng)建待辦事項(xiàng) curl -X POST http://localhost:3000/api/todos \ -H “Content-Type: application/json” \ -d ‘{“title”: “Learn Hono”, “description”: “Build a mini project”}’ # 2. 獲取所有待辦事項(xiàng) curl http://localhost:3000/api/todos # 3. 更新待辦事項(xiàng) (標(biāo)記為完成) curl -X PATCH http://localhost:3000/api/todos/1 \ -H “Content-Type: application/json” \ -d ‘{“completed”: true}’ # 4. 刪除待辦事項(xiàng) curl -X DELETE http://localhost:3000/api/todos/1嘗試發(fā)送錯(cuò)誤數(shù)據(jù)看看 Zod 的驗(yàn)證是否生效curl -X POST http://localhost:3000/api/todos \ -H “Content-Type: application/json” \ -d ‘{“title”: “”}’ # 標(biāo)題為空應(yīng)該返回400錯(cuò)誤6. 進(jìn)階與生產(chǎn)化考量這個(gè) Mini Project 跑通了但離一個(gè)健壯的生產(chǎn)應(yīng)用還有距離。下面是一些你接下來可以深入探索的方向和避坑點(diǎn)。6.1 錯(cuò)誤處理中間件目前我們的錯(cuò)誤處理分散在各個(gè)路由中。Hono 支持自定義中間件進(jìn)行全局錯(cuò)誤處理。// src/index.ts const app new Hono(); // 全局錯(cuò)誤處理中間件 app.onError((err, c) { console.error(err); // 可以根據(jù) err 的類型返回不同的狀態(tài)碼和消息 if (err.message.includes(‘Validation’)) { return c.json({ error: ‘Request validation failed’, details: err.message }, 400); } // 默認(rèn)返回 500 內(nèi)部服務(wù)器錯(cuò)誤 return c.json({ error: ‘Internal server error’ }, 500); }); // 之后的路由如果拋出錯(cuò)誤都會(huì)被這個(gè)中間件捕獲 app.get(‘/error’, (c) { throw new Error(‘Something went wrong!’); });6.2 環(huán)境變量與配置永遠(yuǎn)不要將敏感信息如數(shù)據(jù)庫連接字符串、API 密鑰硬編碼在代碼中。使用dotenv和 Zod 可以很好地管理環(huán)境變量。npm install dotenv npm install -D types/node # 如果之前沒裝的話創(chuàng)建.env文件DATABASE_URL“postgresql://user:passlocalhost:5432/mydb” PORT3000 NODE_ENV“development”創(chuàng)建src/config.tsimport { z } from ‘zod’; import { config } from ‘dotenv’; config(); // 加載 .env 文件中的變量到 process.env const envSchema z.object({ DATABASE_URL: z.string().url(), PORT: z.coerce.number().int().positive().default(3000), // coerce 將字符串轉(zhuǎn)為數(shù)字 NODE_ENV: z.enum([‘development’, ‘production’, ‘test’]).default(‘development’), }); // 驗(yàn)證并導(dǎo)出環(huán)境變量 const env envSchema.safeParse(process.env); if (!env.success) { console.error(‘? Invalid environment variables:’, env.error.format()); process.exit(1); } export const config env.data;然后在index.ts中使用import { config } from ‘./config’; export default { port: config.PORT, fetch: app.fetch, };這樣做的好處是應(yīng)用啟動(dòng)時(shí)會(huì)立即檢查所有必需的環(huán)境變量是否正確而不是在運(yùn)行時(shí)才崩潰。6.3 連接數(shù)據(jù)庫內(nèi)存數(shù)組只是演示。真實(shí)項(xiàng)目需要連接數(shù)據(jù)庫。以 Prisma ORM 和 PostgreSQL 為例npm install prisma prisma/client npx prisma init這會(huì)創(chuàng)建prisma/schema.prisma文件。定義你的Todo模型然后運(yùn)行npx prisma migrate dev創(chuàng)建數(shù)據(jù)庫表。最后在你的路由中導(dǎo)入PrismaClient實(shí)例來操作數(shù)據(jù)庫。6.4 測試為你的路由編寫測試。Hono 應(yīng)用本身就是一個(gè)fetch兼容的對象可以直接用測試框架調(diào)用。// test/todos.test.ts import { describe, it, expect, beforeEach } from ‘vitest’; // 或 jest import app from ‘../src/index’; describe(‘Todos API’, () { beforeEach(() { // 清空內(nèi)存數(shù)據(jù)或重置測試數(shù)據(jù)庫 }); it(‘should create a todo’, async () { const res await app.request(‘/api/todos’, { method: ‘POST’, headers: { ‘Content-Type’: ‘a(chǎn)pplication/json’ }, body: JSON.stringify({ title: ‘Test Todo’ }), }); expect(res.status).toBe(201); const body await res.json(); expect(body.todo.title).toBe(‘Test Todo’); }); });6.5 部署Hono 應(yīng)用可以輕松部署到各種平臺(tái)Node.js 服務(wù)器: 使用serve或node直接運(yùn)行編譯后的文件。Bun: 使用bun run src/index.ts。Cloudflare Workers: 這是 Hono 的強(qiáng)項(xiàng)幾乎無需修改代碼。Vercel/Netlify: 作為 Serverless Function 部署。部署時(shí)確保運(yùn)行npm run build生成dist目錄如果配置了的話并設(shè)置好生產(chǎn)環(huán)境的環(huán)境變量。7. 常見問題與排查思路在實(shí)際操作中你可能會(huì)遇到以下問題TypeScript 編譯錯(cuò)誤 “找不到模塊 ‘hono’ 或其相應(yīng)的類型聲明”檢查: 確保npm install hono成功并且node_modules中存在types/honoHono 自帶類型通常不需要單獨(dú)安裝。檢查tsconfig.json中的“moduleResolution”: “node”。中間件zValidator不生效或者c.req.valid是undefined檢查: 確認(rèn)安裝了hono/zod-validator包。確認(rèn)中間件使用順序正確zValidator必須在路由處理函數(shù)之前。檢查導(dǎo)入路徑是否正確。Zod 驗(yàn)證通過了但業(yè)務(wù)邏輯里類型還是any或報(bào)錯(cuò)檢查: 確保你使用了c.req.valid(‘json’)而不是原始的c.req.json()。c.req.valid()的返回值類型是由 Schema 推斷出來的。如果問題依舊檢查z.infertypeof yourSchema是否正確定義和導(dǎo)出。應(yīng)用運(yùn)行正常但修改代碼后熱重載不生效檢查: 確認(rèn)package.json中的dev腳本使用的是tsx watch或nodemonts-node。檢查文件是否保存在src目錄下并且tsx監(jiān)聽的是正確的入口文件。部署到邊緣環(huán)境如 Cloudflare Workers時(shí)報(bào)錯(cuò)檢查: 邊緣環(huán)境可能不支持某些 Node.js 原生模塊如fs,path。確保你的代碼和依賴特別是數(shù)據(jù)庫驅(qū)動(dòng)兼容邊緣運(yùn)行時(shí)。Hono 的官方文檔有針對各運(yùn)行時(shí)的具體指南。這個(gè)組合的核心優(yōu)勢在于它通過類型安全將很多運(yùn)行時(shí)錯(cuò)誤提前到了編譯時(shí)和請求驗(yàn)證時(shí)。我建議你在自己的項(xiàng)目中從一個(gè)小模塊開始實(shí)踐比如先給一個(gè)用戶注冊接口加上 Zod 驗(yàn)證體會(huì)一下它帶來的信心和開發(fā)效率的提升。當(dāng)你習(xí)慣了這種“先定義契約再寫邏輯”的模式后就很難再回到那種對輸入數(shù)據(jù)提心吊膽的編碼方式了。