Express JWT 认证实现指南：基于4GeeksAcademy项目模板-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00388/article/details/148971137

Express JWT 认证实现指南：基于4GeeksAcademy项目模板

Templates-Boilerplates 📙 Configuration is one of the biggest deterrents for learning coding skills, use one of these well-maintained boilerplates and focused on what really matters: Polishing your coding skills 🔥💻. 项目地址: https://gitcode.com/gh_mirrors/te/Templates-Boilerplates

前言

在现代Web应用开发中，身份认证是保障系统安全的重要环节。JSON Web Token (JWT) 作为一种轻量级的认证方案，因其跨语言、易扩展的特性而被广泛应用。本文将详细介绍如何在Express框架中实现JWT认证机制，基于4GeeksAcademy提供的项目模板进行讲解。

JWT基础概念

JWT是一种开放标准(RFC 7519)，它定义了一种紧凑且自包含的方式，用于在各方之间安全地传输信息作为JSON对象。JWT由三部分组成：

Header（头部）
Payload（负载）
Signature（签名）

这种结构使得JWT非常适合用于身份认证和信息交换场景。

实现步骤

1. 安装依赖

首先需要安装必要的Node.js库：

npm install express-jwt @types/express-jwt jsonwebtoken @types/jsonwebtoken --save

express-jwt：Express中间件，用于验证JWT
jsonwebtoken：JWT的生成和验证库
@types包：为TypeScript项目提供类型定义

2. 创建登录端点

登录端点是客户端获取JWT的入口，通常接收用户名和密码，验证成功后返回Token。

// 公共路由中定义token端点
router.post('/token', safe(createToken));

// 创建Token的业务逻辑
export const createToken = async (req: Request, res: Response): Promise<Response> => {
  // 验证请求体
  if(!req.body.email) throw new Exception("请求体中必须包含email", 400)
  if(!req.body.password) throw new Exception("请求体中必须包含password", 400)

  // 查询数据库验证用户
  const userRepo = await getRepository(Users)
  const user = await userRepo.findOne({ 
    where: { 
      email: req.body.email, 
      password: req.body.password 
    }
  })
  
  if(!user) throw new Exception("邮箱或密码无效", 401)

  // 生成JWT Token
  const token = jwt.sign({ user }, process.env.JWT_KEY as string, {
    expiresIn: '24h' // 建议设置过期时间
  });
  
  // 返回用户信息和Token
  return res.json({ 
    user: {
      id: user.id,
      email: user.email
      // 注意：不应返回密码等敏感信息
    }, 
    token 
  });
}

安全建议：

密码应加密存储，使用bcrypt等库进行哈希处理
Token应设置合理的过期时间
返回的用户信息应过滤敏感字段

3. 实现认证中间件

认证中间件负责拦截请求并验证JWT的有效性。

// 在Express应用配置中添加中间件
const jwtOptions: Options = { 
  secret: process.env.JWT_KEY as string, 
  algorithms: ["HS256"],
  credentialsRequired: true // 要求必须提供Token
}

// 应用JWT中间件
app.use(jwt(jwtOptions))

// 错误处理中间件
app.use((err: any, req: any, res: any, next: any) => {
  if (err.name === 'UnauthorizedError') {
    return res.status(401).json({ 
      status: 'error',
      message: '无效或过期的Token' 
    });
  }
  next(err);
})

中间件位置的重要性：

中间件上方的路由是公开的
中间件下方的路由是受保护的

示例：

// 公开路由
app.get('/public', (req, res) => {
  res.json({ message: "所有人都可以访问" }); 
})

// JWT中间件
app.use(jwt(jwtOptions))

// 私有路由
app.get('/private', (req, res) => {
  res.json({ message: "只有登录用户才能看到" }); 
})

4. 获取认证用户信息

通过JWT中间件后，可以在请求对象中获取认证用户信息。

export const getCurrentUser = async (req: Request, res: Response): Promise<Response> => {
  // 直接从Token中获取用户信息
  const userFromToken = req.auth.user;
  
  // 也可以从数据库获取更完整的用户信息
  const userRepo = await getRepository(Users);
  const fullUserInfo = await userRepo.findOne(userFromToken.id);
  
  return res.json({
    tokenInfo: req.auth,
    userInfo: fullUserInfo
  });
}

进阶实践

Token刷新机制

可以考虑实现Token刷新机制，避免用户频繁登录：

生成长期有效的Refresh Token
短期有效的Access Token
提供/refresh端点用于获取新的Access Token

权限控制

基于JWT可以实现更细粒度的权限控制：

// 自定义权限检查中间件
const checkPermission = (requiredRole: string) => {
  return (req: Request, res: Response, next: NextFunction) => {
    if(req.auth.user.role !== requiredRole) {
      return res.status(403).json({ message: "权限不足" });
    }
    next();
  }
}

// 使用示例
app.get('/admin', 
  jwt(jwtOptions), 
  checkPermission('admin'),
  (req, res) => {
    // 管理员专属逻辑
  }
);