nocobase/docs/en-US/api/resourcer/action.md

Action

Action 是对资源的操作过程的描述，通常包含数据库处理等，类似其他框架中的 service 层，最简化的实现可以是一个 Koa 的中间件函数。在资源管理器里，针对特定资源定义的普通操作函数会被包装成 Action 类型的实例，当请求匹配对应资源的操作时，执行对应的操作过程。

构造函数

通常不需要直接实例化 Action，而是由资源管理器自动调用 Action 的静态方法 toInstanceMap() 进行实例化。

constructor(options: ActionOptions)

参数

参数名	类型	默认值	描述
handler	Function	-	操作函数
middlewares?	Middleware | Middleware[]	-	针对操作的中间件
values?	Object	-	默认的操作数据
fields?	string[]	-	默认针对的字段组
appends?	string[]	-	默认附加的关联字段组
except?	string[]	-	默认排除的字段组
filter	FilterOptions	-	默认的过滤参数
sort	string[]	-	默认的排序参数
page	number	-	默认的页码
pageSize	number	-	默认的每页数量
maxPageSize	number	-	默认最大每页数量

实例成员

actionName

被实例化后对应的操作名称。在实例化时从请求中解析获取。

resourceName

被实例化后对应的资源名称。在实例化时从请求中解析获取。

resourceOf

被实例化后对应的关系资源的主键值。在实例化时从请求中解析获取。

readonly middlewares

针对操作的中间件列表。

params

操作参数。包含对应操作的所有相关参数，实例化时根据定义的 action 参数初始化，之后请求中解析前端传入的参数并根据对应参数的合并策略合并。如果有其他中间件的处理，也会有类似的合并过程。直到 handler 处理时，访问 params 得到的是经过多次合并的最终参数。

参数的合并过程提供了针对操作处理的可扩展性，可以通过自定义中间件的方式按业务需求进行参数的前置解析和处理，例如表单提交的参数验证就可以在此环节实现。

预设的参数可以参考 [/api/actions] 中不同操作的参数。

参数中还包含请求资源路由的描述部分，具体如下：

参数名	类型	默认值	描述
resourceName	string	-	资源名称
resourceIndex	string | number	-	资源的主键值
associatedName	string	-	所属关系资源的名称
associatedIndex	string | number	-	所属关系资源的主键值
associated	Object	-	所属关系资源的实例
actionName	string	-	操作名称

示例

app.resourcer.define('books', {
  actions: {
    publish(ctx, next) {
      ctx.body = ctx.action.params.values;
      // {
      //   id: 1234567890
      //   publishedAt: '2019-01-01',
      // }
    }
  },
  middlewares: [
    async (ctx, next) => {
      ctx.action.mergeParams({
        values: {
          id: Math.random().toString(36).substr(2, 10),
          publishedAt: new Date(),
        }
      });
      await next();
    }
  ]
});

实例方法

mergeParams()

将额外的参数合并至当前参数集，且可以根据不同的策略进行合并。

签名

• mergeParams(params: ActionParams, strategies: MergeStrategies = {})

参数

参数名	类型	默认值	描述
params	ActionParams	-	额外的参数集
strategies	MergeStrategies	-	针对每个参数的合并策略

内置操作的默认合并策略如下表：

参数名	类型	默认值	合并策略	描述
filterByTk	number | string	-	SQL and	查询主键值
filter	FilterOptions	-	SQL and	查询过滤参数
fields	string[]	-	取并集	字段组
appends	string[]	[]	取并集	附加的关联字段组
except	string[]	[]	取并集	排除的字段组
whitelist	string[]	[]	取交集	可处理字段的白名单
blacklist	string[]	[]	取并集	可处理字段的黑名单
sort	string[]	-	SQL order by	查询排序参数
page	number	-	覆盖	页码
pageSize	number	-	覆盖	每页数量
values	Object	-	深度合并	操作提交的数据

示例

ctx.action.mergeParams({
  filter: {
    name: 'foo',
  },
  fields: ['id', 'name'],
  except: ['name'],
  sort: ['id'],
  page: 1,
  pageSize: 10,
  values: {
    name: 'foo',
  },
}, {
  filter: 'and',
  fields: 'union',
  except: 'union',
  sort: 'overwrite',
  page: 'overwrite',
  pageSize: 'overwrite',
  values: 'deepMerge',
});