时里院子市集

5.0 KiB

Raw Blame History

微信小程序扫码登录集成文档

概述

本文档介绍如何在微信小程序中集成扫码登录功能，支持用户通过小程序扫描网页端二维码快速登录。

功能特性

✅ 多平台支持 - 支持网页端、移动APP、微信小程序
✅ 安全可靠 - Token有效期控制，防重复使用
✅ 用户体验好 - 5分钟有效期，实时状态反馈
✅ 微信集成 - 自动获取微信用户信息
✅ 组件化设计 - 提供多种使用方式

后端接口

1. 生成扫码token

POST /api/qr-login/generate

2. 检查登录状态

GET /api/qr-login/status/{token}

3. 确认登录（通用）

POST /api/qr-login/confirm

4. 微信小程序专用确认接口

POST /api/qr-login/wechat-confirm

前端集成

1. API接口层

文件：src/api/qr-login/index.ts

提供了完整的扫码登录API接口封装：

generateQRToken() - 生成扫码token
checkQRLoginStatus() - 检查登录状态
confirmQRLogin() - 确认登录
confirmWechatQRLogin() - 微信小程序专用确认

2. Hook层

文件：src/hooks/useQRLogin.ts

提供了扫码登录的状态管理和业务逻辑：

const {
  state,           // 当前状态
  error,           // 错误信息
  result,          // 登录结果
  isLoading,       // 是否加载中
  startScan,       // 开始扫码
  cancel,          // 取消扫码
  reset,           // 重置状态
  handleScanResult, // 处理扫码结果
  canScan          // 是否可以扫码
} = useQRLogin();

3. 组件层

QRLoginScanner 完整扫码组件

文件：src/components/QRLoginScanner.tsx

功能完整的扫码登录组件，包含状态显示和错误处理：

<QRLoginScanner
  onSuccess={(result) => console.log('登录成功', result)}
  onError={(error) => console.log('登录失败', error)}
  buttonText="扫码登录"
  showStatus={true}
/>

QRLoginButton 简化按钮组件

文件：src/components/QRLoginButton.tsx

简化的按钮组件，支持两种模式：

{/* 直接扫码模式 */}
<QRLoginButton
  text="扫码登录"
  onSuccess={handleSuccess}
  onError={handleError}
/>

{/* 页面跳转模式 */}
<QRLoginButton
  text="扫码登录"
  usePageMode={true}
/>

4. 页面层

文件：src/passport/qr-login/index.tsx

专门的扫码登录页面，提供完整的用户体验：

用户信息展示
扫码功能
使用说明
登录历史
安全提示

使用方式

方式一：在现有组件中集成

import { useQRLogin } from '@/hooks/useQRLogin';

const MyComponent = () => {
  const { startScan, isLoading } = useQRLogin();
  
  const handleScan = async () => {
    try {
      await startScan();
    } catch (error) {
      console.error('扫码失败:', error);
    }
  };

  return (
    <Button loading={isLoading} onClick={handleScan}>
      扫码登录
    </Button>
  );
};

方式二：使用预制组件

import QRLoginButton from '@/components/QRLoginButton';

const MyComponent = () => {
  return (
    <QRLoginButton
      text="扫码登录"
      usePageMode={true}
    />
  );
};

方式三：跳转到专门页面

import Taro from '@tarojs/taro';

const handleQRLogin = () => {
  Taro.navigateTo({
    url: '/passport/qr-login/index'
  });
};

工作流程

网页端流程

用户访问登录页面
点击"扫码登录"按钮
调用 POST /api/qr-login/generate 生成token
显示包含token的二维码
每2秒调用 GET /api/qr-login/status/{token} 检查状态
状态变为 confirmed 时获取JWT token
自动跳转到主页面

小程序端流程

用户在小程序中点击扫码登录
调用 Taro.scanCode() 扫描二维码
解析二维码获取token
调用 POST /api/qr-login/wechat-confirm 确认登录
传递用户ID和微信用户信息
显示登录确认成功提示

安全考虑

Token有效期 - 默认5分钟有效期，防止长期暴露
一次性使用 - Token确认后立即失效，防止重复使用
用户确认 - 需要用户主动确认，防止误操作
来源验证 - 只扫描官方网站的二维码
权限检查 - 确保用户已登录小程序

错误处理

常见错误及处理方式：

用户未登录 - 提示用户先登录小程序
扫码失败 - 提示重新扫码或检查二维码
Token无效 - 提示二维码已过期，请刷新
网络错误 - 提示检查网络连接
权限拒绝 - 引导用户开启相机权限

测试建议

功能测试 - 测试完整的扫码登录流程
异常测试 - 测试各种异常情况的处理
性能测试 - 测试扫码响应速度和网络请求
兼容性测试 - 测试不同设备和微信版本
安全测试 - 测试Token安全性和权限控制

注意事项

确保后端接口已正确实现
配置正确的API基础URL
处理好用户权限和登录状态
提供清晰的用户提示和错误信息
考虑网络异常和超时情况

5.0 KiB Raw Blame History