precognition
nuxt-precognition

在 Nitro 中实现 Laravel Precognition 协议的 Nuxt 模块
529 次下载17 个星标v0.1.2
sot1986sot1986

Nuxt Precognition

npm versionnpm downloadsLicenseNuxt

Nuxt Precognition 是一个 Nuxt 验证模块，它以与后端无关的方式实现了 Precognition 协议。它支持任何后端或验证库，并且不与 Laravel 绑定。

目录

要求

  • Nuxt >= 3.x
  • Node.js >= 18

为什么选择 Nuxt Precognition？

  • 后端无关： 适用于任何支持 Precognition 协议的后端。
  • 验证库无关： 使用 Zod、Yup 或任何其他验证库。
  • 客户端和服务器端验证： 两端无缝验证。
  • 最佳 TypeScript 支持： 类型安全的表单和错误处理。
  • 高度可定制： 插入您自己的错误解析器和状态处理程序。

快速示例

interface User {
  email: string
  password: string
}

const form = useForm(
  (): User => ({ email: '', password: '' }),
  (body, headers) => $fetch('/api/login', { method: 'POST', headers, body })
)

功能

  • 符合 Laravel 规范
  • 验证库无关
  • 客户端和服务器端验证
  • 支持 TypeScript
  • 可定制的错误解析和状态处理

安装

在您的 Nuxt 应用程序中安装模块

npx nuxi module add nuxt-precognition

工作原理

核心概念是错误解析器：从抛出的错误中提取验证错误的函数。

type ValidationErrors = Record<string, string | string[]>

interface ValidationErrorsData {
  message: string
  errors: ValidationErrors
}

type ValidationErrorParser = (error: Error) => ValidationErrorsData | undefined | null

定义 Zod 错误解析器

// app/utils/precognition.ts or shared/utils/precognition.ts
import { ZodError } from 'zod'

export const zodPrecognitionErrorParser: ValidationErrorParser = (error) => {
  if (error instanceof ZodError) {
    const errors: Record<string, string[]> = {}
    for (const issue of error.issues) {
      const key = issue.path.join('.')
      if (key in errors) {
        errors[key].push(issue.message)
        continue
      }
      errors[key] = [issue.message]
    }
    return { errors, message: error.message }
  }
  return null
}

注意
对于服务器端验证，请将此文件放置在 shared/utils 文件夹中。

客户端验证

在客户端全局添加解析器。

// app/plugins/precognition.ts
export default defineNuxtPlugin(() => {
  const { $precognition } = useNuxtApp()

  $precognition.errorParsers.push(zodErrorParser)

  // ..
})

在 setup 方法中使用 composable。

const UserSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
})

const form = useForm(
  (): z.infer<typeof UserSchema> => ({
    email: '',
    password: '',
  }),
  (body, headers) => $fetch('/api/login', {
    method: 'POST',
    headers,
    body,
  }),
  {
    clientValidation(data) {
      UserSchema.parse(data)
    },
  },
)

function login() {
  form.submit()
}

function reset() {
  form.reset()
  document.getElementById('email')?.focus()
}

<form
  @submit.prevent="login"
  @reset.prevent="reset"
>
  <div>
    <label for="email">Email address</label>
    <input
      id="email"
      v-model="form.email"
      name="email"
      type="email"
      @change="form.validate('email')"
    >
    <span v-if="form.valid('email')">OK!!</span>
    <span v-if="form.invalid('email')">{{ form.errors.email }}</span>
  </div>

  <div>
    <label for="password">Password</label>
    <input
      id="password"
      v-model="form.password"
      name="password"
      type="password"
      autocomplete="current-password"
      required
      @change="form.validate('password')"
    >
    <span v-if="form.valid('password')">OK!!</span>
    <span v-if="form.invalid('password')">{{ form.errors.password }}</span>
  </div>

  <div>
    <button type="submit">Sign in</button>
    <button type="reset">Reset</button>
  </div>
</form>

服务器端验证

  1. 更新默认配置。
// nuxt.config.ts

export default defineNuxtConfig({
  modules: [
    'nuxt-precognition'
  ],
  precognition: {
    backendValidation: true, 
    enableNuxtClientErrorParser: true,
  },
})
  1. 创建一个 Nitro 插件来解析服务器错误
// server/plugins/precognition.ts
import { ZodError } from 'zod'

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('request', (event) => {
    event.context.$precognition.errorParsers = [
      zodErrorParser
    ]
  })
})
  1. 以对象方式使用 definePrecognitiveEventHandler，并在 onRequest 钩子中添加验证。
// server/api/login.post.ts
import { z } from 'zod'
import { definePrecognitiveEventHandler, readBody } from '#imports'

const loginSchema = z.object({
  email: z.string().email(),
  password: z.string()
}).refine((_data) => {
  // Check for email and password match
  // ...
  return true
},
{ message: 'invalid credentials', path: ['email'] },
)

export default definePrecognitiveEventHandler({
  async onRequest(event) {
    const body = await readBody(event)
    loginSchema.parse(body)
  },
  handler: () => {
    return {
      status: 200,
      body: {
        message: 'Success',
      },
    }
  },
})

Precognition 协议

