zhaoxi/wechat

Fork 0

Files

T

zhaoxi 1da41ec774 第一次提交

2026-07-14 14:52:44 +08:00

9.2 KiB

Raw Permalink Blame History

微信云开发规则

概述

本文档定义了使用微信云开发（CloudBase）为小程序提供后端服务的开发规范。当 PRD 分析判定小程序需要后端服务且目标平台包含微信小程序时，在前端开发过程中同步生成云函数代码。部署操作在用户确认后通过 CloudBase MCP 工具完成。

适用条件

当小程序需要后端服务时启用（Taro 项目默认支持编译为微信小程序）
Taro.cloud API 只在微信小程序（weapp）运行时可用，H5 预览时走 mock 数据
所有涉及 Taro.cloud 的代码必须用 process.env.TARO_ENV === 'weapp' 包裹

开发流程

Phase A：后端需求分析

在 PRD 分析阶段（第一阶段）同步完成，识别需要云端支持的功能：

需要用户身份识别 → 云函数 login（获取 openid）
需要数据持久化 → 对应集合 + 云函数（CRUD）
需要文件上传/下载 → 云存储 API

输出格式：

### 数据库集合设计
| 集合名 | 用途 | 核心字段 | 索引字段 |
|--------|------|----------|----------|
| users | 用户信息 | _openid, nickname, avatar, createTime | _openid |
| orders | 订单 | _openid, items, status, createTime | _openid, status |

### 云函数列表
| 函数名 | 用途 | 入参 | 返回 |
|--------|------|------|------|
| login | 获取用户openid | 无 | { openid } |
| getOrders | 查询订单 | { status? } | { orders: [] } |

Phase B：生成云函数代码

在前端页面开发阶段（第六阶段）同步完成。每开发一个需要后端数据的页面时，同时生成对应的云函数代码，写入项目根目录的 cloudfunctions/ 目录。每个云函数一个独立子目录。

Phase C：前端调用层

前端统一使用 src/services/cloud.ts（模板已预置）封装调用：

微信平台（weapp）：走真实 Taro.cloud.callFunction
非微信平台（H5 预览、抖音、支付宝）：走 mock 数据

页面通过 service 层获取数据。涉及云函数的 mock 文件命名为 src/data/<functionName>.ts，cloud.ts 会在非微信环境下按函数名自动加载对应文件。

Phase D：通过 MCP 部署（用户确认后执行）

用户确认部署后，使用 CloudBase MCP 工具完成部署（MCP 自动处理认证，无需主动管理登录状态）。

部署成功后，通过 MCP 的 envQuery 工具获取当前环境 ID，然后将 app.tsx 中 Taro.cloud.init() 的 env 参数设置为真实的环境 ID。如果 envQuery 无法获取，则询问用户提供环境 ID。

Phase E：验证（部署后执行）

通过 MCP 调用云函数验证部署成功，输出结果摘要。

云函数代码规范

目录结构

cloudfunctions/
├── login/
│   ├── index.js
│   └── package.json
├── getUsers/
│   ├── index.js
│   └── package.json
└── createOrder/
    ├── index.js
    └── package.json

入口文件模板（index.js）

const cloud = require('wx-server-sdk')
cloud.init({ env: cloud.DYNAMIC_CURRENT_ENV })
const db = cloud.database()

exports.main = async (event, context) => {
  try {
    const wxContext = cloud.getWXContext()
    const openid = wxContext.OPENID

    // 业务逻辑...
    const result = null // 替换为实际逻辑

    return { code: 0, message: 'success', data: result }
  } catch (err) {
    console.error('[functionName] error:', err)
    return { code: -1, message: err.message || '服务异常', data: null }
  }
}

package.json 模板

{
  "name": "functionName",
  "version": "1.0.0",
  "main": "index.js",
  "dependencies": {
    "wx-server-sdk": "~2.6.3"
  }
}

编码规范

函数命名：camelCase，动词开头（getXxx, createXxx, updateXxx, deleteXxx）
必须调用 cloud.init({ env: cloud.DYNAMIC_CURRENT_ENV })
通过 cloud.getWXContext().OPENID 获取用户身份（免鉴权）
统一返回格式：{ code: number, message: string, data: any }
- code=0 表示成功，code<0 表示失败
必须有 try-catch 错误处理
日志使用 console.error('[函数名]', err) 格式
云函数使用 CommonJS（require / exports.main），不使用 ESM

数据库规范

集合命名

小写字母 + 下划线：users, user_profiles, order_items
避免使用数据库保留字

文档结构约定

用户相关数据必须包含 _openid 字段用于权限控制
时间字段使用 db.serverDate() 写入
必须为高频查询字段建立索引

安全规则

默认规则："仅创建者可读写"（通过 _openid 匹配）
公开数据（如商品列表）：所有人可读，仅管理员可写

