koatty_validation 1.6.0 → 1.6.3

package/.turbo/turbo-build.log

@@ -0,0 +1,120 @@
+
+> koatty_validation@1.6.3 build /Users/richen/Workspace/nodejs/koatty-monorepo/packages/koatty-validation
+> npm run build:js && npm run build:dts && npm run build:doc && npm run build:cp
+
+
+> koatty_validation@1.6.3 build:js
+> del-cli --force dist && npx rollup --bundleConfigAsCjs -c .rollup.config.js
+
+
+./src/index.ts → ./dist/index.js...
+(!) Unresolved dependencies
+https://rollupjs.org/troubleshooting/#warning-treating-module-as-external-dependency
+lru-cache (imported by "src/performance-cache.ts")
+reflect-metadata (imported by "src/util.ts")
+koatty_lib (imported by "src/util.ts", "src/rule.ts" and "src/decorators.ts")
+koatty_container (imported by "src/util.ts" and "src/decorators.ts")
+class-validator (imported by "src/rule.ts", "src/decorator-factory.ts" and "src/decorators.ts")
+created ./dist/index.js in 2s
+
+./src/index.ts → ./dist/index.mjs...
+(!) Unresolved dependencies
+https://rollupjs.org/troubleshooting/#warning-treating-module-as-external-dependency
+lru-cache (imported by "src/performance-cache.ts")
+reflect-metadata (imported by "src/util.ts")
+koatty_lib (imported by "src/util.ts", "src/rule.ts" and "src/decorators.ts")
+koatty_container (imported by "src/util.ts" and "src/decorators.ts")
+class-validator (imported by "src/rule.ts", "src/decorator-factory.ts" and "src/decorators.ts")
+created ./dist/index.mjs in 1.1s
+
+> koatty_validation@1.6.3 build:dts
+> del-cli --force temp && npx tsc && npx api-extractor run --local --verbose
+
+
+api-extractor 7.55.2  - https://api-extractor.com/
+
+Using configuration from ./api-extractor.json
+Analysis will use the bundled TypeScript version 5.8.2
+*** The target project appears to use TypeScript 5.9.3 which is newer than the bundled compiler engine; consider upgrading API Extractor.
+Writing: /Users/richen/Workspace/nodejs/koatty-monorepo/packages/koatty-validation/temp/koatty_validation.api.json
+Writing package typings: /Users/richen/Workspace/nodejs/koatty-monorepo/packages/koatty-validation/dist/index.d.ts
+Warning: src/error-handler.ts:185:6 - (tsdoc-undefined-tag) The TSDoc tag "@private" is not defined in this configuration
+Warning: src/performance-cache.ts:410:14 - (ae-forgotten-export) The symbol "MetadataCache" needs to be exported by the entry point index.d.ts
+Warning: src/performance-cache.ts:411:14 - (ae-forgotten-export) The symbol "ValidationCache" needs to be exported by the entry point index.d.ts
+Warning: src/performance-cache.ts:412:14 - (ae-forgotten-export) The symbol "RegexCache" needs to be exported by the entry point index.d.ts
+Warning: src/performance-cache.ts:413:14 - (ae-forgotten-export) The symbol "PerformanceMonitor" needs to be exported by the entry point index.d.ts
+Warning: src/rule.ts:28:4 - (tsdoc-undefined-tag) The TSDoc tag "@export" is not defined in this configuration
+Warning: src/rule.ts:29:17 - (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
+Warning: src/rule.ts:29:10 - (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
+Warning: src/rule.ts:29:4 - (tsdoc-undefined-tag) The TSDoc tag "@enum" is not defined in this configuration
+Warning: src/rule.ts:54:6 - (tsdoc-undefined-tag) The TSDoc tag "@static" is not defined in this configuration
+Warning: src/rule.ts:56:6 - (tsdoc-undefined-tag) The TSDoc tag "@memberof" is not defined in this configuration
+Warning: src/rule.ts:65:13 - (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}'
+Warning: src/rule.ts:66:13 - (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}'
+Warning: src/rule.ts:67:23 - (tsdoc-param-tag-with-invalid-optional-name) The @param should not include a JSDoc-style optional name; it must not be enclosed in '[ ]' brackets.
+Warning: src/rule.ts:67:13 - (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}'
+Warning: src/rule.ts:68:33 - (tsdoc-param-tag-with-invalid-optional-name) The @param should not include a JSDoc-style optional name; it must not be enclosed in '[ ]' brackets.
+Warning: src/rule.ts:68:13 - (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}'
+Warning: src/rule.ts:69:28 - (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
+Warning: src/rule.ts:69:15 - (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
+Warning: src/rule.ts:70:6 - (tsdoc-undefined-tag) The TSDoc tag "@memberof" is not defined in this configuration
+Warning: src/rule.ts:111:14 - (ae-forgotten-export) The symbol "ValidateClass" needs to be exported by the entry point index.d.ts
+Warning: src/rule.ts:116:4 - (tsdoc-undefined-tag) The TSDoc tag "@export" is not defined in this configuration
+Warning: src/rule.ts:117:17 - (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
+Warning: src/rule.ts:117:10 - (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
+Warning: src/rule.ts:117:4 - (tsdoc-undefined-tag) The TSDoc tag "@type" is not defined in this configuration
+Warning: src/rule.ts:152:64 - (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
+Warning: src/rule.ts:152:63 - (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
+Warning: src/rule.ts:339:4 - (tsdoc-undefined-tag) The TSDoc tag "@export" is not defined in this configuration
+Warning: src/types.ts:58:6 - (tsdoc-undefined-tag) The TSDoc tag "@default" is not defined in this configuration
+Warning: src/types.ts:64:6 - (tsdoc-undefined-tag) The TSDoc tag "@default" is not defined in this configuration
+Warning: src/util.ts:144:4 - (tsdoc-undefined-tag) The TSDoc tag "@export" is not defined in this configuration
+Warning: src/util.ts:145:11 - (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}'
+Warning: src/util.ts:146:11 - (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}'
+Warning: src/util.ts:147:21 - (tsdoc-param-tag-with-invalid-optional-name) The @param should not include a JSDoc-style optional name; it must not be enclosed in '[ ]' brackets.
+Warning: src/util.ts:147:11 - (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}'
+Warning: src/util.ts:226:11 - (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}'
+Warning: src/util.ts:227:11 - (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}'
+Warning: src/util.ts:228:15 - (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
+Warning: src/util.ts:228:13 - (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
+Warning: src/util.ts:252:11 - (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}'
+Warning: src/util.ts:253:11 - (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}'
+Warning: src/util.ts:254:15 - (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
+Warning: src/util.ts:254:13 - (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
+Warning: src/util.ts:323:11 - (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}'
+Warning: src/util.ts:324:11 - (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}'
+Warning: src/util.ts:325:15 - (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
+Warning: src/util.ts:325:13 - (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
+
+API Extractor completed successfully
+
+> koatty_validation@1.6.3 build:doc
+> del-cli --force docs/api && npx api-documenter markdown --input temp --output docs/api
+
+
+api-documenter 7.28.2  - https://api-extractor.com/
+
+Reading koatty_validation.api.json
+
+Deleting old output from docs/api
+Writing koatty_validation package
+Unsupported block tag: @export
+Unsupported block tag: @export
+Unsupported block tag: @enum
+Unsupported block tag: @export
+Unsupported block tag: @default
+Unsupported block tag: @default
+Unsupported block tag: @default
+Unsupported block tag: @default
+Unsupported block tag: @export
+Unsupported block tag: @type
+Unsupported block tag: @export
+Unsupported block tag: @enum
+Unsupported block tag: @export
+Unsupported block tag: @export
+Unsupported block tag: @export
+Unsupported block tag: @type
+
+> koatty_validation@1.6.3 build:cp
+> node scripts/postBuild && copyfiles package.json LICENSE README.md dist/
+

package/.turbo/turbo-test.log

@@ -0,0 +1,8 @@
+
+> koatty_validation@1.6.3 test /Users/richen/Workspace/nodejs/koatty-monorepo/packages/koatty-validation
+> npm run eslint && jest --passWithNoTests
+
+
+> koatty_validation@1.6.3 eslint
+> eslint --ext .ts,.js ./
+

package/CHANGELOG.md

@@ -1,92 +1,97 @@
 # Changelog
 
+## 1.6.3
+
+### Patch Changes
+
+- Updated dependencies
+  - koatty_lib@1.4.2
+  - koatty_container@1.17.1
+  - koatty_logger@2.3.1
+
+## 1.6.2
+
+### Patch Changes
+
+- build
+
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
-## [1.6.0](https://github.com/koatty/koatty_validation/compare/v1.5.0...v1.6.0) (2025-10-22)
+### [1.6.1](https://github.com/koatty/koatty_validation/compare/v1.6.0...v1.6.1) (2025-10-23)
 
+## [1.6.0](https://github.com/koatty/koatty_validation/compare/v1.5.0...v1.6.0) (2025-10-22)
 
 ### Features
 
-* improve validation with instance conversion and caching ([9865b93](https://github.com/koatty/koatty_validation/commit/9865b93e469a7df16fe67e0b85dab3191437b0a8))
+- improve validation with instance conversion and caching ([9865b93](https://github.com/koatty/koatty_validation/commit/9865b93e469a7df16fe67e0b85dab3191437b0a8))
 
 ## [1.5.0](https://github.com/koatty/koatty_validation/compare/v1.4.0...v1.5.0) (2025-10-22)
 
-
 ### Features
 
-* comprehensive code optimization and enhancements ([f7ac738](https://github.com/koatty/koatty_validation/commit/f7ac7381a75a12365aee2a83530a12044c5e1d44))
+- comprehensive code optimization and enhancements ([f7ac738](https://github.com/koatty/koatty_validation/commit/f7ac7381a75a12365aee2a83530a12044c5e1d44))
 
 ## [1.4.0](https://github.com/koatty/koatty_validation/compare/v1.3.2...v1.4.0) (2025-06-10)
 
-
 ### Features
 
-* add validation examples and decorator factory ([d448709](https://github.com/koatty/koatty_validation/commit/d44870987a808cd43c5a7ed5fabd5ca43162d0b6))
+- add validation examples and decorator factory ([d448709](https://github.com/koatty/koatty_validation/commit/d44870987a808cd43c5a7ed5fabd5ca43162d0b6))
 
 ### [1.3.2](https://github.com/koatty/koatty_validation/compare/v1.3.1...v1.3.2) (2024-01-14)
 
-
 ### Bug Fixes
 
-* deps ([6da3e43](https://github.com/koatty/koatty_validation/commit/6da3e437c946c9de2fc45f5319768fef0c4609b0))
+- deps ([6da3e43](https://github.com/koatty/koatty_validation/commit/6da3e437c946c9de2fc45f5319768fef0c4609b0))
 
 ### [1.3.1](https://github.com/koatty/koatty_validation/compare/v1.3.0...v1.3.1) (2024-01-07)
 
-
 ### Bug Fixes
 
-* comment ([d898cf6](https://github.com/koatty/koatty_validation/commit/d898cf68bc8693f78155b7208b419dc4b11dffb4))
-* dto赋值类型 ([5a1d68d](https://github.com/koatty/koatty_validation/commit/5a1d68dea0b67e988427c54abae9bfe76a6eaf48))
+- comment ([d898cf6](https://github.com/koatty/koatty_validation/commit/d898cf68bc8693f78155b7208b419dc4b11dffb4))
+- dto 赋值类型 ([5a1d68d](https://github.com/koatty/koatty_validation/commit/5a1d68dea0b67e988427c54abae9bfe76a6eaf48))
 
 ## [1.3.0](https://github.com/koatty/koatty_validation/compare/v1.2.10...v1.3.0) (2024-01-03)
 
-
 ### Features
 
-* 增加@CheckFunc ([d5bdc2d](https://github.com/koatty/koatty_validation/commit/d5bdc2d51cdbf6d558e376bfda51e126158d4e75))
-
+- 增加@CheckFunc ([d5bdc2d](https://github.com/koatty/koatty_validation/commit/d5bdc2d51cdbf6d558e376bfda51e126158d4e75))
 
 ### Bug Fixes
 
-* export ValidFuncs ([7d42023](https://github.com/koatty/koatty_validation/commit/7d42023138e9577c9646423c4c38faffba46fb10))
+- export ValidFuncs ([7d42023](https://github.com/koatty/koatty_validation/commit/7d42023138e9577c9646423c4c38faffba46fb10))
 
 ### [1.2.10](https://github.com/koatty/koatty_validation/compare/v1.2.9...v1.2.10) (2023-12-16)
 
-
 ### Bug Fixes
 
-* assign dto property ([2357642](https://github.com/koatty/koatty_validation/commit/2357642f6ac1479c839454d40ec4bd89f3fbd7b2))
+- assign dto property ([2357642](https://github.com/koatty/koatty_validation/commit/2357642f6ac1479c839454d40ec4bd89f3fbd7b2))
 
 ### [1.2.9](https://github.com/koatty/koatty_validation/compare/v1.2.8...v1.2.9) (2023-09-01)
 
 ### [1.2.8](https://github.com/koatty/koatty_validation/compare/v1.2.7...v1.2.8) (2023-02-17)
 
-
 ### Bug Fixes
 
-* convert type ([924449d](https://github.com/koatty/koatty_validation/commit/924449d9f5fd7b14cbe3c1532f96416e69cc4eed))
+- convert type ([924449d](https://github.com/koatty/koatty_validation/commit/924449d9f5fd7b14cbe3c1532f96416e69cc4eed))
 
 ### [1.2.7](https://github.com/koatty/koatty_validation/compare/v1.2.6...v1.2.7) (2023-02-17)
 
-
 ### Bug Fixes
 
-* add script ([ca82c14](https://github.com/koatty/koatty_validation/commit/ca82c14b0a2226024fb2c4476ba7353be7a2f65a))
-* plainToClass convert type ([06ed46e](https://github.com/koatty/koatty_validation/commit/06ed46e21ce191dc1c9f5c18ee7d029e9b6d4abf))
+- add script ([ca82c14](https://github.com/koatty/koatty_validation/commit/ca82c14b0a2226024fb2c4476ba7353be7a2f65a))
+- plainToClass convert type ([06ed46e](https://github.com/koatty/koatty_validation/commit/06ed46e21ce191dc1c9f5c18ee7d029e9b6d4abf))
 
 ### [1.2.6](https://github.com/koatty/koatty_validation/compare/v1.2.5...v1.2.6) (2023-01-09)
 
-
 ### Bug Fixes
 
-* err msg ([18632d4](https://github.com/koatty/koatty_validation/commit/18632d4c9b05b1d117be7f8170da0ce014018ab8))
+- err msg ([18632d4](https://github.com/koatty/koatty_validation/commit/18632d4c9b05b1d117be7f8170da0ce014018ab8))
 
 ### [1.2.5](https://github.com/koatty/koatty_validation/compare/v1.2.4...v1.2.5) (2022-08-19)
 
-
 ### Bug Fixes
 
-* merge ([52c65f4](https://github.com/koatty/koatty_validation/commit/52c65f41c46a02a3fc5735e6e22ee6a3ed5337f8))
+- merge ([52c65f4](https://github.com/koatty/koatty_validation/commit/52c65f41c46a02a3fc5735e6e22ee6a3ed5337f8))
 
 ### [1.2.4](https://github.com/koatty/koatty_validation/compare/v1.2.3...v1.2.4) (2022-05-27)
 

package/README.md

@@ -36,10 +36,16 @@ export class Controller {
         // 业务逻辑
     }
 
-    // DTO 验证
+    // DTO 验证 - 异步模式（默认，适用于 Koatty 框架）
     @Validated()
     TestDto(user: UserDTO) {
-        // 自动验证 UserDTO
+        // 框架会在异步获取参数后自动验证 UserDTO
+    }
+    
+    // DTO 验证 - 同步模式（适用于参数已准备好的场景）
+    @Validated(false)
+    TestDtoSync(user: UserDTO) {
+        // 方法执行前立即验证 UserDTO
     }
 }
 
@@ -101,11 +107,107 @@ export class UserDTO {
 
 ```typescript
 @Valid(rule, options)   // 参数验证
-@Validated()           // DTO验证
+@Validated()           // DTO验证 (默认异步模式)
+@Validated(true)       // DTO验证 (异步模式)
+@Validated(false)      // DTO验证 (同步模式)
 @Expose()             // 暴露属性
 @IsDefined()          // 已定义（Expose别名）
 ```
 
+## 🎭 Validated 装饰器
+
+`@Validated` 装饰器支持同步和异步两种验证模式，以适应不同的应用场景。
+
+### 异步模式（默认）
+
+适用于 **Koatty 框架**中，控制器方法的参数需要异步获取的场景。
+
+```typescript
+import { Validated, checkValidated } from 'koatty_validation';
+
+class UserController {
+  // 默认异步模式
+  @Validated()
+  async register(user: UserDTO) {
+    // 框架流程：
+    // 1. 框架接收 HTTP 请求
+    // 2. 框架异步解析请求体，构造 UserDTO 实例
+    // 3. 框架检测到 @Validated() 元数据
+    // 4. 框架调用 checkValidated() 验证参数
+    // 5. 验证通过后调用此方法
+    return { success: true };
+  }
+  
+  // 显式指定异步模式
+  @Validated(true)
+  async update(id: number, user: UserDTO) {
+    return { success: true };
+  }
+}
+```
+
+**异步模式特点：**
+- ✅ 装饰器保存验证元数据到 IOC 容器
+- ✅ 由框架在异步获取参数后执行验证
+- ✅ 适用于参数值需要异步获取的场景
+- ✅ 是 Koatty 框架的推荐模式
+
+### 同步模式
+
+适用于**单元测试**或参数值已经准备好的场景。
+
+```typescript
+class UserService {
+  // 同步模式 - 立即验证
+  @Validated(false)
+  async createUser(user: UserDTO) {
+    // 方法执行前已经完成验证
+    return { success: true };
+  }
+  
+  // 适用于多个参数的场景
+  @Validated(false)
+  async updateUser(id: number, user: UserDTO) {
+    // 只验证类类型参数（UserDTO），基础类型（number）不验证
+    return { success: true };
+  }
+}
+```
+
+**同步模式特点：**
+- ✅ 装饰器包装原方法，在调用时立即执行验证
+- ✅ 适用于单元测试场景
+- ✅ 适用于参数已准备好的场景
+- ✅ 验证失败立即抛出错误
+
+### 手动调用 checkValidated
+
+在框架拦截器或中间件中，可以手动调用 `checkValidated` 函数：
+
+```typescript
+import { checkValidated } from 'koatty_validation';
+
+async function validateInMiddleware(args: any[], paramTypes: any[]) {
+  try {
+    const { validatedArgs, validationTargets } = await checkValidated(args, paramTypes);
+    console.log('验证通过');
+    return validationTargets;
+  } catch (error) {
+    console.error('验证失败:', error);
+    throw error;
+  }
+}
+```
+
+### 选择合适的模式
+
+| 场景 | 推荐模式 | 原因 |
+|------|---------|------|
+| Koatty 框架控制器 | 异步 `@Validated()` | 参数需要异步获取 |
+| 单元测试 | 同步 `@Validated(false)` | 参数已准备好，立即验证 |
+| 独立服务/工具 | 同步 `@Validated(false)` | 不依赖框架，立即验证 |
+| 框架拦截器 | 手动 `checkValidated()` | 完全控制验证时机 |
+
 ## 🔧 自定义装饰器
 
 ### 使用装饰器工厂创建自定义验证器
@@ -310,6 +412,7 @@ const validatedData = await ClassValidator.valid(UserSchema, rawData, true);
 - [基础用法示例](./examples/basic-usage.ts)
 - [自定义装饰器示例](./examples/custom-decorators-example.ts)
 - [完整使用示例](./examples/usage-example.ts)
+- [Validated 异步/同步模式示例](./examples/validated-async-sync-example.ts)
 
 ## 🔍 可用验证函数
 

package/dist/README.md

@@ -36,10 +36,16 @@ export class Controller {
         // 业务逻辑
     }
 
-    // DTO 验证
+    // DTO 验证 - 异步模式（默认，适用于 Koatty 框架）
     @Validated()
     TestDto(user: UserDTO) {
-        // 自动验证 UserDTO
+        // 框架会在异步获取参数后自动验证 UserDTO
+    }
+    
+    // DTO 验证 - 同步模式（适用于参数已准备好的场景）
+    @Validated(false)
+    TestDtoSync(user: UserDTO) {
+        // 方法执行前立即验证 UserDTO
     }
 }
 
@@ -101,11 +107,107 @@ export class UserDTO {
 
 ```typescript
 @Valid(rule, options)   // 参数验证
-@Validated()           // DTO验证
+@Validated()           // DTO验证 (默认异步模式)
+@Validated(true)       // DTO验证 (异步模式)
+@Validated(false)      // DTO验证 (同步模式)
 @Expose()             // 暴露属性
 @IsDefined()          // 已定义（Expose别名）
 ```
 
+## 🎭 Validated 装饰器
+
+`@Validated` 装饰器支持同步和异步两种验证模式，以适应不同的应用场景。
+
+### 异步模式（默认）
+
+适用于 **Koatty 框架**中，控制器方法的参数需要异步获取的场景。
+
+```typescript
+import { Validated, checkValidated } from 'koatty_validation';
+
+class UserController {
+  // 默认异步模式
+  @Validated()
+  async register(user: UserDTO) {
+    // 框架流程：
+    // 1. 框架接收 HTTP 请求
+    // 2. 框架异步解析请求体，构造 UserDTO 实例
+    // 3. 框架检测到 @Validated() 元数据
+    // 4. 框架调用 checkValidated() 验证参数
+    // 5. 验证通过后调用此方法
+    return { success: true };
+  }
+  
+  // 显式指定异步模式
+  @Validated(true)
+  async update(id: number, user: UserDTO) {
+    return { success: true };
+  }
+}
+```
+
+**异步模式特点：**
+- ✅ 装饰器保存验证元数据到 IOC 容器
+- ✅ 由框架在异步获取参数后执行验证
+- ✅ 适用于参数值需要异步获取的场景
+- ✅ 是 Koatty 框架的推荐模式
+
+### 同步模式
+
+适用于**单元测试**或参数值已经准备好的场景。
+
+```typescript
+class UserService {
+  // 同步模式 - 立即验证
+  @Validated(false)
+  async createUser(user: UserDTO) {
+    // 方法执行前已经完成验证
+    return { success: true };
+  }
+  
+  // 适用于多个参数的场景
+  @Validated(false)
+  async updateUser(id: number, user: UserDTO) {
+    // 只验证类类型参数（UserDTO），基础类型（number）不验证
+    return { success: true };
+  }
+}
+```
+
+**同步模式特点：**
+- ✅ 装饰器包装原方法，在调用时立即执行验证
+- ✅ 适用于单元测试场景
+- ✅ 适用于参数已准备好的场景
+- ✅ 验证失败立即抛出错误
+
+### 手动调用 checkValidated
+
+在框架拦截器或中间件中，可以手动调用 `checkValidated` 函数：
+
+```typescript
+import { checkValidated } from 'koatty_validation';
+
+async function validateInMiddleware(args: any[], paramTypes: any[]) {
+  try {
+    const { validatedArgs, validationTargets } = await checkValidated(args, paramTypes);
+    console.log('验证通过');
+    return validationTargets;
+  } catch (error) {
+    console.error('验证失败:', error);
+    throw error;
+  }
+}
+```
+
+### 选择合适的模式
+
+| 场景 | 推荐模式 | 原因 |
+|------|---------|------|
+| Koatty 框架控制器 | 异步 `@Validated()` | 参数需要异步获取 |
+| 单元测试 | 同步 `@Validated(false)` | 参数已准备好，立即验证 |
+| 独立服务/工具 | 同步 `@Validated(false)` | 不依赖框架，立即验证 |
+| 框架拦截器 | 手动 `checkValidated()` | 完全控制验证时机 |
+
 ## 🔧 自定义装饰器
 
 ### 使用装饰器工厂创建自定义验证器
@@ -310,6 +412,7 @@ const validatedData = await ClassValidator.valid(UserSchema, rawData, true);
 - [基础用法示例](./examples/basic-usage.ts)
 - [自定义装饰器示例](./examples/custom-decorators-example.ts)
 - [完整使用示例](./examples/usage-example.ts)
+- [Validated 异步/同步模式示例](./examples/validated-async-sync-example.ts)
 
 ## 🔍 可用验证函数