XTan 主题

Appearance

权鉴接口 ​

类说明 ​

Accounts 类提供用户账户相关的功能，包括登录、注册、密码重置、头像上传和登出等。

功能特点：

  • 支持用户名/邮箱登录
  • 邮箱验证码注册
  • 忘记密码和重置密码
  • 头像上传（支持审核机制）
  • IP限流和防暴力破解
  • JWT Token认证

安全机制：

  • IP级别登录尝试限制（5次失败后锁定15分钟）
  • 邮箱发送频率限制（单IP每日10次，单邮箱每日10次）
  • CSRF保护（状态变更接口需要X-WP-Nonce头）
  • 密码强度验证（最少6位）

用户登录 ​

Method : POST

URL : /wp-json/vtheme/v1/accounts/login

Auth required : False

Headers :

  • Content-Type: application/json

Body :

json
{
  "username": "admin",
  "password": "123456"
}

参数说明：

  • username : [string] 用户名或邮箱
  • password : [string] 密码

Success Response ​

Code : 200 OK

Content example :

json
{
  "user_id": 1,
  "username": "admin",
  "email": "admin@example.com",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

返回字段说明：

  • user_id : 用户ID
  • username : 用户名
  • email : 邮箱
  • access_token : JWT Token，用于后续API请求认证

Error Response ​

Code : 400 Bad Request

Content example :

json
{
  "error": {
    "code": "missing_fields",
    "message": "Please fill in all required fields"
  }
}

Code : 401 Unauthorized

Content example :

json
{
  "error": {
    "code": "login_failed",
    "message": "Invalid username or password"
  }
}

Code : 429 Too Many Requests

Content example :

json
{
  "error": {
    "code": "too_many_attempts",
    "message": "Too many login attempts. Please try again later."
  }
}

用户注册 ​

Method : POST

URL : /wp-json/vtheme/v1/accounts/register

Auth required : False

Headers :

  • Content-Type: application/json

Body :

json
{
  "username": "newuser",
  "email": "newuser@example.com",
  "password": "123456",
  "verification_code": "123456"
}

参数说明：

  • username : [string] 用户名
  • email : [string] 邮箱地址
  • password : [string] 密码（至少6位）
  • verification_code : [string] 邮箱验证码

Success Response ​

Code : 201 Created

Content example :

json
{
  "user_id": 2,
  "username": "newuser",
  "email": "newuser@example.com",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

注意： 注册成功后会自动登录并返回JWT Token

Error Response ​

Code : 400 Bad Request

Content examples :

json
{
  "error": {
    "code": "missing_fields",
    "message": "Please fill in all required fields"
  }
}
json
{
  "error": {
    "code": "weak_password",
    "message": "Password must be at least 6 characters long"
  }
}
json
{
  "error": {
    "code": "invalid_verification_code",
    "message": "Verification code is incorrect or expired"
  }
}

Code : 409 Conflict

Content examples :

json
{
  "error": {
    "code": "username_exists",
    "message": "Username already exists"
  }
}
json
{
  "error": {
    "code": "email_exists",
    "message": "Email has been registered"
  }
}

发送注册验证码 ​

Method : POST

URL : /wp-json/vtheme/v1/accounts/send-verification-code

Auth required : False

Headers :

  • Content-Type: application/json

Body :

json
{
  "email": "newuser@example.com"
}

参数说明：

  • email : [string] 邮箱地址

Success Response ​

Code : 200 OK

Content example :

json
{
  "message": "Verification code has been sent to your email"
}

Error Response ​

Code : 400 Bad Request

Content examples :

json
{
  "error": {
    "code": "missing_email",
    "message": "Please enter your email address"
  }
}
json
{
  "error": {
    "code": "invalid_email",
    "message": "Please enter a valid email address"
  }
}

Code : 409 Conflict

Content example :

json
{
  "error": {
    "code": "email_exists",
    "message": "This email has been registered"
  }
}

Code : 429 Too Many Requests

Content examples :

json
{
  "error": {
    "code": "daily_limit",
    "message": "This email has reached the daily sending limit."
  }
}
json
{
  "error": {
    "code": "too_frequent",
    "message": "This IP has reached the daily sending limit."
  }
}

Code : 500 Internal Server Error

Content example :

json
{
  "error": {
    "code": "email_send_failed",
    "message": "Failed to send verification code, please try again later"
  }
}

忘记密码 ​

Method : POST

URL : /wp-json/vtheme/v1/accounts/forgot-password

Auth required : False

Headers :

  • Content-Type: application/json

Body :

json
{
  "email": "user@example.com"
}

参数说明：

  • email : [string] 注册的邮箱地址

Success Response ​

Code : 200 OK

Content example :

json
{
  "message": "Password reset verification code has been sent to your email"
}

Error Response ​

Code : 400 Bad Request

Content example :

json
{
  "error": {
    "code": "missing_email",
    "message": "Please enter your email address"
  }
}

Code : 404 Not Found

Content example :

json
{
  "error": {
    "code": "user_not_found",
    "message": "No account found associated with this email"
  }
}

Code : 429 Too Many Requests

Content example :

json
{
  "error": {
    "code": "daily_limit",
    "message": "This email has reached the daily sending limit."
  }
}

Code : 500 Internal Server Error

Content example :

json
{
  "error": {
    "code": "email_send_failed",
    "message": "Failed to send email, please contact administrator"
  }
}

重置密码 ​

Method : POST

URL : /wp-json/vtheme/v1/accounts/reset-password

Auth required : False

Headers :

  • Content-Type: application/json

Body :

json
{
  "email": "user@example.com",
  "code": "123456",
  "new_password": "newpass123"
}

参数说明：

  • email : [string] 邮箱地址
  • code : [string] 收到的验证码
  • new_password : [string] 新密码（至少6位）

Success Response ​

Code : 200 OK

Content example :

json
{
  "message": "Password reset successful"
}

注意： 密码重置成功后会自动登录

Error Response ​

Code : 400 Bad Request

Content examples :

json
{
  "error": {
    "code": "missing_fields",
    "message": "Please fill in all required fields"
  }
}
json
{
  "error": {
    "code": "weak_password",
    "message": "Password must be at least 6 characters long"
  }
}
json
{
  "error": {
    "code": "invalid_verification_code",
    "message": "Verification code is incorrect or expired"
  }
}
json
{
  "error": {
    "code": "verification_code_expired",
    "message": "Verification code has expired, please request a new one"
  }
}
json
{
  "error": {
    "code": "verification_code_mismatch",
    "message": "Verification code is incorrect"
  }
}

上传头像 ​

Method : POST

URL : /wp-json/vtheme/v1/accounts/upload-avatar

Auth required : True

Headers :

  • Authorization: Bearer

Form Data :

  • avatar : [file] 头像文件 (JPG/PNG/GIF, 最大5MB)

Success Response ​

Code : 200 OK

Content example (启用审核) :

json
{
  "success": true,
  "message": "Avatar submitted, waiting for review",
  "status": "pending"
}

Content example (未启用审核) :

json
{
  "success": true,
  "message": "Avatar uploaded successfully",
  "avatar_url": "http://example.com/avatar.jpg",
  "status": "approved"
}

Error Response ​

Code : 400 Bad Request

Content examples :

json
{
  "error": {
    "code": "missing_file",
    "message": "Please select an avatar file to upload"
  }
}
json
{
  "error": {
    "code": "invalid_file_type",
    "message": "Only JPG, PNG or GIF format images are allowed"
  }
}
json
{
  "error": {
    "code": "file_too_large",
    "message": "Avatar file size cannot exceed 5MB"
  }
}
json
{
  "success": false,
  "message": "You already have an avatar pending review"
}

Code : 401 Unauthorized

Content examples :

json
{
  "error": {
    "code": "unauthorized",
    "message": "Please login first"
  }
}
json
{
  "error": {
    "code": "unauthorized",
    "message": "You do not have permission to upload avatar"
  }
}

Code : 500 Internal Server Error

Content example :

json
{
  "success": false,
  "message": "具体错误信息"
}

获取当前用户信息 ​

Method : GET

URL : /wp-json/vtheme/v1/accounts/current-user

Auth required : True

Headers :

  • Authorization: Bearer

Success Response ​

Code : 200 OK

Content example :

json
{
  "user_id": 1,
  "username": "admin",
  "email": "admin@example.com",
  "display_name": "管理员",
  "avatar_url": "http://example.com/avatar.jpg",
  "registered_date": "2023-01-01 12:00:00"
}

Error Response ​

Code : 401 Unauthorized

Content example :

json
{
  "error": {
    "code": "unauthorized",
    "message": "Please login first"
  }
}

Code : 404 Not Found

Content example :

json
{
  "error": {
    "code": "user_not_found",
    "message": "User does not exist"
  }
}

用户登出 ​

Method : POST

URL : /wp-json/vtheme/v1/accounts/logout

Auth required : True

Headers :

  • Authorization: Bearer

Success Response ​

Code : 200 OK

Content example :

json
{
  "message": "Logout successful"
}

Error Response ​

Code : 401 Unauthorized

Content example :

json
{
  "error": {
    "code": "unauthorized",
    "message": "Please login first"
  }
}

使用示例 ​

登录 ​

javascript
// 用户登录
fetch('/wp-json/vtheme/v1/accounts/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    username: 'admin',
    password: '123456'
  })
})
.then(response => response.json())
.then(data => {
  if (data.access_token) {
    // 保存Token
    localStorage.setItem('jwt_token', data.access_token);
    console.log('登录成功，用户ID:', data.user_id);
    
    // 后续请求携带Token
    fetch('/wp-json/vtheme/v1/orders', {
      headers: {
        'Authorization': 'Bearer ' + data.access_token
      }
    });
  }
})
.catch(error => {
  console.error('登录失败:', error);
});

