MindGuard 开发者指南

字数

6517 字

阅读时间

30 分钟

MindGuard 心理健康支持小程序开发指南
版本：v1.0.0 | 更新时间：2025年10月20日

项目概述
开发环境搭建
项目结构说明
开发流程
代码规范
测试指南
部署流程
贡献指南
故障排除
扩展开发

🎯 项目概述

项目简介

MindGuard 是一个面向高校场景的心理健康支持微信小程序，通过"情绪打卡 → AI建议 → 任务闭环 → 社区守护"的四阶段循环，帮助学生建立健康的心理支持系统。

技术栈

前端: 微信小程序 (WXML/WXSS/JavaScript)
后端: 微信云开发 (CloudBase)
UI框架: TDesign Miniprogram
AI能力: Dify 工作流
数据库: NoSQL (微信云数据库)
构建工具: 微信开发者工具、npm

核心功能

情绪健康闭环: 情绪打卡 → AI建议 → 任务执行 → 行为改善
社区守护系统: 树洞发帖 → 风险识别 → 互助支持 → 危机干预
成长激励体系: 徽章系统 → 周报生成 → 趋势分析 → 成长记录
AI对话系统: 多Agent对话 → 专业支持 → 个性化建议

🛠️ 开发环境搭建

前置要求

基础环境

操作系统: Windows 10+ / macOS 10.14+ / Linux
Node.js: 16.0+ (推荐 18.x LTS)
npm: 8.0+ 或 yarn 1.22+
Git: 2.20+

开发工具

微信开发者工具: 最新稳定版
代码编辑器: VS Code (推荐插件: 微信小程序助手、ESLint、Prettier)
调试工具: Chrome DevTools (小程序调试)

环境配置步骤

1. 安装微信开发者工具

bash

# 下载地址
https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html

# 选择对应平台版本下载安装

2. 配置 Node.js 环境

bash

# 使用 nvm 管理 Node.js 版本 (推荐)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18

# 或直接从官网下载安装
# https://nodejs.org/

3. 克隆项目

bash

# 克隆项目仓库
git clone https://github.com/your-org/MindGuard.git

# 进入项目目录
cd MindGuard

# 查看项目结构
ls -la

4. 安装依赖

bash

# 进入小程序目录
cd miniprogram

# 安装项目依赖
npm install

# 安装 TDesign 组件库
npm install tdesign-miniprogram

# 构建npm (在微信开发者工具中操作)
# 工具 → 构建 npm

5. 配置云开发环境

开通云开发
- 在微信开发者工具中点击"云开发"
- 选择"开通云开发"
- 创建新环境 (环境ID: cloud1-9gpfk3ie94d8630a)

配置环境变量

javascript

// 在 cloudfunctions 中配置
const env = 'cloud1-9gpfk3ie94d8630a';

创建数据库集合

javascript

// 在云开发控制台创建以下集合：
- users (用户信息)
- checkins (情绪打卡)
- behavior_tasks (任务)
- suggestions (建议)
- forum_posts (社区帖子)
- journals (日记)
- ask_sessions (AI对话会话)

开发工具配置

VS Code 插件推荐

json

{
  "recommendations": [
    "wechat-miniprogram.vscode-wxml",
    "wechat-miniprogram.vscode-wechat",
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "ms-vscode.vscode-typescript-next",
    "bradlc.vscode-tailwindcss"
  ]
}

VS Code 设置

json

{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "emmet.includeLanguages": ["wxml"],
  "files.associations": {
    "*.wxml": "html",
    "*.wxss": "css"
  }
}

📁 项目结构说明

整体结构

MindGuard/
├── miniprogram/                # 小程序前端代码
│   ├── pages/                 # 页面文件
│   │   ├── today/            # 今天页面
│   │   ├── tasks/            # 任务页面
│   │   ├── treehole/         # 树洞页面
│   │   ├── journal/          # 随笔页面
│   │   └── mine/             # 我的页面
│   ├── packages/             # 分包
│   │   ├── community/        # 社区分包
│   │   ├── profile/          # 个人资料分包
│   │   ├── journal/          # 日记分包
│   │   ├── tasks/            # 任务分包
│   │   ├── breath/           # 呼吸练习
│   │   └── mindfulness/      # 正念冥想
│   ├── independent/          # 独立分包
│   │   ├── sos/              # SOS紧急求助
│   │   └── heartchat/        # 心语精灵
│   ├── services/             # 服务层API
│   ├── utils/                # 工具函数
│   ├── components/           # 自定义组件
│   ├── miniprogram_npm/      # npm构建产物
│   ├── app.js               # 小程序入口
│   ├── app.json             # 小程序配置
│   └── app.wxss             # 全局样式
├── cloudfunctions/          # 云函数
│   ├── checkinRecorder/      # 情绪打卡
│   ├── taskWorkflow/         # 任务工作流
│   ├── suggestionOrchestrator/ # 建议编排
│   ├── treeholeModeration/   # 树洞审核
│   ├── weeklyReport/         # 周报生成
│   ├── sosRelay/             # SOS中继
│   └── askMessageManager/    # AI对话管理
├── docs/                     # 项目文档
├── dify/                     # Dify工作流配置
└── README.md                # 项目说明

