Giao diện
Luồng dữ liệu & request
Tài liệu mô tả pipeline request thực tế từ client đến repository/database.
1) Khái niệm cốt lõi
| Thành phần | Trách nhiệm |
|---|---|
ResourceManager | Parse URL → resolve Resource + Action |
Action | Gom params (query/path/body) + middleware chain |
DataSourceManager | Chọn data source (main hoặc header x-data-source) |
Repository | Parse filter/options → query/update database |
Auth | Xác thực request (JWT, token) |
ACL | Phân quyền (role → resource → action) |
2) Sơ đồ tổng quát request pipeline
3) Sequence cho read action (list / get / query)
4) Sequence cho write action (create / update / destroy)
5) Đường đi của ctx.action.params
params được hợp nhất từ nhiều nguồn:
Chiến lược merge của Action.mergeParams():
| Trường | Chiến lược | Ý nghĩa |
|---|---|---|
filter | and-merge | Filter từ nhiều nguồn được AND lại, đảm bảo không mất điều kiện bảo mật |
fields / whitelist / blacklist | intersect | Chỉ giữ trường nằm trong tất cả các danh sách |
appends / except | union | Gộp lại, cho phép mở rộng |
sort | overwrite | Nguồn sau ghi đè nguồn trước |
Tại sao filter dùng and-merge?
ACL middleware thường inject filter ẩn (ví dụ: { createdById: currentUserId } cho quyền "view own"). Nếu merge bằng overwrite, plugin hoặc client có thể vô tình xóa filter bảo mật này.
6) Điểm đặt policy bảo mật
| Lớp bảo mật | Chức năng | Ví dụ |
|---|---|---|
| Auth middleware | Xác định token → ctx.state.currentUser | JWT decode, session check |
| ACL middleware | Kiểm tra role có quyền thực hiện action không | editor không được destroy trên users |
| ACL fixed params | Ép filter theo role vào params | { createdById: ctx.state.currentUser.id } |
| Pre-handler plugin | Bổ sung logic permission phức tạp | Check quyền trên association lồng |
7) Điểm đặt logic plugin
Plugin can thiệp vào pipeline tại nhiều vị trí:
| Mục đích | API | Scope |
|---|---|---|
| Thêm middleware toàn app | app.use(fn, { tag, after, before }) | Tất cả request |
| Thêm middleware toàn data source | dataSourceManager.use(fn) | Request có data source |
| Thêm action mới | resourceManager.registerActionHandler(name, fn) | Resource cụ thể |
| Thêm logic tiền xử lý | resourceManager.registerPreActionHandler(name, fn, topo) | Trước handler |
Thứ tự middleware quan trọng
Middleware dùng Toposort (tag + after/before). Nếu plugin thêm middleware không khai báo dependency đúng, thứ tự thực thi có thể không như mong đợi. Luôn khai báo after/before rõ ràng.
8) Mối liên hệ client ↔ server
- Client chỉ giao tiếp qua HTTP/WS, không truy cập repository trực tiếp.
- Data block trên client tạo request theo schema + params (field selection, filter, sort).
- Response JSON được render lại bởi UI schema / component map.
- WebSocket dùng cho trạng thái realtime (maintaining, notification), không dùng cho data query.
Đọc tiếp
- Server - Application - vòng đời app, middleware stack chi tiết
- Resourcer & Actions - parse request, action chain
- Database - Collection & Repository - filter parser, repository workflow
- Engine ACL - role, resource, action, snippet
- Auth & AuthManager - JWT, skipCheck, public action