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/statusVai 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).inputgồmbody,query,headersđã kiểm theoschema,paramlấy từ thư mục[id:int], vàuserlà người đang gọi.clà context của Hono, dùng choc.status(201)và header.schema(tuỳ chọn):body,query,headerslà object zod;summary,tagsnếu muốn đặt nhãn riêng. Không khai báoparam, 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ả 429RATE_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;scopelà"user"hoặc"public".
Giá trị trả về
| Trả về | Status |
|---|---|
| object, mảng, số, boolean | 200, JSON |
| chuỗi | 200, text |
null hoặc undefined | 204 |
Response | giữ nguyên |
| sai vai trò hoặc chưa đăng nhập | 403 hoặc 401, kiểm trước schema |
schema không khớp | 400 |
fail(status, message, code) | status đó, body { error, message, code } |
| lỗi khác | 500, 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
accesslà"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áocode.no-inline-drizzle-in-handler. Đặt lệnh database trongrepository.ts. cachetrên GET có ghi dữ liệu hay gửi email bị cảnh báocache.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.tshaypatch.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
accesscho cả một thư mục.
Cập nhật