API 快速开始

认证流程

系统使用 JWT（JSON Web Token）进行身份认证，流程如下：

Token 说明

Token	有效期	存储位置	用途
accessToken	2 小时	内存	访问 API 资源
refreshToken	7 天	localStorage	刷新 accessToken

请求头规范

所有需要认证的接口必须携带以下请求头：

Authorization: Bearer {accessToken}
Content-Type: application/json

Token 刷新机制

当 accessToken 过期时，前端会自动使用 refreshToken 刷新：

// src/utils/request.ts
axiosInstance.interceptors.response.use(
  response => response,
  async error => {
    if (error.response?.status === 401) {
      const refreshToken = localStorage.getItem('refreshToken')
      if (refreshToken) {
        const res = await axios.post('/api/v1/auth/refresh', { refreshToken })
        const newToken = res.data.data.accessToken
        // 更新 Token 并重试原请求
        localStorage.setItem('accessToken', newToken)
        error.config.headers.Authorization = `Bearer ${newToken}`
        return axios.request(error.config)
      }
    }
    return Promise.reject(error)
  }
)

请求签名

部分敏感接口（如支付）需要额外的请求签名：

1. 将请求参数按字母顺序排序
2. 拼接成 key1=value1&key2=value2 格式
3. 使用 HMAC-SHA256 签名
4. 将签名放入 X-Signature 请求头

import CryptoJS from 'crypto-js'

function generateSignature(params: Record<string, any>, secret: string) {
  const sortedKeys = Object.keys(params).sort()
  const query = sortedKeys.map(k => `${k}=${params[k]}`).join('&')
  return CryptoJS.HmacSHA256(query, secret).toString()
}

统一响应格式

所有接口遵循统一响应格式：

interface ApiResponse<T> {
  code: string      // 状态码（见错误码表）
  message: string   // 提示信息
  data: T          // 业务数据
}

下一步

• 认证接口 - 登录、登出、刷新 Token
• 错误码速查 - 完整错误码对照表
• 用户接口 - 用户管理 API