Pothos GraphQL 中使用 Zod 国际化错误验证的实践

背景介绍

Pothos 是一个强大的 GraphQL Schema 构建工具，其验证插件（validation plugin）基于 Zod 库提供了强大的输入验证功能。在实际开发中，我们经常需要将验证错误信息本地化，以提供更好的用户体验。

问题分析

在 Pothos 中使用 Zod 进行验证时，开发者可能会遇到国际化错误消息的需求。虽然 Zod 本身提供了 setErrorMap 方法来定制错误消息，但在 Pothos 环境中直接使用可能不会生效，这是因为：

1. Pothos 验证插件可能有自己独立的 Zod 实例
2. 错误消息的聚合方式需要特殊处理

解决方案

基础配置

首先需要配置 Zod 的国际化错误映射。这里以法语为例：

import i18next from 'i18next';
import { z } from 'zod';
import { makeZodI18nMap } from 'zod-i18n-map';

// 初始化i18n实例
i18next.init({
  lng: 'fr',
  resources: {
    fr: { 
      zod: {
        // 这里放置Zod的法语翻译资源
      } 
    },
  },
});

// 设置Zod的错误映射
z.setErrorMap(makeZodI18nMap({ t: i18next.t }));

与Pothos集成

在 Pothos 中，验证插件会自动处理 Zod 的验证错误。通过上述配置，Zod 产生的原始错误消息已经是本地化后的内容。Pothos 验证插件会将这些错误收集并转换为 GraphQL 错误响应。

高级定制

如果需要更精细地控制错误展示方式，可以在创建 Pothos Builder 时配置验证插件的错误处理：

import { createPlugin } from '@pothos/core';
import { ValidationPlugin } from '@pothos/plugin-validation';

const builder = new SchemaBuilder({
  plugins: [
    ValidationPlugin({
      // 自定义错误处理逻辑
      formatError: (error) => {
        // 可以在这里进一步处理错误格式
        return error;
      },
    }),
  ],
});

注意事项

1. 初始化时机：确保在创建 Pothos Builder 之前完成 Zod 的错误映射配置
2. 翻译完整性：检查所有 Zod 验证规则是否都有对应的翻译
3. 错误聚合：Pothos 可能会将多个验证错误合并，需要考虑如何展示复合错误

最佳实践

1. 将 Zod 国际化配置放在应用初始化阶段
2. 为不同的语言环境准备完整的翻译资源
3. 在开发环境中保留原始错误代码，便于调试
4. 考虑前端如何消费这些本地化错误信息

通过以上方法，开发者可以在 Pothos GraphQL 应用中实现完整的验证错误国际化方案，为用户提供更友好的错误提示体验。