18 GraphQL API中的定制错误消息处理

在上一篇文章中，我们探讨了如何在GraphQL API中处理错误与异常。我们了解了基本的错误处理策略和对常见错误的处理方法。在本篇中，我们将深入讨论如何生成定制的错误消息，以便在出现错误时提供更清晰的信息给客户端。这种定制化不仅能提高用户体验，还能为开发者提供更明确的调试信息。

1. 定义错误类型

在GraphQL中，我们可以定义自定义的错误类型，以便在返回给客户端时能包含足够的信息。首先，让我们定义一个错误类型。

type CustomError {
    message: String!
    code: String!
    details: String
}

• message: 通用的错误消息。
• code: 错误代码，通常对应于应用程序中的某种错误类型。
• details: 可选的详细信息，可帮助开发者理解错误的上下文。

2. 集成定制错误到解析器中

在GraphQL的解析器中，我们可以使用自定义的错误类型来返回更有意义的错误信息。下面是一个示例解析器，它演示了如何处理错误并返回 CustomError：

const resolvers = {
    Query: {
        user: async (parent, args, context, info) => {
            try {
                const user = await getUserById(args.id);
                if (!user) {
                    throw new UserNotFoundError(`User with ID ${args.id} not found`);
                }
                return user;
            } catch (error) {
                return {
                    message: error.message || "An unknown error occurred",
                    code: "USER_NOT_FOUND",
                    details: error.details || null,
                };
            }
        },
    },
};

在这个示例中，当找不到用户时，我们抛出了一个自定义错误，并在捕获到错误后返回了明确的错误信息。

3. 将定制错误转换为GraphQL错误

在GraphQL中，我们也可以通过上下文来统一处理错误，再加上定制错误消息。以下是一个中间件示例，它捕获所有解析过程中的错误，并将其转换为 CustomError 格式：

const formatError = (error) => {
    // 检查错误的类型，并返回适当的定制错误消息
    if (error.extensions?.code === 'USER_NOT_FOUND') {
        return new CustomError(`User not found`, 'USER_NOT_FOUND');
    }
    
    return new CustomError(`Unexpected error occurred`, 'INTERNAL_SERVER_ERROR');
};

// 设置Apollo Server
const server = new ApolloServer({
    typeDefs,
    resolvers,
    formatError,
});

这里，我们通过 formatError 函数格式化错误信息，使得每个GraphQL错误都遵循我们的 CustomError 格式。

4. 客户端如何处理错误

假设我们在客户端调用GraphQL API并收到错误响应，响应格式如下：

{
    "errors": [
        {
            "message": "User not found",
            "extensions": {
                "code": "USER_NOT_FOUND"
            }
        }
    ]
}

客户端可以通过错误代码来处理不同的错误场景：

fetch('/graphql', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query: '{ user(id: "1234") { name } }' }),
})
.then(response => response.json())
.then(({ data, errors }) => {
    if (errors) {
        errors.forEach(error => {
            switch (error.extensions.code) {
                case 'USER_NOT_FOUND':
                    console.error("处理用户未找到的错误");
                    break;
                default:
                    console.error("处理其他错误");
            }
        });
    } else {
        console.log(data);
    }
});

在这个示例中，客户端可以通过 error.extensions.code 来识别并做出相应的处理，从而提高用户体验。

5. 结论

在本篇教程中，我们探讨了如何在GraphQL API中生成和处理定制的错误消息。通过自定义错误类型、处理解析器中的异常，以及在服务器中统一格式化错误，开发者能够提供更清晰和更有信息量的错误响应。这对于优化用户体验和简化调试过程都是非常重要的。

下一篇文章我们将讨论GraphQL与认证之间的关系，特别是OAuth与JWT的基本概念，敬请期待！