注册流程 ​

javascript
// 步骤1：发送验证码
document.getElementById('send-code-btn').addEventListener('click', () => {
  const email = document.getElementById('email').value;
  
  fetch('/wp-json/vtheme/v1/accounts/send-verification-code', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ email })
  })
  .then(response => response.json())
  .then(data => {
    alert('验证码已发送到您的邮箱');
  })
  .catch(error => {
    console.error('发送失败:', error);
  });
});

// 步骤2：提交注册
document.getElementById('register-btn').addEventListener('click', () => {
  const formData = {
    username: document.getElementById('username').value,
    email: document.getElementById('email').value,
    password: document.getElementById('password').value,
    verification_code: document.getElementById('code').value
  };
  
  fetch('/wp-json/vtheme/v1/accounts/register', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(formData)
  })
  .then(response => response.json())
  .then(data => {
    if (data.access_token) {
      localStorage.setItem('jwt_token', data.access_token);
      alert('注册成功！');
      window.location.href = '/';
    }
  })
  .catch(error => {
    console.error('注册失败:', error);
  });
});

忘记密码流程 ​

javascript
// 步骤1：发送重置验证码
document.getElementById('forgot-btn').addEventListener('click', () => {
  const email = document.getElementById('email').value;
  
  fetch('/wp-json/vtheme/v1/accounts/forgot-password', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ email })
  })
  .then(response => response.json())
  .then(data => {
    alert('重置验证码已发送到您的邮箱');
  })
  .catch(error => {
    console.error('发送失败:', error);
  });
});

