跨端团队协作规范建立

跨端开发涉及多平台、多角色协作，其复杂性远超单一平台开发。一套清晰、可执行的团队协作规范，是保障跨端项目高效推进、代码质量稳定、多端体验一致性的基石。它不仅是流程的约束，更是团队共同语言的建立。

协作流程与角色定义

跨端团队通常由产品经理、设计师、前端跨端开发者、原生开发者（负责桥接或特定模块）、测试工程师构成。规范需明确各角色在跨端项目中的职责与协作节点。

产品需求阶段，产品经理需明确需求涉及的目标平台（iOS、Android、Web、各小程序），并标注可能存在的平台特性差异或限制。需求评审时，跨端开发者需早期介入，评估技术可行性及跨端实现成本。

设计阶段，设计师应在统一的跨端设计规范下进行，使用通用的色彩、间距、字体系统。交付物除设计稿外，应明确标注多端交互差异（如下拉刷新、导航返回）。建议使用如Figma等支持多端预览的设计工具，并建立跨端组件库。

开发阶段，建立“跨端需求卡”制度。每项需求需附带一张卡片，明确：

涉及平台
公共业务逻辑
平台特定逻辑（用条件编译或文件后缀区分）
依赖的原生能力
联调接口

示例的“跨端需求卡”模板（Markdown格式）：

markdown 复制代码

## 需求：用户登录页优化
**目标平台**： H5、微信小程序、支付宝小程序、App（RN）
**公共逻辑**：
1. 手机号+密码登录表单UI与验证逻辑
2. 登录API调用与token管理
**平台特定逻辑**：
- 微信小程序： 需增加“微信一键登录”按钮，调用`wx.login`。
- App（RN）： 需集成第三方社会化登录SDK，调用原生模块`NativeLoginModule`。
- H5： 仅展示标准表单。
**条件编译标识**： `#ifdef MP-WEIXIN`, `#ifdef APP-PLUS`
**依赖原生模块**： `NativeLoginModule` (由原生团队提供)
**接口人**： 前端-张三（跨端逻辑）， 原生-李四（桥接模块）

代码仓库与分支管理策略

推荐采用Monorepo（单仓库）管理跨端项目，便于共享代码、统一依赖和版本管理。目录结构应清晰区分通用代码、平台特定代码和项目配置。

复制代码

project-monorepo/
├── packages/
│   ├── common/           # 跨端通用工具函数、常量、类型定义
│   ├── ui-components/    # 跨端UI组件库（使用框架提供的多端组件方案）
│   ├── project-h5/       # H5端项目
│   ├── project-mp-weixin/# 微信小程序项目
│   ├── project-rn/       # React Native项目
│   └── native-modules/   # 原生模块源码（Android/iOS）
├── scripts/              # 跨端构建、部署脚本
├── docs/                 # 项目文档、规范
└── package.json          # 根目录管理依赖

分支模型采用Git Flow或简化版。master分支对应生产环境，develop为集成开发分支。每个功能分支从develop检出，命名规范为 feature/平台简写-需求简述，例如 feature/mp-login-optimize 或 feature/rn-add-social-login。平台简写可统一为：h5, mp（小程序通用）, mp-weixin, rn, native。

代码规范与提交约定

代码规范是跨端一致性的核心。除了基本的ESLint、StyleLint规则，需特别制定：

平台API调用抽象：禁止在业务逻辑中直接调用wx.xxx或uni.xxx。应封装成统一的服务。

javascript 复制代码

// ❌ 错误：在业务代码中直接使用平台API
// 在微信小程序中
wx.request({ url: '/api/login', method: 'POST' });

// ✅ 正确：封装成统一服务
// common/network.js
import { getPlatform } from './platform';

const request = (options) => {
  const platform = getPlatform();
  if (platform === 'mp-weixin') {
    return wx.request(options);
  } else if (platform === 'h5') {
    // 使用fetch或axios
    return fetch(options.url, { method: options.method, body: options.data });
  }
  // ... 其他平台
};

export default request;

// 业务代码中使用
import request from '@common/network';
request({ url: '/api/login', method: 'POST', data: { phone, password } });

样式编写规范：采用支持跨端的样式方案（如Taro的样式语法、UniApp的rpx、RN的StyleSheet）。规定通用样式变量。
css 复制代码
```
/* common/variables.css */
:root {
  --color-primary: #007aff;
  --spacing-base: 8px;
  --font-size-title: 18px;
}
```
在组件中引用这些变量，确保多端视觉统一。

条件编译注释规范：明确条件编译代码块的格式和位置，避免嵌套过深。

javascript 复制代码

// 使用清晰的注释块
// #ifdef MP-WEIXIN
console.log('这段代码只在微信小程序中出现');
const weixinSpecificData = getWeixinData();
// #endif

// #ifdef APP-PLUS || H5
console.log('这段代码在App和H5中出现');
// #endif

提交信息采用Conventional Commits规范，并强制关联需求卡或任务ID。

复制代码

<类型>[可选 平台范围]: <描述>

[可选 正文]

[可选 脚注，如关闭的issue]

示例：

复制代码

feat(mp): 新增微信小程序一键登录功能

- 封装wx.login API至authService
- 新增LoginButton组件，支持条件编译
- 更新用户状态管理逻辑

Closes #PROJ-123

类型包括：feat, fix, docs, style, refactor, test, chore。平台范围可选，如(mp), (rn), (native), (all)。

文档、通信与知识沉淀

项目文档应集中存放于仓库docs目录，至少包括：

ONBOARDING.md：新成员上手指南，包含环境搭建、项目结构、运行命令。
DEVELOPMENT.md：详细开发规范，包含代码规范、提交规范、测试规范。
PLATFORM-DIFFERENCES.md：关键平台差异记录及解决方案。
NATIVE-BRIDGE.md：原生模块开发、集成、调用指南。

日常沟通：设立每日站会同步各平台进度和阻塞问题。使用项目管理工具（如Jira、Trello）跟踪“跨端需求卡”状态。技术决策和方案讨论应在PR评论或专门的技术讨论区进行，结论更新至文档。

知识沉淀：鼓励团队成员将解决平台特定问题的经验写成技术笔记，归档至团队知识库。定期举行跨端技术分享会，同步各平台最新动态和最佳实践。

质量保障与发布流程

代码审查是保证跨端代码质量的关键环节。PR（Pull Request）必须至少由一位熟悉该平台和一位熟悉公共逻辑的成员评审。审查重点包括：

公共代码是否被不当修改，影响其他平台。
平台特定代码是否正确使用条件编译或文件隔离。
新增API调用是否已做抽象封装。
样式是否遵循变量系统，有无硬编码。
提交信息是否符合规范。

自动化测试需覆盖多端：

单元测试：针对common和ui-components中的通用逻辑和组件。
端到端测试：针对各端核心业务流程，使用对应平台的测试框架（如小程序自动化、Appium for RN）。

发布流程应实现自动化或半自动化。通过CI/CD管道，在代码合并到develop或master后，自动触发各端应用的构建、测试和打包。发布时，需同步更新各应用市场的版本说明，确保功能描述一致。建立统一的版本号管理规则，如主版本.次版本.修订版本-平台标识，便于追踪和回滚。

分享

复制链接

微信扫码分享

协作流程与角色定义

代码仓库与分支管理策略

代码规范与提交约定

文档、通信与知识沉淀

质量保障与发布流程