跳到主要内容

邮轮穿舱件管理系统-小程序端 API接口文档

文档概述​

本文档详细记录了邮轮穿舱件管理系统小程序端的API接口规范，重点分析bindUser.js等核心接口的请求参数、响应格式和错误处理机制。通过系统架构图、序列图和类图等可视化工具，全面展示接口间的依赖关系和执行流程。

参考源文件：

系统架构概览​

整体架构图​

flowchart TD
    subgraph 前端层
        A[页面组件] --> B[API接口层]
        A --> C[行为模块]
    end
    
    subgraph API接口层
        B --> D[请求封装层]
        D --> E[配置管理]
    end
    
    subgraph 后端服务
        F[用户服务] --> G[绑定服务]
        H[认证服务] --> G
    end
    
    E --> F
    D --> F
    D --> G
    D --> H
    
    style B fill:#e1f5fe
    style D fill:#f3e5f5

模块依赖关系​

flowchart LR
    A[bindUser页面] --> B[bindUser.js API]
    A --> C[useToast行为]
    B --> D[request.js]
    D --> E[config配置]
    C --> F[TD组件库]
    
    style B fill:#fff3e0
    style D fill:#e8f5e8

API接口详细分析​

1. 请求封装层 (request.js)​

核心功能： 统一处理HTTP请求，包含认证、错误处理和配置管理。

请求参数格式​

// 基础请求结构
{
  url: '/api/endpoint',
  method: 'GET|POST|PUT|DELETE',
  data: {}, // 请求数据
  header: {
    'content-type': 'application/json',
    'Authorization': 'Bearer {token}'
  }
}

错误处理机制​

flowchart TD
    A[发起请求] --> B{请求状态}
    B -->|成功| C[检查HTTP状态码]
    B -->|失败| D[网络错误处理]
    
    C -->|200/201| E[解析响应数据]
    C -->|其他状态码| F[业务错误处理]
    
    E --> G[返回成功结果]
    F --> H[抛出错误对象]
    D --> H
    
    H --> I[错误信息展示]

错误对象结构：

{
  statusCode: 400, // HTTP状态码
  message: '错误描述', // 错误消息
  data: {} // 原始响应数据
}

参考源文件： request.js

2. 用户绑定接口 (bindUser.js)​

2.1 获取当前用户信息​

接口定义：

export const getCurrentUser = () => {
  return request({
    url: '/api/user/current',
    method: 'GET'
  });
};

请求参数： 无

响应格式：

{
  id: '用户ID',
  username: '用户名',
  email: '邮箱',
  sms: '短信验证',
  status: '状态',
  openid: '微信OpenID',
  is_system: false, // 是否系统账户
  created_at: '创建时间',
  updated_at: '更新时间'
}

错误处理：

  • 401: 未授权，需要重新登录
  • 404: 用户不存在
  • 500: 服务器内部错误

参考源文件： bindUser.js

2.2 绑定系统账户​

接口定义：

export const bindAccount = (data) => {
  return request({
    url: '/api/bind/account',
    method: 'POST',
    data
  });
};

请求参数：

{
  username: '系统用户名', // 必填，至少3个字符
  password: '系统密码',   // 必填，至少6个字符
  openid: '微信OpenID'   // 必填
}

响应格式：

{
  success: true,
  message: '绑定成功',
  data: {
    user_id: '用户ID',
    bind_time: '绑定时间'
  }
}

错误处理：

  • 400: 参数验证失败
  • 401: 认证失败
  • 409: 账户已绑定
  • 500: 绑定过程错误

参考源文件： bindUser.js

2.3 获取绑定状态​

接口定义：

export const getBindStatus = (openid) => {
  return request({
    url: '/api/bind/status',
    method: 'GET',
    data: { openid }
  });
};

请求参数：

{
  openid: '微信OpenID' // 必填
}

响应格式：

{
  is_bound: true,      // 是否已绑定
  bind_time: '绑定时间', // 绑定时间戳
  user_info: {}        // 用户信息（如果已绑定）
}

参考源文件： bindUser.js

2.4 解绑账户​

接口定义：

export const unbindAccount = (openid) => {
  return request({
    url: '/api/bind/account',
    method: 'DELETE',
    data: { openid }
  });
};

请求参数：

{
  openid: '微信OpenID' // 必填
}

响应格式：

{
  success: true,
  message: '解绑成功'
}

错误处理：

  • 404: 绑定关系不存在
  • 500: 解绑过程错误

参考源文件： bindUser.js

3. 页面级接口调用分析​

绑定页面执行流程​

