首页 > web前端 > js教程 > 正文

使用全面的开发人员解决方案有效管理 Next.js 中的错误

Susan Sarandon
发布: 2024-11-01 11:47:29
原创
750 人浏览过

Efficiently Manage Errors in Next.js with a Comprehensive Developer Solution

介绍

我很高兴推出一个新的轻量级包,旨在简化 Next.js 应用程序中的错误管理:nextjs-centralized-error-handler。作为开发人员,我们经常遇到错误处理方面的挑战,尤其是在 Next.js 这样的框架中,传统方法可能会导致重复代码和被忽视的场景。

从我使用 Yii2 框架的经验中汲取灵感——内置错误类简化了错误管理,无需硬编码状态代码或消息——我认识到 Node.js 生态系统中也有类似的需求。这种认识促使在此包中开发自定义错误类,从而增强一致性和可用性。

重要提示:此软件包目前处于测试阶段。作为一个新发布的工具,您的反馈对于识别潜在问题并提高其稳定性至关重要。我鼓励您尝试 nextjs-centralized-error-handler 包并分享您的见解,无论是通过错误报告还是改进建议。我们可以共同为 Next.js 社区加强这个软件包。

目录

  • 简介
  • 快速入门
    • 安装软件包
    • 包装您的 API 路由处理程序
    • 自定义错误处理(可选)
  • 为什么将 nextjs-centralized-error-handler 与 Next.js 中间件一起使用?
  • 与 Next.js 13 中间件的比较
    • Next.js 13 中间件示例
    • 与 nextjs-centralized-error-handler 的比较
    • 了解范围和灵活性:Next.js 中间件与 nextjs-centralized-error-handler
  • 示例
    • 处理不同的 HTTP 方法
    • 验证请求参数
    • 处理未经授权的访问
    • 强制有效负载限制
    • 自定义错误响应(高级)
  • 与日志服务集成
  • 社区反馈和稳定性
  • 好处一览
  • 结论

快速入门

  1. 安装软件包

    npm install nextjs-centralized-error-handler
    # or
    yarn add nextjs-centralized-error-handler
    
    登录后复制
    登录后复制
    登录后复制
    登录后复制
    登录后复制
    登录后复制
    登录后复制
    登录后复制
    登录后复制
    登录后复制
    登录后复制
  2. 包装您的 API 路由处理程序

    // pages/api/example.js
    
    const { errorHandler, BadRequestError } = require('nextjs-centralized-error-handler');
    
    const handler = async (req, res) => {
      if (!req.body.name) {
        throw new BadRequestError('Name is required.');
      }
    
      res.status(200).json({ message: 'Success' });
    };
    
    export default errorHandler(handler);
    
    登录后复制
    登录后复制
    登录后复制
    登录后复制
    登录后复制
    登录后复制
  3. 自定义错误处理(可选)

    npm install nextjs-centralized-error-handler
    # or
    yarn add nextjs-centralized-error-handler
    
    登录后复制
    登录后复制
    登录后复制
    登录后复制
    登录后复制
    登录后复制
    登录后复制
    登录后复制
    登录后复制
    登录后复制
    登录后复制

为什么将 nextjs-centralized-error-handler 与 Next.js 中间件一起使用?

