useApiAuth

API 认证 composable，提供登录、登出和 Session 管理，与 nuxt-auth-utils 无缝集成。

Usage

使用自动导入的 useApiAuth composable 管理用户认证，包括登录、登出、Session 管理等功能。与 nuxt-auth-utils 完全集成。

<script setup lang="ts">
// 获取认证相关方法和状态
const { login, clear, loggedIn, user } = useApiAuth()

// 基础登录
const handleLogin = async () => {
  await login({
    loginPath: '/auth/login',
    credentials: {
      username: 'admin',
      password: '123456'
    }
  })

  // 登录成功后跳转
  if (loggedIn.value) {
    navigateTo('/dashboard')
  }
}

// 登出
const handleLogout = async () => {
  await clear()
  navigateTo('/login')
}

// 响应式状态
watchEffect(() => {
  if (loggedIn.value) {
    console.log('当前用户:', user.value)
  }
})
</script>

useApiAuth 基于 nuxt-auth-utils 提供的 Session 管理功能。
支持自动获取用户信息、自定义 token 提取和 session 构建。
登录后 token 会自动添加到后续 API 请求的请求头。

useApiAuth 依赖 nuxt-auth-utils 模块。确保已安装并正确配置该模块。

了解认证相关的全局配置选项

登录流程

login() 方法执行以下步骤:

调用登录接口，传递凭证
从响应中提取 token(通过 tokenExtractor)
如果提供 userInfoPath，使用 token 调用用户信息接口
构建 session 数据(通过 sessionBuilder)
设置 session 到服务端
刷新客户端 session 状态

// 完整流程示例
await login({
  // 1. 登录接口
  loginPath: '/auth/login',
  credentials: { username: 'admin', password: '123456' },

  // 2. 用户信息接口(可选)
  userInfoPath: '/auth/me',

  // 3. 自定义 token 提取
  tokenExtractor: (res) => res.data?.accessToken,

  // 4. 自定义 session 构建
  sessionBuilder: (user, token) => ({
    user: { id: user.id, name: user.name },
    secure: { token, permissions: user.permissions }
  })
})

Token 提取

默认 tokenExtractor 会依次尝试以下路径:

data.token
data.accessToken
token

如果 API 响应格式不同，可以自定义提取逻辑:

// 自定义 token 路径
await login({
  loginPath: '/auth/login',
  credentials: { username: 'admin', password: '123456' },
  tokenExtractor: (res) => res.data?.jwt  // 从 data.jwt 提取
})

// 复杂嵌套结构
await login({
  loginPath: '/auth/login',
  credentials: { username: 'admin', password: '123456' },
  tokenExtractor: (res) => res.data?.session?.accessToken
})

Session 构建

默认 sessionBuilder 构建以下 session 结构:

{
  user: User,           // 用户信息
  token: string,        // 访问令牌
  loggedInAt: string    // 登录时间(ISO 格式)
}

可以自定义 session 结构，例如分离敏感数据:

await login({
  loginPath: '/auth/login',
  credentials: { username: 'admin', password: '123456' },
  sessionBuilder: (user, token) => ({
    user: {
      id: user.id,
      name: user.name,
      avatar: user.avatar
    },
    secure: {
      token,
      refreshToken: user.refreshToken,
      permissions: user.permissions
    }
  })
})

nuxt-auth-utils 会自动加密 secure 字段，保护敏感数据。

Session 配置

通过 sessionConfig 选项可以自定义 Session 的行为，包括过期时间、Cookie 配置等。

默认配置

nuxt.config.ts

{
  name: useSiteConfig().name,
  password: process.env.NUXT_SESSION_PASSWORD || '',
  cookie: {
    sameSite: 'lax'
  }
}

生产环境务必设置 NUXT_SESSION_PASSWORD 环境变量，用于加密 Session 数据。建议使用至少 32 位的随机字符串。

了解更多 Session 配置选项，请参考 nuxt-auth-utils 文档

用户信息获取

有两种方式获取用户信息:

方式 1: 从登录响应获取

// 登录响应包含用户信息
await login({
  loginPath: '/auth/login',
  credentials: { username: 'admin', password: '123456' }
})

// 用户信息从登录响应的 data 字段提取

登录响应格式示例:

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "id": 1,
    "name": "Admin",
    "email": "admin@example.com"
  }
}

方式 2: 调用独立的用户信息接口

// 使用 userInfoPath 自动调用用户信息接口
await login({
  loginPath: '/auth/login',
  credentials: { username: 'admin', password: '123456' },
  userInfoPath: '/auth/me'  // 使用 token 调用此接口
})

此方式会自动:

从登录响应提取 token
使用 token 调用 /auth/me
将用户信息接口的响应作为用户数据

API

useApiAuth()

useApiAuth(): UseApiAuthReturn

创建认证管理器。

Returns

返回包含以下方法和属性的认证管理器对象:

<LoginRData = unknown>(options: LoginOptions<LoginRData>) => Promise<LoginResult>

执行登录流程。

loggedIn

Ref<boolean>

是否已登录(响应式)。

user

Ref<User | null>

当前用户信息(响应式)。

session

Ref<UserSession | null>

当前 session 数据(响应式)。

fetch()

() => Promise<void>

刷新 session 状态。

clear()

() => Promise<void>

清除 session(登出)。

Changelog

91089 — refactor: 自动推断站点配置并简化 Session 配置

70c6d — refactor: 完善 useApiAuth Session 配置并修正类型导出

56c83 — feat: 支持自定义 Session 配置

f2709 — refactor: 重构 API 配置架构并新增上传下载组件

b0c67 — refactor: 简化 API 模块类型和认证流程

36ab5 — feat: ✨ 增加 UserSession.token 类型并将 token 存储在 session 公开字段

useClientApiFetch

仅客户端执行的 API 请求 composable，适用于非 SEO 敏感数据。

useUploadWithProgress

带进度监控的文件上传 composable，支持实时进度和取消上传。