strapi-utils

页面摘要： @strapi/utils 包提供 Strapi 核心内部使用的共享辅助函数，也可在你的自定义代码中使用。它包括错误类、环境变量辅助函数、钩子工厂、类型解析、字符串和文件工具，以及异步辅助函数。

@strapi/utils 包（import { ... } from '@strapi/utils'）包含 Strapi 内部使用的工具函数，但你也可以在自定义的 控制器、服务、策略、中间件 和 生命周期钩子 中使用它们。

async

async 命名空间提供异步工具函数。导入方式如下：

const { async } = require('@strapi/utils');

以下函数可用：

以下示例使用 pipe 组合异步函数，并使用 reduce 累积值：

const { async: asyncUtils } = require('@strapi/utils');

// Compose async functions into a pipeline
const result = await asyncUtils.pipe(
  fetchUser,
  enrichWithProfile,
  formatResponse
)(userId);

// Reduce an array asynchronously (note the curried call)
const total = await asyncUtils.reduce([1, 2, 3])(
  async (sum, n) => sum + n,
  0
); // 6

contentTypes

contentTypes 命名空间暴露用于处理 Strapi 内容类型模式的常量和辅助函数。导入方式如下：

const { contentTypes } = require('@strapi/utils');

Constants

以下常量可用：

Attribute inspection functions

以下函数检查单个属性的类型：

Schema inspection functions

以下函数检查整个内容类型模式：

以下示例遍历内容类型的属性以查找关系和可写字段：

const { contentTypes } = require('@strapi/utils');

const articleSchema = strapi.contentType('api::article.article');

// List all relation fields
for (const [name, attribute] of Object.entries(articleSchema.attributes)) {
  if (contentTypes.isRelationalAttribute(attribute)) {
    console.log(`${name} is a relation`);
  }
}

// Get only the fields that can be written to
const writableFields = contentTypes.getWritableAttributes(articleSchema);

// Check if draft and publish is enabled
if (contentTypes.hasDraftAndPublish(articleSchema)) {
  console.log('This content type supports drafts');
}

env

一个用于以类型安全方式解析读取环境变量的辅助函数。env 函数返回原始字符串值，而其方法将值解析为特定类型。导入方式如下：

const { env } = require('@strapi/utils');
// or in TypeScript: import { env } from '@strapi/utils';

env 辅助函数可直接调用，也可使用以下类型化方法：

以下示例展示了如何在服务器配置文件中使用 env 辅助函数：

const { env } = require('@strapi/utils');

module.exports = {
  host: env('HOST', '0.0.0.0'),
  port: env.int('PORT', 1337),
  app: {
    keys: env.array('APP_KEYS'),
  },
};

errors

扩展 Node.js Error 类的自定义错误类。所有错误共享一个通用结构：

错误类导入方式如下：

const { errors } = require('@strapi/utils');
// or in TypeScript: import { errors } from '@strapi/utils';

以下错误类可用：

PolicyError 扩展自 ForbiddenError。所有其他错误类都扩展自 ApplicationError。

以下示例展示了如何在服务中以及在策略中抛出异常：

const { errors } = require('@strapi/utils');

// In a service or lifecycle hook
throw new errors.ApplicationError('Something went wrong', { foo: 'bar' });

// In a policy
throw new errors.PolicyError('Access denied', { policy: 'is-owner' });

file

file 命名空间提供用于处理流和文件大小的辅助函数。导入方式如下：

const { file } = require('@strapi/utils');

以下函数可用：

以下示例将上传的流转换为 buffer 并记录其大小：

const { file } = require('@strapi/utils');

const buffer = await file.streamToBuffer(uploadStream);
const sizeInKb = file.bytesToKbytes(buffer.length);
console.log(`Uploaded ${file.bytesToHumanReadable(buffer.length)} (${sizeInKb} KB)`);

hooks

用于创建钩子注册表的工厂函数。钩子允许你注册处理函数并以不同模式执行它们。命名空间导入方式如下：

const { hooks } = require('@strapi/utils');

每个钩子实例暴露以下 4 个方法：

Available hook factories

以下工厂函数创建不同的钩子类型。当处理函数必须按顺序运行时使用 series（串行），当每个处理函数为下一个转换数据时使用 waterfall（瀑布），当处理函数相互独立且可并发运行时使用 parallel（并行），当你需要第一个返回值以短路其余处理函数时使用 bail（中断）：

