微信认证API开发说明手册

概述

本文档为前端开发工程师提供微信认证相关API的详细使用说明，包括路由路径、请求参数、响应格式、错误码说明以及前端示例代码。

基础信息

API基础路径: /api/parse
Content-Type: application/json
字符编码: UTF-8
响应格式: JSON

统一响应格式

所有API接口都遵循统一的JSON响应格式：

{
  "reason": "successed|failed",
  "return_code": 200,
  "result": {
    // 具体数据对象
  },
  "error": "错误信息（仅在失败时返回）"
}

HTTP状态码说明

状态码	说明
200	请求成功
201	创建成功
400	请求参数错误
401	认证失败
404	资源不存在
409	资源冲突（如用户已存在）
500	服务器内部错误

1. 用户注册

接口信息

路径: POST /api/parse/wechat-register
功能: 注册新的微信用户
认证: 无需认证

请求参数

参数名	类型	必填	说明	示例
wechat_code	string	是	微信授权码/openid	"wx_openid_123456"
phone_number	string	否	手机号码	"13800138000"
id_card_number	string	否	身份证号码	"110101199001011234"

请求示例

{
  "wechat_code": "wx_openid_123456",
  "phone_number": "13800138000",
  "id_card_number": "110101199001011234"
}

响应示例

成功响应 (201)

{
  "reason": "successed",
  "return_code": 201,
  "result": {
    "id": "1",
    "wechat_code": "wx_openid_123456",
    "phone_number": "13800138000",
    "id_card_number": "110101199001011234",
    "login_status": false,
    "user_status": "active",
    "created_at": "2024-01-15T10:30:00+08:00"
  }
}

失败响应 (409)

{
  "reason": "failed",
  "return_code": 409,
  "result": null,
  "error": "用户已存在，微信授权码: wx_openid_123456"
}

前端示例代码

JavaScript (Fetch API)

async function registerWechatUser(wechatCode, phoneNumber = null, idCardNumber = null) {
  try {
    const response = await fetch('/api/parse/wechat-register', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        wechat_code: wechatCode,
        phone_number: phoneNumber,
        id_card_number: idCardNumber
      })
    });
    
    const data = await response.json();
    
    if (data.return_code === 201) {
      console.log('注册成功:', data.result);
      return { success: true, data: data.result };
    } else {
      console.error('注册失败:', data.error);
      return { success: false, error: data.error };
    }
  } catch (error) {
    console.error('网络错误:', error);
    return { success: false, error: '网络请求失败' };
  }
}

// 使用示例
registerWechatUser('wx_openid_123456', '13800138000', '110101199001011234')
  .then(result => {
    if (result.success) {
      // 注册成功处理
      alert('注册成功！');
    } else {
      // 注册失败处理
      alert('注册失败: ' + result.error);
    }
  });

jQuery

function registerWechatUser(wechatCode, phoneNumber, idCardNumber) {
  $.ajax({
    url: '/api/parse/wechat-register',
    type: 'POST',
    contentType: 'application/json',
    data: JSON.stringify({
      wechat_code: wechatCode,
      phone_number: phoneNumber,
      id_card_number: idCardNumber
    }),
    success: function(data) {
      if (data.return_code === 201) {
        console.log('注册成功:', data.result);
        alert('注册成功！');
      } else {
        console.error('注册失败:', data.error);
        alert('注册失败: ' + data.error);
      }
    },
    error: function(xhr, status, error) {
      console.error('请求失败:', error);
      alert('网络请求失败');
    }
  });
}

2. 用户登录

接口信息

路径: POST /api/parse/wechat-login
功能: 微信用户登录，更新登录状态和时间
认证: 无需认证

请求参数

参数名	类型	必填	说明	示例
wechat_code	string	是	微信授权码/openid	"wx_openid_123456"

请求示例

{
  "wechat_code": "wx_openid_123456"
}

响应示例

成功响应 (200)

