xueteng/video-flow-b

Fork 0

forked from 77media/video-flow

qikongjian e161cbb05b 实现Google OAuth登录功能和邮箱冲突处理

2025-09-19 21:04:16 +08:00

6.8 KiB

Raw Blame History

Google OAuth2 API 接口文档

📋 概述

本文档为前端开发者提供 Google OAuth2 登录、注册和账户绑定相关的 API 接口说明。

基础信息：

基础路径：/api/auth/google
认证方式：Sa-Token（部分接口需要登录）
数据格式：JSON
字符编码：UTF-8

🔐 接口列表

1. 获取 Google 登录授权 URL

接口地址： GET /api/auth/google/authorize

描述： 生成 Google OAuth2 授权链接，用户访问此链接进行 Google 登录授权

请求参数： 无

响应示例：

{
  "success": true,
  "data": {
    "authUrl": "https://accounts.google.com/oauth/authorize?client_id=847079918888-xxx&redirect_uri=http://localhost:8080/api/auth/google/callback&response_type=code&scope=openid+email+profile&state=uuid-string",
    "state": "uuid-string",
    "clientId": "847079918888-xxx"
  }
}

错误响应：

{
  "success": false,
  "error": "AUTHORIZATION_URL_GENERATION_FAILED",
  "message": "生成授权链接失败"
}

2. Google 登录/注册

接口地址： POST /api/auth/google/login

描述： 通过 Google ID Token 进行用户登录或注册，支持新用户自动注册和邮箱冲突处理

请求参数：

{
  "idToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6...", // Google ID Token（必填）
  "action": "auto" // 操作类型：login | register | auto（可选，默认 auto）
}

成功响应：

{
  "success": true,
  "data": {
    "token": "sa-token-string",
    "userInfo": {
      "userId": "user-123",
      "userName": "user@gmail.com",
      "name": "张三",
      "email": "user@gmail.com",
      "authType": "GOOGLE",
      "url": "https://lh3.googleusercontent.com/...",
      "isNewUser": false
    }
  }
}

邮箱冲突响应（HTTP 409）：

{
  "success": false,
  "error": "EMAIL_ALREADY_EXISTS",
  "message": "该邮箱已被其他账户使用，是否绑定 Google 账户？",
  "data": {
    "bindToken": "temporary-bind-token",
    "existingUser": {
      "email": "user@gmail.com",
      "authType": "LOCAL"
    }
  }
}

其他错误响应：

{
  "success": false,
  "error": "INVALID_GOOGLE_TOKEN",
  "message": "Google Token 验证失败"
}

错误码说明：

INVALID_GOOGLE_TOKEN: Google Token 无效或过期
EMAIL_ALREADY_EXISTS: 邮箱已被其他账户使用
USER_NOT_FOUND: 用户不存在（仅当 action=login 时）
REGISTRATION_FAILED: 用户注册失败
GOOGLE_LOGIN_FAILED: 登录处理失败

3. Google 账户绑定

接口地址： POST /api/auth/google/bind

描述： 将 Google 账户绑定到当前登录的用户账户

认证要求： 需要用户登录（Sa-Token）

请求参数：

{
  "idToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6...", // Google ID Token（可选）
  "confirm": true // 确认绑定（必填）
}

成功响应：

{
  "success": true,
  "data": {
    "token": "new-sa-token",
    "message": "Google 账户绑定成功"
  }
}

错误响应：

{
  "success": false,
  "error": "BINDING_FAILED",
  "message": "账户绑定失败"
}

4. 获取 Google 绑定状态

接口地址： GET /api/auth/google/status

描述： 查询当前用户的 Google 账户绑定状态

认证要求： 需要用户登录（Sa-Token）

请求参数： 无

响应示例：

{
  "success": true,
  "data": {
    "isBound": true,
    "userId": "user-123"
  }
}

🔄 前端集成流程

方案一：使用 Google JavaScript SDK

引入 Google SDK

<script src="https://accounts.google.com/gsi/client" async defer></script>

初始化 Google 登录按钮

function initializeGoogleSignIn() {
  google.accounts.id.initialize({
    client_id:
      '847079918888-o1nne8d3ij80dn20qurivo987pv07225.apps.googleusercontent.com',
    callback: handleGoogleResponse,
  })

  google.accounts.id.renderButton(
    document.getElementById('google-signin-button'),
    {
      theme: 'outline',
      size: 'large',
      text: 'signin_with',
      locale: 'zh_CN',
    }
  )
}

处理 Google 响应

async function handleGoogleResponse(response) {
  try {
    const result = await fetch('/api/auth/google/login', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        idToken: response.credential,
        action: 'auto',
      }),
    })

    const data = await result.json()

    if (data.success) {
      // 登录成功
      localStorage.setItem('token', data.data.token)
      console.log('用户信息:', data.data.userInfo)
      // 跳转到主页面
    } else if (result.status === 409) {
      // 邮箱冲突，需要处理绑定逻辑
      handleEmailConflict(data)
    } else {
      // 其他错误
      console.error('登录失败:', data.message)
    }
  } catch (error) {
    console.error('请求失败:', error)
  }
}

方案二：使用授权 URL 重定向

获取授权 URL

async function getGoogleAuthUrl() {
  try {
    const response = await fetch('/api/auth/google/authorize')
    const data = await response.json()

    if (data.success) {
      // 保存 state 参数用于验证
      sessionStorage.setItem('google_oauth_state', data.data.state)
      // 重定向到 Google 授权页面
      window.location.href = data.data.authUrl
    }
  } catch (error) {
    console.error('获取授权 URL 失败:', error)
  }
}

处理回调（需要后端回调处理接口）

// 在回调页面处理授权码
function handleGoogleCallback() {
  const urlParams = new URLSearchParams(window.location.search)
  const code = urlParams.get('code')
  const state = urlParams.get('state')
  const savedState = sessionStorage.getItem('google_oauth_state')

  if (state !== savedState) {
    console.error('State 参数不匹配，可能存在 CSRF 攻击')
    return
  }

  // 发送授权码到后端处理
  // 这需要后端提供相应的回调处理接口
}

🛡️ 安全注意事项

Token 安全
- 妥善保存用户的 Sa-Token
- 定期刷新 Token
- 在请求头中正确传递 Token
CSRF 防护
- 验证 state 参数
- 使用 HTTPS 协议
错误处理
- 妥善处理各种错误情况
- 不要在前端暴露敏感信息
用户体验
- 提供清晰的错误提示
- 处理网络异常情况
- 支持重试机制

📞 联系方式

如有疑问，请联系后端开发者：周梓鑫

测试环境： http://localhost:8080
生产环境： https://your-production-domain.com

📝 更新日志

2025-01-20: 初始版本，支持 Google OAuth2 登录、注册和绑定功能

6.8 KiB Raw Blame History Unescape Escape