二、nextjs API 路由如何做好 JWT 登录鉴权、身份鉴权， joi 字段校验，全局处理异常等

介绍

在这篇文章中，我们将学习如何在 C-Shopping 电商开源项目中，基于 Next.js 14 ，处理所有 API 路由中添加身份验证和错误处理中间件的思路与实现。

这篇文章中的代码片段取自我最近开源项目 C-Shopping

完整的项目和文档可在https://github.com/huanghanzhilian/c-shopping 地址查看。

项目在线演示地址：

docker 部署地址：http://shop.huanghanlian.com/

vercel 部署地址：https://c-shopping-three.vercel.app/

Next.js 中的 API 路由

在 Next.js14 中，/app/api 文件夹包含所有基于文件名路由的 api 接口

例如文件 /app/api/user/route.js 会自动映射到路由 /api/user。API 路由处理程序导出一个默认函数，该函数传递给 HTTP 请求处理程序。

有关 Next.js API 路由的更多信息，请参阅 https://nextjs.org/docs/app/building-your-application/routing/route-handlers。

官方示例 Next.js API 路由处理程序

下面是一个 API 路由处理程序的基本示例，它将用户列表返回给 HTTP GET 请求。

只需要导出一个支持 HTTP 协议名称，再返回一个 Response ，就完成了一个 API

export async function GET() {
  const res = await fetch('https://data.mongodb-api.com/...', {
    headers: {
      'Content-Type': 'application/json',
      'API-Key': process.env.DATA_API_KEY,
    },
  })
  const data = await res.json()
 
  return Response.json({ data })
}

Next.js 自定义编码设计 API 处理器

我们会发现，如果按照官方的文档来写 API ，虽然简单，但是毫无设计感，当面对复杂项目时候很多引用会重复出现，我们需要设计一些中间间，来帮助我们更好的扩展 API 编码。

为了增加对中间件的支持，我创建了apiHandler包装器函数，该包装器接受一个 API 处理程序对象，并返回一个HTTP方法(例如GET， POST， PUT， DELETE等)，再到route文件导出该API，这样就既简单又高效的做好了基础的编码设计。

通过apiHandler包装器函数，再扩展了jwtMiddleware、identityMiddleware、validateMiddleware、errorHandler，来更好的设计优化代码：

jwtMiddleware （处理 JWT 校验）；
identityMiddleware （处理身份校验）；
validateMiddleware （处理 joi ，字段校验）；
errorHandler （全局处理异常）。

项目中的路径 /helpers/api/api-handler.js

import { NextRequest, NextResponse } from 'next/server'

import { errorHandler, jwtMiddleware, validateMiddleware, identityMiddleware } from '.'

export { apiHandler }

function isPublicPath(req) {
  // public routes that don't require authentication
  const publicPaths = ['POST:/api/auth/login', 'POST:/api/auth/logout', 'POST:/api/auth/register']
  return publicPaths.includes(`${req.method}:${req.nextUrl.pathname}`)
}

function apiHandler(handler, { identity, schema, isJwt } = {}) {
  return async (req, ...args) => {
    try {
      if (!isPublicPath(req)) {
        // global middleware
        await jwtMiddleware(req, isJwt)
        await identityMiddleware(req, identity, isJwt)
        await validateMiddleware(req, schema)
      }
      // route handler
      const responseBody = await handler(req, ...args)
      return NextResponse.json(responseBody || {})
    } catch (err) {
      console.log('global error handler', err)
      // global error handler
      return errorHandler(err)
    }
  }
}

users [id] API 路由处理程序

下面代码我们可以看到，使用了apiHandler包装器

第一个参数是当前 HTTP 请求的核心逻辑，解析body、query、params，查询数据，最后通过统一的setJson返回数据结构
第二个参数是一个对象，里面包含了一些中间层扩展参数逻辑，isJwt是否需要 JWT 校验、schema需要校验的字段和类型、identity操作的用户是否符合权限等。

项目中的路径 /app/api/user/[id]/route.js

import joi from 'joi'

import { usersRepo, apiHandler, setJson } from '@helpers'

const updateRole = apiHandler(
  async (req, { params }) => {
    const { id } = params
    const body = await req.json()
    await usersRepo.update(id, body)

    return setJson({
      message: '更新成功',
    })
  },
  {
    isJwt: true,
    schema: joi.object({
      role: joi.string().required().valid('user', 'admin'),
    }),
    identity: 'root',
  }
)

const deleteUser = apiHandler(
  async (req, { params }) => {
    const { id } = params
    await usersRepo.delete(id)
    return setJson({
      message: '用户信息已经删除',
    })
  },
  {
    isJwt: true,
    identity: 'root',
  }
)

export const PATCH = updateRole
export const DELETE = deleteUser
export const dynamic = 'force-dynamic'

Next.js jwtMiddleware 授权中间件

项目中JWT身份验证中间件是使用jsonwebtoken库来验证发送到受保护 API 路由的请求中的 JWT 令牌，如果令牌无效，则抛出错误，导致全局错误处理程序返回 401 Unauthorized 响应。JWT 中间件被添加到 API 处理程序包装函数中的 Next.js 请求管道中。

项目中的路径:/api/jwt-middleware.js

import { auth } from '../'

