Skip to Content

get.ts, post.ts, put.ts, patch.ts, delete.ts

Mỗi file get.ts, post.ts, put.ts, patch.ts hay delete.ts là một API endpoint cho đúng method đó, ở đường dẫn của thư mục chứa nó.

app/orders/ ├── get.ts # GET /api/orders ├── post.ts # POST /api/orders ├── stats/ │ └── get.ts # GET /api/orders/stats └── [id:int]/ ├── get.ts # GET /api/orders/:id ├── patch.ts # PATCH /api/orders/:id ├── delete.ts # DELETE /api/orders/:id └── status/ └── post.ts # POST /api/orders/:id/status

Vai trò

Tên file là method, viết chữ thường. Handler chạy trên server, nhận input đã kiểm, gọi một hàm trong repository.ts rồi trả kết quả. Handler phục vụ dưới /api trên tên miền của app.

Export

  • default: hàm (c, input). input gồm body, query, headers đã kiểm theo schema, param lấy từ thư mục [id:int], và user là người đang gọi. c là context của Hono, dùng cho c.status(201) và header.
  • schema (tuỳ chọn): body, query, headers là object zod; summary, tags nếu muốn đặt nhãn riêng. Không khai báo param, manh.run tự thêm.
  • access (tuỳ chọn): "public" (mọi người), "user" (đã đăng nhập) hoặc danh sách vai như ["admin", "manager"].
  • rateLimit (tuỳ chọn): lệnh ghi có access = "public" mặc định bị giới hạn 30 request mỗi 10 phút cho mỗi IP và route, quá thì trả 429 RATE_LIMITED. { max: 5, windowSec: 60 } để đổi mức, false để tắt (webhook từ hệ thống khác). GET không bao giờ bị giới hạn.
  • cache (chỉ GET, tuỳ chọn): { maxAge: 30, scope: "user" }, giây từ 1 đến 300; scope là "user" hoặc "public".

Giá trị trả về

Trả vềStatus
object, mảng, số, boolean200, JSON
chuỗi200, text
null hoặc undefined204
Responsegiữ nguyên
sai vai trò hoặc chưa đăng nhập403 hoặc 401, kiểm trước schema
schema không khớp400
fail(status, message, code)status đó, body { error, message, code }
lỗi khác500, body { error: "INTERNAL", message: "Máy chủ gặp lỗi…" }, chi tiết chỉ có trong log

Ví dụ

app/orders/post.ts
import { z } from "@hono/zod-openapi"; import { createOrder } from "./repository"; export const access = ["admin", "sales"]; export const schema = { body: z.object({ productId: z.number().int().positive(), quantity: z.number().int().min(1).max(100), customerName: z.string().min(1).max(200), }), }; export default async (c, { user, body }) => { c.status(201); return createOrder(user, body); };
app/orders/[id:int]/get.ts
import { getOrder } from "../repository"; export default (c, { user, param }) => getOrder(user, param.id); // param.id đã là số

Client sinh sẵn đặt tên theo file: get.ts không có id thành api.orders.list(), post.ts thành api.orders.create(body), [id:int]/get.ts thành api.orders.detail(id), [id:int]/status/post.ts thành api.orders.status(id, body).

Cần biết

  • Lỗi phải ném, không trả về: fail(404, "Không tìm thấy đơn", "NOT_FOUND") từ manh/errors. Trả c.json({ error }, 404) làm giao diện mất body chuẩn.
  • Mặc định của access là "user" khi app có app/auth.ts; không có thì không kiểm. Chưa đăng nhập nhận 401, sai vai nhận 403.
  • Gọi db.* thẳng trong handler bị cảnh báo code.no-inline-drizzle-in-handler. Đặt lệnh database trong repository.ts.
  • cache trên GET có ghi dữ liệu hay gửi email bị cảnh báo cache.side-effect: lần trả từ cache bỏ qua handler.
  • Mọi request không phải GET xoá cache của app trước khi chạy.
  • Không rẽ nhánh theo c.req.method. Mỗi method một file.
  • GET chỉ đọc, kể cả các hàm nó gọi. Trang mở ra là gọi GET, nên một lệnh UPDATE hay DELETE ở đó sẽ âm thầm sửa hoặc xoá dữ liệu của chủ app. Việc thay đổi đặt trong post.ts hay patch.ts. Tạo dòng mặc định còn thiếu khi đọc lần đầu thì được. manh.run ghi cảnh báo vào log khi một GET đổi dữ liệu: [warn] GET /settings/setup changed table warehouses (UPDATE).

Bước tiếp theo

  • API handler — khoá của schema, access, cache và client sinh sẵn.
  • repository.ts — nơi đặt lệnh database và quy tắc nghiệp vụ mà handler gọi.
  • middleware.ts — đặt access cho cả một thư mục.
Cập nhật