#APIResource

Resource API thông dụng gửi request theo URL, phù hợp với bất kỳ HTTP API nào. Kế thừa từ class cơ sở FlowResource và mở rộng cấu hình request và refresh(). Khác với MultiRecordResource, SingleRecordResource, APIResource không phụ thuộc vào tên resource, gửi request trực tiếp theo URL, phù hợp với các kịch bản như API tùy chỉnh, third-party API.

Cách tạo: ctx.makeResource('APIResource') hoặc ctx.initResource('APIResource'). Trước khi sử dụng cần đặt setURL(); trong ngữ cảnh RunJS sẽ tự động inject ctx.api (APIClient), không cần setAPIClient thủ công.

#Kịch bản áp dụng

#Khả năng class cơ sở (FlowResource)

Tất cả Resource đều có:

#Cấu hình request

#Định dạng URL

• Kiểu resource: Hỗ trợ rút gọn resource NocoBase, như users:list, posts:get, sẽ được nối với baseURL
• Path tương đối: Như /api/custom/endpoint, được nối với baseURL của ứng dụng
• URL đầy đủ: Sử dụng địa chỉ đầy đủ khi cross-domain, đích cần cấu hình CORS

#Lấy dữ liệu

#Ví dụ

#GET request cơ bản

const res = ctx.makeResource('APIResource');
res.setURL('/api/custom/endpoint');
res.setRequestParameters({ page: 1, pageSize: 10 });
await res.refresh();
const data = res.getData();

#URL kiểu resource

const res = ctx.makeResource('APIResource');
res.setURL('users:list');
res.setRequestParameters({ pageSize: 20, sort: ['-createdAt'] });
await res.refresh();
const rows = res.getData()?.data ?? [];

#POST request (với request body)

const res = ctx.makeResource('APIResource');
res.setURL('/api/custom/submit');
res.setRequestMethod('post');
res.setRequestBody({ name: '测试', type: 'report' });
await res.refresh();
const result = res.getData();

#Lắng nghe sự kiện refresh

const res = ctx.makeResource('APIResource');
res.setURL('/api/stats');
res.on('refresh', () => {
  const data = res.getData();
  ctx.render(<div>统计: {JSON.stringify(data)}</div>);
});
await res.refresh();

#Xử lý lỗi

const res = ctx.makeResource('APIResource');
res.setURL('/api/may-fail');
try {
  await res.refresh();
  const data = res.getData();
} catch (e) {
  const err = res.getError();
  ctx.message.error(err?.message ?? '请求失败');
}

#Header request tùy chỉnh

const res = ctx.makeResource('APIResource');
res.setURL('https://api.example.com/data');
res.addRequestHeader('X-Custom-Header', 'value');
res.addRequestParameter('key', 'xxx');
await res.refresh();

#Lưu ý

• Phụ thuộc ctx.api: Trong RunJS, ctx.api được inject bởi môi trường runtime, thường không cần setAPIClient thủ công; nếu sử dụng trong kịch bản không có ngữ cảnh, cần tự đặt.
• refresh tức request: refresh() sẽ gửi một request theo cấu hình hiện tại, method, params, data, v.v. cần được cấu hình trước khi gọi.
• Lỗi không cập nhật data: Khi request thất bại, getData() giữ giá trị gốc, có thể lấy thông tin lỗi qua getError().
• Với ctx.request: Request đơn giản một lần dùng ctx.request(); khi cần dữ liệu reactive, sự kiện, quản lý trạng thái lỗi dùng APIResource.

#Liên quan

• ctx.resource - Instance resource trong ngữ cảnh hiện tại
• ctx.initResource() - Khởi tạo và bind vào ctx.resource
• ctx.makeResource() - Tạo instance resource mới, không bind
• ctx.request() - HTTP request thông dụng, phù hợp với gọi đơn giản một lần
• MultiRecordResource - Hướng đến collection/list, hỗ trợ CRUD, phân trang
• SingleRecordResource - Hướng đến bản ghi đơn