// 步骤2：重置密码
document.getElementById('reset-btn').addEventListener('click', () => {
  const formData = {
    email: document.getElementById('email').value,
    code: document.getElementById('code').value,
    new_password: document.getElementById('new-password').value
  };
  
  fetch('/wp-json/vtheme/v1/accounts/reset-password', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(formData)
  })
  .then(response => response.json())
  .then(data => {
    alert('密码重置成功！');
    window.location.href = '/login';
  })
  .catch(error => {
    console.error('重置失败:', error);
  });
});

上传头像 ​

javascript
// 上传头像
document.getElementById('avatar-input').addEventListener('change', (e) => {
  const file = e.target.files[0];
  if (!file) return;
  
  const formData = new FormData();
  formData.append('avatar', file);
  
  fetch('/wp-json/vtheme/v1/accounts/upload-avatar', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + localStorage.getItem('jwt_token')
    },
    body: formData
  })
  .then(response => response.json())
  .then(data => {
    if (data.success) {
      if (data.status === 'pending') {
        alert('头像已提交，等待审核');
      } else {
        alert('头像上传成功');
        // 更新头像显示
        document.getElementById('avatar-img').src = data.avatar_url;
      }
    }
  })
  .catch(error => {
    console.error('上传失败:', error);
  });
});

获取当前用户信息 ​

javascript
// 获取当前用户信息
fetch('/wp-json/vtheme/v1/accounts/current-user', {
  headers: {
    'Authorization': 'Bearer ' + localStorage.getItem('jwt_token')
  }
})
.then(response => response.json())
.then(data => {
  console.log('当前用户:', data);
  document.getElementById('username').textContent = data.display_name;
  document.getElementById('avatar').src = data.avatar_url;
});

登出 ​

javascript
// 用户登出
document.getElementById('logout-btn').addEventListener('click', () => {
  fetch('/wp-json/vtheme/v1/accounts/logout', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + localStorage.getItem('jwt_token')
    }
  })
  .then(response => response.json())
  .then(data => {
    // 清除本地Token
    localStorage.removeItem('jwt_token');
    alert('已退出登录');
    window.location.href = '/login';
  })
  .catch(error => {
    console.error('登出失败:', error);
  });
});

注意事项 ​

  1. 认证方式：

    • 所有需要认证的接口都需要在请求头中携带 Authorization: Bearer {token}
    • Token通过登录或注册接口获取
    • Token有效期由系统配置决定

  2. 限流机制：

    • 登录失败5次后，该IP会被锁定15分钟
    • 发送邮件验证码：单IP每日最多10次，单邮箱每日最多10次
    • 超过限制会返回429状态码

  3. 头像上传：

    • 支持JPG、PNG、GIF格式
    • 文件大小不超过5MB
    • 可配置是否启用审核机制
    • VIP用户可能有特殊权限（根据后台配置）

  4. 验证码：

    • 注册验证码有效期10分钟
    • 密码重置验证码有效期10分钟
    • 使用后自动删除

  5. 安全性：

    • 生产环境登录失败不会返回具体错误原因
    • 密码长度至少6位
    • 使用JWT Token进行API认证
    • 敏感操作有CSRF保护

  6. 自动登录：

    • 注册成功后会自动登录
    • 密码重置成功后会自动登录
    • 同时设置WordPress原生Cookie和JWT Token

  7. 错误处理：

    • 所有错误都返回统一的JSON格式
    • 包含错误代码和错误消息
    • 前端应根据错误代码显示友好提示