如果您需要在 Nitro 之外定义自己的后端逻辑，请遵循以下要求。

  • Precognitive 请求必须具有
    1. Precognitive Header { 'Precognitive': 'true' }
  • 要验证特定变量，每个键必须在 ValidateOnly Header 中指定，用逗号分隔并利用点符号 { 'Precognition-Validate-Only': 'name,age,address.street,address.number' }
  • 要验证完整的表单，应省略 ValidateOnly Header 或将其定义为空字符串。
  • 成功的验证响应必须具有
    1. Precognitive Header { 'Precognitive': 'true' }
    2. Precognitive Successful Header { 'Precognition-Success': 'true' }
    3. Precognitive Successful 状态码：204
  • 错误验证响应必须具有
    1. Precognitive Header { 'Precognitive': 'true' }
    2. 如果需要，Precognition-Validate-Only header { 'Precognition-Validate-Only': 'name,age,address.street,address.number' }
    3. 验证错误状态码：422
    4. 验证错误和消息将根据您的定义逻辑解析，或使用标准 errorParsers
      • NuxtErrorParsers: NuxtPrecognitiveErrorResponse: Response & { _data: { data: ValidationErrorsData }}
      • LaravelErrorParsers: LaravelPrecognitiveErrorResponse: Response & { _data: ValidationErrorsData }

配置

添加到您的 nuxt.config.ts

export default defineNuxtConfig({
  modules: ['nuxt-precognition'],
  precognition: {
    backendValidation: true,
    enableNuxtClientErrorParser: true,
    // ...other options
  }
})

选项

name类型默认描述
validationTimeoutnumber1500两次预感知验证请求之间的去抖时间（毫秒）。
backendValidationbooleanfalse启用预感知验证的标志。
validateFilesbooleanfalse在预感知请求中启用文件验证的标志。
enableNuxtClientErrorParserbooleanfalse在客户端（在 form.validate 和 form.submit 中）启用 nuxtErrorParsers 的标志。
enableLaravelClientErrorParserbooleanfalse在客户端（在 form.validate 和 form.submit 中）启用 laravelErrorParsers 的标志。
enableLaravelServerErrorParserbooleanfalse在服务器端（在 definePrecognitiveEventHandler 中）启用 laravelErrorParsers 的标志。

状态处理程序

与 官方包 中一样，您可以全局或在 @实例级别定义特定错误代码的自定义处理程序

// plugins/precognition.ts

export default defineNuxtPlugin(() => {
  const { $precognition } = useNuxtApp()

  $precognition.statusHandlers = {
    401: async (error, form) => {
      form.error = createError('Unauthorized')
      await navigateTo('/login')
    },
    403: async (error, form) => {
      form.error = createError('Forbidden')
    },
  }
})

Laravel 集成

如果您想使用 Laravel，则不需要 nuxt nitro 集成。

  1. 启用后端验证和错误解析器
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-precognition'],
  precognition: {
    backendValidation: true,
    enableLaravelClientErrorParser: true,
  }
})
  1. 插件示例

添加 Sanctum token 预取并确保所有预感知请求得到正确处理。

// plugins/laravel.ts
export default defineNuxtPlugin((app) => {
  const { $precognition } = useNuxtApp()
  const token = useCookie('XSRF-TOKEN')

  const api = $fetch.create({
    baseURL: 'https://',
    credentials: 'include',
    headers: {
      'Accept': 'application/json',
      'Content-Type': 'application/json',
    },
    onRequest: ({ options }) => {
      if (token.value) {
        const headers = new Headers(options.headers)
        headers.set('X-XSRF-TOKEN', token.value)
        options.headers = headers
      }
    },
    onResponse: (context) => {
      // ensure non false positive validations
      $precognition.assertSuccessfulPrecognitiveResponses(context)
    },
  })

  async function fetchSanctumToken() {
    try {
      await api('/sanctum/csrf-cookie')
      token.value = useCookie('XSRF-TOKEN').value
      if (!token.value) throw new Error('Failed to get CSRF token')
    } catch (e) {
      console.error(e)
    }
  }

  app.hook('app:mounted', fetchSanctumToken)

  return {
    provide: {
      api,
      sanctum: {
        fetchToken: fetchSanctumToken,
        token,
      },
    },
  }
})
  1. Laravel CORS 配置

确保 Precognitive header 将与 Nuxt 应用程序共享。

// config/cors.php
return [
  'paths' => ['*'],
  'allowed_methods' => ['*'],
  'allowed_origins' => ['*'],
  'allowed_origins_patterns' => [env('FRONTEND_URL', 'https://:3000')],
  'allowed_headers' => ['*'],
  'exposed_headers' => ['Precognition', 'Precognition-Success'],
  'max_age' => 0,
  'supports_credentials' => true,
];
  1. 启用 Precognition 中间件

在需要的地方应用预感知中间件。

// routes/api.php
Route::middleware('precognitive')->group(function () {
    Route::apiResource('posts', \App\Http\Controllers\PostController::class);
});

就是这样。Nuxt 验证将与 Laravel 同步！！。

贡献

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Run Vitest
npm run test
npm run test:watch

# Release new version
npm run release

许可证

MIT © sot1986