@zenweb/helper

Zenweb 数据转换与验证模块，基于 typecasts 实现。

安装

npm install @zenweb/helper

依赖

使用前需先安装以下模块：

• @zenweb/inject
• @zenweb/messagecode

提示：Zenweb 项目已集成本模块，可直接使用无需单独安装。

配置

import helper from '@zenweb/helper';

app.setup(helper({
  // 可选，设置默认分页选项
  page: {
    defaultLimit: 20,     // 默认每页条数
    maxLimit: 100,        // 最大每页条数
    minLimit: 1,          // 最小每页条数
    allowOrder: ['id'],   // 允许排序的字段
    defaultOrder: '-id',  // 默认排序
  }
}));

使用方式

方式一：注入（推荐）

在控制器中直接注入 Helper 类：

import { Controller, Get } from '@zenweb/core';
import { QueryHelper } from '@zenweb/helper';

@Controller()
export class UserController {
  @Get()
  list(query: QueryHelper) {
    const params = query.get({
      id: '!int',
      name: 'trim',
      status: 'int[]',
    });
    const page = query.page({ total: 1000 });
    return { params, page };
  }
}

方式二：全局方法

无需注入，直接调用：

import { $query, $param } from '@zenweb/helper';

@Get()
async list() {
  const params = await $query.get({ id: '!int' });
  const page = await $query.page();
  return { params, page };
}

可注入类

| 类 | 说明 | 输入源 | |---|---|---| | QueryHelper | URL 查询参数 | ctx.query | | ParamHelper | 路由路径参数（需 @zenweb/router） | ctx.params | | TypeCastHelper | 通用数据转换 | 手动传入 |

方法说明

get(fields) - 获取并转换指定字段

page(opt?) - 获取分页参数

pick(data, fields) - TypeCastHelper 专用，从任意数据中提取字段

字段定义语法

| 语法 | 说明 | |---|---| | '!int' | 必填整数 | | 'int' | 可选整数 | | '?int' | 可为 null | | 'int[]' | 整数数组 | | 'trim' | 去除两端空格 | | { type: 'int', default: 0 } | 带默认值 | | { type: { id: '!int', name: 'string' } } | 嵌套对象 |

更多语法请参考 typecasts 文档。

分页参数

客户端可提交以下参数：

| 参数 | 说明 | |---|---|---| | limit | 每页条数 | | offset | 起始位置（从 0 开始） | | page | 页码（从 1 开始，优先级高于 offset） | | order | 排序字段，-id 表示降序 |

返回结果包含：limit、offset、page、pages（需设置 total）、order

错误处理

验证失败时会抛出消息码，可通过 @zenweb/messagecode 配置错误提示。

常见消息码：

• helper.required.{field} - 必填字段缺失
• helper.validate.{type}.{field} - 类型转换失败
• helper.page.order-unknown - 排序字段不允许
• helper.page.limit-min/max - 条数超出范围

完整示例

import { Controller, Get } from '@zenweb/core';
import { QueryHelper, ParamHelper } from '@zenweb/helper';

@Controller()
export class UserController {
  // 查询参数转换
  @Get()
  search(query: QueryHelper) {
    const { id, name, tags } = query.get({
      id: '!int',
      name: 'trim',
      tags: 'string[]',
    });
    
    const { limit, offset, order } = query.page({
      total: 500,
      allowOrder: ['id', 'created_at'],
    });
    
    return { id, name, tags, limit, offset, order };
  }

  // 路径参数转换
  @Get('/:userId')
  detail(param: ParamHelper) {
    const { userId } = param.get({ userId: '!int' });
    return { userId };
  }
}