API接口文档

文档概述

本文档详细记录了邮轮穿舱件管理系统-小程序端的API接口规范，涵盖请求封装、加密方法、事件总线等核心模块。通过分析代码结构，提供完整的接口使用说明和架构可视化。

目录

• 1. 请求封装模块
• 2. 加密工具模块
• 3. 事件总线模块
• 4. 用户绑定API模块
• 5. 工具函数模块
• 6. 配置管理模块
• 7. 系统架构图
• 8. 依赖关系分析

1. 请求封装模块

1.1 核心请求函数

请求封装模块位于 api/request.js，提供统一的HTTP请求处理功能。

核心功能特性：

• 自动添加Bearer Token认证头
• 支持GET/POST/DELETE等HTTP方法
• 统一的错误处理机制
• 可配置的延迟模拟（用于Mock测试）

代码实现：

function request(url, method = 'GET', data = {}) {
  const header = {
    'content-type': 'application/json',
  };
  
  // 自动添加Token认证
  const tokenString = wx.getStorageSync('access_token');
  if (tokenString) {
    header.Authorization = `Bearer ${tokenString}`;
  }
  
  return new Promise((resolve, reject) => {
    wx.request({
      url: baseUrl + url,
      method,
      data,
      dataType: 'json',
      header,
      success(res) {
        // HTTP状态码为200或201视为成功
        if (res.statusCode === 200 || res.statusCode === 201) {
          resolve(res.data);
        } else {
          reject({
            statusCode: res.statusCode,
            message: res.data?.detail || '请求失败',
            data: res.data
          });
        }
      },
      fail(err) {
        reject(err);
      }
    });
  });
}

使用示例：

import request from './request';

// GET请求示例
const getUserInfo = () => request('/api/user/info');

// POST请求示例  
const updateUser = (data) => request('/api/user/update', 'POST', data);

参考文件：

• request.js

1.2 请求流程控制图

flowchart TD
    A[调用request函数] --> B[构建请求头]
    B --> C{Token是否存在?}
    C -->|是| D[添加Authorization头]
    C -->|否| E[使用基础请求头]
    D --> F[发送wx.request]
    E --> F
    F --> G{请求成功?}
    G -->|是| H{状态码200/201?}
    G -->|否| I[触发fail回调]
    H -->|是| J[resolve返回数据]
    H -->|否| K[reject错误信息]
    I --> L[reject网络错误]
    J --> M[请求完成]
    K --> M
    L --> M

2. 加密工具模块

2.1 MD5加密函数

加密工具模块位于 utils/crypto.js，提供MD5加密功能。

功能特性：

• 实现标准的MD5加密算法
• 支持字符串加密处理
• 包含完整的MD5算法组件

核心算法组件：

// MD5核心函数
function F(x, y, z) { return (x & y) | ((~x) & z); }
function G(x, y, z) { return (x & z) | (y & (~z)); }
function H(x, y, z) { return (x ^ y ^ z); }
function I(x, y, z) { return (y ^ (x | (~z))); }

// MD5轮函数
function FF(a, b, c, d, x, s, ac) {
  a = addUnsigned(a, addUnsigned(addUnsigned(F(b, c, d), x), ac));
  return addUnsigned(rotateLeft(a, s), b);
}

使用示例：

import { md5 } from './crypto';

const encrypted = md5('password123');
console.log(encrypted); // 输出MD5加密结果

参考文件：

• crypto.js

2.2 加密算法流程图

flowchart TD
    A[输入字符串] --> B[初始化MD5缓冲区]
    B --> C[填充消息]
    C --> D[处理512位数据块]
    D --> E[应用MD5轮函数]
    E --> F{还有数据块?}
    F -->|是| D
    F -->|否| G[生成最终哈希值]
    G --> H[输出MD5结果]
    
    subgraph MD5轮函数处理
        E1[FF函数] --> E2[GG函数] --> E3[HH函数] --> E4[II函数]
    end
    
    E --> E1

3. 事件总线模块

3.1 事件总线实现

事件总线模块位于 utils/eventBus.js，提供发布-订阅模式的事件管理。

核心功能：

• 事件注册与监听
• 事件触发与传播
• 事件监听器管理

实现代码：

export default function createBus() {
  return {
    events: {},
    on(event, callback) {
      if (!this.events[event]) this.events[event] = [];
      this.events[event].push(callback);
    },
    off(event, callback) {
      if (!this.events[event]) return;
      if (!callback) this.events[event] = [];
      else {
        const index = this.events[event].indexOf(callback);
        if (index !== -1) this.events[event].splice(index, 1);
      }
    },
    emit(event, ...args) {
      if (this.events[event]) this.events[event].forEach((callback) => callback(...args));
    },
  };
}

使用示例：

import createBus from './eventBus';

const eventBus = createBus();

// 监听事件
eventBus.on('userLogin', (userData) => {
  console.log('用户登录:', userData);
});

// 触发事件
eventBus.emit('userLogin', { username: 'admin', userId: 123 });

参考文件：

• eventBus.js

3.2 事件总线序列图