sequenceDiagram
    participant User as 用户
    participant Page as 绑定页面
    participant API as bindUser.js
    participant Request as request.js
    participant Backend as 后端服务
    
    User->>Page: 进入绑定页面
    Page->>API: getCurrentUser()
    API->>Request: 发起GET请求
    Request->>Backend: /api/user/current
    Backend-->>Request: 返回用户数据
    Request-->>API: 处理响应
    API-->>Page: 返回用户信息
    
    User->>Page: 输入绑定信息
    Page->>Page: validateForm()验证
    Page->>API: bindAccount(bindData)
    API->>Request: 发起POST请求
    Request->>Backend: /api/bind/account
    Backend-->>Request: 绑定结果
    Request-->>API: 处理响应
    API-->>Page: 返回绑定结果
    
    Page->>User: 显示绑定结果

表单验证逻辑​

flowchart TD
    A[开始绑定] --> B[表单验证]
    B --> C{用户名验证}
    C -->|为空| D[显示错误：请输入用户名]
    C -->|长度<3| E[显示错误：用户名至少3字符]
    C -->|格式错误| F[显示错误：只能包含字母数字下划线]
    C -->|通过| G{密码验证}
    
    G -->|为空| H[显示错误：请输入密码]
    G -->|长度<6| I[显示错误：密码至少6字符]
    G -->|通过| J[执行绑定操作]
    
    D --> K[验证失败]
    E --> K
    F --> K
    H --> K
    I --> K

参考源文件： bindUser/index.js

4. 错误处理机制详解​

4.1 网络层错误处理​

处理流程：

  1. 检查网络连接状态
  2. 设置请求超时时间
  3. 处理HTTP状态码异常
  4. 统一错误信息展示
// 错误处理示例
try {
  const result = await bindAccount(bindData);
  // 处理成功结果
} catch (error) {
  if (error.statusCode === 401) {
    // 认证失败，跳转到登录页
    wx.reLaunch({ url: '/pages/login/index' });
  } else if (error.statusCode === 409) {
    // 冲突错误，显示具体提示
    wx.showToast({ title: '该账户已被绑定', icon: 'error' });
  } else {
    // 通用错误处理
    wx.showToast({ title: error.message || '操作失败', icon: 'error' });
  }
}

4.2 业务逻辑错误处理​

未绑定状态检测：

checkUnboundStatus(username) {
  return username && username.startsWith('UNBIND_');
}

参考源文件： bindUser/index.js

5. 配置管理​

基础配置​

export const config = {
  useMock: true,      // 是否使用Mock数据
  baseUrl: '服务地址', // 后端API基础地址
  isMock: false       // Mock模式标识
};

参考源文件： config/index.js

6. 类关系图​

classDiagram
    class BindUserPage {
        +data: Object
        +onLoad(): void
        +getCurrentUserInfo(): Promise
        +validateForm(): boolean
        +onBindAccount(): Promise
    }
    
    class BindUserAPI {
        +getCurrentUser(): Promise
        +bindAccount(data): Promise
        +getBindStatus(openid): Promise
        +unbindAccount(openid): Promise
    }
    
    class RequestUtil {
        +request(url, method, data): Promise
        -buildHeaders(): Object
        -handleResponse(res): Object
        -handleError(err): Error
    }
    
    class UseToastBehavior {
        +onShowToast(selector, message): void
        +onHideToast(selector): void
    }
    
    BindUserPage --> BindUserAPI : 使用
    BindUserPage --> UseToastBehavior : 混入
    BindUserAPI --> RequestUtil : 依赖
    RequestUtil --> Config : 配置

性能优化建议​

1. 请求优化​

  • 使用请求缓存减少重复调用
  • 实现请求防抖避免频繁操作
  • 设置合理的超时时间

2. 错误处理优化​

  • 实现错误重试机制
  • 添加网络状态检测
  • 提供详细的错误日志

3. 用户体验优化​

  • 添加加载状态提示
  • 实现表单自动保存
  • 提供操作确认机制

索引​

本文档全面分析了邮轮穿舱件管理系统小程序端的API接口架构，重点记录了bindUser.js等核心接口的详细规范。通过系统化的架构分析和可视化展示，为开发人员提供了清晰的接口使用指南和错误处理方案。

关键特性：

  • 统一的请求封装和错误处理机制
  • 完善的表单验证和用户反馈
  • 清晰的模块依赖关系
  • 详细的执行流程文档

下一步建议：

  1. 根据实际业务需求调整接口参数
  2. 完善Mock数据支持开发测试
  3. 添加接口性能监控和日志记录
  4. 定期更新接口文档保持同步