Resourcer & Actions

1) Core classes và trách nhiệm

Class	Trách nhiệm
ResourceManager	Giữ map resources, global action handlers, middleware graph (topo sort), pre-action handlers
Resource	Đại diện một resource name, map action instances, hỗ trợ only/except
Action	Chứa params, handler, middlewares, merge params bằng chiến lược đặc thù

2) Route parsing (parseRequest)

resourcer/utils.ts parse request theo hai mode:

Mode 1: Explicit route

/resourcer/<resource>:<action>

Mode 2: REST-like routes

/:resourceName
/:resourceName/:resourceIndex
/:associatedName/:associatedIndex/:resourceName

Có biến thể theo type: single, hasOne, hasMany, belongsTo, belongsToMany.

HTTP method → action mapping

HTTP	Đơn resource	Association resource
GET (no index)	list	list
GET (có index)	get	get
POST	create	create / set / add (tùy type)
PUT / PATCH	update	update
DELETE	destroy	destroy / remove

3) Runtime middleware - ResourceManager.middleware()

Action.getHandlers() - thứ tự chain

Middleware chain

Global middleware chạy trước tất cả. Pre-action handler chạy ngay trước handler cuối. Đây là nơi ACL thường inject fixed params.

4) Cơ chế handler registration

API	Scope	Ví dụ
registerActionHandler(name, fn)	Global handler cho action name	registerActionHandler('list', listHandler)
Resource constructor	Inject toàn bộ global handler vào resource actions	Tự động
Override local	Key resource:action	registerActionHandler('users:list', customList)
registerPreActionHandler(name, fn, topo)	Pre-handler theo action	registerPreActionHandler('create', validate)

Pre-action handler hỗ trợ key cụ thể (users:list) hoặc key chung (list). Runtime ưu tiên key cụ thể.

5) Package @digiforce-nc/actions

registerActions(app) nạp handlers chuẩn:

Action	Hành vi	Ghi chú
list	Paged hoặc non-paged theo paginate	Simple pagination mode khi row count lớn
get	repository.findOne
create	repository.create với values, whitelist, blacklist	Hỗ trợ updateAssociationValues
update	repository.update
destroy	repository.destroy
set / add / remove	Thao tác association	Cho belongsToMany, hasMany
query	Aggregate (measures + dimensions)	Không cho association resource

Action query

query bắt buộc có measures hoặc dimensions. Không hỗ trợ trên association resource (sourceId phải rỗng). Dùng cho dashboard/chart data.

6) Quan hệ với DataSourceManager

DataSource trong @digiforce-nc/data-source-manager cũng dùng ResourceManager, nhưng action mặc định được nạp bởi loadDefaultActions():

Pipeline resourcer giống nhau, nhưng bộ default action có thể khác giữa namespace server core và data-source-manager.

7) Điểm cần nhớ khi viết plugin

Best practices

• Logic tiền xử lý theo topo: dùng registerPreActionHandler.
• Action mới: dùng registerActionHandler rồi define resource/action tương ứng.
• Không ghi đè mù params: dùng mergeParams theo strategy để không phá whitelist/filter đã có từ middleware khác.

Tình huống	Nên dùng	Tránh
Validate input trước create	registerPreActionHandler('create', validate)	Override handler create
Thêm filter bảo mật	ACL fixedParams hoặc pre-handler	Ghi đè ctx.action.params.filter
Custom action mới	registerActionHandler + resource.define	Gắn trực tiếp vào router Koa
Sửa response format	Middleware after handler (topo after)	Sửa handler chuẩn

Đọc tiếp

• Database - Collection & Repository - repository mà handler gọi tới
• DataSourceManager - multi data source, default actions riêng