{
  "reason": "successed",
  "return_code": 200,
  "result": {
    "id": "1",
    "wechat_code": "wx_openid_123456",
    "phone_number": "13800138000",
    "id_card_number": "110101199001011234",
    "login_status": true,
    "login_time": "2024-01-15T14:30:00+08:00",
    "user_status": "active"
  }
}

失败响应 (401)

{
  "reason": "failed",
  "return_code": 401,
  "result": null,
  "error": "用户不存在或账户状态异常"
}

前端示例代码

JavaScript (Fetch API)

async function loginWechatUser(wechatCode) {
  try {
    const response = await fetch('/api/parse/wechat-login', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        wechat_code: wechatCode
      })
    });
    
    const data = await response.json();
    
    if (data.return_code === 200) {
      console.log('登录成功:', data.result);
      // 保存用户信息到本地存储
      localStorage.setItem('wechat_user', JSON.stringify(data.result));
      return { success: true, data: data.result };
    } else {
      console.error('登录失败:', data.error);
      return { success: false, error: data.error };
    }
  } catch (error) {
    console.error('网络错误:', error);
    return { success: false, error: '网络请求失败' };
  }
}

// 使用示例
loginWechatUser('wx_openid_123456')
  .then(result => {
    if (result.success) {
      // 登录成功处理
      window.location.href = '/dashboard';
    } else {
      // 登录失败处理
      alert('登录失败: ' + result.error);
    }
  });

Axios

import axios from 'axios';

async function loginWechatUser(wechatCode) {
  try {
    const response = await axios.post('/api/parse/wechat-login', {
      wechat_code: wechatCode
    });
    
    if (response.data.return_code === 200) {
      // 登录成功
      return { success: true, data: response.data.result };
    } else {
      return { success: false, error: response.data.error };
    }
  } catch (error) {
    console.error('登录请求失败:', error);
    return { success: false, error: '网络请求失败' };
  }
}

3. 用户登出

接口信息

路径: POST /api/parse/wechat-logout
功能: 微信用户登出，更新登录状态
认证: 无需认证

请求参数

参数名	类型	必填	说明	示例
wechat_code	string	是	微信授权码/openid	"wx_openid_123456"

请求示例

{
  "wechat_code": "wx_openid_123456"
}

响应示例

成功响应 (200)

{
  "reason": "successed",
  "return_code": 200,
  "result": {
    "message": "用户已成功登出"
  }
}

失败响应 (404)

{
  "reason": "failed",
  "return_code": 404,
  "result": null,
  "error": "用户不存在"
}

前端示例代码

JavaScript (Fetch API)

async function logoutWechatUser(wechatCode) {
  try {
    const response = await fetch('/api/parse/wechat-logout', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        wechat_code: wechatCode
      })
    });
    
    const data = await response.json();
    
    if (data.return_code === 200) {
      console.log('登出成功');
      // 清除本地存储的用户信息
      localStorage.removeItem('wechat_user');
      return { success: true };
    } else {
      console.error('登出失败:', data.error);
      return { success: false, error: data.error };
    }
  } catch (error) {
    console.error('网络错误:', error);
    return { success: false, error: '网络请求失败' };
  }
}

// 使用示例
logoutWechatUser('wx_openid_123456')
  .then(result => {
    if (result.success) {
      // 登出成功处理
      window.location.href = '/login';
    } else {
      // 登出失败处理
      console.error('登出失败:', result.error);
    }
  });

4. 获取用户信息

接口信息

路径: GET /api/parse/wechat-user
功能: 获取指定微信用户的详细信息
认证: 无需认证

请求参数

参数名	类型	必填	传递方式	说明	示例
wechat_code	string	是	Query参数	微信授权码/openid	"wx_openid_123456"

请求示例

GET /api/parse/wechat-user?wechat_code=wx_openid_123456

响应示例

成功响应 (200)

