docs: clarify validator usage in services

rockyshi1993 · rockyshi1993 · commit 57dcb3ee8e33 · 2026-06-02T13:37:54.000+08:00
diff --git a/website/docs/api/app.md b/website/docs/api/app.md
@@ -589,22 +589,38 @@ import { z } from "zod";
 export default definePlugin({
   name: "zod-validator",
   setup(app) {
+    const originalValidator = app.getValidator();
+
     app.setValidator({
       compile(schema) {
-        const zodSchema = z.object(schema);
-        return (data) => {
-          const result = zodSchema.safeParse(data);
-          if (result.success) {
-            return { valid: true, data: result.data };
+        const toVextResult = (result: ReturnType<z.ZodType["safeParse"]>) =>
+          result.success
+            ? { valid: true, data: result.data }
+            : {
+                valid: false,
+                errors: result.error.issues.map((issue) => ({
+                  field: issue.path.join("."),
+                  message: issue.message,
+                })),
+              };
+
+        if (schema instanceof z.ZodType) {
+          return (data) => toVextResult(schema.safeParse(data));
+        }
+
+        const zodShape: Record<string, z.ZodType> = {};
+        for (const [key, value] of Object.entries(schema)) {
+          if (value instanceof z.ZodType) {
+            zodShape[key] = value;
           }
-          return {
-            valid: false,
-            errors: result.error.issues.map((issue) => ({
-              field: issue.path.join("."),
-              message: issue.message,
-            })),
-          };
-        };
+        }
+
+        if (Object.keys(zodShape).length > 0) {
+          const zodSchema = z.object(zodShape);
+          return (data) => toVextResult(zodSchema.safeParse(data));
+        }
+
+        return originalValidator.compile(schema);
       },
     });
   },
@@ -615,19 +631,46 @@ export default definePlugin({
 
 #### `app.getValidator()`
 
-获取当前校验引擎实例。
+获取当前全局校验引擎实例。
 
 ```typescript
 getValidator(): VextValidator;
 ```
 
+默认 validator 基于 schema-dsl 实现。插件可以通过 `app.setValidator()` 将其替换为 Zod、Yup 等实现，因此 `getValidator()` 不等同于固定的 schema-dsl，而是始终返回当前生效的 validator。
+
 ```typescript
 const validator = app.getValidator();
 const validate = validator.compile({ name: "string:1-50" });
 const result = validate({ name: "Alice" });
 // { valid: true, data: { name: 'Alice' } }
 ```
 
+service 中处理非 HTTP 输入时也可以复用它：
+
+```typescript
+import { VextValidationError, type VextApp, type VextValidator } from "vextjs";
+
+export default class UserService {
+  private validateCreateUser: ReturnType<VextValidator["compile"]>;
+
+  constructor(private app: VextApp) {
+    this.validateCreateUser = app.getValidator().compile({
+      name: "string:1-50!",
+      email: "email!",
+    });
+  }
+
+  async createFromMessage(input: unknown) {
+    const result = this.validateCreateUser(input);
+    if (!result.valid) {
+      throw new VextValidationError(result.errors ?? []);
+    }
+    return result.data;
+  }
+}
+```
+
 ---
 
 #### `app.setThrow(wrapper)`
diff --git a/website/docs/examples/zod-validation.md b/website/docs/examples/zod-validation.md
@@ -52,17 +52,17 @@ pnpm add zod
 ```typescript
 // src/plugins/zod-validator.ts
 import { definePlugin } from "vextjs";
-import { ZodType, ZodError } from "zod";
+import { z, ZodType } from "zod";
 
 /**
  * Zod 校验插件
  *
- * 替换内置 schema-dsl 校验引擎，使路由 validate 配置支持 Zod schema。
+ * 替换内置 schema-dsl 校验引擎，使路由 validate 配置支持字段级 Zod schema。
  *
  * 使用方式：
  *   validate: {
- *     body: userCreateSchema,   // 直接传入 Zod schema 对象
- *     query: paginationSchema,
+ *     body: userCreateSchema.shape,   // 字段级 Zod schema 对象
+ *     query: paginationSchema.shape,
  *   }
  *
  * 校验流程：
@@ -114,15 +114,14 @@ export default definePlugin({
         //
         // 支持 validate: { body: { name: z.string(), age: z.number() } }
         // 这种「对象字段为 Zod」的混合模式。
-        // 但更推荐直接传入完整的 z.object({...}) 作为 schema。
+        // 这种写法与 RouteOptions.validate 的公开类型保持一致。
 
         const hasZodFields = Object.values(schema).some(
           (v) => v instanceof ZodType,
         );
 
         if (hasZodFields) {
           // 将散落的 Zod 字段收集为 z.object
-          const { z } = require("zod");
           const shape: Record<string, ZodType> = {};
 
           for (const [key, value] of Object.entries(schema)) {
@@ -889,8 +888,8 @@ app.post(
   "/users",
   {
     validate: {
-      body: createUserBody, // ← Zod schema
-      query: paginationQuery, // ← Zod schema
+      body: createUserBody.shape, // ← 字段级 Zod schema
+      query: paginationQuery.shape, // ← 字段级 Zod schema
     },
   },
   handler,
@@ -910,7 +909,7 @@ app.get(
 );
 ```
 
-插件内部会自动检测 schema 类型，Zod 实例走 Zod 校验路径，普通对象走 schema-dsl 路径。
+插件内部会自动检测 schema 类型：字段值为 Zod 实例时走 Zod 校验路径，普通 schema-dsl 对象走默认校验路径。
 
 ## 关键对比
 
diff --git a/website/docs/guide/plugins.md b/website/docs/guide/plugins.md
@@ -214,19 +214,47 @@ export default definePlugin({
 ```typescript
 import { definePlugin } from "vextjs";
 import type { VextValidator } from "vextjs";
+import { z } from "zod";
 
 export default definePlugin({
   name: "zod-validator",
 
   setup(app) {
+    const originalValidator = app.getValidator();
+
     const zodValidator: VextValidator = {
-      validate(schema, data) {
-        // Zod 校验逻辑...
-        return { valid: true, data };
-      },
-      toJSONSchema(schema) {
-        // 转换为 JSON Schema（供 OpenAPI 使用）
-        return {};
+      compile(schema) {
+        const toVextResult = (result: ReturnType<z.ZodType["safeParse"]>) =>
+          result.success
+            ? { valid: true, data: result.data }
+            : {
+                valid: false,
+                errors: result.error.issues.map((issue) => ({
+                  field: issue.path.join("."),
+                  message: issue.message,
+                })),
+              };
+
+        // 如果整个 location schema 是 Zod schema，直接执行 safeParse
+        if (schema instanceof z.ZodType) {
+          return (data) => toVextResult(schema.safeParse(data));
+        }
+
+        // 如果 schema 对象的字段是 Zod schema，将其组合为 z.object
+        const zodShape: Record<string, z.ZodType> = {};
+        for (const [key, value] of Object.entries(schema)) {
+          if (value instanceof z.ZodType) {
+            zodShape[key] = value;
+          }
+        }
+
+        if (Object.keys(zodShape).length > 0) {
+          const zodSchema = z.object(zodShape);
+          return (data) => toVextResult(zodSchema.safeParse(data));
+        }
+
+        // 非 Zod schema 回退到默认 schema-dsl validator
+        return originalValidator.compile(schema);
       },
     };
 
diff --git a/website/docs/guide/services.md b/website/docs/guide/services.md
@@ -233,7 +233,7 @@ export default class OrderService {
 }
 ```
 
-:::warning 避免循环依赖
+::::warning 避免循环依赖
 `service-loader` 内置循环依赖检测。如果 `ServiceA` 和 `ServiceB` 相互依赖，框架会在启动时报错。
 
 **✅ 正确做法** — 在方法中延迟访问：
@@ -262,7 +262,7 @@ export default class OrderService {
 }
 ```
 
-:::
+::::
 
 ## 使用插件提供的能力
 
@@ -303,7 +303,7 @@ export default class UserService {
 }
 ```
 
-:::tip 类型提示
+::::tip 类型提示
 使用 `declare module` 扩展 `VextApp` 接口可获得完整的类型提示：
 
 ```typescript
@@ -319,7 +319,7 @@ declare module "vextjs" {
 ```
 
 扩展后 `this.app.cache` 即可获得 IDE 自动补全。
-:::
+::::
 
 ## 使用 `app.throw()` 抛出错误
 
@@ -357,6 +357,52 @@ export default class UserService {
 }
 ```
 
+## 在服务中校验非 HTTP 输入
+
+路由入口参数优先通过 `RouteOptions.validate` 声明，并在 handler 中使用 `req.valid()` 读取校验后的数据。对于 service 直接处理的非 HTTP 输入，例如定时任务、消息队列、外部回调或其他 service 调用，可以通过 `this.app.getValidator()` 复用当前全局校验引擎。
+
+`getValidator()` 默认返回基于 schema-dsl 的 validator；如果插件通过 `app.setValidator()` 替换为 Zod、Yup 等实现，service 中获取到的也是替换后的 validator。
+
+```typescript
+import { VextValidationError, type VextApp, type VextValidator } from "vextjs";
+
+const createUserSchema = {
+  name: "string:1-50!",
+  email: "email!",
+};
+
+export default class UserService {
+  private validateCreateUser: ReturnType<VextValidator["compile"]>;
+
+  constructor(private app: VextApp) {
+    const validator = app.getValidator();
+    this.validateCreateUser = validator.compile(createUserSchema);
+  }
+
+  async createFromJob(input: unknown) {
+    const result = this.validateCreateUser(input);
+
+    if (!result.valid) {
+      throw new VextValidationError(result.errors ?? []);
+    }
+
+    const data = result.data as { name: string; email: string };
+    return this.create(data);
+  }
+
+  async create(data: { name: string; email: string }) {
+    // 创建逻辑...
+    return { id: crypto.randomUUID(), ...data };
+  }
+}
+```
+
+::::tip
+
+不要在 service 中直接 `import "schema-dsl"`。直接引用 schema-dsl 会绕过 `app.setValidator()` 的全局替换能力，导致 service 校验与路由校验使用不同引擎。
+
+::::
+
 ## 使用 `app.logger` 记录日志
 
 服务层推荐通过 `this.app.logger` 记录结构化日志。日志自动携带 requestId（通过 AsyncLocalStorage 上下文传播）：
diff --git a/website/docs/guide/validation.md b/website/docs/guide/validation.md
