Skip to Content

Làm một tính năng CRUD

Khoảng 20 phút. Làm xong, bạn có tính năng đơn hàng đủ thêm, xem, sửa, xoá: bảng trong database, repository, API handler, trang danh sách và trang chi tiết.

CRUD là bốn thao tác tạo, đọc, sửa, xoá trên một loại bản ghi, như đơn hàng của cửa hàng vật tư hay lịch hẹn của tiệm spa. Trong Manh, mọi file của một tài nguyên nằm chung một thư mục. Tên thư mục là đường dẫn, tên file là HTTP method.

Nhanh hơn: block resource. block_add("resource", { name: "orders", title: "Đơn hàng", fields: [...], deleteRoles: ["admin"] }) dựa vào danh sách trường để sinh đủ các file trong trang này: bảng có index, enum dùng chung, repository, năm handler, cột và trang danh sách. Mỗi trường có name, label và type, trong đó type là text, textarea, number, money, date, boolean hoặc select (kèm options: [{ value, label, color? }]). Việc còn lại là thêm trang vào menu trong app/layout.tsx và sửa luật nghiệp vụ trong repository.ts. Phần dưới giải thích từng file để bạn hiểu và tự chỉnh.

Danh sách ProTableDanh sách: ProTable với form tìm kiếm, tab trạng thái có số đếm, chọn nhiều để duyệt, valueEnum dạng Badge.
ví-dụ.manh.run · dữ liệu mẫuMở để sửa ↗
Ví dụ chạy khi bạn cuộn tới

Cây thư mục

Bạn viết các file sau. Mỗi file handler thành một API, kèm một hàm trong client sinh sẵn app/api.

app/ ├── shared/order.ts trạng thái đơn và vòng đời, server và giao diện cùng dùng └── orders/ ├── orders.table.ts bảng orders ├── repository.ts mọi truy vấn và luật nghiệp vụ ├── get.ts GET /orders → api.orders.list(params) ├── post.ts POST /orders → api.orders.create(body) ├── [id:int]/ │ ├── get.ts GET /orders/:id → api.orders.detail(id) │ ├── patch.ts PATCH /orders/:id → api.orders.update(id, body) │ ├── delete.ts DELETE /orders/:id → api.orders.remove(id) │ └── page.tsx trang /orders/:id ├── orders-columns.tsx cột dùng chung cho bảng và form └── page.tsx trang /orders

File .ts chạy trên server, file .tsx chạy trên trình duyệt. Hai bên không import lẫn nhau, trừ thư mục app/shared. Giao diện gọi server qua HTTP bằng useApiClient().

1. Khai báo bảng

Mỗi tài nguyên có một file *.table.ts. Hãy đánh index cho những cột mà danh sách dùng để sắp xếp và lọc.