{
  "reason": "successed",
  "return_code": 200,
  "result": {
    "id": "1",
    "wechat_code": "wx_openid_123456",
    "phone_number": "13800138000",
    "id_card_number": "110101199001011234",
    "login_status": true,
    "login_time": "2024-01-15T14:30:00+08:00",
    "user_status": "active",
    "created_at": "2024-01-15T10:30:00+08:00",
    "updated_at": "2024-01-15T14:30:00+08:00"
  }
}

失败响应 (404)

{
  "reason": "failed",
  "return_code": 404,
  "result": null,
  "error": "未找到微信授权码为 wx_openid_123456 的用户"
}

前端示例代码

JavaScript (Fetch API)

async function getWechatUserInfo(wechatCode) {
  try {
    const url = `/api/parse/wechat-user?wechat_code=${encodeURIComponent(wechatCode)}`;
    const response = await fetch(url, {
      method: 'GET',
      headers: {
        'Content-Type': 'application/json',
      }
    });
    
    const data = await response.json();
    
    if (data.return_code === 200) {
      console.log('获取用户信息成功:', data.result);
      return { success: true, data: data.result };
    } else {
      console.error('获取用户信息失败:', data.error);
      return { success: false, error: data.error };
    }
  } catch (error) {
    console.error('网络错误:', error);
    return { success: false, error: '网络请求失败' };
  }
}

// 使用示例
getWechatUserInfo('wx_openid_123456')
  .then(result => {
    if (result.success) {
      // 显示用户信息
      displayUserInfo(result.data);
    } else {
      // 处理错误
      alert('获取用户信息失败: ' + result.error);
    }
  });

function displayUserInfo(userInfo) {
  document.getElementById('user-id').textContent = userInfo.id;
  document.getElementById('user-phone').textContent = userInfo.phone_number || '未设置';
  document.getElementById('user-status').textContent = userInfo.login_status ? '在线' : '离线';
}

jQuery

function getWechatUserInfo(wechatCode) {
  $.ajax({
    url: '/api/parse/wechat-user',
    type: 'GET',
    data: { wechat_code: wechatCode },
    success: function(data) {
      if (data.return_code === 200) {
        console.log('获取用户信息成功:', data.result);
        displayUserInfo(data.result);
      } else {
        console.error('获取用户信息失败:', data.error);
        alert('获取用户信息失败: ' + data.error);
      }
    },
    error: function(xhr, status, error) {
      console.error('请求失败:', error);
      alert('网络请求失败');
    }
  });
}

5. 更新用户信息

接口信息

路径: PUT /api/parse/wechat-user
功能: 更新微信用户的个人信息
认证: 无需认证

请求参数

参数名	类型	必填	说明	示例
wechat_code	string	是	微信授权码/openid	"wx_openid_123456"
phone_number	string	否	要更新的手机号码	"13900139000"
id_card_number	string	否	要更新的身份证号码	"110101199001011234"

请求示例

{
  "wechat_code": "wx_openid_123456",
  "phone_number": "13900139000",
  "id_card_number": "110101199001011234"
}

响应示例

成功响应 (200)

{
  "reason": "successed",
  "return_code": 200,
  "result": {
    "id": "1",
    "wechat_code": "wx_openid_123456",
    "phone_number": "13900139000",
    "id_card_number": "110101199001011234",
    "login_status": true,
    "login_time": "2024-01-15T14:30:00+08:00",
    "user_status": "active",
    "created_at": "2024-01-15T10:30:00+08:00",
    "updated_at": "2024-01-15T16:45:00+08:00"
  }
}

失败响应 (404)

{
  "reason": "failed",
  "return_code": 404,
  "result": null,
  "error": "未找到微信授权码为 wx_openid_123456 的用户"
}

前端示例代码

JavaScript (Fetch API)