Next.js 13 的中间件提供了强大的全局拦截功能,非常适合身份验证和一般请求验证等任务。然而,nextjs-centralized-error-handler 通过提供细粒度的路由级控制和中间件本身无法覆盖的详细响应来增强错误处理。以下是这个包如何补充和扩展 Next.js 中间件:

  1. 特定于路由的错误管理:使用 nextjs-centralized-error-handler,每个路由都可以定义自己的上下文错误处理,并使用与路由功能相匹配的定制消息。这种模块化对于跨不同端点具有不同错误处理需求的复杂应用程序至关重要。

  2. 具有详细响应的自定义错误类:该包引入了具有结构化、前端友好的 JSON 响应的自定义错误类(例如 BadRequestError、UnauthorizedError)。这些响应富含状态代码和错误类型等元数据,确保后端和前端团队的错误处理可预测且标准化。

  3. 增强的安全性和数据隐私:只有故意出现 CustomError 实例的错误才会将其状态代码和消息发送到客户端。对于意外错误,将使用通用错误消息,并将敏感详细信息保留在服务器端,最大限度地减少信息泄露。

  4. 日志记录并与监控工具集成:支持与日志服务(例如 Sentry、Datadog)集成,实现超出中间件单独实现的详细错误跟踪和调试。

  5. 可自定义和可扩展的错误处理:CustomError 类是完全可扩展的,允许开发人员定义特定于应用程序的错误,随着应用程序的发展创建灵活的错误处理策略。

通过将 Next.js 中间件与 nextjs-centralized-error-handler 相结合,您可以实现强大而灵活的错误处理解决方案,支持全局和特定于路由的需求。


与 Next.js 13 中间件的比较

Next.js 13 引入了全局中间件,支持身份验证和一般验证等任务的请求级拦截。下面的比较显示了 Next.js 13 中间件与 nextjs-centralized-error-handler 的不同之处以及何时使用它们。

Next.js 13 中间件示例

Next.js 13 中间件可以全局定义并应用于与指定模式匹配的所有路由。这对于日志记录或授权等高级操作非常有用。

npm install nextjs-centralized-error-handler
# or
yarn add nextjs-centralized-error-handler
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制

与 nextjs-centralized-error-handler 的比较

虽然 Next.js 中间件对于全局、高级任务很有用,但 nextjs-centralized-error-handler 可以使用自定义错误类进行特定于路由的错误处理,以实现细粒度控制。以下是两者如何协同工作:

Feature Next.js 13 Middleware nextjs-centralized-error-handler
Scope Global, based on route pattern matching Route-specific, applied individually to each handler
Use Case Authentication, global request validation Detailed error handling, custom error messages
Custom Error Responses Limited, generalized JSON responses Structured, frontend-compatible JSON responses
Custom Error Classes
Error Logging Integration ✅ (supports Sentry, Datadog, etc.)
Fine-Grained Control
Preventing Information Leakage Limited, as it handles errors globally without distinguishing between error types Enhanced, distinguishes between custom and unexpected errors to prevent sensitive data exposure
Integration with Route Handlers Middleware runs before route handlers, cannot modify responses within handlers Wraps individual route handlers, allowing for customized responses per route
Extensibility Limited to what middleware can handle globally Highly extensible through custom error classes and configurable options

了解范围和灵活性:Next.js 中间件与 nextjs-centralized-error-handler

虽然 Next.js 中间件为高级请求拦截提供了强大的机制,但需要注意的是,中间件路由处理程序执行之前运行。这意味着处理程序内部抛出的任何异常都不会被中间件捕获;相反,这将导致向客户端返回通用的 500 内部服务器错误。相比之下,nextjs-centralized-error-handler 擅长在单个 API 路由中进行细粒度的错误处理。本节阐明了它们的不同角色,并演示了如何有效地一起使用它们。

场景:用户输入验证

假设您正在构建一个 API 路由,需要在请求正文中提供用户名。如果名称丢失,您需要使用清晰且具体的错误消息进行响应。让我们看看每种方法如何处理这种情况。

使用 Next.js 中间件

在 Next.js 中,中间件可用于全局验证请求。但是,它无法捕获单个路由处理程序中引发的异常。

npm install nextjs-centralized-error-handler
# or
yarn add nextjs-centralized-error-handler
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
// pages/api/example.js

const { errorHandler, BadRequestError } = require('nextjs-centralized-error-handler');

const handler = async (req, res) => {
  if (!req.body.name) {
    throw new BadRequestError('Name is required.');
  }

  res.status(200).json({ message: 'Success' });
};