以下示例使用 series hook（串行钩子）注册并调用处理函数 串行钩子按顺序逐一执行处理函数，按照它们注册的顺序。其他模式包括 waterfall（每个处理函数接收前一个处理函数的返回值）、parallel（所有处理函数并发运行）和 bail（在第一个返回值的处理函数处停止）。更多详情请参阅 admin hooks。：

const { hooks } = require('@strapi/utils');

const myHook = hooks.createAsyncSeriesHook();

myHook.register(async (context) => {
  console.log('First handler', context);
});

myHook.register(async (context) => {
  console.log('Second handler', context);
});

// Execute all handlers in order
await myHook.call({ data: 'example' });

pagination

pagination 命名空间提供用于处理分页参数的辅助函数。导入方式如下：

const { pagination } = require('@strapi/utils');

以下函数可用：

withDefaultPagination 函数同时支持 page/pageSize 和 start/limit 格式。它接受一个可选的 options 对象，具有以下属性：

以下示例应用默认分页并转换结果：

const { pagination } = require('@strapi/utils');

const params = pagination.withDefaultPagination({ page: 2 }, { maxLimit: 100 });
const info = pagination.transformPagedPaginationInfo(params, 250);
// { page: 2, pageSize: 25, pageCount: 10, total: 250 }

parseType

将值转换为特定的 Strapi 字段类型。函数导入方式如下：

const { parseType } = require('@strapi/utils');

函数接受以下参数：

返回值取决于目标类型：

以下示例演示了解析不同的字段类型：

parseType({ type: 'boolean', value: 'true' }); // true
parseType({ type: 'integer', value: '42' }); // 42
parseType({ type: 'date', value: '2024-01-15T10:30:00Z' }); // '2024-01-15'

policy

用于创建和管理 策略 的辅助函数。该命名空间暴露 2 个函数：createPolicy 用于定义带有可选配置验证器的策略处理函数，createPolicyContext 用于构建处理函数可检查的带类型上下文对象。命名空间导入方式如下：

const { policy } = require('@strapi/utils');

createPolicy

创建一个带有可选配置验证器的策略。函数接受以下参数：

以下示例创建了一个带有配置验证器的策略：

const myPolicy = policy.createPolicy({
  name: 'is-owner',
  validator: (config) => {
    if (!config.field) throw new Error('Missing field');
  },
  handler: (ctx, config, { strapi }) => {
    // policy logic
    return true;
  },
});

createPolicyContext

createPolicyContext 函数创建一个带类型的上下文对象，供策略处理函数内部使用。它接受一个类型字符串（例如 'admin' 或 'koa'）和 Koa 上下文，并返回一个带有 is() 方法和 type 属性的对象：

const policyCtx = policy.createPolicyContext('admin', ctx);

policyCtx.is('admin'); // true
policyCtx.type; // 'admin'

primitives

底层数据转换辅助函数。以下子模块可作为来自 @strapi/utils 的直接顶层导入使用：

const { strings, objects, arrays, dates } = require('@strapi/utils');

strings

以下字符串工具函数可用：

objects

以下对象工具函数可用：

arrays

以下数组工具函数可用：

dates

以下日期工具函数可用：

providerFactory

创建一个可插拔的注册表，按键存储和检索项目，并带有生命周期钩子。这与 Strapi 内部用于其上传和邮件提供方的工厂相同。当你在自己的插件中需要可互换策略或适配器的存储时，使用 providerFactory。工厂导入方式如下：

const { providerFactory } = require('@strapi/utils');

Parameters

工厂接受以下参数：

Provider methods

返回的提供方实例暴露以下方法：

Provider hooks

每个提供方实例暴露一个 hooks 对象，包含 4 个钩子注册表：

以下示例创建一个提供方，并使用生命周期钩子注册一个项目：

const { providerFactory } = require('@strapi/utils');

const registry = providerFactory();

registry.hooks.willRegister.register(async ({ key, value }) => {
  console.log(`About to register: ${key}`);
});

await registry.register('my-provider', { execute: () => {} });

registry.get('my-provider'); // { execute: [Function] }
registry.has('my-provider'); // true
registry.size(); // 1

relations

relations 命名空间提供用于检查关系属性基数（例如一对多 vs 多对多）的辅助函数。要检查某个属性是否为关系，请改用 contentTypes.isRelationalAttribute。命名空间导入方式如下：

const { relations } = require('@strapi/utils');

以下函数可用：

以下示例过滤内容类型的属性以查找所有一对多或多对多关系：

const { relations, contentTypes } = require('@strapi/utils');

const schema = strapi.contentType('api::article.article');