async function updateWechatUserInfo(wechatCode, updateData) {
  try {
    const requestData = {
      wechat_code: wechatCode,
      ...updateData
    };
    
    const response = await fetch('/api/parse/wechat-user', {
      method: 'PUT',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(requestData)
    });
    
    const data = await response.json();
    
    if (data.return_code === 200) {
      console.log('更新用户信息成功:', data.result);
      return { success: true, data: data.result };
    } else {
      console.error('更新用户信息失败:', data.error);
      return { success: false, error: data.error };
    }
  } catch (error) {
    console.error('网络错误:', error);
    return { success: false, error: '网络请求失败' };
  }
}

// 使用示例
const updateData = {
  phone_number: '13900139000',
  id_card_number: '110101199001011234'
};

updateWechatUserInfo('wx_openid_123456', updateData)
  .then(result => {
    if (result.success) {
      // 更新成功处理
      alert('信息更新成功！');
      // 更新页面显示的用户信息
      displayUserInfo(result.data);
    } else {
      // 更新失败处理
      alert('更新失败: ' + result.error);
    }
  });

Vue.js 示例

// 在Vue组件中使用
export default {
  data() {
    return {
      userForm: {
        wechatCode: 'wx_openid_123456',
        phoneNumber: '',
        idCardNumber: ''
      },
      loading: false
    };
  },
  methods: {
    async updateUserInfo() {
      this.loading = true;
      
      try {
        const response = await fetch('/api/parse/wechat-user', {
          method: 'PUT',
          headers: {
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({
            wechat_code: this.userForm.wechatCode,
            phone_number: this.userForm.phoneNumber,
            id_card_number: this.userForm.idCardNumber
          })
        });
        
        const data = await response.json();
        
        if (data.return_code === 200) {
          this.$message.success('信息更新成功！');
          // 更新本地用户数据
          this.updateLocalUserData(data.result);
        } else {
          this.$message.error('更新失败: ' + data.error);
        }
      } catch (error) {
        this.$message.error('网络请求失败');
        console.error('更新用户信息失败:', error);
      } finally {
        this.loading = false;
      }
    },
    
    updateLocalUserData(userData) {
      // 更新本地存储的用户数据
      localStorage.setItem('wechat_user', JSON.stringify(userData));
    }
  }
};

错误处理最佳实践

1. 统一错误处理函数

function handleApiError(data) {
  const errorMessages = {
    400: '请求参数错误',
    401: '认证失败',
    404: '资源不存在',
    409: '资源冲突',
    500: '服务器内部错误'
  };
  
  const message = data.error || errorMessages[data.return_code] || '未知错误';
  return message;
}

// 使用示例
async function apiCall() {
  try {
    const response = await fetch('/api/parse/wechat-login', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ wechat_code: 'test' })
    });
    
    const data = await response.json();
    
    if (data.return_code === 200) {
      return { success: true, data: data.result };
    } else {
      const errorMessage = handleApiError(data);
      return { success: false, error: errorMessage };
    }
  } catch (error) {
    return { success: false, error: '网络连接失败' };
  }
}

2. 请求重试机制

async function apiCallWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      const data = await response.json();
      
      // 如果是服务器错误且还有重试次数，则重试
      if (data.return_code === 500 && i < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1))); // 递增延迟
        continue;
      }
      
      return data;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
    }
  }
}

3. 请求拦截器示例 (Axios)

import axios from 'axios';

// 创建axios实例
const apiClient = axios.create({
  baseURL: '/api/parse',
  timeout: 10000,
  headers: {
    'Content-Type': 'application/json'
  }
});

// 响应拦截器
apiClient.interceptors.response.use(
  response => {
    const data = response.data;
    
    if (data.return_code >= 200 && data.return_code < 300) {
      return data;
    } else {
      return Promise.reject(new Error(data.error || '请求失败'));
    }
  },
  error => {
    console.error('API请求失败:', error);
    return Promise.reject(error);
  }
);

// 使用示例
async function loginUser(wechatCode) {
  try {
    const data = await apiClient.post('/wechat-login', {
      wechat_code: wechatCode
    });
    return { success: true, data: data.result };
  } catch (error) {
    return { success: false, error: error.message };
  }
}

