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
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);
};schemalà 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ận400.- Tham số thứ hai chứa input đã kiểm:
param(từ[id:int], đã là số),query,body,headersvàuser(người đang đăng nhập:{ id, name, email, role, avatarUrl }). - Không khai báo
paramtrongschema, không bọcrequest: {…}: manh.run tự điền. Gọi thẳngc.req.json()hayc.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ận403 FORBIDDEN. Quyền được kiểm trước schema, nên người sai vai không bao giờ thấy lỗi400để đoán ra schema. - Không khai báo thì mặc định là
"user"khi app cóapp/auth.ts. Đặtaccesstrongmiddleware.tscủ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ằngexport const rateLimit = { max: 5, windowSec: 600 }, tắt bằngexport 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 →
200JSON. Chuỗi →200text.null/undefined→204. - Trả một
Responsekhi cần file hay stream. Muốn status thành công khác 200, gọic.status(...)trướcreturn. - 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 }.
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;
}failcó kiểunever, nên sau dòng đó TypeScript biếtrowchắ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)haythrow { 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.
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
200tố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):
checkcảnh báocache.side-effect.
Cần biết
- Không gọi
c.json(...), hãy trả giá trị thẳng. - App đã deploy không mở
/docshay/openapi.jsonra ngoài.schemadùng để kiểm input và sinh clientapp/apicho 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ằngimport { env } from "manh/env".
Bước tiếp theo
- Database — tạo bảng và viết truy vấn trong
repository.ts. - Đăng nhập và phân quyền —
app/auth.ts, vai trò và đăng nhập bằng Google. - get.ts, post.ts… — mọi export, bảng tham số và thứ tự middleware.