页面结构详解

主包页面 (miniprogram/pages/)

javascript

// 页面命名规范
pages/
├── today/                    // 今天Tab页
│   ├── index.js             // 页面逻辑
│   ├── index.wxml           // 页面结构
│   ├── index.wxss           // 页面样式
│   └── index.json           // 页面配置
│
├── tasks/                    // 任务Tab页
│   ├── index.js
│   ├── index.wxml
│   ├── index.wxss
│   └── index.json
│
├── treehole/                 // 树洞Tab页
├── journal/                  // 随笔Tab页
└── mine/                     // 我的Tab页

分包结构

javascript

packages/
├── community/                // 社区分包
│   ├── post-detail/         // 帖子详情
│   ├── post-editor/         // 发帖编辑
│   ├── drafts/              // 草稿箱
│   └── ...                  // 其他社区页面
│
├── profile/                 // 个人资料分包
│   ├── report-detail/       // 周报详情
│   ├── badge-detail/        // 徽章详情
│   ├── resource-map/        // 资源地图
│   └── ...                  // 其他个人资料页面
│
└── ...                       // 其他分包

服务层结构

javascript

services/
├── auth.js                   // 认证服务
├── checkins.js               // 情绪打卡服务
├── tasks.js                  // 任务管理服务
├── forum.js                  // 社区服务
├── journals.js               // 日记服务
├── suggestions.js            // 微建议服务
├── askMessage.js             // AI对话服务
├── reports.js                // 周报服务
└── ...                       // 其他服务

🔄 开发流程

Git 工作流程

分支策略

main                       # 主分支，生产环境代码
├── develop                # 开发分支，集成测试
├── feature/xxx           # 功能分支
├── bugfix/xxx            # 修复分支
├── release/vx.x.x        # 发布分支
└── hotfix/xxx            # 紧急修复分支

开发流程

创建功能分支
bash
```
git checkout -b feature/new-feature
```

开发和测试

bash

# 进行开发
# 编写测试
# 运行测试
npm test

提交代码

bash

git add .
git commit -m "feat: 添加新功能描述"

推送分支
bash
```
git push origin feature/new-feature
```
创建 Pull Request
- 在 GitHub/GitLab 创建 PR
- 请求代码审查
- 合并到 develop 分支

代码开发流程

1. 需求分析

markdown

## 需求描述
- 功能背景
- 用户场景
- 技术要求

## 技术方案
- 前端实现方案
- 后端API设计
- 数据库设计
- 第三方集成

## 开发计划
- 前端开发任务
- 后端开发任务
- 测试计划
- 上线计划

2. 设计阶段

UI设计: 使用 Figma/Sketch 设计界面
API设计: 定义接口规范
数据库设计: 设计表结构和索引
架构设计: 设计模块间交互

3. 开发阶段

javascript

// 1. 页面开发
// 创建页面文件
// 实现页面逻辑
// 添加样式

// 2. 服务层开发
// 创建服务文件
// 实现API调用
// 添加错误处理

// 3. 云函数开发
// 创建云函数
// 实现业务逻辑
// 添加数据验证

4. 测试阶段

单元测试: 测试函数和组件
集成测试: 测试模块间交互
端到端测试: 测试完整用户流程
性能测试: 测试响应时间和并发

Mock 数据开发

Mock 数据规范

javascript

// services/exampleService.js
const MOCK_EXAMPLE_DATA = [
  {
    id: 'example_001',
    title: '示例数据1',
    status: 'active',
    createdAt: '2024-10-20T10:00:00Z'
  },
  {
    id: 'example_002',
    title: '示例数据2',
    status: 'pending',
    createdAt: '2024-10-20T11:00:00Z'
  }
];

// Mock 数据验证函数
function validateMockData(data) {
  // 验证Mock数据格式
  return data.every(item =>
    item.id &&
    item.title &&
    ['active', 'pending'].includes(item.status)
  );
}

Mock 开发流程

定义数据结构
创建Mock数据
实现Mock API
编写测试用例
验证数据一致性

📝 代码规范

JavaScript 规范

基础规范

javascript

// 1. 使用严格模式
'use strict';