sequenceDiagram
    participant A as 组件A
    participant EB as 事件总线
    participant B as 组件B
    participant C as 组件C
    
    A->>EB: emit('dataUpdate', data)
    EB->>B: callback(data)
    EB->>C: callback(data)
    
    B->>EB: on('dataUpdate', callback)
    C->>EB: on('dataUpdate', callback)
    
    B->>EB: off('dataUpdate', callback)
    EB->>B: 移除监听器

4. 用户绑定API模块

4.1 用户绑定接口

用户绑定API模块位于 api/bindUser.js，提供用户账户绑定相关功能。

接口列表：

接口名称	方法	路径	参数	描述
getCurrentUser	GET	/api/user/current	无	获取当前用户信息
bindAccount	POST	/api/bind/account	username, password, openid	绑定系统账户
getBindStatus	GET	/api/bind/status	openid	获取绑定状态
unbindAccount	DELETE	/api/bind/account	openid	解绑账户

接口实现示例：

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

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

参考文件：

• bindUser.js

4.2 用户绑定状态图

stateDiagram-v2
    [*] --> 未绑定
    未绑定 --> 绑定中: bindAccount()
    绑定中 --> 已绑定: 绑定成功
    绑定中 --> 未绑定: 绑定失败
    已绑定 --> 解绑中: unbindAccount()
    解绑中 --> 未绑定: 解绑成功
    解绑中 --> 已绑定: 解绑失败
    已绑定 --> 已绑定: getCurrentUser()

5. 工具函数模块

5.1 工具函数集合

工具函数模块位于 utils/util.js，提供常用的工具函数。

功能函数：

1. 时间格式化

const formatTime = (date) => {
  const year = date.getFullYear();
  const month = date.getMonth() + 1;
  const day = date.getDate();
  const hour = date.getHours();
  const minute = date.getMinutes();
  const second = date.getSeconds();
  
  return `${[year, month, day].map(formatNumber).join('/')} ${[hour, minute, second].map(formatNumber).join(':')}`;
};

2. 文件路径处理

const getLocalUrl = (path, name) => {
  const fs = wx.getFileSystemManager();
  const tempFileName = `${wx.env.USER_DATA_PATH}/${name}`;
  fs.copyFileSync(path, tempFileName);
  return tempFileName;
};

参考文件：

• util.js

6. 配置管理模块

6.1 系统配置

配置管理模块位于 config/index.js，管理应用配置参数。

配置项：

export const config = {
  useMock: true,  // 是否使用Mock数据
};

export default { config };

参考文件：

• index.js

7. 系统架构图

7.1 整体架构依赖关系

flowchart TD
    subgraph API层
        A1[request.js] --> A2[bindUser.js]
    end
    
    subgraph Utils层
        U1[eventBus.js] --> U2[crypto.js]
        U1 --> U3[util.js]
    end
    
    subgraph 配置层
        C1[config/index.js]
    end
    
    subgraph 页面层
        P1[页面组件]
        P2[业务逻辑]
    end
    
    A2 --> P1
    U1 --> P2
    U2 --> A2
    U3 --> P1
    C1 --> A1
    C1 --> U2
    
    style A1 fill:#e1f5fe
    style U1 fill:#f3e5f5
    style C1 fill:#fff3e0
    style P1 fill:#e8f5e8

7.2 模块依赖关系图

graph TD
    A[页面组件] --> B[bindUser.js]
    B --> C[request.js]
    C --> D[config/index.js]
    A --> E[eventBus.js]
    A --> F[util.js]
    B --> G[crypto.js]
    G --> H[MD5算法]
    
    style A fill:#bbdefb
    style B fill:#c8e6c9
    style C fill:#ffecb3
    style D fill:#d7ccc8

8. 依赖关系分析

8.1 直接依赖关系

模块	依赖模块	依赖类型	说明
bindUser.js	request.js	强依赖	API请求基础
request.js	config/index.js	弱依赖	配置参数读取
页面组件	bindUser.js	强依赖	业务API调用
页面组件	eventBus.js	可选依赖	事件通信
bindUser.js	crypto.js	可选依赖	数据加密

8.2 循环依赖分析

经分析，当前代码架构不存在循环依赖问题，各模块依赖关系清晰单向。

8.3 耦合度分析

• request.js: 低耦合，独立请求封装
• eventBus.js: 低耦合，通用事件管理
• bindUser.js: 中等耦合，依赖请求模块
• crypto.js: 低耦合，独立加密算法

索引

本文档详细记录了邮轮穿舱件管理系统小程序端的API接口规范和架构设计。通过模块化的设计，系统具有良好的可维护性和扩展性。核心的请求封装、事件总线、加密工具等模块为业务开发提供了坚实的基础支持。

关键特性索引：

• 统一的HTTP请求封装，支持自动Token认证
• 完整的事件发布-订阅机制
• 标准的MD5加密算法实现
• 清晰的模块依赖关系
• 可配置的Mock数据支持

下一步建议：

1. 完善错误处理机制，增加重试逻辑
2. 添加请求拦截器功能
3. 扩展更多加密算法支持
4. 增加API接口文档自动生成功能