在 TypeScript 中使用 JWT 令牌：jsonwebtoken 库及完整指南

TypeScript 中的 JWT 令牌：jsonwebtoken 库完整指南

JSON Web Token (JWT) 是一种基于 JSON 格式创建访问令牌的开放标准（RFC 7519）。JWT 广泛用于客户端和服务器之间的身份认证和信息交换。在 TypeScript 中，得益于严格的类型化，使用 JWT 变得特别方便和安全。在本文中，我们将探讨如何在 TypeScript 中使用流行的 jsonwebtoken 库来创建、验证和管理 JWT 令牌。

安装与配置

首先，安装必要的包：

npm install jsonwebtokennpm install -D @types/jsonwebtoken

第一个包是库本身，第二个包是它的 TypeScript 类型定义。安装后，创建一个 jwt.service.ts 文件，用于存放所有令牌处理逻辑。

创建 JWT 令牌

jsonwebtoken 的主要函数是 sign()。让我们看看如何结合类型化使用它：

import jwt from 'jsonwebtoken';

interface TokenPayload {  userId: number;  email: string;  role: 'user' | 'admin';}

const createAccessToken = (payload: TokenPayload): string => {  const secret = process.env.JWT_SECRET || 'default_secret';  const options: jwt.SignOptions = {    expiresIn: '15m', // 令牌有效期为 15 分钟    algorithm: 'HS256',  };

  return jwt.sign(payload, secret, options);};

重要提示：切勿将密钥硬编码在代码中。请使用环境变量（.env 文件）。

验证与解码令牌

使用 verify() 函数验证令牌的真实性。它会自动检查签名和有效期：

const verifyToken = (token: string): TokenPayload => {  const secret = process.env.JWT_SECRET || 'default_secret';

  try {    const decoded = jwt.verify(token, secret) as TokenPayload;    return decoded;  } catch (error) {    if (error instanceof jwt.TokenExpiredError) {      throw new Error('令牌已过期');    }    if (error instanceof jwt.JsonWebTokenError) {      throw new Error('无效令牌');    }    throw error;  }};

请注意类型转换 as TokenPayload——这确保了 TypeScript 知道解码后数据的结构。

刷新令牌：延长会话

在实践中，访问令牌的生命周期较短（15-30 分钟），因此需要一种刷新机制。为此，使用生命周期更长的刷新令牌：

const createRefreshToken = (payload: TokenPayload): string => {  const secret = process.env.JWT_REFRESH_SECRET || 'refresh_secret';  const options: jwt.SignOptions = {    expiresIn: '7d', // 一周    algorithm: 'HS256',  };

  return jwt.sign(payload, secret, options);};

const refreshAccessToken = (refreshToken: string): string => {  const secret = process.env.JWT_REFRESH_SECRET || 'refresh_secret';

  try {    const decoded = jwt.verify(refreshToken, secret) as TokenPayload;    // 可以检查数据库中刷新令牌是否已被撤销    return createAccessToken({      userId: decoded.userId,      email: decoded.email,      role: decoded.role,    });  } catch {    throw new Error('无效的刷新令牌');  }};

TypeScript 中的 Express 中间件

将 JWT 与 Express.js 集成需要创建中间件。以下是类型化版本：

import { Request, Response, NextFunction } from 'express';

interface AuthRequest extends Request {  user?: TokenPayload;}

const authMiddleware = (req: AuthRequest, res: Response, next: NextFunction) => {  const authHeader = req.headers.authorization;

  if (!authHeader || !authHeader.startsWith('Bearer ')) {    return res