Gọi API từ giao diện
Khoảng 10 phút. Làm xong, bạn có trang React đọc và ghi dữ liệu qua client sinh sẵn useApiClient() và hook useRequest, có nút tải lại và báo lỗi.
Trang .tsx chạy trên trình duyệt nên không import được code server. Mọi lệnh đọc và ghi, như lấy danh sách đơn hàng hay đổi trạng thái một đơn, đều gọi qua HTTP bằng client có sẵn kiểu TypeScript, do manh.run sinh từ các file handler.
1. Lấy client
useApiClient() từ app/api trả về một client, trong đó mỗi handler có một hàm tương ứng. Handler trả gì thì hàm nhận đúng như vậy, không phải đọc .data.
import { useApiClient } from "app/api";
export default function OrdersPage() {
const api = useApiClient();
// api.orders.list({ page: 1, pageSize: 20 }) → { data, total }
// …
}Tên hàm đặt theo đường dẫn file:
app/orders/get.ts→api.orders.list(params)·app/orders/post.ts→api.orders.create(body)app/orders/[id:int]/get.ts→api.orders.detail(id)·patch.tshoặcput.ts→api.orders.update(id, body)·delete.ts→api.orders.remove(id)- Với đường dẫn con, tên hàm là đoạn cuối:
app/auth/login/post.ts→api.auth.login(body);app/orders/[id:int]/status/post.ts→api.orders.status(id, body) - Tên thư mục có gạch nối thì đổi sang camelCase:
app/chat-messages/get.ts→api.chatMessages.list()
2. Đọc dữ liệu với useRequest
useRequest từ app/hooks gọi hàm khi component hiện ra và trả về { data, loading, error, run, refresh, mutate }.
import { useParams } from "react-router-dom";
import { Card, Skeleton } from "antd";
import { useApiClient } from "app/api";
import { useRequest } from "app/hooks";
export default function OrderPage() {
const { id } = useParams();
const api = useApiClient();
const { data, loading } = useRequest(() => api.orders.detail(Number(id)), {
refreshDeps: [id], // id đổi thì tải lại
});
if (loading) return <Skeleton active />;
return <Card title={`Đơn ${data?.id}`}>{data?.customerName}</Card>;
}Các tuỳ chọn gồm manual, defaultData, refreshDeps, onSuccess, onError. Không có pollingInterval, debounceWait hay cacheKey.
3. Ghi dữ liệu với useAction
useAction(fn, { ok, reload }) từ app/hooks bọc một lệnh ghi. Hook gọi API, hiện câu ok hoặc câu lỗi của server, tải lại dữ liệu rồi trả true hoặc false.
const api = useApiClient();
const { data, refresh } = useRequest(() => api.orders.detail(Number(id)), { refreshDeps: [id] });
const markPaid = useAction(() => api.orders.update(Number(id), { status: "paid" }),
{ ok: "Đã ghi nhận thanh toán", reload: refresh });
<Button disabled={data?.status !== "pending"} onClick={() => markPaid()}>Đánh dấu đã trả</Button>- Form trong Modal:
onFinish={(v) => save(row.id, v)}. Form chỉ đóng khi lệnh ghi thành công. - Nút chuyển trạng thái theo vòng đời đơn thì dùng
FlowActions, xem Làm một tính năng CRUD. - Muốn
useRequestkhông tự chạy khi trang mở, truyềnmanual: truerồi gọirun().
4. Trang danh sách với ResourceList
Trang danh sách nào cũng làm đi làm lại mấy việc: tải từng trang, tìm kiếm, lọc theo trạng thái, form thêm mới. ResourceList từ manh/shell làm sẵn những việc đó cho một tài nguyên.
import { ResourceList } from "manh/shell";
import { useApiClient } from "app/api";
import { OrderStatus } from "app/shared/order";
export default function OrdersPage() {
const api = useApiClient();
return (
<ResourceList api={api.orders} title="Đơn hàng" path="/orders" status="status" statusEnum={OrderStatus}
columns={[
{ title: "Khách hàng", dataIndex: "customerName", formItemProps: { rules: [{ required: true }] } },
{ title: "Tổng tiền", dataIndex: "total", valueType: "vnd" },
{ title: "Trạng thái", dataIndex: "status", hideInForm: true },
]} />
);
}- Cột vừa là cột của bảng vừa là ô của form Thêm. Cột đầu tiên thành link sang
/orders/<id>. - Tab trạng thái có số đếm khi handler danh sách trả
counts(listOf(…, { counts: "status" })). rowActions(row, reload)thêm nút cho từng dòng,toolBar(reload)thêm nút trên thanh công cụ.- Tự dựng bảng thì dùng
<ProTable request={tableRequest(api.orders.list)} />vớitableRequesttừapp/hooks.
Handler danh sách nhận các tham số này qua listSchema, xem Làm một tính năng CRUD.
5. Xử lý lỗi
Khi server dừng request bằng fail(...), promise bị reject với body { error, message, code }. App dùng AppShell tự hiện message của server khi một lệnh gọi lỗi, nên trang không cần try / catch kèm message.error.
- Lỗi 401 nghĩa là phiên đăng nhập đã hết hạn hoặc tài khoản bị khoá. App tự đăng xuất và đưa người dùng về
/login. - Cần câu lỗi để hiện ở chỗ khác, ví dụ trong form:
errorText(e)từmanh/shell.
6. Gọi API bên thứ ba
Với API nằm ngoài app (bản đồ, tra cứu mã số thuế…), dùng useApi() từ app/hooks. Đây là một instance axios bình thường, bạn tự đọc res.data và dùng URL đầy đủ.
import { Select } from "antd";
import { useApi, useRequest } from "app/hooks";
export function ProvinceSelect(props: { value?: string; onChange?: (v: string) => void }) {
const http = useApi(); // hook: gọi ở đầu component
const { data, loading } = useRequest(() =>
http.get("https://provinces.example.vn/api/p/").then((r) => r.data),
);
return <Select {...props} loading={loading} options={(data ?? []).map((p: any) => ({ label: p.name, value: p.code }))} />;
}Với API của chính app, hãy dùng useApiClient() thay cho useApi(). useApi() vẫn chạy nhưng không có kiểu TypeScript, và check sẽ cảnh báo code.no-raw-useapi-on-own-backend.
Cần biết
- Không import
useRequesttừahooks, vì gói này không có trong danh sách được phép. - Muốn tải lại định kỳ, gọi
setInterval(refresh, ms)tronguseEffect. Muốn chờ người dùng gõ xong mới gọi, hãy debounce giá trị ô nhập rồi đưa vàorefreshDeps. - Sau
signIn(await api.auth.login(values)), mọi lệnh gọi quauseApiClient()vàuseApi()tự gửiAuthorization: Bearer <token>. Bạn không cần tự thêm header hay tự ghi localStorage. - Handler danh sách trả
{ data, total }. Handler xem chi tiết, tạo và sửa trả về bản ghi. - Gọi một hàm không có trong client thì
checksẽ báo lỗi.
Bước tiếp theo
- Làm một tính năng CRUD — viết handler và trang dùng chính client này.
- Đăng nhập và phân quyền — cách lấy token và gửi kèm mỗi lệnh gọi.
- API handler — handler trả gì thì client nhận đúng như thế.