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

Resourcer

Overview

The interfaces in NocoBase follow a resource-oriented design pattern. Resourcer is mainly used to manage the resources and routes of API.

const Koa = require('koa');
const { Resourcer } = require('@nocobase/resourcer');

const resourcer = new Resourcer();

// Define a resource interface
resourcer.define({
  name: 'users',
  actions: {
    async list(ctx) {
      ctx.body = [
        {
          name: "u1",
          age: 18
        },
        {
          name: "u2",
          age: 20
        }
      ]  
    }
  },
});

const app = new Koa();

// Use the resourcer in koa instance
app.use(
  resourcer.middleware({
    prefix: '/api', // Route prefix of the resourcer
  }),
);

app.listen(3000);

Once the service is started, make request using curl:

>$ curl localhost:3000/api/users
[{"name":"u1","age":18},{"name":"u2","age":20}]

More instructions of resourcer can be found in Resources and Actions. Resourcer is built into NocoBase Application, you can access it through app.resourcer.

Constructor

To create resourcer instances.

Signature

• constructor(options: ResourcerOptions)

Parameter

Name	Type	Default	Description
prefix	string	-	Route prefix
accessors	Object	The following values of members	Name identifier of the default operation method
accessors.list	string	'list'	Name identifier of the list operation method
accessors.get	string	'get'	Name identifier of the get operation method
accessors.create	string	'create'	Name identifier of the create operation method
accessors.update	string	'update'	Name identifier of the update operation method
accessors.delete	string	'destroy'	Name identifier of the delete operation method
accessors.add	string	'add'	Name identifier of the add association operation method
accessors.remove	string	'remove'	Name identifier of the remove association operation method
accessors.set	string	'set'	Name identifier of the global set association operation method

Example

Pass in through the resourcer option when creating app:

const app = new Application({
  // Correspond to the configuration item of the default resourcer instance
  resourcer: {
    prefix: process.env.API_BASE_PATH
  }
});

Instance Methods

define()

Define and register a resource object with the resourcer. Usually used instead of the constructor of the Resource class.

Signature

• define(options: ResourceOptions): Resource

Parameter

Refer to Resource Constructor for details.

Example

app.resourcer.define({
  name: 'books',
  actions: {
    // Extended action
    publish(ctx, next) {
      ctx.body = 'ok';
    }
  }
});

isDefined()

Check whether the resource with the corresponding name has been registered.

Signature

• isDefined(name: string): boolean

Parameter

Name	Type	Default	Description
name	string	-	Name of the resource

Example

app.resourcer.isDefined('books'); // true

registerAction()

Register an action with the resourcer. The action is accessible to a specified resource, or all resources if no resource name is specified.

Signature

• registerAction(name: string, handler: HandlerType): void

Parameter

Name	Type	Default	Description
name	string	-	Name of the action
handler	HandlerType	-	Handler of the action

A value of name starting with <resourceName>: means that the action is only accessible to <resourceName> rescource, otherwise it is considered as a global action.

Example

// All resources can take the upload action after registration
app.resourcer.registerAction('upload', async (ctx, next) => {
  ctx.body = 'ok';
});

// Register the upload action only for attachments resource
app.resourcer.registerAction('attachments:upload', async (ctx, next) => {
  ctx.body = 'ok';
});

registerActions()

Register a set of actions with the resourcer.

Signature

• registerActions(actions: { [name: string]: HandlerType }): void

Parameter

Name	Type	Default	Description
actions	{ [name: string]: HandlerType }	-	Set of actions

Example

app.resourcer.registerActions({
  upload: async (ctx, next) => {
    ctx.body = 'ok';
  },
  'attachments:upload': async (ctx, next) => {
    ctx.body = 'ok';
  }
});

getResource()

Get the resource object with the corresponding name.

Signature

• getResource(name: string): Resource

Parameter

Name	Type	Default	Description
name	string	-	Name of the resource

Example

app.resourcer.getResource('books');

getAction()

Get the action handler function with the corresponding name.

Signature

• getAction(name: string): HandlerType

Parameter

Name	Type	Default	Description
name	string	-	Name of the action

A value of name starting with <resourceName>: means that the action is only accessible to <resourceName> rescource, otherwise it is considered as a global action.

Example

app.resourcer.getAction('upload');
app.resourcer.getAction('attachments:upload');

use()

Register a middleware in the form of Koa; the middleware forms a queue which is executed before the action handlers of all resources.

Signature

• use(middleware: Middleware | Middleware[]): void

Parameter

Name	Type	Default	Description
middleware	Middleware | Middleware[]	-	Middleware

Example

app.resourcer.use(async (ctx, next) => {
  console.log(ctx.req.url);
  await next();
});

middleware()

Generate a Koa-compatible middleware for injecting routing processing of resources into the application.

Signature

• middleware(options: KoaMiddlewareOptions): KoaMiddleware

Parameter

Name	Type	Default	Description
options.prefix?	string	''	Route prefix
options.accessors?	Object	{}	Name mapping for common methods, with the same parameter structure as accessors of the constructor

Example

const koa = new Koa();

const resourcer = new Resourcer();

// Generate Koa-compatible middleware
koa.use(resourcer.middleware());