# @decaf-ts/decorator-validation 中文文档

规范地址：https://npmcn.com/package/%40decaf-ts/decorator-validation/

版本：1\.24\.3
npm 元数据更新时间：2026-11-12T15:21:27.536Z
中文译文更新时间：2026-11-13T05:20:13.342Z
软件包许可：MPL-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40decaf-ts/decorator-validation
原文对照：https://npmcn.com/package/%40decaf-ts/decorator-validation/?lang=original
项目主页：https://github.com/decaf-ts/decorator-validation#readme
源码仓库：https://github.com/decaf-ts/decorator-validation

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.5 MB，398 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：1 个
- 首次发布：2024-03-11T21:59:54.199Z
- 最新版本发布：2026-11-12T15:21:27.055Z
- 近 30 天下载量：2207（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：146（近 12 个月 51 个）

## 中文简介

简单的基于装饰器的验证引擎

## 安装

```sh
npm install @decaf-ts/decorator-validation
```

也可以使用：`pnpm add @decaf-ts/decorator-validation`、`yarn add @decaf-ts/decorator-validation`、`bun add @decaf-ts/decorator-validation`

## README

![Banner](https://npmcn.com/package/%40decaf-ts/decorator-validation/workdocs/assets/decaf-logo.svg)

# 装饰者验证

一个由TypeScript装饰器驱动的验证和模型框架. 它让你:

-   在模型属性(如:@required,@min,@pattern)上用声明式装饰来定义验证规则.
-   以可插入的注册和算法构建、验证、序列化和散列模型.
-   通过审定人类别和公用事业登记处扩大审定.
-   可选地将验证暴露为自动化工作流程的MCP工具.

> 2025-11-26. 发布docs刷新. 见 [工作文件/报告/报告](https://npmcn.com/package/%40decaf-ts/decorator-validation/workdocs/reports/RELEASE_NOTES.md) 罚单摘要.

### 核心概念

-   **`@model()`**:一个将普通类转变为可有效模型的类装饰.
-   **认证**:用于定义属性验证规则的一套丰富的装饰(例如, `@required`, (中文(简体) ), `@email`, (中文(简体) ), `@minLength`) (中文(简体) ).
-   **`Model` 类**:一个抽象的基础类,提供验证,序列化,散列,和比较方法.
-   **`Validation` 类**:用于管理验证器注册并创建自定义验证逻辑的静态类.
-   **构建者和注册者**: 用于控制模型构造、序列化和散列的可插件系统.

![Licence](https://img.shields.io/github/license/decaf-ts/decorator-validation.svg?style=plastic) ![GitHub language count](https://img.shields.io/github/languages/count/decaf-ts/decorator-validation?style=plastic) ![GitHub top language](https://img.shields.io/github/languages/top/decaf-ts/decorator-validation?style=plastic)

[![Build & Test](https://github.com/decaf-ts/decorator-validation/actions/workflows/nodejs-build-prod.yaml/badge.svg)](https://github.com/decaf-ts/decorator-validation/actions/workflows/nodejs-build-prod.yaml) [![CodeQL](https://github.com/decaf-ts/decorator-validation/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/decaf-ts/decorator-validation/actions/workflows/codeql-analysis.yml)[![Snyk Analysis](https://github.com/decaf-ts/decorator-validation/actions/workflows/snyk-analysis.yaml/badge.svg)](https://github.com/decaf-ts/decorator-validation/actions/workflows/snyk-analysis.yaml) [![Pages builder](https://github.com/decaf-ts/decorator-validation/actions/workflows/pages.yaml/badge.svg)](https://github.com/decaf-ts/decorator-validation/actions/workflows/pages.yaml) [![.github/workflows/release-on-tag.yaml](https://github.com/decaf-ts/decorator-validation/actions/workflows/release-on-tag.yaml/badge.svg?event=release)](https://github.com/decaf-ts/decorator-validation/actions/workflows/release-on-tag.yaml)

![Open Issues](https://img.shields.io/github/issues/decaf-ts/decorator-validation.svg) ![Closed Issues](https://img.shields.io/github/issues-closed/decaf-ts/decorator-validation.svg) ![Pull Requests](https://img.shields.io/github/issues-pr-closed/decaf-ts/decorator-validation.svg) ![Maintained](https://img.shields.io/badge/Maintained%3F-yes-green.svg)

![Forks](https://img.shields.io/github/forks/decaf-ts/decorator-validation.svg) ![Stars](https://img.shields.io/github/stars/decaf-ts/decorator-validation.svg) ![Watchers](https://img.shields.io/github/watchers/decaf-ts/decorator-validation.svg)

![Node Version](https://img.shields.io/badge/dynamic/json.svg?url=https%3A%2F%2Fraw.githubusercontent.com%2Fbadges%2Fshields%2Fmaster%2Fpackage.json&label=Node&query=$.engines.node&colorB=blue) ![NPM Version](https://img.shields.io/badge/dynamic/json.svg?url=https%3A%2F%2Fraw.githubusercontent.com%2Fbadges%2Fshields%2Fmaster%2Fpackage.json&label=NPM&query=$.engines.npm&colorB=purple)

现有文件 [这里](https://decaf-ts.github.io/decorator-validation/)

最小大小: 14.5 KB kb gziped

# 装饰者验证 - 详细描述

装饰者验证是一个TypeScript库,以两个互补的支柱为中心:

1.  通过装饰器进行声明验证

-   一些丰富的地产装饰者,如:@required,@min,@max,@minLength,@maxLength,@pattern,@email,@url,@type,@equers,@greaterThanOrEqual,@lessThan,@lessThanOrEqual,@step,@list,@diff,@date,@password,以及aync ()旗下帮助者.
-   每个装饰者使用反射-元数据以及共同的验证元数据密钥惯例来写出强烈类型的元数据,因此验证者日后可以一致地解释规则.
-   装饰器在src/validation/decorers.ts中被定义,并辅以执行实际验证逻辑的src/validation/Validers/\*中混凝土验证器类.

2.  适合审定、建造、散列和系列化的模型系统

-   模型是用@model () (src/model/decorator.ts)来标记的普通类. 装饰器取代了构造器,将模型原型公用事业捆绑起来,运行一个全球构造器(如果注册),并给反射元数据作标记以识别.
-   额外的类级装饰器配置算法 :
    -   @hashedBy (algorithm,. args) 定义模型散列执行.
    -   @serializedBy( 序列器, ...args) 定义序列化策略 .
    -   @description(text)将人可读文档附加到一个类,属性,或方法.
-   示范类(src/model/Model.ts)规定:
    -   用于按名称登记和检索模型构造器的模型登记管理器,能够重建/消除流动.
    -   验证集成(model/validation.ts),运行已注册验证器与装饰器所收集的元数据相对抗.
    -   利用方法和元数据帮助确定模型、获取元数据、比较实例并协调散列/序列化战略.

核心运行时架构

-   验证命名空间(弧/验证/Validation.ts):
    -   管理一个可插件的 IValidator Registry, 这样可以注册、 迁移和询问自定义验证器执行 .
    -   曝光辅助工具: 校验. key( ) 用于反射- metata keying, 校验. key( ) 用于列出可用的校验工具密钥, 注册(.)并获得(.) 用于管理校验工具, 装饰工具注册, 将元数据密钥与其装饰工具链接, 以便动态使用 .
-   校正器类(弧/验证/校正器/\*):
    -   BaseValidator.ts定义了常见的行为;具体验证器(需要的Validator,MinValidator,PattleValidator等)执行验证和消息/打字逻辑.
    -   校验器 Registry.ts 存储由校验Keys常数键入的校验器实例 .
    -   常数.ts定义了DEFAULT ERROR MESSAGES,DEFAULT PATERNS,以及验证键(如REQUIRED,MIN,MAX.).
    -   装饰者.ts包含可直接注册标准验证器的装饰糖,并使用装饰/参考设施构建元数据.
-   公用事业(电弧/功率/\*):
    -   字符串、日期、类型、序列化、散列、登记、装饰、装饰辅助器,以及用于穿行巢穴属性和应用元数据的路径Proxy.

图书馆的意向

-   提供连贯的,装饰者-第一开发者的经验,以强制执行对模型类的验证限制.
-   确保验证、模型生命周期(构建/序列化/hash)和元数据一致并通过登记册加以推广.
-   允许高级组成(海关验证员、替代登记册)并纳入自动化流程(MCP工具).

设计原则

-   声明超越必要:限制存在于它们验证的属性旁边.
-   广泛性:注册和助手工厂允许互换执行而无需改变消费者代码.
-   类型安全:元数据与装饰器被打入;验证器对被支持的类型进行广告;公用功能在实用之处使用狭义类型.
-   关注事项的分离: 装饰者表达意向; 验证者班级实施行为; 模型提供生命周期公用事业.

# 如何使用

本指南举例说明如何利用《公约》的主要特点 `@decaf-ts/decorator-validation` 图书馆.

## 创建模式

这个 `@model()` 装饰器是创建可验证模型的切入点.

```typescript
import { model, Model } from '@decaf-ts/decorator-validation';

@model()
class User extends Model {
  // ...
}
```

## 认证

库为定义属性的验证规则提供了一套丰富的装饰.

```typescript
import { model, Model, required, email, minLength } from '@decaf-ts/decorator-validation';

@model()
class User extends Model {
  @required()
  name!: string;

  @required()
  @email()
  email!: string;

  @minLength(8)
  password!: string;
}
```

## 验证一个模型

您可以使用 `hasErrors()` 方法.

```typescript
const user = new User();
const errors = user.hasErrors();

if (errors) {
  console.log('Validation errors:', errors);
}
```

### 忽略属性

您可以在验证过程中忽略属性, 将属性名称传递给 `hasErrors()`。 。 。 .

```typescript
const user = new User();
// Ignore the 'password' property during validation
const errors = user.hasErrors('password');
```

## 串行和上行

这个 `Model` 类提供了序列化和散列实例的方法.

```typescript
const user = new User({ name: 'John Doe', email: 'john.doe@example.com' });

const serializedUser = user.serialize();
const userHash = user.hash();
```

## 模型建筑

该图书馆为构建模型实例提供了一个灵活的系统.

```typescript
import { Model } from '@decaf-ts/decorator-validation';

// Create a new instance
const user1 = new User({ name: 'Jane Doe' });

// Create an instance from a plain object
const user2 = Model.build({
  [Model.ANCHOR]: 'User',
  name: 'John Smith',
  email: 'john.smith@example.com'
});
```

## 自定义验证器

您可以通过扩展 `Validator` 并登记在 `Validation` 课.

```typescript
import { Validator, Validation, metadata } from '@decaf-ts/decorator-validation';

// 1. Create a custom validator
class MyCustomValidator extends Validator {
  constructor() {
    super('my-custom-validator', 'Invalid value');
  }

  validate(value: any): boolean {
    // Custom validation logic
    return value === 'valid';
  }
}

// 2. Register the validator
Validation.register(new MyCustomValidator());

// 3. Create a decorator for the validator
function myCustom() {
  return metadata(Validation.key('my-custom-validator'), {});
}

// 4. Use the decorator
@model()
class MyModel extends Model {
  @myCustom()
  myProp: string;
}
```

## 日期操作

图书馆包括: `DateBuilder` 用于创建和操纵日期.

```typescript
import { DateBuilder } from '@decaf-ts/decorator-validation';

const date = new DateBuilder().addDays(5).build();
```

### 相关

[![decaf-ts](https://github-readme-stats.vercel.app/api/pin/?username=decaf-ts&repo=decaf-ts)](https://github.com/decaf-ts/decaf-ts) [![Reflection](https://github-readme-stats.vercel.app/api/pin/?username=decaf-ts&repo=reflection)](https://github.com/decaf-ts/reflection)

### 社会

[![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/TiagoVenceslau/)

#### 语文

![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white) ![JavaScript](https://img.shields.io/badge/JavaScript-F7DF1E?style=for-the-badge&logo=javascript&logoColor=black) ![NodeJS](https://img.shields.io/badge/Node.js-43853D?style=for-the-badge&logo=node.js&logoColor=white) ![ShellScript](https://img.shields.io/badge/Shell_Script-121011?style=for-the-badge&logo=gnu-bash&logoColor=white)

## 获得帮助

如果您有错误报告, 请回答问题或建议 [创建一个新问题](https://github.com/decaf-ts/ts-workspace/issues/new/choose)。 。 。 .

## 捐款

我感谢对这一项目作出的任何贡献。 请阅读 [这个](https://npmcn.com/package/%40decaf-ts/decorator-validation/workdocs/98-Contributing.md) 要开始.

## 支助

第一种最简单的方法就是支持它 [捐款](https://npmcn.com/package/%40decaf-ts/decorator-validation/workdocs/98-Contributing.md). 甚至在文档中找到打字很重要.

财政支持总是受到欢迎,帮助我和该项目保持生命和健康.

所以,如果你可以, 如果这个项目以任何方式。 要么通过学习 要么只是帮助你 节省宝贵的时间, 请考虑捐赠.

## 许可证

这个项目将在 [Mozilla 公共许可证2.0](https://npmcn.com/package/%40decaf-ts/decorator-validation/LICENSE.md)。 。 。 .

由开发者为开发者...

## 常见问题

### @decaf-ts/decorator-validation 是什么？

简单的基于装饰器的验证引擎

### 如何安装 @decaf-ts/decorator-validation？

在项目目录运行 npm install @decaf-ts/decorator-validation，或使用 pnpm add / yarn add / bun add。

### @decaf-ts/decorator-validation 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @decaf-ts/decorator-validation 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @decaf-ts/decorator-validation 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @decaf-ts/decorator-validation 可以商用吗？

@decaf-ts/decorator-validation 使用 MPL-2\.0 许可。弱 Copyleft：可以商用，也可以和闭源代码一起使用；但如果分发时修改了 MPL 授权的文件，这些文件的修改需以 MPL 开源。以上为概括，不构成法律意见，请以许可原文为准。

### @decaf-ts/decorator-validation 的下载量有多少？

根据 npm 官方下载统计，@decaf-ts/decorator-validation 在 2026/10/12 – 2026/11/10 这 30 天内被下载 2,207 次，日均约 74 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @decaf-ts/decorator-validation 还在维护吗？

最新版本 1\.24\.3 发布于 2026/11/12（今天）；至今共发布 146 个版本，其中过去 12 个月发布了 51 个；首次发布于 2024/03/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。