常见问题 (FAQ)

Q1: 如何处理网络超时？

A: 建议设置合理的超时时间（如10秒），并提供重试机制：

const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 10000);

fetch('/api/parse/wechat-login', {
  signal: controller.signal,
  // ... 其他选项
}).finally(() => {
  clearTimeout(timeoutId);
});

Q2: 如何存储用户登录状态？

A: 建议使用localStorage或sessionStorage存储用户信息：

// 登录成功后存储
localStorage.setItem('wechat_user', JSON.stringify(userData));

// 检查登录状态
function isUserLoggedIn() {
  const user = localStorage.getItem('wechat_user');
  return user && JSON.parse(user).login_status;
}

// 登出时清除
localStorage.removeItem('wechat_user');

Q3: 如何处理并发请求？

A: 对于同一用户的多个请求，建议使用请求队列或防抖机制：

let pendingRequest = null;

async function loginWithDebounce(wechatCode) {
  if (pendingRequest) {
    return pendingRequest;
  }
  
  pendingRequest = loginWechatUser(wechatCode);
  
  try {
    const result = await pendingRequest;
    return result;
  } finally {
    pendingRequest = null;
  }
}

Q4: 如何实现自动重新登录？

A: 可以在应用启动时检查本地存储的用户信息并验证：

async function autoLogin() {
  const storedUser = localStorage.getItem('wechat_user');
  if (!storedUser) return false;
  
  const userData = JSON.parse(storedUser);
  
  // 验证用户状态是否仍然有效
  const result = await getWechatUserInfo(userData.wechat_code);
  
  if (result.success && result.data.login_status) {
    return true;
  } else {
    // 清除无效的本地数据
    localStorage.removeItem('wechat_user');
    return false;
  }
}

// 应用启动时调用
autoLogin().then(isLoggedIn => {
  if (isLoggedIn) {
    // 跳转到主页面
    window.location.href = '/dashboard';
  } else {
    // 跳转到登录页面
    window.location.href = '/login';
  }
});

版本信息

文档版本: v1.0.0
API版本: v1.0.0
最后更新: 2025-09-02
维护者: DataOps团队

联系支持

如有问题或建议，请联系：

技术支持: tech-support@dataops.com
API文档: https://docs.dataops.com/api
GitHub: https://github.com/dataops/platform

wechat-auth-api-guide.md 20 KB Geçmiş Ham

微信认证API开发说明手册

概述

基础信息

统一响应格式

HTTP状态码说明

1. 用户注册

接口信息

请求参数

请求示例

响应示例

成功响应 (201)

失败响应 (409)

前端示例代码

JavaScript (Fetch API)

jQuery

2. 用户登录

接口信息

请求参数

请求示例

响应示例

成功响应 (200)

失败响应 (401)

前端示例代码

JavaScript (Fetch API)

Axios

3. 用户登出

接口信息

请求参数

请求示例

响应示例

成功响应 (200)

失败响应 (404)

前端示例代码

JavaScript (Fetch API)

4. 获取用户信息

接口信息

请求参数

请求示例

响应示例

成功响应 (200)

失败响应 (404)

前端示例代码

JavaScript (Fetch API)

jQuery

5. 更新用户信息

接口信息

请求参数

请求示例

响应示例

成功响应 (200)

失败响应 (404)

前端示例代码

JavaScript (Fetch API)

Vue.js 示例

错误处理最佳实践

1. 统一错误处理函数

2. 请求重试机制

3. 请求拦截器示例 (Axios)

常见问题 (FAQ)

Q1: 如何处理网络超时？

Q2: 如何存储用户登录状态？

Q3: 如何处理并发请求？

Q4: 如何实现自动重新登录？

版本信息

联系支持

wechat-auth-api-guide.md 20 KB

Geçmiş Ham