// 2. 优先使用 const/let
const constant = '常量';
let variable = '变量';

// 3. 函数声明
function functionName(param1, param2) {
  // 函数体
  return result;
}

// 4. 箭头函数
const arrowFunction = (param) => {
  return param * 2;
};

// 5. 模板字符串
const message = `Hello ${name}`;

// 6. 解构赋值
const { id, title } = data;
const [first, second] = array;

命名规范

javascript

// 变量和函数: camelCase
const userName = 'john';
const getUserInfo = () => {};

// 常量: UPPER_SNAKE_CASE
const API_BASE_URL = 'https://api.example.com';
const MAX_RETRY_COUNT = 3;

// 类名: PascalCase
class UserService {
  constructor() {}
}

// 文件名: kebab-case
// user-service.js
// checkin-recorder.js

函数规范

javascript

/**
 * 函数描述
 *
 * @param {string} param1 - 参数1描述
 * @param {number} param2 - 参数2描述
 * @returns {Object} 返回值描述
 * @throws {Error} 错误情况描述
 */
async function processData(param1, param2) {
  try {
    // 参数验证
    if (!param1) {
      throw new Error('param1 is required');
    }

    // 业务逻辑
    const result = await someAsyncOperation(param1, param2);

    // 返回结果
    return {
      success: true,
      data: result
    };
  } catch (error) {
    console.error('Process data error:', error);
    throw error;
  }
}

CSS 规范

命名规范

css

/* BEM 命名规范 */
.block {
  /* 块 */
}

.block__element {
  /* 元素 */
}

.block--modifier {
  /* 修饰符 */
}

.block__element--modifier {
  /* 元素修饰符 */
}

/* 示例 */
.task-card {
  padding: 16px;
}

.task-card__title {
  font-size: 16px;
  font-weight: bold;
}

.task-card__title--completed {
  color: #67C23A;
}

样式组织

css

/* 1. 变量定义 */
:root {
  --primary-color: #3A7BD5;
  --success-color: #67C23A;
  --warning-color: #E6A23C;
  --danger-color: #F56C6C;
  --text-color: #333333;
  --border-color: #DCDFE6;
}

/* 2. 基础样式 */
* {
  box-sizing: border-box;
}

body {
  font-family: -apple-system, BlinkMacSystemFont, sans-serif;
  line-height: 1.5;
  color: var(--text-color);
}

/* 3. 组件样式 */
.component {
  /* 组件样式 */
}

/* 4. 工具类 */
.text-center { text-align: center; }
.flex { display: flex; }
.flex-1 { flex: 1; }

文件组织规范

页面文件结构

pages/example/
├── index.js              // 页面逻辑
├── index.json            // 页面配置
├── index.wxml            // 页面结构
├── index.wxss            // 页面样式
└── components/           // 页面组件
    ├── component-a.js
    ├── component-a.wxml
    ├── component-a.wxss
    └── component-a.json

组件文件结构

components/example-component/
├── index.js              // 组件逻辑
├── index.json            // 组件配置
├── index.wxml            // 组件结构
├── index.wxss            // 组件样式
└── README.md             // 组件说明

注释规范

JSDoc 注释

javascript

/**
 * 用户服务类
 *
 * 提供用户相关的操作方法，包括登录、注册、信息获取等
 *
 * @class UserService
 * @version 1.0.0
 * @since 2024-10-20
 * @author MindGuard Team
 */
class UserService {
  /**
   * 用户登录
   *
   * @param {string} username - 用户名
   * @param {string} password - 密码
   * @returns {Promise<Object>} 登录结果
   * @throws {AuthenticationError} 认证失败时抛出
   *
   * @example
   * // 使用示例
   * const userService = new UserService();
   * const result = await userService.login('user123', 'password123');
   * console.log(result.token);
   */
  async login(username, password) {
    // 实现登录逻辑
  }
}

行内注释

javascript

// 数据验证 - 确保用户输入的数据格式正确
if (!email || !email.includes('@')) {
  throw new Error('Invalid email format');
}

// TODO: 优化性能 - 使用缓存减少数据库查询
const userData = await getUserFromDatabase(userId);

// FIXME: 修复边界情况 - 处理空数组的情况
if (!Array.isArray(items) || items.length === 0) {
  return [];
}

🧪 测试指南

测试策略

测试金字塔

    /\
   /  \
  /E2E \     <- 端到端测试 (少量)
 /______\
/        \
/Integration\ <- 集成测试 (适量)
/__________\
/            \
/  Unit Tests  \ <- 单元测试 (大量)
/______________\

测试分类

单元测试: 测试独立的函数和组件
集成测试: 测试模块间的交互
端到端测试: 测试完整的用户流程
性能测试: 测试系统性能指标