async function jwtMiddleware(req, isJwt = false) {
  const id = await auth.verifyToken(req, isJwt)
  req.headers.set('userId', id)
}
export { jwtMiddleware }

项目中的路径:/helpers/auth.js

import jwt from 'jsonwebtoken'

const verifyToken = async (req, isJwt) => {
  try {
    const token = req.headers.get('authorization')
    const decoded = jwt.verify(token, process.env.NEXT_PUBLIC_ACCESS_TOKEN_SECRET)
    const id = decoded.id
    return new Promise(resolve => resolve(id))
  } catch (error) {
    if (isJwt) {
      throw error
    }
  }
}

const createAccessToken = payload => {
  return jwt.sign(payload, process.env.NEXT_PUBLIC_ACCESS_TOKEN_SECRET, {
    expiresIn: '1d',
  })
}

export const auth = {
  verifyToken,
  createAccessToken,
}

Next.js identityMiddleware 身份校验中间件

在项目设计中，暂时只设计了user普通用户、admin管理员用户，以及一个超级管理员权限root字段，在apiHandler()包装器函数调用时，可以来控制该接口的权限以及身份。

如果权限不匹配，将抛出全局错误，进入 Next.js 请求管道中，交给全局错误处理程序，从而做到接口异常处理。

项目中的路径：/helpers/api/identity-middleware.js

import { usersRepo } from '../db-repo'

async function identityMiddleware(req, identity = 'user', isJwt = false) {
  if (identity === 'user' && isJwt === false) return

  const userId = req.headers.get('userId')
  const user = await usersRepo.getOne({ _id: userId })
  req.headers.set('userRole', user.role)
  req.headers.set('userRoot', user.root)

  if (identity === 'admin' && user.role !== 'admin') {
    throw '无权操作'
  }

  if (identity === 'root' && !user.root) {
    throw '无权操作，仅超级管理可操作'
  }
}

export { identityMiddleware }

Next.js validateMiddleware 请求参数校验中间件

在apiHandler()包装器函数调用时，通过joi工具，schema 参数，来指定需要接收和校验的参数，从而避免一些冗余的字段传递，减少异常的发生。

项目中的路径：/helpers/api/validate-middleware.js

import joi from 'joi'

export { validateMiddleware }

async function validateMiddleware(req, schema) {
  if (!schema) return

  const options = {
    abortEarly: false, // include all errors
    allowUnknown: true, // ignore unknown props
    stripUnknown: true, // remove unknown props
  }

  const body = await req.json()
  const { error, value } = schema.validate(body, options)

  if (error) {
    throw `Validation error: ${error.details.map(x => x.message).join(', ')}`
  }

  // update req.json() to return sanitized req body
  req.json = () => value
}

Next.js 全局错误处理程序

使用全局错误处理程序捕获所有错误，并消除了在整个 Next.js API 中重复错误处理代码的需要。

通常按照惯例，'string'类型的错误被视为自定义(特定于应用程序)错误，这简化了抛出自定义错误的代码，因为只需要抛出一个字符串(例如抛出'Username 或 password is incorrect')，如果自定义错误以'not found'结尾，则返回 404 响应代码，否则返回标准的 400 错误响应。

如果错误是一个名为“UnauthorizedError”的对象，则意味着 JWT 令牌验证失败，因此 HTTP 401 未经授权的响应代码将返回消息“无效令牌”。

所有其他(未处理的)异常都被记录到控制台，并返回一个 500 服务器错误响应代码。

项目中的路径：/helpers/api/error-handler.js

import { NextResponse } from 'next/server'
import { setJson } from './set-json'

export { errorHandler }

function errorHandler(err) {
  if (typeof err === 'string') {
    // custom application error
    const is404 = err.toLowerCase().endsWith('not found')
    const status = is404 ? 404 : 400
    return NextResponse.json(
      setJson({
        message: err,
        code: status,
      }),
      { status }
    )
  }

  if (err.name === 'JsonWebTokenError') {
    // jwt error - delete cookie to auto logout
    return NextResponse.json(
      setJson({
        message: 'Unauthorized',
        code: '401',
      }),
      { status: 401 }
    )
  }

  if (err.name === 'UserExistsError') {
    return NextResponse.json(
      setJson({
        message: err.message,
        code: '422',
      }),
      { status: 422 }
    )
  }

  // default to 500 server error
  console.error(err)
  return NextResponse.json(
    setJson({
      message: err.message,
      code: '500',
    }),
    { status: 500 }
  )
}

Next.js 统一处理 NextResponse ，灵活统一使用 setJson

为什么要这样设计？我们不想在每个route中，来回的去引用NextResponse，这会使得代码可读性很差，所以在apiHandler包装器函数中，调用了 HTTP handler ，拿到了路由管道中想要的数据，最后统一输出。

项目中的路径：/helpers/api/set-json.js

const setJson = ({ code, message, data } = {}) => {
  return {
    code: code || 0,
    message: message || 'ok',
    data: data || null,
  }
}

export { setJson }

至此，我们已经完成了API的设计，这将会给后期的开发带来效率，但同时也带来了代码的难以理解度，只能说设计程序需要有取舍，合适就好。这是我自己基于Next.js Route 的一些设计，也欢迎大家一起共同探讨。