export default errorHandler(handler);
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制

这里发生了什么:

  1. 中间件在路由处理程序之前运行以处理请求。
  2. 如果 req.body.name 缺失,则会抛出错误。
  3. 但是,中间件不会捕获此错误,从而导致一般的 500 内部服务器错误。

使用 nextjs-centralized-error-handler

相比之下,nextjs-centralized-error-handler 提供了一个高阶函数,可以捕获路由处理程序中抛出的错误。

const handler = async (req, res) => {
  // Your logic here
};

const options = {
  logger: customLoggerFunction,
  defaultMessage: 'Something went wrong!',
  formatError: (error, req) => ({
    message: error.message,
    type: error.name,
    timestamp: new Date().toISOString(),
  }),
};

export default errorHandler(handler, options);
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制

这里发生了什么:

  1. errorHandler 包装了路由处理程序,拦截其中抛出的任何错误。
  2. 如果 req.body.name 缺失,则会抛出 BadRequestError 并被 errorHandler 捕获。
  3. 这会产生一个结构化响应,带有适当的状态代码 (400) 和明确的错误消息(“名称为必填项。”)。

为什么同时使用这两种方法

结合 Next.js 中间件和 nextjs-centralized-error-handler 提供了全面的错误处理策略:

  • 全局请求验证和身份验证:使用 Next.js 中间件来处理需要跨多个路由应用的任务,例如身份验证、授权和一般请求验证。
  • 特定于路由的详细错误处理: 使用 nextjs-centralized-error-handler 来管理各个路由处理程序中发生的错误,从而允许根据每个路由的特定需求进行定制和结构化错误响应。

示例:同时使用中间件和 nextjs-centralized-error-handler

中间件(middleware.js):

npm install nextjs-centralized-error-handler
# or
yarn add nextjs-centralized-error-handler
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制

路由处理程序 (pages/api/example.js):

// pages/api/example.js

const { errorHandler, BadRequestError } = require('nextjs-centralized-error-handler');

const handler = async (req, res) => {
  if (!req.body.name) {
    throw new BadRequestError('Name is required.');
  }

  res.status(200).json({ message: 'Success' });
};

export default errorHandler(handler);
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制