单元测试

Jest 配置

javascript

// jest.config.js
module.exports = {
  testEnvironment: 'node',
  collectCoverage: true,
  coverageDirectory: 'coverage',
  coverageReporters: ['text', 'lcov', 'html'],
  testMatch: [
    '**/__tests__/**/*.test.js',
    '**/?(*.)+(spec|test).js'
  ],
  collectCoverageFrom: [
    'services/**/*.js',
    'utils/**/*.js',
    'cloudfunctions/**/*.js',
    '!**/node_modules/**',
    '!**/coverage/**'
  ]
};

测试示例

javascript

// services/__tests__/checkins.test.js
const { getTodayCheckin, createCheckin } = require('../checkins');

describe('Checkins Service', () => {
  beforeEach(() => {
    // 测试前准备
    wx.setStorageSync('USE_MOCK', true);
  });

  describe('getTodayCheckin', () => {
    test('应该返回今日打卡数据', async () => {
      const result = await getTodayCheckin();

      expect(result).toBeDefined();
      expect(result.hasCheckedIn).toBeDefined();
      expect(typeof result.mood).toBe('string');
    });

    test('未打卡时应该返回默认值', async () => {
      // Mock 无打卡数据的情况
      const result = await getTodayCheckin();

      expect(result.hasCheckedIn).toBe(false);
      expect(result.mood).toBe('');
    });
  });

  describe('createCheckin', () => {
    test('应该成功创建打卡记录', async () => {
      const data = {
        mood: 'calm',
        intensity: 4,
        note: '今天心情不错'
      };

      const result = await createCheckin(data);

      expect(result.id).toBeDefined();
      expect(result.mood).toBe('calm');
      expect(result.intensity).toBe(4);
    });

    test('应该验证必需字段', async () => {
      const invalidData = {
        // 缺少 mood 字段
        intensity: 4
      };

      await expect(createCheckin(invalidData))
        .rejects.toThrow('mood is required');
    });
  });
});

集成测试

API 集成测试

javascript

// tests/integration/api.test.js
const request = require('supertest');
const app = require('../../app');

describe('API Integration Tests', () => {
  test('POST /api/checkins 应该创建打卡记录', async () => {
    const response = await request(app)
      .post('/api/checkins')
      .send({
        mood: 'calm',
        intensity: 4
      })
      .expect(201);

    expect(response.body.success).toBe(true);
    expect(response.body.data.id).toBeDefined();
  });

  test('GET /api/checkins/today 应该返回今日打卡', async () => {
    const response = await request(app)
      .get('/api/checkins/today')
      .expect(200);

    expect(response.body.success).toBe(true);
    expect(Array.isArray(response.body.data)).toBe(true);
  });
});

云函数测试

javascript

// cloudfunctions/__tests__/checkinRecorder.test.js
const cloud = require('wx-server-sdk');
const { main } = require('../checkinRecorder/index');

// Mock 云开发环境
jest.mock('wx-server-sdk', () => ({
  init: jest.fn(),
  getWXContext: jest.fn(() => ({
    OPENID: 'test-openid'
  })),
  database: jest.fn(() => ({
    collection: jest.fn(() => ({
      where: jest.fn().mockReturnThis(),
      get: jest.fn(),
      add: jest.fn(),
      update: jest.fn()
    }))
  }))
}));

describe('CheckinRecorder Cloud Function', () => {
  test('getToday action 应该返回今日打卡', async () => {
    const event = {
      action: 'getToday'
    };

    const result = await main(event, {});

    expect(result.ok).toBe(true);
    expect(result.data).toBeDefined();
  });

  test('create action 应该创建新打卡', async () => {
    const event = {
      action: 'create',
      mood: 'calm',
      intensity: 4
    };

    const result = await main(event, {});

    expect(result.ok).toBe(true);
    expect(result.data.id).toBeDefined();
  });
});

端到端测试

微信小程序测试

javascript

// tests/e2e/miniprogram.test.js
const { driver } = require('@wdio/allure-reporter');

describe('MindGuard 小程序端到端测试', () => {
  before(async () => {
    // 启动小程序
    await driver.launchApp();
  });

  test('用户应该能够完成情绪打卡流程', async () => {
    // 1. 进入今天页面
    await driver.element('today-tab').click();

    // 2. 点击打卡按钮
    await driver.element('checkin-button').click();

    // 3. 选择情绪
    await driver.element('emotion-calm').click();

    // 4. 调整强度
    await driver.element('intensity-slider').setValue(4);

    // 5. 添加备注
    await driver.element('note-input').setValue('今天心情不错');

    // 6. 提交打卡
    await driver.element('submit-button').click();

    // 7. 验证结果
    const successMessage = await driver.element('success-message').getText();
    expect(successMessage).toContain('打卡成功');
  });
});