前端调用规范

初始化（app.tsx）

在 App 组件中初始化云开发，必须做平台判断：

import { useEffect } from 'react'

function App(props) {
  useEffect(() => {
    if (process.env.TARO_ENV === 'weapp') {
      Taro.cloud.init({ env: 'your-env-id', traceUser: true })
    }
  }, [])
  return props.children
}

注意：process.env.TARO_ENV 在编译时被替换为常量，非微信平台的 cloud 代码会被 tree shaking 移除。

Service 层封装（src/services/cloud.ts）

项目模板中已预置 src/services/cloud.ts，提供统一的云调用封装：

微信平台：走真实云函数调用
非微信平台（H5 预览、抖音、支付宝）：走 mock 数据

开发云函数时，只需修改此文件中的 mock fallback 逻辑为真实云调用即可。

页面中使用

import { callFunction } from '@/services/cloud'

const [orders, setOrders] = useState<Order[]>([])

useEffect(() => {
  callFunction<Order[]>('getOrders', { status: 'pending' })
    .then(setOrders)
    .catch(err => console.error('[OrderPage]', err))
}, [])

MCP 部署操作

配置 MCP

部署前需确认用户 IDE 已配置 CloudBase MCP。如果 MCP 工具不可用，通过以下方式帮助用户配置：

方式一（推荐）：自动触发安装

使用终端工具执行以下命令（根据操作系统选择），系统会自动打开 Trae 的 MCP 配置确认窗口：

macOS: open "trae-cn://trae.ai-ide/mcp-import?type=stdio&name=cloudbase&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjbG91ZGJhc2UvY2xvdWRiYXNlLW1jcEBsYXRlc3QiXX0%3D"
Windows: start "" "trae-cn://trae.ai-ide/mcp-import?type=stdio&name=cloudbase&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjbG91ZGJhc2UvY2xvdWRiYXNlLW1jcEBsYXRlc3QiXX0%3D"

执行后告知用户：

在弹出的确认窗口中点击「确认」（添加 CloudBase MCP 服务）
在弹出的 MCP 管理面板中，点击「+ 添加」按钮左侧的 🔄 按钮刷新，等待 cloudbase 下的工具列表加载成功
回复「已配置」继续部署

重要：MCP 工具只有在用户发起新一轮对话后才能被检测到，因此必须等待用户回复后再继续部署流程，不要尝试在当前轮次中轮询检测。

方式二：手动配置（仅当方式一失败时使用）

打开「设置」→「MCP」
点击「+ 添加」→「手动配置」
将以下 JSON 粘贴到输入框中并点击确认：

{
  "mcpServers": {
    "cloudbase": {
      "command": "npx",
      "args": [
        "-y",
        "@cloudbase/cloudbase-mcp@latest"
      ]
    }
  }
}

用户确认配置完成后，可直接调用以下 MCP 工具。

部署顺序

创建所有数据库集合
为集合创建索引
部署所有云函数
调用 login 函数验证部署成功

创建数据库集合

工具：writeNoSqlDatabaseStructure
参数：action: "createCollection", collectionName: "xxx"

创建索引

工具：writeNoSqlDatabaseStructure
参数：action: "updateCollection", collectionName: "xxx", 包含 CreateIndexes 配置

部署云函数

工具：manageFunctions
参数：action: "createFunction", functionName: "xxx", functionRootPath: "<项目路径>/cloudfunctions"

验证部署

工具：manageFunctions
参数：action: "invoke", functionName: "login", params: {}

输出部署结果

部署完成后，向用户输出摘要（环境 ID 从部署阶段 envQuery 获取的真实值动态替换）：

✅ 后端部署完成：
- 已部署云函数：login, getUsers, createOrder（共 3 个）
- 已创建数据库集合：users, orders（共 2 个）
- 验证结果：login 函数调用成功

🔗 云开发管理控制台：https://tcb.cloud.tencent.com/dev?envId=<环境ID>#/scf
   您可以点击上方链接，在腾讯云控制台中查看和管理云函数、数据库等资源。

约束

禁止执行任何 CLI 命令（tcb、cloudbase、npm 等），所有云端操作通过 MCP 工具完成
H5 预览模式下使用 mock 数据，不调用真实云端
env-id 在部署阶段确定：生成代码时 Taro.cloud.init({ env: '' }) 可留空或用任意占位，部署阶段通过 MCP envQuery 获取真实环境 ID 后修改 app.tsx
云函数使用 CommonJS：require / exports.main，不使用 ESM
平台判断是强制的：所有涉及 Taro.cloud 的代码必须用 process.env.TARO_ENV === 'weapp' 包裹
MCP 认证由 MCP 内部自动处理：Skill 不需要主动调用 auth 工具或管理登录状态

9.2 KiB Raw Permalink Blame History Unescape Escape