参数修改器
灵活修改 API 接口的请求和响应参数，支持增加、删除、修改参数类型
参数修改器
本插件用于灵活修改 API 接口的请求和响应参数，支持增加、删除和修改参数类型。
主要功能
- 支持修改
params、pathParams、data、response四个维度的参数 - 支持增加、删除、修改参数类型
- 支持修改参数层级（
flat） - 通过
match规则精确控制需要修改的字段 - 通过
path规则限定仅对匹配的接口路径生效 - 通过
handler函数动态修改参数的类型和必填性
基本使用
import { defineConfig } from 'wormajs';
import { payloadModifier } from 'wormajs/plugin';
export default defineConfig({
generator: [
{
// ...
plugins: [
// 修改请求参数中的 userId 字段
payloadModifier([
{
scope: 'params',
match: key => key === 'userId',
handler: schema => {
return {
attr1: { required: false, type: 'string' }, // 生成为可选参数
attr2: 'number', // 生成为必填参数
attr3: {
// 嵌套数据
innerAttr: { oneOf: ['string', 'number'] },
},
};
},
},
]),
],
},
],
});配置参数
ModifierScope（修改范围）
type ModifierScope = 'params' | 'pathParams' | 'data' | 'response';Schema（数据模式定义）
定义参数类型的核心类型，支持多种模式：
- 基本类型：
'number' | 'string' | 'boolean' | 'undefined' | 'null' | 'unknown' | 'any' | 'never' - 数组类型：
Schema[]（由元素类型组成的原生数组，例如['string']表示string[]，['string', 'number']表示元组[string, number]） - 引用类型（对象）：
{ [attr: string]: Schema }（可选属性使用SchemaOptional包装形式{ required: false, type: Schema }） - 联合类型：
{ oneOf: Schema[] } | { anyOf: Schema[] } | { allOf: Schema[] } - 枚举类型：
{ enum: Array<string | number | boolean | null>; type?: SchemaPrimitive }（值必须是给定集合之一，type可选表示枚举元素的基础类型） - 可选普通类型：
{ required: boolean; type: Schema }（独立的普通类型字段本身可选时使用，以type字段为准）
Config（插件配置接口）
interface Config {
/** 生效范围 */
scope: ModifierScope;
/** 接口路径过滤：仅当 apiDescriptor.url 命中时才生效；省略则对所有接口生效。匹配规则与 match 一致 */
path?: string | RegExp | ((url: string) => boolean);
/** 匹配规则，不指定则匹配全部 */
match?: string | RegExp | ((key: string) => boolean);
/**
* 处理器
* - 返回 Schema 表示修改类型
* - 返回 { required: boolean; type: Schema } 表示修改必填性（以 type 字段为准）
* - 返回 void | null | undefined 表示移除字段
* handler 第一个参数为当前字段的 Schema，第二个参数为命中的字段名 key（未配置 match 时为 undefined）
* handler 参数默认类型为 Schema，如需更精确的类型可在 handler 内部进行断言（as）
*/
handler: (
schema: Schema,
key?: string,
) => Schema | { required: boolean; type: Schema } | void | null | undefined;
}示例
修改参数类型
将 params 中的 age 字段修改为 number 类型：
payloadModifier([
{
scope: 'params',
match: 'age',
handler: () => 'number',
},
]);修改嵌套参数
修改 data 中的 user 对象及其嵌套结构：
payloadModifier([
{
scope: 'data',
match: 'user',
handler: () => ({
name: 'string',
age: 'number',
address: {
city: 'string',
zipCode: 'number',
},
}),
},
]);移除参数
移除 response 中的 debugInfo 字段：
payloadModifier([
{
scope: 'response',
match: 'debugInfo',
handler: () => undefined,
},
]);联合类型
将 pathParams 中的 id 字段修改为 string | number 类型：
payloadModifier([
{
scope: 'pathParams',
match: 'id',
handler: () => ({ oneOf: ['string', 'number'] }),
},
]);枚举类型
将 params 中的 status 字段修改为枚举类型，值只能是给定集合之一：
payloadModifier([
{
scope: 'params',
match: 'status',
handler: () => ({ enum: ['active', 'inactive', 'pending'], type: 'string' }),
},
]);SchemaEnum 也可用于接收入参时的判断：当字段在 OpenAPI 中本身就是枚举时，handler 收到的 schema 即为 { enum: [...], type?: ... }，可据此再转换。
常用场景示例
以下为日常使用中高频出现的组合配置，可直接复制并按需调整。
数字 id 统一改为 string（避免前端精度丢失）
后端 id 多为 integer，前端用 number 接收会丢失精度。用正则把以 id/Id 结尾的字段统一改为 string：
payloadModifier([
{ scope: 'response', match: /[Ii]d$/, handler: () => 'string' },
{ scope: 'params', match: /[Ii]d$/, handler: () => 'string' },
]);时间字段统一改为 number 时间戳
把以 time/at 结尾的字段（如 createTime、updated_at）统一改为 number：
payloadModifier([
{ scope: 'data', match: /(time|at)$/i, handler: () => 'number' },
{ scope: 'response', match: /(time|at)$/i, handler: () => 'number' },
]);批量移除内部 / 调试字段
移除以 debug、_、internal 开头的响应字段：
payloadModifier([
{ scope: 'response', match: /^(debug|_|internal)/i, handler: () => undefined },
]);必填与可选互转
把 nickname 改为可选、把 phone 改为必填：
payloadModifier([
{ scope: 'data', match: 'nickname', handler: () => ({ required: false, type: 'string' }) },
{ scope: 'data', match: 'phone', handler: () => ({ required: true, type: 'string' }) },
]);根据原类型动态改写（handler 接收 schema）
把疑似数组（以 list/List 结尾）的响应字段统一规整为 string[]：
payloadModifier([
{
scope: 'response',
match: /list$/i,
handler: (schema) => ({ type: ['string'] }),
},
]);组合多个 scope / path 的实战配置
一个真实项目中常见的完整配置，兼顾路径过滤与类型修正：
payloadModifier([
// 1) 仅对 /api/admin 下的接口，给请求体增加内部字段
{
path: /^\/api\/admin/,
scope: 'data',
match: 'operatorId',
handler: () => ({ required: true, type: 'string' }),
},
// 2) 所有接口：数字 id 转 string
{ scope: 'response', match: /[Ii]d$/, handler: () => 'string' },
// 3) 所有接口：移除调试字段
{ scope: 'response', match: /^(debug|internal)/i, handler: () => undefined },
]);高级用法
动态修改必填性
通过返回 { required: true/false, type: schema } 对象来控制（以 type 字段为准）：
payloadModifier([
{
scope: 'data',
match: 'email',
handler: () => ({ required: true, type: 'string' }),
},
]);可选参数与必填参数
在 Schema 对象中，必填属性直接写；可选属性使用 SchemaOptional 包装形式 { required: false, type: Schema } 表示：
handler: () => ({
username: 'string', // 必填
age: { required: false, type: 'number' }, // 可选
});SchemaOptional 与逐字段调用时「可选普通类型」的入参表示完全一致，因此整段调用和逐字段调用的 handler 处理逻辑可以统一。
使用正则匹配
匹配所有以 _date 结尾的 params 参数：
payloadModifier([
{
scope: 'params',
match: /_date$/,
handler: () => 'string',
},
]);支持 oneOf、anyOf、allOf
联合类型统一使用关键字写法：
handler: () => ({
oneOf: [
{ type: 'string', cardNumber: 'string' },
{ type: 'number', email: 'string' },
],
});anyOf：定义可选参数组合allOf：定义参数组合（必须同时满足）
数组类型
返回由元素类型组成的原生数组即可表示数组：
handler: () => (['string']); // string[]
handler: () => (['string', 'number']); // 元组 [string, number]指定接口路径（path 过滤）
通过 path 限定配置仅对匹配的接口路径生效，未命中的接口将原样返回、不受影响。匹配规则与 match 一致，支持字符串子串、正则、函数三种形式：
payloadModifier([
// 仅对路径包含 /pets 的接口生效
{
path: '/pets',
scope: 'data',
match: 'userId',
handler: () => ({ required: true, type: 'string' }),
},
// 仅对 /admin 开头的接口生效（正则）
{
path: /^\/admin/,
scope: 'params',
match: 'token',
handler: () => ({ required: true, type: 'string' }),
},
]);