for (const [name, attribute] of Object.entries(schema.attributes)) {
  if (contentTypes.isRelationalAttribute(attribute) && relations.isAnyToMany(attribute)) {
    console.log(`${name} is a *-to-many relation`);
  }
}

sanitize

sanitize 命名空间提供基于内容类型模式清理输入和输出数据的函数。在处理或返回数据之前，使用 sanitize 移除不允许的、私有的或受限的字段。

命名空间导入方式如下：

const { sanitize } = require('@strapi/utils');

createAPISanitizers 函数接受一个模型解析器，并返回一组限定于该模型的清理器方法。模型解析器是一个函数，给定内容类型 UID（例如 'api::article.article'），返回相应的模式。实际上，strapi.getModel 已经做到了这一点。你通常在 bootstrap 期间或服务顶部调用一次 createAPISanitizers：

const sanitizers = sanitize.createAPISanitizers({
  getModel: strapi.getModel.bind(strapi),
});

返回的对象提供以下内容：

每个方法接受一个可选的 options 对象，具有以下属性：

setCreatorFields

在实体上设置 createdBy 和 updatedBy 字段。当你构建在 Strapi 默认 文档服务 之外创建或更新条目的自定义控制器或服务时，使用此函数。该函数返回一个柯里化函数 柯里化函数是一种不一次性接收所有参数的函数。相反，它为每一个参数返回一个新的函数。这让你可以先固定某些参数，稍后再传入其余参数。例如，setCreatorFields({ user }) 返回一个可复用的函数，你可以在任意实体数据上调用它。：先使用选项调用它，再使用实体数据调用它。导入方式如下：

const { setCreatorFields } = require('@strapi/utils');

函数接受以下参数：

以下示例展示了如何在创建和更新时设置创建者字段：

const { setCreatorFields } = require('@strapi/utils');

const addCreator = setCreatorFields({ user: { id: 1 } });
const data = addCreator({ title: 'My Article' });
// { title: 'My Article', createdBy: 1, updatedBy: 1 }

const updateCreator = setCreatorFields({ user: { id: 2 }, isEdition: true });
const updated = updateCreator(data);
// { title: 'My Article', createdBy: 1, updatedBy: 2 }

validate

validate 命名空间提供用于根据内容类型模式检查输入和查询数据的函数。使用 validate 拒绝引用未知、私有或受限字段的请求。

命名空间导入方式如下：

const { validate } = require('@strapi/utils');

createAPIValidators 函数接受一个模型解析器（详见 sanitize），并返回一组限定于该模型的验证器方法：

const validators = validate.createAPIValidators({
  getModel: strapi.getModel.bind(strapi),
});

返回的对象提供以下内容：

每个方法接受一个可选的 options 对象，其属性与 sanitize 选项 相同：auth 用于基于权限的检查，strictParams 用于拒绝未知字段，route 用于在严格模式下允许自定义路由参数。

以下示例在自定义服务中验证查询并捕获错误：

const { validate, errors } = require('@strapi/utils');

const validators = validate.createAPIValidators({
  getModel: strapi.getModel.bind(strapi),
});

try {
  await validators.query(ctx.query, 'api::article.article', {
    auth: ctx.state.auth,
  });
} catch (error) {
  // error is a ValidationError with details about which fields failed
  console.error(error.message, error.details);
}

yup

yup 命名空间重新导出了 Yup 验证库 并带有 Strapi 特定的扩展。导入方式如下：

const { yup } = require('@strapi/utils');

Additional Yup methods

Strapi 向 Yup 模式添加了以下方法：

Schema validation helpers

validateYupSchema 和 validateYupSchemaSync 是 @strapi/utils 的顶层导出，不属于 yup 命名空间：

const { validateYupSchema, validateYupSchemaSync } = require('@strapi/utils');

以下辅助函数可用：

zod

Strapi 重新导出了来自 Zod 的 z 实例，并提供了一个 validateZod 辅助函数，将 Zod 模式包装为 Strapi 风格的验证器。Strapi 不会向 Zod 添加自定义方法。z 是标准的 Zod API。辅助函数导入方式如下：

const { validateZod, z } = require('@strapi/utils');

以下示例定义了一个模式，并使用 validateZod 创建了一个验证器函数。成功时，函数返回解析后的数据。失败时，它抛出 ValidationError（参见 errors），并附带哪些字段失败的详情：

const schema = z.object({
  name: z.string().min(1),
  age: z.number().positive(),
});

const validate = validateZod(schema);

const parsed = validate({ name: 'Alice', age: 30 }); // returns parsed data
validate({ name: '' }); // throws ValidationError