性能测试

前端性能测试

javascript

// tests/performance/load-time.test.js
const { performance } = require('perf_hooks');

describe('性能测试', () => {
  test('页面加载时间应该小于2秒', async () => {
    const startTime = performance.now();

    // 模拟页面加载
    await loadPage('today');

    const endTime = performance.now();
    const loadTime = endTime - startTime;

    expect(loadTime).toBeLessThan(2000);
  });

  test('API响应时间应该小于500ms', async () => {
    const startTime = performance.now();

    const response = await api.getTodayCheckin();

    const endTime = performance.now();
    const responseTime = endTime - startTime;

    expect(responseTime).toBeLessThan(500);
  });
});

🚀 部署流程

开发环境部署

1. 本地开发

bash

# 启动微信开发者工具
# 导入项目
# 配置云开发环境
# 本地调试

2. 代码提交

bash

# 提交代码
git add .
git commit -m "feat: 新功能描述"
git push origin feature/new-feature

# 创建 PR
# 代码审查
# 合并到 develop

测试环境部署

1. 云函数部署

bash

# 部署单个云函数
# 在微信开发者工具中右键云函数目录
# 选择"上传并部署：云端安装依赖"

# 批量部署
# 使用脚本批量部署
npm run deploy:cloudfunctions

2. 小程序部署

bash

# 在微信开发者工具中
# 点击"上传"按钮
# 填写版本号和项目备注
# 上传代码包

# 提交审核
# 等待审核通过

生产环境部署

1. 预发布检查

bash

# 运行测试套件
npm run test:all

# 代码质量检查
npm run lint
npm run type-check

# 安全扫描
npm run security:scan

2. 生产部署

bash

# 创建发布分支
git checkout -b release/v1.0.0

# 合并最新代码
git merge develop

# 部署到生产环境
npm run deploy:production

# 标记版本
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

3. 部署验证

bash

# 健康检查
curl -f https://api.example.com/health

# 功能验证
npm run test:e2e:production

# 性能监控
npm run monitor:performance

CI/CD 流程

GitHub Actions 配置

yaml

# .github/workflows/deploy.yml
name: Deploy to Production

on:
  push:
    tags:
      - 'v*'

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

      - name: Run linting
        run: npm run lint

      - name: Run security audit
        run: npm audit --audit-level high

  deploy:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Deploy to WeChat Cloud
        run: |
          # 部署脚本
          npm run deploy:production

      - name: Notify deployment
        run: |
          # 发送部署通知
          curl -X POST "$NOTIFICATION_URL" \
            -H "Content-Type: application/json" \
            -d '{"text": "MindGuard v${{ github.ref_name }} deployed successfully"}'

🤝 贡献指南

参与贡献

贡献方式

代码贡献: 提交 Pull Request
文档贡献: 改进文档和教程
Bug 报告: 报告问题并协助修复
功能建议: 提出新功能建议
测试反馈: 参与测试并提供反馈

贡献流程

Fork 项目

bash

# Fork 项目到你的 GitHub 账户
# 克你的 Fork
git clone https://github.com/your-username/MindGuard.git

创建功能分支

bash

git checkout -b feature/your-feature-name

开发和测试

bash

# 编写代码
# 添加测试
# 确保测试通过
npm test

提交代码

bash

git add .
git commit -m "feat: 添加功能描述"

推送和 PR

bash

git push origin feature/your-feature-name
# 在 GitHub 上创建 Pull Request

代码审查标准

审查清单

[ ] 代码符合项目规范
[ ] 包含必要的测试
[ ] 文档已更新
[ ] 没有安全漏洞
[ ] 性能影响可接受
[ ] 兼容现有功能

审查流程

自我审查
- 代码符合规范
- 功能完整实现
- 测试覆盖充分
同行审查
- 至少一人审查
- 关注代码质量
- 验证功能正确性
维护者审查
- 整体架构影响
- 长期维护考虑
- 最终合并决定

文档贡献

文档类型

API 文档: 接口说明和示例
用户指南: 功能使用说明
开发指南: 开发环境搭建
架构文档: 系统设计说明
部署文档: 部署流程说明

文档规范

markdown

# 文档标题

> 简短描述

## 概述
背景信息和总体介绍

## 安装/使用
详细的步骤说明

## 示例
代码示例和使用案例

## API 参考
详细的 API 说明

## 常见问题
FAQ 和故障排除

## 贡献
如何贡献和改进

Issue 模板

Bug 报告模板

markdown

## Bug 描述
简要描述 bug

## 复现步骤
1. 打开页面
2. 点击按钮
3. 观察结果

