2.1.1 模块划分#

2.1.2 核心流程图#

2.3.1 Controller层#

2.3.2 Service层#

IAuthService 接口新增方法：

ICaptchaService 接口方法：

2.3.3 配置类#

TurnstileProperties

2.4.1 Redis缓存键设计#

说明：发送频率限制使用 @RateLimit 注解（基于Sentinel限流）。

2.4.2 缓存数据结构#

1
// 魔法链接Token缓存
2
{
3
  "key": "cache:magic_link:xxx-token-xxx",
4
  "value": "user@example.com",
5
  "expire": 900 // 15分钟
6
}

2.5.1 发送魔法链接#

请求体：

成功响应（200）：

1
{
2
  "code": 200,
3
  "msg": "success",
4
  "data": "魔法链接已发送至您的邮箱，15分钟内有效"
5
}

失败响应（400）：

1
{
2
  "code": 400,
3
  "msg": "人机校验失败，请重试",
4
  "data": null
5
}

2.5.2 魔法链接回调#

请求参数：

成功响应（302）：

• Location: /（首页地址，可配置）
• Set-Cookie: access_token=xxx; HttpOnly; Secure; SameSite=Strict

失败响应（302）：

• Location: /login?error=invalid_token

方案 A：预校验（已废弃）#

流程： 用户进入页面 → 完成Turnstile校验 → 获取临时凭证 → 输入邮箱 → 携带凭证调用登录接口

优点：

• 登录时无需等待人机校验结果，登录接口响应更快
• 可以提前拦截恶意流量，不让无效请求到达登录接口

致命缺点：

• 多一次网络请求：页面加载就调用后端，浪费服务器资源
• 安全漏洞：临时凭证如果没有严格的过期/防重放设计，攻击者可以批量刷凭证后暴力登录
• 体验割裂：用户还没打算登录，就被强制完成人机校验
• 实现复杂：需要管理临时凭证的生命周期（Redis存储、过期时间、单用户限制等）

方案 B：登录时校验（当前实现）#

流程： 用户输入邮箱 → 点击登录 → 前端完成Turnstile校验 → 携带turnstileToken调用登录接口 → 后端实时校验

优点：

• 极致用户体验：全程静默无感，用户只操作一次登录
• 最高安全性：登录和人机强绑定，不通过校验就绝对无法进入登录逻辑
• 架构极简：无额外接口、无额外存储、无凭证管理逻辑
• 抗攻击最强：每一次登录请求都必须携带全新的有效TurnstileToken，几乎无法批量刷接口

唯一小缺点：

• 登录接口会多一步校验逻辑（调用Cloudflare API），但Turnstile接口响应极快（毫秒级），几乎无感知

4.2.1 application.yml 新增配置#

1
# Cloudflare Turnstile 配置
2
turnstile:
3
  secret-key: ${TURNSTILE_SECRET_KEY:your-secret-key}
4
  site-key: ${TURNSTILE_SITE_KEY:your-site-key}
5
  verify-url: https://challenges.cloudflare.com/turnstile/v0/siteverify
6

7
# 魔法链接配置
8
magic-link:
9
  redirect-url: ${MAGIC_LINK_REDIRECT_URL:http://localhost:8080}

说明：

• expire-minutes: 魔法链接有效期固定为15分钟，无需配置
• rate-limit: 限流由 @RateLimit 注解控制，无需在此配置

5.3.1 发送魔法链接#

步骤1：初始化Turnstile组件

前端页面加载时，初始化Cloudflare Turnstile组件：

1
<!-- 登录页面嵌入Turnstile -->
2
<div
3
  class="cf-turnstile"
4
  data-sitekey="your-site-key"
5
  data-callback="onTurnstileSuccess"
6
></div>

步骤2：用户输入邮箱并点击登录

用户输入邮箱后点击登录按钮，触发Turnstile校验：

1
// 前端发送魔法链接请求
2
import { sendMagicLink } from '@/api/auth'
3

4
const handleSendMagicLink = async (email: string) => {
5
  // 等待Turnstile校验完成获取token
6
  const turnstileToken = await getTurnstileToken()
7

8
  // 调用后端接口
9
  await sendMagicLink({
10
    email,
11
    turnstileToken
12
  })
13
}

步骤3：处理响应

后端返回成功后，提示用户检查邮箱；校验失败则提示用户重试。

5.3.2 魔法链接回调处理#

步骤1：用户点击邮件链接

邮件中的链接格式：https://your-domain/magic-link/callback?token=xxx

步骤2：后端验证并重定向

后端验证Token成功后，设置Cookie并重定向到首页：

• Set-Cookie: access_token=xxx; HttpOnly; Secure; SameSite=Strict
• Location: /

5.3.3 通过Cookie获取UserInfo#

步骤1：应用初始化时检查Cookie

前端应用启动时，从Cookie读取access_token：

1
import { useEffect } from 'react'
2
import { useUserStore } from '@/stores/user'
3
import { getCurrentUser } from '@/api/auth'
4
import { getStorageValue, STORAGE_KEYS } from '@/utils/storage'
5

6
useEffect(() => {
7
  const initUser = async () => {
8
    // 从Cookie读取access_token
9
    const token = getStorageValue<string>(STORAGE_KEYS.TOKEN, undefined, 'cookie')
10

11
    if (token && !userInfo) {
12
      // 调用接口获取用户信息
13
      const user = await getCurrentUser()
14
      if (user) {
15
        setUserInfo(user)
16
      }
17
    }
18
  }
19
  initUser()
20
}, [])

步骤2：请求拦截器自动携带Token

Axios请求拦截器自动从Cookie读取Token并添加到请求头：

1
request.interceptors.request.use((config) => {
2
  const token = getStorageValue<string>(STORAGE_KEYS.TOKEN, undefined, 'cookie')
3
  if (token && config.withToken !== false) {
4
    config.headers.Authorization = `Bearer ${token}`
5
  }
6
  return config
7
})

步骤3：获取用户信息接口

调用/system/user/current接口获取当前登录用户信息：

1
export function getCurrentUser() {
2
  return get<UserInfo>('/system/user/current')
3
}

步骤4：响应拦截器处理Token过期

当返回401状态码时，清除Cookie并跳转到登录页：

1
request.interceptors.response.use(
2
  (response) => response,
3
  (error) => {
4
    if (error.response?.status === 401) {
5
      // 清除Cookie和本地存储
6
      removeStorage(STORAGE_KEYS.TOKEN, 'cookie')
7
      removeStorage(STORAGE_KEYS.USER_INFO, 'local')
8
      // 跳转到登录页
9
      window.location.href = '/login'
10
    }
11
    return Promise.reject(error)
12
  }
13
)

5.3.4 Cookie操作工具函数#

前端使用js-cookie库封装Cookie操作：

1
import Cookies from 'js-cookie'
2

3
export function getStorageValue<T>(
4
  key: string,
5
  defaultValue?: T,
6
  type: 'local' | 'session' | 'cookie' = 'local'
7
): T | undefined {
8
  if (type === 'cookie') {
9
    const item = Cookies.get(key)
10
    if (item === undefined) return defaultValue
11
    try {
12
      return JSON.parse(item) as T
13
    } catch {
14
      return item as unknown as T
15
    }
16
  }
17
  // ... localStorage/sessionStorage 处理
18
}
19

20
export const STORAGE_KEYS = {
21
  TOKEN: 'access_token',  // 与后端设置的Cookie名称一致
22
  USER_INFO: 'zsk_user_info',
23
  // ... 其他键名
24
} as const