ts-api-core
Version:
Nodejs api framework core
452 lines (451 loc) • 19.4 kB
TypeScript
/**
* 请求数据定义
* ```
* 使用此类来定义一个 api 请求给客户端调用
* ```
*/
export declare class RequestData {
/** 请求HTTP方法 */
methed: RequestMethod | RequestMethod[];
/** 请求接口名称 */
name: string;
/** 请求接口路径 */
path: string;
/** 请求类型, 不同的请求类型，会有不同的 `Wrapper` 来处理, 自定义的类型请使用 `@Wrapper` 注解添加 */
type: RequestType | string;
/** 请求 Header 参数定义, 默认 `{"Content-Type": "application/json"}` */
headers?: Record<string, RequestHeaderItem | string>;
/** 请求 Query 参数定义 */
query?: (string | RequestParam)[] | undefined;
/** 请求 Body 参数定义 */
body?: (string | RequestBodyParam) | (string | RequestBodyParam)[] | undefined;
/** 请求 Response 返回配置 */
resp?: RequestResultConfig | undefined;
/** 未配置 `resp` 时，直接用来返回的数据 */
result?: any | undefined;
/** 备注信息 */
remarks?: string | Promise<string>;
/** 数据源 api 列表 */
apis?: (string | RequestItem)[];
/** 请求配置信息 (配置是否使用驼峰转换，字段合并等) */
config?: RequestConfig | ExecuteWrapperRequestConfig | GraphWrapperRequestConfig | SQLWrapperRequestConfig | Record<string, any> | undefined;
/** 是否输出打包的 api 日志, 默认使用 `Route` 配置，未指定时随 `logger` 配置 */
logPackage?: boolean;
}
/** 请求 Header 定义 */
export declare class RequestHeaderItem {
/** 参数值 */
value?: string;
/** 是否必须 */
must: boolean;
/** 示例 */
demo?: string;
/** 备注 */
remark?: string;
}
/** 请求方法参数选项 */
export declare enum RequestItemArgsOption {
/** 默认值，仅包含指定的参数 */
None = 0,
/** Get 请求时全部Query源; POST请求时将全部 Query 源作为 Body */
AllQuery = 1,
/** Get请求时使用当前请求的所有BODY源作为Query， POST请求时使用全部Body源 */
AllBody = 2,
/** 使用当前请求的全部Query和Body源 */
AllQueryBody = 3,
/** 使用当前请求的全部Query和Body源， 但排除掉 `args` 指定的参数 */
Exclude = 4
}
/** 请求方法 */
export declare class RequestItem {
/** api URL */
api: string;
/** 请求方法, 默认 `GET` */
methed?: RequestMethod;
/** 请求Query参数 */
args?: (string | RequestItemArgs)[];
/** 请求Body参数 */
body?: (string | RequestItemArgs)[];
/** 自动使用参数选项，默认 `RequestItemArgsOption.None` */
args_opt?: RequestItemArgsOption;
/** 自动使用参数选项，默认 `RequestItemArgsOption.None` */
body_opt?: RequestItemArgsOption;
/** 自动解析api，默认为 `true` (取出返回数据的 `RetObject` 部份) */
parser?: boolean;
}
/** api 请求参数数据来源 */
export declare enum RequestItemArgsSource {
/** 数据来自于 Query */
QUERY = "query",
/** 数据来自于 Body */
BODY = "body",
/** 自动，GET 请求来源于 Query, POST 请求优先使用 Body, 不存在是使用 Query */
AUTO = "auto",
/** 固定值，配置中直接指定的 `default` 值 */
FIXED = "fixed"
}
/** api 请求参数选项 */
export declare class RequestItemArgs {
/** 参数字段名称 */
name: string;
/** 参数数据来源字段名, 不指定则使用 `name` */
field?: string;
/** 参数数据来源（默认：AUTO) */
src?: RequestItemArgsSource;
/** 参数是否是整个源数据（不设置 `field` 时有效） */
all_src?: boolean;
/** 参数类型，默认 `string` */
type?: RequestParamType;
/** 默认值 */
default?: any;
/** 参数值等于什么的时候需要忽略? 比如将此设置为"1"，当参数值为1时，实际请求时会设置为 undefined */
ignore?: any;
/** 参数值不等于什么的时候需要忽略? 比如将此设置为"0"，当参数值不为0时，实际请求时会设置为 undefined */
ignoreNot?: any;
/** 当使用 `all_src` 时，是否强制转换成 dto 对象 */
convert?: boolean;
}
/** 请求方法 */
export declare enum RequestMethod {
/** GET 请求 */
GET = "get",
/** POST 请求 */
POST = "post"
}
/** 请求类型 */
export declare enum RequestType {
/** 原始请求，直接根据参数调用API后按指定规则返回数据 */
Raw = "raw",
/** 动态执行指定的 Wrapper， `config` 必须指定 `wrapper` 名称， `func` 要执行的函数名称， 及此函数需要的参数 `args` 列表。 配置类型： `ExecuteWrapperRequestConfig`
* @description 返回配置 `resp` 仅作为文档使用 */
ExecuteWrapper = "wrapper",
/** 执行 GraphQL 查询, `config` 必须指定 `name` GraphQL查询名称, `query` 查询命令， 及此函数可能需要的参数 `args` 列表。 配置类型： `GraphWrapperRequestConfig`
* @description 返回配置 `resp` 仅作为文档使用 */
GraphQL = "graph",
/** 执行 SQL 语句， `config` 必须指定 `sql` 语句。 配置类型： `SQLWrapperRequestConfig`
* @description 返回配置 `resp` 仅作为文档使用 */
SQL = "sql"
}
/** 请求返回值选项 */
export declare enum RequestResultValue {
/** 取值源于请求参数中的 query */
QUERY = -1,
/** 取值源于请求参数中的 body */
BODY = -2,
/** 固定的，不取值 */
FIXED = -3
}
/** 请求参数类型 */
export declare enum RequestParamType {
/** 字符串（默认） */
StringType = "string",
/** 数字型（浮点数，长整数） */
NumberType = "number",
/** 整型数字 */
IntType = "int",
/** 布尔类型 */
BoolType = "bool",
/** 日期类型 */
DateType = "date",
/** 对象型 */
ObjectType = "object"
}
/** 请求参数校验器 */
export declare enum RequestParamValidate {
/** 数字型参数校验, 参数：`(message, max, min, defaultValue)` */
NumberValidator = "number",
/** 整数型参数校验, 参数：`(message, max, min, defaultValue, must = true)` */
IntValidator = "int",
/** 枚举型参数校验 `@pick`, 参数：`(pick[], defaultValue, must = true, message)` */
PickValidator = "pick",
/** 手机号码参数校验, 参数：`must = true` */
MobileValidator = "mobile",
/** 必填参数校验, 参数：`message` */
RequiredValidator = "required",
/** 字符串参数长度校验, 参数：`lengthMin = 0, lengthMax = 50, message` */
LengthValidator = "length",
/** 分页页码参数校验, 参数：`defaultValue = 1, message` */
PageIndexValidator = "pageIndex",
/** 分页大小参数校验, 参数：`defaultValue = 50, message, max, min` */
PageSizeValidator = "pageSize"
}
/** 请求返回数据字段转换器类型 */
export declare enum RequestResultConvert {
/** 直接排除掉某个字段, 参数：`无` */
ExcludeField = "exclude_field",
/** 数据筛选转换器, 参数：`field: string, value: any | undefined` */
ValueFilter = "value_filter",
/** 布尔值转换, 参数：`trueValue?: any | undefined` */
BoolValue = "bool_value",
/** 布尔值计算转换, 参数：`calcCallBack?: (v: any | undefined) => boolean` */
BoolCalc = "bool_calc",
/** 数值型转换, 参数：`calcCallBack?: (v: any) => number` */
INT = "int",
/** JSON字符串转对象, 参数：`convSubFieldName = false` */
JSON = "json",
/** 日期型转换器，参数：`无` */
DATE = "date",
/** 子对象转换至父级，参烤：`convSubFieldName = false, convFieldName?: boolean` */
SubObject = "sub_obj"
}
/** SQL 请求返回数据来源类型 */
export declare enum SQLRequestResultType {
/** sql 语句执行的响应结果 */
SQL = "sql",
/** 插入语句执行结果 */
Insert = "insert",
/** 更新语句执行结果 */
Update = "update",
/** 查询语句执行结果 */
Query = "query",
/** 删除语句执行结果 */
Delete = "delete",
/** 插入或更新语句执行结果 */
InsertUpdate = "json"
}
/** 请求 Query 参数 */
export declare class RequestParam {
/** 参数名称 */
name: string;
/** 源数据字段名称，不设置时使用 `name` */
src?: string;
/** 参数类型，默认 `string` */
type?: RequestParamType;
/** 是否是数组, `0 | false | undefined` 不是数组, `1 | true` 必须是数组, `2` 允许是数组或非数组 */
array?: boolean | number;
/** 参数校验器类型 */
validate?: RequestParamValidate;
/** 参数校验器参数列表 */
validate_value?: any[];
/** 备注信息 */
remarks?: string;
/** 是否必须，默认 `false` */
must?: boolean | number;
/** 默认值 */
default?: any | undefined;
/** 参数示例 */
demo?: string | number;
}
/** 请求 Body 参数 */
export declare class RequestBodyParam extends RequestParam {
/** 子类, 只有 `type` 为 `Object` 类型时有效 */
children?: (string | RequestBodyParam) | (string | RequestBodyParam)[] | undefined;
}
/** 请求返回配置 */
export declare class RequestResultConfig {
/** 返回数据类型，默认为 `object`，`fields` 存在时强制为 `object` 或 `array` */
type?: RequestParamType;
/** 字段列表 (string类型时只表示字段名称) */
fields?: (string | RequestResultFiled)[] | (string | RequestResultFiled) | undefined;
/** 自动合并字段，默认 `否`，如果需要，指定 api数据源索引号（小于0或超出api数组则不合并） */
merage?: number | string;
/** 是否是数组 （根配置时可用， 默认 `false` ） */
array?: boolean;
/** 是否返回的是原始数据。默认为 `false`，表示返回数据使用 `Result` 模型包裹 */
raw?: boolean;
/**
* 源数据字段名称或源数组数据下标索引，不设置时使用整个源数据
* ```
* 注意：
*
* - `GraphQL` 查询时应该通过此字段，指定查询返回数据源字段名称(一般情况下，应该是查询语句中的名称或别名)
* - `SQL` 查询时，如果一次性执行了多个语句，可通过此字段指定返回数据来源 `SQLRequestResultType` 。
* ```
*/
src?: string | SQLRequestResultType | number;
/** 自动合并的数据的条件，根据条件处理器从源数据中获取需要的数据来合并 */
condition?: RequestResultMerageConditionConfig | undefined;
/** 备注信息 */
remarks?: string;
}
/** 请求返回值合并条件枚举 */
export declare enum RequestResultMarageCondition {
/** 将源数据作为一个对象数组，从此数组中选择1个匹配的数据项，参数：`数组对象字段名`, `当前数据字段名` */
GetObjectArrayItem = "get_object_array_item"
}
/** 请求返回数据自动合并数据条件配置 */
export declare class RequestResultMerageConditionConfig {
/** 过滤器类型 */
type: RequestResultMarageCondition;
/** 源数据字段名称，不设置时使用整个源数据 */
src?: string;
/** 过滤器参数 */
args?: any[] | undefined;
}
/** 请求返回字段配置 */
export declare class RequestResultFiled {
/** 字段名称 */
name: string;
/**
* api 数据源索引号或 `RequestResultValue` 枚举值（如果不指定时，如果是在数组中，则使用当前数据的数据）。
* SQL 查询时的数据来源类型，不指定时默认使用当前数据
*/
api?: RequestResultValue | SQLRequestResultType | number | string;
/** 源字段名称，不设置时使用 `name`（如果使用小驼峰转换，则不区分大小写） */
src?: string;
/** 是否是整个源数据（不设置 `src` 时有效） */
all_src?: boolean;
/** 字段类型，存在 `children` 时默认为 `object`, 否则默认 `string` */
type?: RequestParamType;
/** 是否是数组, 默认 `false` */
array?: boolean | number;
/**
* 转换器
* ```
* 提示：ValueFilter 转换器可用于过滤数组
* ```
*/
convert?: RequestResultConvert | undefined;
/** 转换器参数 */
convert_param?: any[] | undefined;
/** 默认值 */
default?: any;
/** 备注信息 */
remarks?: string;
/** 返回示例 */
demo?: any;
/** 是否必须, 默认 `true` */
must?: boolean;
/** 子级请求返回配置, api = -3 时有效, 不传则使用父级配置 */
children?: RequestResultConfig | undefined;
}
/** SQL 字段自定义选项 */
export declare class SQLFieldRequestOptions {
/** 是否是主键，默认 `false` */
primary?: boolean;
/** 是否允许更新，默认 `true` */
updated?: boolean;
/** 是否允许插入，默认 `true` */
inserted?: boolean;
/** 是否允许查询, 默认 `true` */
query?: boolean;
/** 是否存在默认值，默认 `false` */
default?: boolean;
/** 是否允许使用累加的方式更新值, 默认 `false` */
accumulation?: boolean;
/** 别名，默认 `undefined` */
axios?: string;
}
declare type SQLField = string;
/** 请求配置 */
export declare class RequestConfig {
/** 是否使用小驼峰转换返回数据, `true` 或 `1` 时使用小驼峰, (默认 `true` ) */
hump?: boolean | number;
/** 是否自动合并请求参数的字段, `true` 或 `1` 时自动合并所有字段, (默认 `false`) */
merage?: boolean | number;
/** 是否将请求参数指定的字段认为是需要排除的字段, `true` 或 `1` 时需要排除, (默认 `false`) */
exclude?: boolean | number;
}
/** ExecuteWrapper 请求配置 */
export declare class ExecuteWrapperRequestConfig extends RequestConfig {
/** 要执行的 Wrapper 名称（需要先注册） */
wrapper: string;
/** 指定 Wrapper 要执行的的函数名称, 必须完全一致 */
func: string;
/** 参数列表 */
args?: RequestItemArgs[];
}
/** GraphWrapper 请求配置, 使用 GraphQL 查询时，`apis` 默认为 `API_Graphql_Execute`, 要自定义则必须是 `string` */
export declare class GraphWrapperRequestConfig extends RequestConfig {
/** 要执行的 GraphQL 查询名称 */
name: string;
/** 指定 GraphQL 要执行的的查询语句 */
query: string;
/** 指定 GraphQL 要执行的操作名称 */
operationName?: string;
/** 参数列表，必须与 `query` 语句中用到的变量相对应 */
args?: RequestItemArgs[];
/** 是否直接返回源数据，默认为 `true`, 不会根据 `resp` 中的配置解析返回数据 */
raw?: boolean | number;
}
/** SQL 请求配置, 会将所以配置项生成 sql 后一起执行 （如果接口设置了 `resp`，最终响应数据可以受 `resp` 影响，否则会返回完整的执行结果） */
export declare class SQLWrapperRequestConfig extends RequestConfig {
/** 数据库配置名称, 默认使用系统当前数据库配置。当配置了多个数据库时，可通过此值指定数据库配置名称 */
db?: string;
/** 完整的 SQL 查询语句，不会空会直接执行 */
sql?: string;
/** 参数值数组，会按顺序替代 `sql` 语句中的 `?` */
args?: any[];
/** 是否开启事务，默认为 `false` */
transaction?: boolean | number;
/** 删除 */
delete?: {
/** 表名称，动态生成SQL语句时必须指定 */
table: string;
/** 条件语句, 会跟在 `where` 后面。 设置了 `id` 时无效 */
where?: string;
/** 根据ID来删除数据, 未设置 where 语句时有效 */
id?: {
/** ID 字段名称 */
field: string;
/** ID 列表 */
id: string | string[];
};
/** 参数值数组 */
args?: any[];
};
/** 插入 */
insert?: {
/** 表名称，动态生成SQL语句时必须指定 */
table: string;
/** 数据对象, 示例：`{id: 0, name: ''}` (为数组时会批量插入) */
value: Record<string, any> | Record<string, any>[];
/** 字段自定义选项 */
options?: Record<SQLField, SQLFieldRequestOptions>;
};
/** 更新 */
update?: {
/** 表名称，动态生成SQL语句时必须指定 */
table: string;
/** 数据对象, 示例：`{id: 0, name: ''}` */
value: Record<string, any>;
/** 条件语句, 会跟在 `where` 后面 */
where?: string;
/** 更新操作类型, 默认 (覆盖 即用新的值覆盖调原有值) `1`,
* 可设置为 `2` 累加 （需要设置使用累加模式的字段名称列表）
**/
operatorType?: 1 | 2;
/** 参数值数组 */
args?: any[];
/** 字段自定义选项 */
options?: Record<SQLField, SQLFieldRequestOptions>;
};
/** 插入或更新 */
insertUpdate?: {
/** 表名称，动态生成SQL语句时必须指定 */
table: string;
/** 数据对象, 示例：`{id: 0, name: ''}` (为数组时会批量插入或更新) */
value: Record<string, any> | Record<string, any>[];
/** 更新操作类型, 默认 (覆盖 即用新的值覆盖调原有值) `1`,
* 可设置为 `2` 累加 （需要设置使用累加模式的字段名称列表）
**/
operatorType?: 1 | 2;
/** 字段自定义选项 */
options?: Record<SQLField, SQLFieldRequestOptions>;
};
/** 查询 */
query?: {
/** 表名称，动态生成SQL语句时必须指定 */
table: string;
/** 数据字段或模型 (推荐使用模型)，多个字段以 `,` 分隔，示例： `"id, name"` 或 `{id: 0, name: ''}`，如果不指定，则会返回所有字段 */
fields?: string | Record<string, any>;
/** 条件语句, 会跟在 `where` 后面 */
where?: string;
/** 表的别名。一般存在 join 语句时需要用到 */
alias?: string;
/** Join SQL 语句 */
joinSql?: string;
/** 附加的字段信息 */
extFields?: string;
/** 页码 */
page?: number;
/** 分页大小 */
pageSize?: number;
/** 参数值数组 */
args?: any[];
/** 是否需要返回总行数信息，默认为 `false`。设置为 `true` 时会自动生成统计总行数的 SQL，也可以设置一个自定义的统计总行数的 SQL 字符串。
* 当需要获取总行数量， 响应数据会从数组变成 `{page: ${当前页码}, total: ${数据总数}, totalPage: ${总页数}, items: [] }` */
total?: boolean | string;
};
}
export {};