## 期望结果
描述应该发生什么

## 实际结果
描述实际发生了什么

## 环境信息
- 操作系统:
- 微信版本:
- 小程序版本:

## 附加信息
截图、日志等

功能请求模板

markdown

## 功能描述
描述希望添加的功能

## 问题背景
说明为什么需要这个功能

## 解决方案
描述你希望的解决方案

## 替代方案
描述你考虑过的其他解决方案

## 附加信息
任何其他相关信息

🔧 故障排除

常见问题

开发环境问题

Q: 微信开发者工具无法识别项目

bash

# 解决方案
1. 确保 project.config.json 存在
2. 检查 appid 配置是否正确
3. 重新导入项目

Q: npm install 失败

bash

# 解决方案
1. 清除 npm 缓存: npm cache clean --force
2. 删除 node_modules 和 package-lock.json
3. 重新安装: npm install
4. 检查网络连接

Q: 云函数调用失败

javascript

// 检查清单
1. 云开发环境是否已开通
2. 环境ID是否正确
3. 云函数是否已部署
4. 权限配置是否正确

运行时问题

Q: 页面白屏

javascript

// 排查步骤
1. 检查控制台错误信息
2. 确认页面路径配置正确
3. 检查组件引用是否正确
4. 验证数据加载是否成功

Q: API 调用失败

javascript

// 调试步骤
1. 检查网络连接
2. 验证 API 地址正确
3. 检查请求参数格式
4. 查看 CloudBase 控制台日志

Q: 云函数超时

javascript

// 解决方案
1. 检查云函数执行时间
2. 优化数据库查询
3. 增加超时时间配置
4. 考虑异步处理

调试技巧

前端调试

javascript

// 1. 使用 console.log 调试
console.log('Debug info:', data);

// 2. 使用 debugger 断点
debugger;

// 3. 使用微信开发者工具调试
// - Network 面板查看网络请求
// - Console 面板查看日志
// - Sources 面板设置断点

// 4. 使用 vConsole (移动端调试)
import vconsole from 'vconsole';
new vconsole();

云函数调试

javascript

// 1. 添加详细日志
exports.main = async (event, context) => {
  console.log('Input:', event);
  console.log('Context:', context);

  try {
    // 业务逻辑
    const result = await processEvent(event);
    console.log('Result:', result);

    return { ok: true, data: result };
  } catch (error) {
    console.error('Error:', error);
    return { ok: false, error: error.message };
  }
};

// 2. 本地调试
// 使用微信开发者工具的云函数本地调试功能

// 3. 远程调试
// 在 CloudBase 控制台查看日志

数据库调试

javascript

// 1. 查询数据
const result = await db.collection('collection')
  .where({
    _openid: openid,
    status: 'active'
  })
  .get();

console.log('Query result:', result);

// 2. 检查数据格式
result.data.forEach(item => {
  console.log('Item:', item);
  console.log('Item fields:', Object.keys(item));
});

// 3. 聚合查询调试
const aggregateResult = await db.collection('collection')
  .aggregate()
  .match({
    created_at: db.command.gte('2024-01-01')
  })
  .group({
    _id: '$category',
    count: db.command.sum(1)
  })
  .end();

console.log('Aggregate result:', aggregateResult);

性能优化

前端优化

javascript

// 1. 组件懒加载
const lazyLoad = () => {
  // 动态加载组件
};

// 2. 数据缓存
const cache = new Map();

function getCachedData(key) {
  if (cache.has(key)) {
    return cache.get(key);
  }

  const data = fetchData(key);
  cache.set(key, data);
  return data;
}

// 3. 防抖和节流
function debounce(func, wait) {
  let timeout;
  return function executedFunction(...args) {
    const later = () => {
      clearTimeout(timeout);
      func(...args);
    };
    clearTimeout(timeout);
    timeout = setTimeout(later, wait);
  };
}

function throttle(func, limit) {
  let inThrottle;
  return function() {
    const args = arguments;
    const context = this;
    if (!inThrottle) {
      func.apply(context, args);
      inThrottle = true;
      setTimeout(() => inThrottle = false, limit);
    }
  };
}

云函数优化

javascript

// 1. 数据库查询优化
async function getOptimizedData(openid) {
  // 使用索引优化查询
  const result = await db.collection('collection')
    .where({
      _openid: openid,
      status: 'active'  // 添加索引字段
    })
    .field({  // 只查询需要的字段
      id: true,
      title: true,
      status: true
    })
    .limit(20)  // 限制返回数量
    .get();

  return result;
}

// 2. 批量操作
async function batchUpdate(updates) {
  const batch = db.collection('collection').batch();

  updates.forEach(item => {
    batch.doc(item.id).update({
      data: item.data
    });
  });

  return await batch.commit();
}