app/orders/orders.table.ts
import { sqliteTable, integer, text, index } from "app/db"; import { OrderStatus } from "app/shared/order"; export const orders = sqliteTable("orders", { id: integer("id").primaryKey({ autoIncrement: true }), customerName: text("customer_name").notNull(), total: integer("total").notNull(), // đồng status: text("status", { enum: OrderStatus.values }).notNull().default("pending"), createdAt: integer("created_at").notNull(), }, (t) => [ index("orders_created_at_idx").on(t.createdAt), // danh sách sắp theo cột này index("orders_status_idx").on(t.status), // lọc theo trạng thái ]);

Lần deploy sau, manh.run tạo bảng trong database SQLite riêng của app. Bạn không phải viết migration.

2. Khai báo trạng thái một lần

app/shared là thư mục duy nhất mà cả server lẫn giao diện cùng import được. Khai báo danh sách trạng thái ở đây bằng defineEnum để nhãn, màu và giá trị nằm cùng một chỗ.

app/shared/order.ts
import { defineEnum } from "manh/enum"; export const OrderStatus = defineEnum({ pending: ["Chờ thanh toán", "processing"], // [nhãn, màu] paid: ["Đã thanh toán", "success"], cancelled: ["Đã huỷ", "error"], }); export type OrderStatus = (typeof OrderStatus.values)[number];
Thuộc tínhDùng ở
OrderStatus.valuesz.enum(OrderStatus.values) trong schema, text("status", { enum }) trong bảng
OrderStatus.valueEnumcột ProTable, ProDescriptions (hiện Badge)
OrderStatus.optionsSelect, Segmented
OrderStatus.label(v), OrderStatus.color(v)Tag, email
OrderStatus.is(v)kiểm tra một chuỗi có phải trạng thái hợp lệ không

Vòng đời của đơn cũng khai báo ở đây bằng defineFlow từ manh/flow. Bạn ghi rõ trạng thái nào được chuyển sang trạng thái nào và vai trò nào được làm bước đó. Server dựa vào đây để chặn bước sai, giao diện dựa vào đây để chọn nút cần hiện.

app/shared/order.ts
import { defineFlow } from "manh/flow"; // … OrderStatus như trên export const OrderFlow = defineFlow({ pending: { paid: ["sales", "admin"], cancelled: ["sales", "admin"] }, // trạng thái hiện tại → trạng thái tiếp theo → vai trò được làm paid: { cancelled: ["admin"] }, cancelled: {}, // trạng thái cuối });

Thay danh sách vai trò bằng true thì ai đã đăng nhập cũng làm được bước đó. Tên vai trò phải có trong app/auth.ts.

HàmDùng ở
OrderFlow.assert(user, from, to)server, trước lệnh ghi: ném 409 FLOW_ILLEGAL khi không có bước này, 403 FORBIDDEN khi sai vai trò
OrderFlow.next(status, role)giao diện: các trạng thái tiếp theo mà vai trò này được chuyển sang, mỗi trạng thái là một nút
OrderFlow.can(role, from, to)kiểm tra một bước cụ thể, trả true / false
OrderFlow.isFinal(status)trạng thái cuối, không chuyển đi đâu được nữa
OrderFlow.statesmảng mọi trạng thái đã khai báo

File trong app/shared có đuôi .ts, không chứa JSX và chỉ import app/shared/*, manh/enum, manh/flow hoặc manh/vn. Nếu import app/db, react hay dùng window ở đây, check sẽ báo shared.impure-import.

3. Viết repository

Mọi truy vấn và luật nghiệp vụ nằm trong repository.ts. Handler và cron job cùng gọi các hàm này, nên mỗi luật chỉ phải viết một lần.

listOf(table, query, opts) từ app/db trả về một trang của danh sách kèm tổng số dòng, dạng { data, total }. Bạn khai báo cột nào được tìm, lọc và sắp xếp. Mặc định bản ghi mới nhất đứng đầu.

app/orders/repository.ts
import { fail } from "manh/errors"; import { db, eq, listOf } from "app/db"; import { OrderFlow, type OrderStatus } from "app/shared/order"; import { orders } from "./orders.table"; type User = { id: number; role: string }; export const listOrders = (query: Record<string, unknown>) => listOf(orders, query, { search: [orders.customerName], // `search` → LIKE trên các cột này filters: { status: orders.status }, // khoá query → cột (so sánh bằng) sort: { createdAt: orders.createdAt, total: orders.total }, // chỉ các cột này được sắp xếp }); // { data, total } 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; } export async function createOrder(input: { customerName: string; total: number }) { const [row] = await db.insert(orders).values({ ...input, createdAt: Date.now() }).returning(); return row; } export async function updateOrder(user: User, id: number, patch: Partial<{ customerName: string; total: number; status: OrderStatus }>) { const current = await getOrder(id); // 404 nếu không có if (patch.status && patch.status !== current.status) { OrderFlow.assert(user, current.status, patch.status); // 409 FLOW_ILLEGAL / 403 FORBIDDEN } else if (current.status === "cancelled") { fail(409, "Đơn đã huỷ, không sửa được", "CANCELLED"); } const [row] = await db.update(orders).set(patch).where(eq(orders.id, id)).returning(); return row; } export async function deleteOrder(id: number) { await getOrder(id); await db.delete(orders).where(eq(orders.id, id)); }

Gặp lỗi nghiệp vụ thì ném lỗi bằng fail(status, message, code) từ manh/errors. Giao diện nhận body { error, message, code } và hiện message. OrderFlow.assert cũng ném lỗi với body cùng dạng.

Danh sách cần join, cần tính tổng hay có cột tính toán thì viết Drizzle như bình thường, vì listOf chỉ dành cho danh sách trên một bảng.

4. Viết handler danh sách và tạo mới

Mỗi handler export schema (Zod cho query hoặc body) và một hàm mặc định gọi repository. Dữ liệu đầu vào đã kiểm tra nằm ở tham số thứ hai. Hàm trả về gì thì manh.run gửi lại dạng JSON.

listSchema(opts) từ app/db sinh schema cho query của danh sách: page (hoặc current của ProTable), pageSize (mặc định 20, tối đa 100), search, sort (chỉ các khoá bạn liệt kê), order (asc | desc) và các bộ lọc bạn thêm trong filters.

schemaOf(orders) từ app/db sinh schema Zod { insert, update } từ các cột của bảng. Chỉ pick những trường mà client được phép gửi.

app/orders/get.ts
import { z } from "@hono/zod-openapi"; import { listSchema } from "app/db"; import { OrderStatus } from "app/shared/order"; import { listOrders } from "./repository"; export const schema = { query: listSchema({ filters: { status: z.enum(OrderStatus.values).optional() }, sort: ["createdAt", "total"], }), }; export default (c, { query }) => listOrders(query); // { data, total }
app/orders/post.ts
import { z } from "@hono/zod-openapi"; import { schemaOf } from "app/db"; import { orders } from "./orders.table"; import { createOrder } from "./repository"; export const schema = { body: schemaOf(orders).insert .pick({ customerName: true, total: true }) // không cho client gửi status .extend({ total: z.number().int().positive() }), }; export default (c, { body }) => { c.status(201); return createOrder(body); };

5. Viết handler theo id

Thư mục [id:int] đảm bảo id là số nguyên. Đọc giá trị bằng param.id và không khai báo param trong schema.

app/orders/[id:int]/get.ts
import { getOrder } from "../repository"; export const schema = {}; export default (c, { param }) => getOrder(param.id);
app/orders/[id:int]/patch.ts
import { schemaOf } from "app/db"; import { orders } from "../orders.table"; import { updateOrder } from "../repository"; export const schema = { body: schemaOf(orders).update.pick({ customerName: true, total: true, status: true }), }; export default (c, { user, param, body }) => updateOrder(user, param.id, body);
app/orders/[id:int]/delete.ts
import { deleteOrder } from "../repository"; export const access = ["admin"]; // vai trò khai báo trong app/auth.ts export const schema = {}; export default async (c, { param }) => { await deleteOrder(param.id); return null; // 204 No Content };

patch.ts truyền user cho repository để OrderFlow.assert biết vai trò của người gọi. Khi app có app/auth.ts, mọi handler mặc định chỉ cho người đã đăng nhập gọi. access trong delete.ts chỉ cho vai trò admin xoá. Xem thêm ở Đăng nhập và phân quyền.

6. Khai báo cột một lần

Một mảng cột dùng chung cho bảng, form và trang chi tiết. Trạng thái lấy từ app/shared/order.ts nên nhãn và màu giống hệt phía server.

app/orders/orders-columns.tsx
import type { ProColumns } from "@ant-design/pro-components"; import type { VnValueType } from "manh/shell"; import type { OrderStatus } from "app/shared/order"; export type Order = { id: number; customerName: string; total: number; status: OrderStatus; createdAt: number }; export const orderColumns: ProColumns<Order, VnValueType>[] = [ { title: "Mã", dataIndex: "id", hideInForm: true, search: false, width: 80 }, { title: "Khách hàng", dataIndex: "customerName", search: false, // tìm bằng ô từ khoá formItemProps: { rules: [{ required: true }] } }, { title: "Tổng tiền", dataIndex: "total", valueType: "vnd", search: false, formItemProps: { rules: [{ required: true }] } }, { title: "Trạng thái", dataIndex: "status", hideInForm: true }, // đổi bằng nút, không qua form { title: "Ngày tạo", dataIndex: "createdAt", valueType: "dateTime", hideInForm: true, search: false }, ];

7. Dựng trang danh sách và trang chi tiết

ResourceList từ manh/shell dựng trang danh sách: tab trạng thái có số đếm, ô tìm kiếm, phân trang, form Thêm từ chính mảng cột, cột đầu tiên link sang trang chi tiết.

app/orders/page.tsx
import { ResourceList } from "manh/shell"; import { useApiClient } from "app/api"; import { OrderStatus } from "app/shared/order"; import { orderColumns } from "./orders-columns"; export default function OrdersPage() { const api = useApiClient(); return ( <ResourceList api={api.orders} title="Đơn hàng" path="/orders" columns={orderColumns} status="status" statusEnum={OrderStatus} createTitle="Tạo đơn" /> ); }

ResourceDetail dựng trang chi tiết: tiêu đề, thẻ trạng thái, thông tin lấy từ các cột, nút Sửa, nút Xoá và nút chuyển trạng thái. Nút chuyển trạng thái lấy từ OrderFlow.next(status, role), nên mỗi người chỉ thấy những bước mình được làm.

app/orders/[id:int]/page.tsx
import { ResourceDetail } from "manh/shell"; import { useApiClient } from "app/api"; import { OrderFlow, OrderStatus } from "app/shared/order"; import { orderColumns, type Order } from "../orders-columns"; export default function OrderPage() { const api = useApiClient(); return ( <ResourceDetail<Order> api={api.orders} columns={orderColumns} path="/orders" listTitle="Đơn hàng" title={(r) => `Đơn #${r.id}`} status="status" statusEnum={OrderStatus} flow={OrderFlow} move={(to, r) => api.orders.update(r.id, { status: to })} remove /> ); }

Cần biết

  • ResourceList chuyển current, pageSize, các ô lọc và từ khoá (tên search) cho API. listSchema nhận cả current lẫn page.
  • Tab trạng thái có số đếm khi repository gọi listOf(…, { counts: "status" }).
  • Lưu thành công thì Modal đóng lại. Khi lỗi, Modal vẫn mở và hiện message của server.
  • Bước chuyển sang trạng thái huỷ được hỏi lại trước khi làm. Bước cần nhập thêm, như lý do huỷ, thì khai báo bằng ask. Giá trị người dùng nhập đến move ở tham số thứ ba.
  • Thêm nút riêng cho từng dòng bằng rowActions(row, reload), cho trang chi tiết bằng actions(r, reload). Mỗi nút gọi API qua useAction từ app/hooks.
  • Từ bên ngoài, gọi API này qua địa chỉ https://<id>.manh.run/api/orders.
  • check sẽ cảnh báo khi handler gọi db.* trực tiếp (code.no-inline-drizzle-in-handler), khi danh sách sắp theo cột chưa có index (perf.order-unindexed) và khi schema pageSize viết tay không có .max(…) (list.unbounded).

Bước tiếp theo

  • Gọi API từ giao diện — cách đặt tên hàm trong client sinh sẵn và cách xử lý lỗi.
  • Trang danh sách — thêm tab trạng thái, chọn nhiều dòng, hiện danh sách dạng thẻ.
  • Database — kiểu cột, khoá ngoại và cách schema thay đổi khi deploy.
Cập nhật