微信小程序双 Token 登录设计

本文原发表于「Eric 技术圈」，现迁移并修订至夏有木工作室官网。

在微信小程序开发中，用户的身份认证是一个重要的环节。为了提升安全性和用户体验，可以采用双 Token 认证机制，包括短生命周期的 AccessToken 和长生命周期的 RefreshToken。本文将介绍双 Token 的设计思路、登录流程以及小程序端对 401 和 403 错误的处理。

双 Token 的概念

AccessToken 访问令牌

• 作用：用于访问受保护的 API。
• 特点：生命周期较短（如 15 分钟到 1 小时），以减少被盗用的风险。
• 失效处理：需要通过 RefreshToken 获取新的 AccessToken。

RefreshToken 刷新令牌

• 作用：用于刷新 AccessToken。
• 特点：生命周期较长（如 7 天或更长），通常只在高风险操作或用户注销时失效。
• 失效处理：用户需要到登录页面手动发起登录。

双 Token 设计流程

---

登录流程要点：

1）用户登录

• 用户使用微信提供的 wx.login() 方法获取临时登录凭证（code）。
• 前端将 code 发送给后端，后端通过微信登录接口换取用户的 OpenID 和 SessionKey。

2）生成 Token

• 后端根据用户信息生成 AccessToken 和 RefreshToken。
• AccessToken 通过标准的 JWT（JSON Web Token）生成，并设置较短的过期时间。
• RefreshToken 通过标准的 JWT（JSON Web Token）生成，并设置较长的过期时间。

3）返回 Token

• 后端将 AccessToken 返回给小程序前端，供后续 API 请求使用。

4）刷新 Token

• 在 AccessToken 过期后，前端可以调用刷新接口，通过 RefreshToken 获取新的 AccessToken。
• 如果 RefreshToken 也失效，则需要重新登录。

---

小程序端 API Request 设计要点：

1）校验用户登录状态

• 小程序端未找到 AccessToken ，且不为 login 等 auth 接口时，小程序端请求一次静默登录。
• 如果 AccessToken 存在，则继续往下发起 wx.request

2）使用 AccessToken 发起 API 请求

• 在 Http Header 中携带 AccessToken 访问后端服务器 API
• 后端通过 Filter 统一校验 AccessToken 的有效性
• 如果 AccessToken 有效，则获取到资源数据

3）校验是否为 Auth 接口

• 小程序端判断 API 请求是否为 login 、refresh等权限接口
• 如果是，接口报错，直接返回 API 的错误信息
• 否则，继续处理 401、403 错误

4）AccessToken 失效（401 ）

• 后端获取的 AccessToken 为空、过期或者非法后，返回 401 错误码
• 小程序端接收到 401 错误码后，使用 RefreshToken 调用后端的 refresh 接口
• 如果 RefreshToken 有效，则获取到新的 AccessToken，小程序端再次发起 API 请求

5）RefreshToken 失效

• 后端 refresh 接口获取到的 RefreshToken 为空，过期或者非法后，则报错 401
• 小程端封装后端的 refresh 接口，如果接口调用不成功，则使用 reject 抛出异常
• 调用封装后的 refresh 方法报错后，再次发起一次登录，成功则再次请求原 API 接口
• 失败则进行错误提示并终止 return

6）Access Token 有效，但是权限不足（403）

• 后端接收的 AccessToken 有效，但是用户的权限不足，不能访问该 API 资源，则会报错 403 给前端
• 小程序端调用后端 logout 接口，并跳转到登录页面或首页

总结

通过双 Token 的设计，可以显著提升微信小程序用户的体验，不用频繁的触发登录操作。切记在开发过程中，记得做好测试工作，模拟 AccessToken 和 RefreshToken 失效的场景，防止出现循环调用的情况。