// 3. 异步处理
async function processDataAsync(data) {
  // 立即返回任务ID
  const taskId = generateTaskId();

  // 异步处理
  processTask(taskId, data).catch(console.error);

  return { taskId };
}

🔮 扩展开发

添加新功能

功能开发流程

需求分析

markdown

## 功能需求
- 功能描述
- 用户故事
- 验收标准

## 技术方案
- 前端实现
- 后端API
- 数据库设计

设计阶段
- UI/UX 设计
- API 接口设计
- 数据模型设计
- 技术架构设计
开发阶段
- 前端页面开发
- 后端API开发
- 云函数开发
- 数据库创建
测试阶段
- 单元测试
- 集成测试
- 端到端测试
- 性能测试
部署阶段
- 测试环境部署
- 生产环境部署
- 监控和告警
- 用户反馈收集

示例：添加新功能

假设要添加"冥想练习"功能：

创建页面

javascript

// packages/meditation/index.js
Page({
  data: {
    exercises: [],
    currentExercise: null,
    isPlaying: false
  },

  onLoad() {
    this.loadExercises();
  },

  startExercise(exercise) {
    this.setData({
      currentExercise: exercise,
      isPlaying: true
    });
  }
});

创建服务

javascript

// services/meditation.js
async function getMeditationExercises() {
  if (shouldUseMock()) {
    return MOCK_MEDITATION_EXERCISES;
  }

  const result = await callFunction('meditationManager', {
    action: 'list'
  });

  return result.data;
}

创建云函数

javascript

// cloudfunctions/meditationManager/index.js
exports.main = async (event, context) => {
  const { action } = event;

  switch (action) {
    case 'list':
      return await listExercises();
    case 'start':
      return await startSession(event.data);
    default:
      return { ok: false, error: 'Unsupported action' };
  }
};

添加新页面

页面创建步骤

创建页面文件

bash

mkdir miniprogram/pages/new-page
cd miniprogram/pages/new-page

touch index.js index.wxml index.wxss index.json

配置页面

javascript

// index.json
{
  "navigationBarTitleText": "新页面",
  "usingComponents": {}
}

实现页面逻辑

javascript

// index.js
Page({
  data: {
    // 页面数据
  },

  onLoad(options) {
    // 页面加载
  },

  onShow() {
    // 页面显示
  },

  onHide() {
    // 页面隐藏
  },

  onUnload() {
    // 页面卸载
  }
});

设计页面结构

xml

<!-- index.wxml -->
<view class="container">
  <view class="header">页面标题</view>
  <view class="content">页面内容</view>
</view>

添加页面样式

css

/* index.wxss */
.container {
  padding: 20px;
}

.header {
  font-size: 18px;
  font-weight: bold;
}

注册页面

json

// app.json
{
  "pages": [
    "pages/new-page/index"
  ]
}

添加新组件

组件开发步骤

创建组件目录

bash

mkdir miniprogram/components/new-component
cd miniprogram/components/new-component

touch index.js index.wxml index.wxss index.json

定义组件

javascript

// index.js
Component({
  properties: {
    title: {
      type: String,
      value: '默认标题'
    }
  },

  data: {
    // 组件内部数据
  },

  methods: {
    onTap() {
      this.triggerEvent('tap', {
        title: this.properties.title
      });
    }
  }
});

使用组件

xml

<!-- 在页面中使用 -->
<new-component
  title="组件标题"
  bind:tap="onComponentTap"
/>

数据库扩展

创建新集合

javascript

// 在云开发控制台创建集合
// 1. 登录云开发控制台
// 2. 进入数据库
// 3. 创建新集合
// 4. 设置权限规则

权限规则配置

json

{
  "read": "auth.uid == resource._openid || auth.uid == 'admin'",
  "write": "auth.uid == resource._openid || auth.uid == 'admin'",
  "create": "auth.uid != null"
}

索引创建

javascript

// 创建索引
db.collection('new_collection').createIndex({
  _openid: 1,
  created_at: -1
});

// 复合索引
db.collection('new_collection').createIndex({
  _openid: 1,
  status: 1,
  created_at: -1
});

第三方集成

集成新服务

添加依赖
bash
```
npm install third-party-service
```

创建适配器

javascript

// services/thirdPartyAdapter.js
const ThirdPartyService = require('third-party-service');

class ThirdPartyAdapter {
  constructor(config) {
    this.client = new ThirdPartyService(config);
  }

  async processData(data) {
    // 适配数据格式
    const adaptedData = this.adaptData(data);

    // 调用第三方服务
    const result = await this.client.process(adaptData);

    // 适配返回结果
    return this.adaptResult(result);
  }

