Skip to Content

API handler

Khoảng 10 phút. Làm xong, app của bạn có API tạo đơn và xem đơn, kiểm input, phân quyền theo vai và báo lỗi bằng tiếng Việt.

Mỗi file get.ts, post.ts, put.ts, patch.ts, delete.ts là một endpoint, ví dụ app/bookings/post.ts nhận một lịch hẹn mới của tiệm spa. File export schema và một hàm handler, manh.run gửi giá trị hàm trả về dưới dạng JSON.

Handler chạy trên server, viết bằng Hono và Zod. Tên file là HTTP method viết thường, còn thư mục chứa file là đường dẫn.

File thành endpoint

app/orders/get.ts GET /api/orders app/orders/post.ts POST /api/orders app/orders/stats/get.ts GET /api/orders/stats app/orders/[id:int]/get.ts GET /api/orders/:id app/orders/[id:int]/patch.ts PATCH /api/orders/:id app/orders/[id:int]/status/post.ts POST /api/orders/:id/status

Đường dẫn tính trên tên miền của app, ví dụ https://<id>.manh.run/api/orders. Đoạn tĩnh được ưu tiên hơn đoạn động, nên /api/orders/stats không bao giờ rơi vào [id:int]/get.ts.

Một handler

app/orders/post.ts
import { z } from "@hono/zod-openapi"; import { createOrder } from "./repository"; export const access = ["staff", "manager"]; export const schema = { body: z.object({ customerName: z.string().min(1).max(200), productId: z.number().int().positive(), quantity: z.number().int().min(1).max(100), }), }; export default (c, { user, body }) => { c.status(201); return createOrder(user, body); };
  • schema là object phẳng với các khoá query, body, headers. Chỉ viết khoá handler cần. Input sai schema thì handler không chạy, client nhận 400.
  • Tham số thứ hai chứa input đã kiểm: param (từ [id:int], đã là số), query, body, headers và user (người đang đăng nhập: { id, name, email, role, avatarUrl }).
  • Không khai báo param trong schema, không bọc request: {…}: manh.run tự điền. Gọi thẳng c.req.json() hay c.req.query() là bỏ qua bước kiểm.

Ai được gọi: access

access khai báo ai được gọi handler, manh.run kiểm trước khi handler chạy: "public" (mọi người), "user" (đã đăng nhập) hoặc danh sách vai như ["manager", "admin"].

  • Chưa đăng nhập nhận 401 UNAUTHENTICATED, sai vai nhận 403 FORBIDDEN. Quyền được kiểm trước schema, nên người sai vai không bao giờ thấy lỗi 400 để đoán ra schema.
  • Không khai báo thì mặc định là "user" khi app có app/auth.ts. Đặt access trong middleware.ts của một thư mục để áp cho mọi handler bên dưới.
  • Handler ghi dữ liệu có access = "public" được giới hạn sẵn 30 lần mỗi 10 phút cho mỗi người gửi, vượt thì trả 429. Đổi bằng export const rateLimit = { max: 5, windowSec: 600 }, tắt bằng export const rateLimit = false (webhook từ hệ thống khác).
  • Giới hạn theo từng dòng dữ liệu (chỉ xem đơn do mình tạo) viết trong repository.

Chi tiết ở Đăng nhập và phân quyền.

Giá trị trả về

  • Object, mảng, số, boolean → 200 JSON. Chuỗi → 200 text. null / undefined → 204.
  • Trả một Response khi cần file hay stream. Muốn status thành công khác 200, gọi c.status(...) trước return.
  • Lỗi bất ngờ bị ném ra → 500, nội dung lỗi không lộ ra ở bản chạy thật.

Báo lỗi

Lỗi nghiệp vụ thì ném ra, đừng trả về. Gọi fail(status, message, code) từ manh/errors ở handler, repository hay cron. Client nhận { error, message, code }.

app/orders/repository.ts
import { fail } from "manh/errors"; import { db, eq } from "app/db"; import { orders } from "./orders.table"; export async function getOrder(id: number) { const [row] = await db.select().from(orders).where(eq(orders.id, id)); if (!row) fail(404, "Không tìm thấy đơn", "NOT_FOUND"); return row; }
  • fail có kiểu never, nên sau dòng đó TypeScript biết row chắc chắn có giá trị.
  • Lỗi 5xx có mã, ví dụ fail(503, "Đang bảo trì, vui lòng quay lại sau", "MAINTENANCE"), đến tay client đúng như vậy.
  • c.json({ error }, 404), c.text("…", 404) hay throw { status: 404 } không trả body chuẩn, đừng dùng.

Handler mỏng, logic trong repository

Handler chỉ kiểm input, gọi một hàm trong app/<resource>/repository.ts rồi trả kết quả. Truy vấn, luật chuyển trạng thái và quyền theo dòng nằm trong repository, để cron và handler khác dùng lại. Gọi db.* thẳng trong handler thì check cảnh báo code.no-inline-drizzle-in-handler.

Cache cho GET

Handler GET export cache thì các request GET giống nhau được trả từ cache, không chạy lại handler.

app/dashboard/stats/get.ts
import { dashboardStats } from "./repository"; export const cache = { maxAge: 30, scope: "user" }; // giây (1–300) export default () => dashboardStats();
  • scope: "user" (mặc định) lưu riêng theo token. scope: "public" dùng chung cho mọi người, chỉ hợp với dữ liệu ai xem cũng giống nhau.
  • Mọi request không phải GET tới app (ghi, cron, job nền, sửa ở tab Dữ liệu) xoá toàn bộ cache. Chỉ response 200 tối đa 256 KB được lưu.
  • Không dùng cho GET có tác dụng phụ (ghi dữ liệu, gửi email): check cảnh báo cache.side-effect.

Cần biết

  • Không gọi c.json(...), hãy trả giá trị thẳng.
  • App đã deploy không mở /docs hay /openapi.json ra ngoài. schema dùng để kiểm input và sinh client app/api cho giao diện.
  • Mỗi gói có giới hạn CPU cho một request. Việc nặng (xuất file lớn, lặp qua hàng nghìn dòng) đưa vào job nền manh/jobs. Xem Hạn mức theo gói.
  • Code server chạy trên runtime Web API: không có window, document, localStorage. Đọc secret bằng import { env } from "manh/env".

Bước tiếp theo

Cập nhật