说明:

  • 中间件 (middleware.js): 处理身份验证等全局任务。适用于基于匹配器配置的所有 /api/* 路由。
  • 路由处理程序 (example.js): 处理特定于路由的逻辑。利用 nextjs-centralized-error-handler 进行详细的错误处理和结构化响应。

通过使用 Next.js 中间件进行请求级检查,使用 nextjs-centralized-error-handler 进行响应级错误处理,您可以实现广泛的验证和细粒度的错误管理。


nextjs-centralized-error-handler 的主要优点:

  • 通过高阶函数进行集中错误处理
  • 自定义错误类以简化和标准化错误分类。
  • 前端兼容的响应,使基于 Next.js 的前端更容易有效地解析和显示错误消息。

传统方法与 nextjs-centralized-error-handler

在传统的 Node.js/Express 应用程序中,集中式错误处理通常通过中间件进行管理,中间件会跨路由一致地拦截请求和错误。然而,在 Next.js 中,API 路由不以同样的方式支持中间件,这给集中式错误处理带来了挑战。 nextjs-centralized-error-handler 通过使用高阶函数来提供跨所有 API 路由的特定于路由的错误处理,从而填补了这一空白。

Express 中的传统方法(使用中间件)

在 Express 中,集中式错误处理是通过中间件函数实现的,这允许跨路由进行可重用的错误管理:

const handler = async (req, res) => {
  // Your logic here
};

const options = {
  logger: customLoggerFunction,
  defaultMessage: 'Something went wrong!',
  formatError: (error, req) => ({
    message: error.message,
    type: error.name,
    timestamp: new Date().toISOString(),
  }),
};

export default errorHandler(handler, options);
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制

在这种方法中,错误被传递给 next(error),然后触发集中式错误处理中间件以跨路由做出一致的响应。

在 Next.js 中使用 nextjs-centralized-error-handler

使用 nextjs-centralized-error-handler,您可以通过包装路由处理程序的高阶函数 (errorHandler) 获得为 Next.js 量身定制的类似中间件的行为,在路由级别拦截和管理错误:

npm install nextjs-centralized-error-handler
# or
yarn add nextjs-centralized-error-handler
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制

使用 nextjs-centralized-error-handler,您可以避免在每个路由中重复的错误处理代码。相反,自定义错误类和 errorHandler 高阶函数提供集中、一致的错误响应,从而简化维护并在整个应用程序中扩展错误处理。


特征

1. 集中错误处理

  • 高阶错误处理:该包使用高阶函数 errorHandler 来集中所有 API 路由的错误处理。 errorHandler 不需要重复的 try-catch 块,而是拦截错误,确保前端集成具有一致的 JSON 格式的响应结构。

2. 结构化自定义错误类

  • 可自定义的 HTTP 错误类:该包包括预定义的类,例如 BadRequestError、UnauthorizedError 和 NotFoundError,每个类都映射到适当的 HTTP 状态代码。这种方法提高了代码可读性并减少了冗余,允许开发人员通过扩展 CustomError 基类来创建其他自定义错误类型。

3. JSON 序列化和前端兼容性

  • 错误类型元数据:序列化错误响应包括错误类型等元数据,使前端能够一致地处理特定错误。这通过提供清晰、可操作的反馈来增强用户体验,同时还确保敏感的服务器详细信息不会暴露。

背景

什么是错误处理?

错误处理确保应用程序可以优雅地响应意外情况(例如无效输入、缺乏访问权限)。具有强大错误处理功能的应用程序不会崩溃,而是会向用户提供有用的反馈并记录错误以进行调试。

Next.js API 路由中的挑战

Next.js API 路由支持全局中间件方法,但它们本身并不支持像 Express 那样的特定于路由的细粒度错误处理。否则,每个路由处理程序都需要单独的错误管理,从而导致冗余代码和不一致的错误响应。 nextjs-centralized-error-handler 通过提供一个高阶函数 errorHandler 来解决这个问题,该函数包装路由处理程序以确保在路由级别进行一致且集中的错误处理。


安装

使用 npm

npm install nextjs-centralized-error-handler
# or
yarn add nextjs-centralized-error-handler
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制

使用纱线

// pages/api/example.js

const { errorHandler, BadRequestError } = require('nextjs-centralized-error-handler');

const handler = async (req, res) => {
  if (!req.body.name) {
    throw new BadRequestError('Name is required.');
  }

  res.status(200).json({ message: 'Success' });
};

export default errorHandler(handler);
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制

用法

基本设置

将 errorHandler 和自定义错误类导入到您的 Next.js API 路由中:

const handler = async (req, res) => {
  // Your logic here
};

const options = {
  logger: customLoggerFunction,
  defaultMessage: 'Something went wrong!',
  formatError: (error, req) => ({
    message: error.message,
    type: error.name,
    timestamp: new Date().toISOString(),
  }),
};

export default errorHandler(handler, options);
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制

自定义错误类

该包包含几个预定义的错误类:

  • 错误请求错误 (400)
  • 未经授权错误 (401)
  • 禁止错误 (403)
  • 未发现错误 (404)
  • 方法不允许错误 (405)
  • 内部服务器错误 (500)
  • 付款要求错误 (402)
  • 不可接受的错误 (406)
  • 请求超时错误 (408)
  • PayloadTooLargeError (413)
  • 太多请求错误 (429)
  • 错误网关错误 (502)
  • 服务不可用错误 (503)
  • 网关超时错误 (504)
  • 存储空间不足错误 (507)
  • 带宽限制超出错误 (509)
  • NetworkAuthenticationRequiredError (511)

这些类简化了错误创建,无需在每个路由中硬编码状态代码:

// middleware.js (placed at the root of the app)

import { NextResponse } from 'next/server';

export function middleware(req) {
  // Example of request validation or general logging
  if (!req.headers.get('Authorization')) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  return NextResponse.next(); // Continue to the route handler
}

// Optional: Configure route matching
export const config = {
  matcher: '/api/:path*', // Applies middleware only to /api/* routes
};
登录后复制
登录后复制
登录后复制

默认消息的用法示例

如果您只是实例化错误而不指定消息,则它默认为预定义的、用户友好的消息。

// middleware.js

import { NextResponse } from 'next/server';

export function middleware(req) {
  try {
    // You can include any logic here that might throw an error
    return NextResponse.next(); // Proceed to the route handler
  } catch (error) {
    // Handle the error and return an appropriate response
    return NextResponse.json({ error: 'An error occurred while processing your request.' }, { status: 500 });
  }
}
登录后复制
登录后复制
登录后复制

创建自定义错误

为了满足预定义类之外的特定需求,该包被设计为可扩展的,允许您为高级用例创建独特的自定义错误。您可以扩展 CustomError 基类来定义您自己的错误类型,根据特定的业务逻辑进行定制。以下是您可能创建的自定义错误的一些示例:

  • HTTPVersionNotSupportedError (505)
  • 未实现错误 (501)
  • VariantAlsoNegotiatesError (506)
  • 冲突错误 (409)
例子
// pages/api/example.js

const handler = async (req, res) => {
  if (!req.body.name) {
    throw new Error('Name is required.'); // This will not be caught by middleware
  }

  res.status(200).json({ message: `Hello, ${req.body.name}!` });
};

export default handler;
登录后复制

此示例定义了一个自定义的 ConflictError (HTTP 409),在发生资源冲突的情况下可能会抛出该错误。创建自定义错误使您能够有效地处理独特的业务逻辑或特定于应用程序的需求。


将 nextjs-centralized-error-handler 与 App Router 结合使用

除了支持传统的 API 路由之外,nextjs-centralized-error-handler 还可以与 Next.js 13 中引入的 App Router 一起使用。以下是如何使用该包在 App Router 中实现错误处理。

示例:将 nextjs-centralized-error-handler 与 App Router 结合使用

创建带有错误处理的路由

您可以在 App Router 中创建路由并使用错误处理程序来有效管理错误。

npm install nextjs-centralized-error-handler
# or
yarn add nextjs-centralized-error-handler
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制

解释

  • 处理函数:处理函数处理传入的请求。它检查名称参数,如果丢失则抛出 BadRequestError。
  • 错误处理:处理程序由 errorHandler 包装,它捕获执行期间抛出的任何错误并返回结构化错误响应。

App Router 中的错误处理

使用 App Router 可以以干净、结构化的方式来管理错误,同时利用 nextjs-centralized-error-handler 的强大功能。通过将两者结合起来,您可以确保您的应用程序有效地处理错误,无论使用哪种路由方法。


自定义错误处理行为

除了自定义错误之外,该包还允许开发人员通过以下方式完全控制错误处理的行为:

  • 自定义日志记录:您可以插入任何日志记录功能来跟踪错误。这包括集成外部服务(例如 Sentry、LogRocket)或自定义记录器。
  • 错误消息格式:使用formatError添加自定义字段(例如requestId、时间戳)。
  • 默认状态和消息:控制未处理错误的默认值,确保用户友好的反馈而不暴露服务器详细信息。

错误处理选项

您可以使用自定义日志记录、错误格式和默认消息的选项配置 errorHandler:

// pages/api/example.js

const { errorHandler, BadRequestError } = require('nextjs-centralized-error-handler');

const handler = async (req, res) => {
  if (!req.body.name) {
    throw new BadRequestError('Name is required.');
  }

  res.status(200).json({ message: 'Success' });
};

export default errorHandler(handler);
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制

formatError 的其他示例

formatError 函数非常灵活,允许您创建符合应用程序要求的详细且结构化的错误响应。下面是一些示例配置,展示了 formatError 的多功能性:

添加用户和请求信息

const handler = async (req, res) => {
  // Your logic here
};

const options = {
  logger: customLoggerFunction,
  defaultMessage: 'Something went wrong!',
  formatError: (error, req) => ({
    message: error.message,
    type: error.name,
    timestamp: new Date().toISOString(),
  }),
};

export default errorHandler(handler, options);
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制

包括用于开发的详细堆栈跟踪

// middleware.js (placed at the root of the app)

import { NextResponse } from 'next/server';

export function middleware(req) {
  // Example of request validation or general logging
  if (!req.headers.get('Authorization')) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  return NextResponse.next(); // Continue to the route handler
}

// Optional: Configure route matching
export const config = {
  matcher: '/api/:path*', // Applies middleware only to /api/* routes
};
登录后复制
登录后复制
登录后复制

集成应用程序元数据

// middleware.js

import { NextResponse } from 'next/server';

export function middleware(req) {
  try {
    // You can include any logic here that might throw an error
    return NextResponse.next(); // Proceed to the route handler
  } catch (error) {
    // Handle the error and return an appropriate response
    return NextResponse.json({ error: 'An error occurred while processing your request.' }, { status: 500 });
  }
}
登录后复制
登录后复制
登录后复制

自定义错误响应

formatError 函数可以根据您的要求灵活地添加或省略字段,从而轻松生成结构化、信息丰富的错误响应。这些选项使开发人员能够标准化其 API 中的错误消息传递和可追溯性,从而使该包能够适应不同的应用程序。


安全考虑

全面的异常处理

errorHandler 高阶函数单独包装每个路由处理程序,捕获所有异常(包括预期的和意外的),而不需要重复的 try-catch 块。这种方法确保即使是第三方或不可预见的错误也能被拦截,从而在所有路由上实现一致且安全的错误响应。

防止信息泄露

为了保护敏感数据,我们的软件包区分故意的已知错误(例如 CustomError 实例)和意外错误:

  • 仅限自定义错误:仅作为 CustomError(或其子类)实例创建的错误在客户端响应中包含其状态代码和消息,为已知问题提供清晰、用户友好的错误反馈。

  • 意外错误的通用处理:对于不是 CustomError 实例的错误(例如第三方库问题或不可预见的服务器错误),errorHandler 会自动应用状态代码 500 和一般消息(“发生内部服务器错误”)。这可以防止敏感信息无意中暴露给客户。

用于安全和监控的可定制日志记录

在保持对客户端的响应安全和通用的同时,errorHandler 还支持服务器端日志记录。这允许在内部记录和监控意外错误,而无需向客户端透露详细信息,从而将安全性与有效的错误跟踪相结合。

示例:安全处理意外错误

考虑一个依赖第三方库的 API 路由,这可能会引发我们无法预测的错误:

npm install nextjs-centralized-error-handler
# or
yarn add nextjs-centralized-error-handler
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制

幕后发生了什么

如果thirdPartyLibrary.doSomething()抛出一个不是CustomError的错误,errorHandler将:

  1. 将 statusCode 设置为 500(或配置的默认StatusCode)。
  2. 将消息设置为“发生内部服务器错误。请稍后再试。” (或默认消息,如果已配置)。
  3. 防止信息泄漏:确保不会将敏感详细信息(例如原始错误消息或堆栈跟踪)发送到客户端。
  4. 记录错误服务器端:使用提供的记录器进行内部监控来记录错误。

错误处理策略注意事项

errorHandler 函数区分自定义错误和意外错误:

  • 自定义错误(CustomError 实例):您定义的特定状态代码和消息将发送到客户端,为已知问题提供清晰且用户友好的反馈。
  • 其他错误:使用默认的状态代码和消息来防止意外错误导致信息泄漏。

通过以这种方式捕获所有错误,nextjs-centralized-error-handler 提供了专为 Next.js 应用程序量身定制的强大、安全且统一的错误处理解决方案,并具有内置保护功能以防止意外数据泄露。


示例

以下真实场景演示了 nextjs-centralized-error-handler 如何简化各种用例的错误处理。

注意:如果在没有特定消息的情况下实例化错误,则会自动提供默认的、用户友好的消息。

1. 处理不同的HTTP方法

用例:确保 API 路由仅允许使用特定的 HTTP 方法(例如 POST),并在方法不正确时提供有意义的错误消息。

在此示例中,如果传入请求使用 POST 以外的任何方法,则会抛出 MethodNotAllowedError,以确保一致、用户友好的反馈。如果未提供自定义消息,则将使用默认消息“不允许使用方法”。

npm install nextjs-centralized-error-handler
# or
yarn add nextjs-centralized-error-handler
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制

2. 验证请求参数

用例:检查请求中是否存在所需参数,如果验证失败,则返回结构化错误。

这里,当缺少必需的参数(名称)时,会抛出 BadRequestError 。如果未指定自定义消息,则使用默认消息“您的请求似乎有错误”。

// pages/api/example.js

const { errorHandler, BadRequestError } = require('nextjs-centralized-error-handler');

const handler = async (req, res) => {
  if (!req.body.name) {
    throw new BadRequestError('Name is required.');
  }

  res.status(200).json({ message: 'Success' });
};

export default errorHandler(handler);
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制

3. 处理未授权访问

用例:仅限制授权用户的访问。如果用户未通过身份验证,则响应 UnauthorizedError 以表示未经授权的访问。

在此示例中,UnauthorizedError 用于确保只有经过身份验证的用户才能访问该路由。如果没有提供自定义消息,则默认为“未经授权的访问。请登录。”

const handler = async (req, res) => {
  // Your logic here
};

const options = {
  logger: customLoggerFunction,
  defaultMessage: 'Something went wrong!',
  formatError: (error, req) => ({
    message: error.message,
    type: error.name,
    timestamp: new Date().toISOString(),
  }),
};

export default errorHandler(handler, options);
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制

4. 强制有效负载限制

用例:拒绝包含超过定义大小的有效负载的请求,有助于防止误用或拒绝服务攻击。

如果有效负载超过特定限制,则会抛出 PayloadTooLargeError 来通知客户端。如果没有自定义消息,将显示默认消息“请求实体太大”。

// middleware.js (placed at the root of the app)

import { NextResponse } from 'next/server';

export function middleware(req) {
  // Example of request validation or general logging
  if (!req.headers.get('Authorization')) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  return NextResponse.next(); // Continue to the route handler
}

// Optional: Configure route matching
export const config = {
  matcher: '/api/:path*', // Applies middleware only to /api/* routes
};
登录后复制
登录后复制
登录后复制

5. 自定义错误响应(高级)

如果您想包含其他元数据或自定义错误响应,nextjs-centralized-error-handler 允许您定义 formatError 函数。可以定制此函数以包含额外的字段,例如请求路径或时间戳。

有关完整详细信息,请参阅自定义错误处理行为部分。这是一个简单的例子:

// middleware.js

import { NextResponse } from 'next/server';

export function middleware(req) {
  try {
    // You can include any logic here that might throw an error
    return NextResponse.next(); // Proceed to the route handler
  } catch (error) {
    // Handle the error and return an appropriate response
    return NextResponse.json({ error: 'An error occurred while processing your request.' }, { status: 500 });
  }
}
登录后复制
登录后复制
登录后复制

与日志记录服务集成

为了增强可观察性,nextjs-centralized-error-handler 支持通过任何服务(例如 Sentry、Datadog 或自定义日志记录解决方案)进行自定义日志记录。通过向errorHandler传递一个日志函数(如Sentry.captureException),可以实时监控错误,同时保证安全性和效率。

什么是自定义记录器?

“自定义记录器”是您提供给 errorHandler 以在服务器端记录错误的任何日志记录函数或外部服务(例如 console.log、Sentry.captureException 或自定义实现)。此日志记录功能不是 nextjs-centralized-error-handler 本身的一部分,但该包旨在与您选择的记录器无缝集成。

安全日志记录的最佳实践

  • 避免记录敏感数据:确保您的自定义记录器不会无意中记录敏感用户数据,例如凭据或个人详细信息。仅将日志限制为基本错误信息,以维护安全性并符合数据保护标准。

使用 Sentry 增强日志记录

如果您使用流行的监控工具 Sentry,您可以将其与此包集成以进行生产错误跟踪:

关于 Sentry 的注意事项:Sentry 帮助开发人员实时跟踪、调试和解决问题。将 Sentry 与 nextjs-centralized-error-handler 集成,您可以记录生产中的错误,从而深入了解故障发生的位置和原因,而不会暴露敏感细节。

下面的示例演示了如何使用 Sentry 的 captureException 函数作为带有 errorHandler 的记录器。

npm install nextjs-centralized-error-handler
# or
yarn add nextjs-centralized-error-handler
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制
登录后复制

此设置捕获错误以进行监控,同时防止向客户泄露敏感信息。通过利用自定义记录器,nextjs-centralized-error-handler 将强大的安全性与有效的错误跟踪相结合,确保安全且可观察的应用程序环境。


社区反馈和稳定性

由于这个包是新发布的,我意识到生产环境中稳定性的重要性。虽然我已经进行了测试,但现实世界的使用情况和社区的反馈对于识别任何潜在问题并进一步改进软件包至关重要。

我鼓励开发者将 nextjs-centralized-error-handler 集成到他们的项目中并分享他们的经验。无论是错误报告、改进建议,还是只是分享它如何帮助简化应用程序中的错误管理,您的反馈都是非常宝贵的。我们可以一起增强这个包,并使其对 Next.js 社区更加有效。


优势一览

  • 专为 Next.js 定制:通过集中错误处理来处理 Next.js API 路由限制。
  • 自定义错误类:用于结构化错误管理的预定义和可扩展类。
  • JSON 格式的响应:前端兼容且元数据丰富的错误消息。
  • 可自定义日志记录:与第三方日志服务集成以进行错误监控。
  • 无缝集成:快速适应现有的 Next.js 应用程序。

结论:

我希望 nextjs-centralized-error-handler 能够极大地增强 Next.js 开发人员的错误管理,提供全面且用户友好的方法来处理错误。通过集中错误管理、利用自定义错误类以及与日志记录服务顺利集成,该包解决了 Next.js 应用程序开发中的常见痛点。

我邀请 dev.to 社区提供反馈并为该项目做出贡献,因为您的见解对于完善此包非常宝贵。您可以在 npm 上查看该软件包并探索 GitHub 存储库以获取更多详细信息!

探索该软件包并为其开发做出贡献:

  • 在 npm 上查看
  • 在 GitHub 上查看

您的意见对于识别问题和增强稳定性至关重要。我鼓励您尝试 nextjs-centralized-error-handler 并分享您的经验。我们可以共同为 Next.js 社区推进这个软件包。

感谢您的支持,我很高兴听到您的想法和经历!

以上是使用全面的开发人员解决方案有效管理 Next.js 中的错误的详细内容。更多信息请关注PHP中文网其他相关文章!

来源:dev.to
本站声明
本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系admin@php.cn
作者最新文章
热门教程
更多>
最新下载
更多>
网站特效
网站源码
网站素材
前端模板