  adaptData(data) {
    return {
      // 数据格式转换
    };
  }

  adaptResult(result) {
    return {
      // 结果格式转换
    };
  }
}

module.exports = ThirdPartyAdapter;

配置环境变量

javascript

// config/thirdParty.js
module.exports = {
  apiKey: process.env.THIRD_PARTY_API_KEY,
  baseUrl: process.env.THIRD_PARTY_BASE_URL,
  timeout: 5000
};

📚 相关资源

官方文档

技术资源

社区资源

📞 联系我们

开发团队

项目维护者: MindGuard 开发团队
技术支持: tech-support@mindguard.com
问题反馈: GitHub Issues

贡献者

感谢所有为 MindGuard 项目做出贡献的开发者和用户！

本文档会持续更新，请关注最新版本。

MindGuard 开发团队 🚀 让技术服务于心理健康

贡献者

Cai Hongyu

文件历史

最后编辑于 4 个月前查看完整历史

MindGuard 开发者指南 ​

🎯 项目概述 ​

项目简介 ​

技术栈 ​

核心功能 ​

🛠️ 开发环境搭建 ​

前置要求 ​

基础环境 ​

开发工具 ​

环境配置步骤 ​

1. 安装微信开发者工具 ​

2. 配置 Node.js 环境 ​

3. 克隆项目 ​

4. 安装依赖 ​

5. 配置云开发环境 ​

开发工具配置 ​

VS Code 插件推荐 ​

VS Code 设置 ​

📁 项目结构说明 ​

整体结构 ​

页面结构详解 ​

主包页面 (miniprogram/pages/) ​

分包结构 ​

服务层结构 ​

🔄 开发流程 ​

Git 工作流程 ​

分支策略 ​

开发流程 ​

代码开发流程 ​

1. 需求分析 ​

2. 设计阶段 ​

3. 开发阶段 ​

4. 测试阶段 ​

Mock 数据开发 ​

Mock 数据规范 ​

Mock 开发流程 ​

📝 代码规范 ​

JavaScript 规范 ​

基础规范 ​

命名规范 ​

函数规范 ​

CSS 规范 ​

命名规范 ​

样式组织 ​

文件组织规范 ​

页面文件结构 ​

组件文件结构 ​

注释规范 ​

JSDoc 注释 ​

行内注释 ​

🧪 测试指南 ​

测试策略 ​

测试金字塔 ​

测试分类 ​

单元测试 ​

Jest 配置 ​

测试示例 ​

集成测试 ​

API 集成测试 ​

云函数测试 ​

端到端测试 ​

微信小程序测试 ​

性能测试 ​

前端性能测试 ​

🚀 部署流程 ​

开发环境部署 ​

1. 本地开发 ​

2. 代码提交 ​

测试环境部署 ​

1. 云函数部署 ​

2. 小程序部署 ​

生产环境部署 ​

1. 预发布检查 ​

2. 生产部署 ​

3. 部署验证 ​

CI/CD 流程 ​

GitHub Actions 配置 ​

🤝 贡献指南 ​

参与贡献 ​

贡献方式 ​

MindGuard 开发者指南

🎯 项目概述

项目简介

技术栈

核心功能

🛠️ 开发环境搭建

前置要求

基础环境

开发工具

环境配置步骤

1. 安装微信开发者工具

2. 配置 Node.js 环境

3. 克隆项目

4. 安装依赖

5. 配置云开发环境

开发工具配置

VS Code 插件推荐

VS Code 设置

📁 项目结构说明

整体结构

页面结构详解

主包页面 (miniprogram/pages/)

分包结构

服务层结构

🔄 开发流程

Git 工作流程

分支策略

开发流程

代码开发流程

1. 需求分析

2. 设计阶段

3. 开发阶段

4. 测试阶段

Mock 数据开发

Mock 数据规范

Mock 开发流程

📝 代码规范

JavaScript 规范

基础规范

命名规范

函数规范

CSS 规范

命名规范

样式组织

文件组织规范

页面文件结构

组件文件结构

注释规范

JSDoc 注释

行内注释

🧪 测试指南

测试策略

测试金字塔

测试分类

单元测试

Jest 配置

测试示例

集成测试

API 集成测试

云函数测试

端到端测试

微信小程序测试

性能测试

前端性能测试

🚀 部署流程

开发环境部署

1. 本地开发

2. 代码提交

测试环境部署

1. 云函数部署

2. 小程序部署

生产环境部署

1. 预发布检查

2. 生产部署

3. 部署验证

CI/CD 流程

GitHub Actions 配置

🤝 贡献指南

参与贡献

贡献方式