@hydrooj/framework 装饰器与验证器

用于路由处理方法的参数绑定装饰器和类型验证器。

import { param, query, post, route, Types } from 'hydrooj';

参数装饰器

将处理方法的参数绑定到特定请求源的装饰器。它们在将值传递给方法之前进行提取、验证和转换。

装饰器	来源	说明
param	全部（query + body）	从合并后的请求参数中绑定参数。
query	查询字符串	从 request.query 绑定参数（GET 参数）。
get	查询字符串	query 的别名。
post	请求体	从 request.body 绑定参数（POST body）。
route	路由参数	从路由路径参数及 domainId 绑定参数。
subscribe	—	将方法（或类）注册为指定频道名的 WebSocket 订阅处理器。

用法

每个参数装饰器接受 (name: string, type?: Type, ...options)：

class MyHandler extends Handler {
    @param('name', Types.ShortString)
    @param('page', Types.PositiveInt, true)       // 可选
    @param('tags', Types.CommaSeperatedArray)
    async run(name: string, page: number | undefined, tags: string[]) { }
}

签名

(name: string, type: Type, validate?: Validator | null, convert?: Converter) => MethodDecorator
(name: string, type?: Type, isOptional?: boolean, validate?: Validator, convert?: Converter) => MethodDecorator

Type 可以是 Schemastery schema 或元组 [convert, validate?, isOptional?]。

类型验证器 — Types

预置的类型定义，组合了转换器和验证器。每个都是 Type<T>，可用作任何参数装饰器的第二个参数。

字符串类型

名称	输出	说明
Types.Content	string	多行文本内容（去除首尾空格，最长 65535 字符）。
Types.Key	string	标识符键（/^[\w-]{1,255}$/，SASLprep）。
Types.Name	string	通用名称字段（1–255 字符，SASLprep）。@deprecated
Types.Username	string	用户名（3–31 字符或 2 个 CJK 字符，SASLprep）。
Types.Password	string	密码字符串（6–255 字符）。
Types.UidOrName	string	用户 ID（数字）或用户名（3–31 字符或 2 个 CJK 字符，SASLprep）。
Types.Email	string	邮箱地址（user@domain.tld，SASLprep）。
Types.Filename	string	文件名（1–255 字符，不含 `/?#~!
Types.DomainId	string	域标识符（字母开头，4–32 个 \w 字符，SASLprep）。
Types.ProblemId	string | number	题目 ID —— 数字字符串自动转换为 number。
Types.Role	string	角色名（1–31 个 \w 或 CJK 字符，SASLprep）。
Types.Title	string	短标题（1–64 字符，去除首尾空格）。
Types.ShortString	string	短字符串（1–255 字符）。
Types.String	string	任意非空字符串。
Types.Emoji	string	单个 emoji 字符。

数值类型

名称	输出	说明
Types.Int	number	有符号整数（从字符串转换）。
Types.UnsignedInt	number	非负整数（允许零）。
Types.PositiveInt	number	正整数（≥ 1）。
Types.Float	number	有限浮点数（从字符串转换）。

特殊类型

名称	输出	说明
Types.ObjectId	ObjectId	MongoDB ObjectId（通过 ObjectId.isValid 验证）。
Types.Boolean	boolean	布尔值 —— 除 'false'/'off'/'no'/'0' 外的值为真；始终可选。
Types.Date	string	YYYY-MM-DD 格式的日期字符串（零填充）。
Types.Time	string	HH:MM 格式的时间字符串（零填充）。

组合类型

名称	输出	说明
Types.Range(arr | obj)	T	接受给定数组或对象键中的任意值；数字字符串自动转换为 number。
Types.NumericArray	number[]	有限数字数组（逗号分隔字符串或 JSON 数组）。
Types.CommaSeperatedArray	string[]	以逗号分隔的字符串数组。
Types.Set	Set<any>	将数组或单个值转换为 Set。
Types.Any	any	透传，不做验证。
Types.ArrayOf(type, isOptional?)	T[]	将任意 Type<T> 包装为数组变体；可选元素变为 undefined。
Types.AnyOf(...types)	T	联合类型 —— 接受匹配给定类型中任意一个的值。

工具类型

重新导出的 TypeScript 类型，用于构建自定义验证器：

类型	说明
Converter<T>	(value: any) => T —— 将原始输入转换为类型化输出。
Validator	(value: any) => boolean —— 值有效时返回 true。
Type<T>	Schema<T> | readonly [Converter<T>, Validator?, (boolean | 'convert')?] —— Schemastery schema 或 [convert, validate?, optional?] 元组。