前端跨团队协作规范

🤝 前端跨团队协作规范（实战版）

🎯 一、协作的核心原则

黄金法则：

"代码是给人看的，顺便让机器运行"

  • 新人3天能上手
  • 老鸟5分钟能看懂任何模块
  • 团队内任意两人可互相接手代码

📁 二、目录结构规范（必须统一）

React项目标准结构

src/
├── 📁 api/              # 所有API接口定义
│   ├── user.js         # 用户相关API
│   ├── product.js      # 产品相关API
│   └── index.js        # 统一导出
├── 📁 assets/          # 静态资源
│   ├── images/         # 图片
│   ├── styles/         # 全局样式
│   └── fonts/          # 字体
├── 📁 components/      # 公共组件
│   ├── common/         # 通用组件（按钮、输入框）
│   ├── business/       # 业务组件
│   └── layout/         # 布局组件
├── 📁 hooks/           # 自定义Hooks
│   ├── useAuth.js      # 权限相关Hook
│   └── useFetch.js     # 请求Hook
├── 📁 pages/           # 页面组件
│   ├── Home/
│   │   ├── index.jsx   # 主组件
│   │   ├── components/ # 页面私有组件
│   │   └── styles.css  # 页面样式
│   └── User/
├── 📁 store/           # 状态管理
│   ├── modules/        # 模块store
│   └── index.js        # store配置
├── 📁 utils/           # 工具函数
│   ├── request.js      # 请求封装
│   └── validate.js     # 验证工具
├── App.jsx             # 根组件
└── main.jsx            # 入口文件

Vue项目标准结构

src/
├── 📁 api/             # API接口
├── 📁 assets/          # 静态资源
├── 📁 components/      # 组件
│   ├── base/          # 基础组件
│   └── modules/       # 模块组件
├── 📁 composables/     # Composition API
├── 📁 views/          # 页面视图
├── 📁 router/         # 路由
├── 📁 store/          # Pinia状态
├── 📁 utils/          # 工具函数
└── App.vue            # 根组件

📝 三、代码编写规范（简单记住）

1. 命名规范（必须遵守）

// ✅ 正确的命名
const userList = [];           // 变量：小驼峰
function getUserInfo() {}       // 函数：动词+名词
const MAX_COUNT = 100;         // 常量：全大写+下划线
class UserService {}           // 类：大驼峰
const API_BASE = '/api';       // 全局配置：全大写

// ❌ 错误的命名
const userlist = [];           // 没有下划线
const GetUser = () => {}       // 函数用大驼峰
const maxCount = 100;          // 常量用小驼峰

2. 组件规范

// 组件文件模板（复制使用）
import React from 'react';
import PropTypes from 'prop-types';
import styles from './UserCard.module.css';

/**
 * 用户卡片组件
 * @param {Object} props
 * @param {User} props.user - 用户信息
 * @param {boolean} props.isActive - 是否激活
 * @param {Function} props.onClick - 点击回调
 * @example
 * <UserCard 
 *   user={userData}
 *   isActive={true}
 *   onClick={handleClick}
 * />
 */
const UserCard = ({ user, isActive = false, onClick }) => {
  // 1. 状态定义
  const [loading, setLoading] = useState(false);
  
  // 2. 副作用
  useEffect(() => {
    // 初始化逻辑
  }, []);
  
  // 3. 事件处理
  const handleClick = () => {
    onClick?.(user);
  };
  
  // 4. 渲染
  return (
    <div 
      className={`${styles.card} ${isActive ? styles.active : ''}`}
      onClick={handleClick}
    >
      <img src={user.avatar} alt={user.name} />
      <span>{user.name}</span>
    </div>
  );
};

// 5. Props类型检查
UserCard.propTypes = {
  user: PropTypes.shape({
    id: PropTypes.number.isRequired,
    name: PropTypes.string.isRequired,
    avatar: PropTypes.string,
  }).isRequired,
  isActive: PropTypes.bool,
  onClick: PropTypes.func,
};

// 6. 默认Props
UserCard.defaultProps = {
  isActive: false,
};

export default React.memo(UserCard);

3. Git提交规范（必须！）

# 提交格式：type(scope): subject
# type类型：
#   feat:     新功能
#   fix:      修复bug
#   docs:     文档更新
#   style:    代码格式（不影响功能）
#   refactor: 重构
#   test:     测试
#   chore:    构建/工具变更

# ✅ 好的提交信息
git commit -m "feat(user): 新增用户登录功能"
git commit -m "fix(auth): 修复token过期问题"
git commit -m "docs(readme): 更新项目启动说明"

# ❌ 坏的提交信息
git commit -m "更新代码"
git commit -m "修复bug"
git commit -m "."

🔧 四、开发流程规范

1. 分支管理策略

# 主分支
main        # 生产环境代码（保护分支）
develop     # 开发分支（保护分支）

# 功能分支（从develop拉取）
feature/user-login     # 新功能开发
bugfix/login-error     # bug修复
hotfix/payment-issue   # 紧急修复

# 发布分支
release/v1.2.0         # 版本发布

2. Code Review清单

## 代码审查检查项

### 功能性 ✅
- [ ] 功能是否完成需求？
- [ ] 是否有明显的bug？
- [ ] 边界情况处理了吗？

### 代码质量 ✅
- [ ] 命名规范吗？（变量、函数、文件）
- [ ] 有重复代码吗？
- [ ] 函数是否太长？（超过50行要拆分）
- [ ] 注释清晰吗？（特别是复杂逻辑）

### 性能 ✅
- [ ] 有内存泄漏风险吗？（定时器、事件监听）
- [ ] 组件渲染优化了吗？（React.memo、useMemo）
- [ ] 请求有缓存吗？
- [ ] 大图片压缩了吗？

### 安全性 ✅
- [ ] 有XSS风险吗？
- [ ] 敏感信息暴露了吗？
- [ ] 权限检查了吗？

### 兼容性 ✅
- [ ] 支持目标浏览器吗？
- [ ] 移动端适配了吗？

3. PR模板（复制使用）

## 变更描述
[简要描述这次PR做了什么]

## 变更类型
- [ ] Bug修复
- [ ] 新功能
- [ ] 代码重构
- [ ] 文档更新
- [ ] 其他

## 测试情况
- [ ] 单元测试通过
- [ ] 集成测试通过
- [ ] 手动测试通过（描述测试步骤）

## 截图/录屏（如有UI变更）
[上传截图]

## 关联Issue
Closes #123

## 自查清单
- [ ] 代码符合团队规范
- [ ] 没有console.log调试代码
- [ ] 已处理所有TODO注释
- [ ] 文档已更新（如有必要）

🚀 五、API协作规范

1. API接口定义模板

// api/user.js
import request from '@/utils/request';

/**
 * 用户服务API
 */
export const userApi = {
  /**
   * 用户登录
   * @param {Object} params
   * @param {string} params.username - 用户名
   * @param {string} params.password - 密码
   * @returns {Promise<User>}
   */
  login: (params) => request.post('/api/user/login', params),
  
  /**
   * 获取用户信息
   * @param {number} userId - 用户ID
   * @returns {Promise<UserInfo>}
   */
  getUserInfo: (userId) => request.get(`/api/user/${userId}`),
  
  /**
   * 更新用户信息
   * @param {number} userId - 用户ID
   * @param {Object} userInfo - 用户信息
   * @returns {Promise<void>}
   */
  updateUser: (userId, userInfo) => 
    request.put(`/api/user/${userId}`, userInfo),
};

// 类型定义（配合TypeScript更好）
/**
 * @typedef {Object} User
 * @property {number} id
 * @property {string} name
 * @property {string} avatar
 */

2. 请求封装统一处理

// utils/request.js
import axios from 'axios';

// 创建实例
const request = axios.create({
  baseURL: process.env.REACT_APP_API_URL,
  timeout: 10000,
});

// 请求拦截器
request.interceptors.request.use(
  (config) => {
    // 添加token
    const token = localStorage.getItem('token');
    if (token) {
      config.headers.Authorization = `Bearer ${token}`;
    }
    return config;
  },
  (error) => Promise.reject(error)
);

// 响应拦截器
request.interceptors.response.use(
  (response) => {
    // 统一处理响应格式
    return response.data;
  },
  (error) => {
    // 统一错误处理
    if (error.response?.status === 401) {
      // token过期，跳转登录
      window.location.href = '/login';
    }
    
    // 返回统一格式的错误
    return Promise.reject({
      code: error.response?.status || 500,
      message: error.response?.data?.message || '网络错误',
    });
  }
);

export default request;

🎨 六、UI/设计协作规范

1. 设计稿转代码规范

// 尺寸转换：设计稿750px -> 实际用rem
// 设置：1rem = 100px（750设计稿）
html {
  font-size: calc(100vw / 7.5); /* 750设计稿适配 */
}

// 使用：设计稿20px -> 0.2rem
.button {
  width: 0.2rem;  /* 实际20px */
  height: 0.2rem;
}

2. 颜色管理

/* 颜色变量统一管理 */
:root {
  /* 主色 */
  --primary-color: #1890ff;
  --primary-hover: #40a9ff;
  
  /* 文本色 */
  --text-primary: #333;
  --text-secondary: #666;
  
  /* 背景色 */
  --bg-white: #fff;
  --bg-gray: #f5f5f5;
  
  /* 状态色 */
  --success: #52c41a;
  --warning: #faad14;
  --error: #f5222d;
}

3. 组件库使用规范

## 组件使用优先级

1. 🥇 团队组件库 (@company/ui)   # 优先使用
2. 🥈 Ant Design / Element UI    # 基础组件
3. 🥉 自定义组件                # 特殊需求时

## 禁止行为
- ❌ 直接修改第三方组件样式
- ❌ 复制粘贴组件库代码
- ❌ 一个页面混用多个UI库

📊 七、文档规范

1. README必须包含

# 项目名称

## 🚀 快速开始
```bash
# 安装依赖
npm install

# 启动开发
npm start

# 构建
npm run build

📁 项目结构

[说明目录结构]

🔧 技术栈

  • React 18
  • TypeScript
  • Ant Design
  • ...

👥 团队成员

  • 张三 - 前端负责人
  • 李四 - 后端负责人

📞 沟通方式

  • 前端群：钉钉群「xxx」
  • 文档：Confluence「项目文档」
  • 会议：每周三 10:00 站会

### **2. 组件文档示例**
```markdown
# UserCard 用户卡片组件

## 何时使用
- 显示用户基本信息
- 用户列表项

## 基本用法
```jsx
import UserCard from '@/components/UserCard';

<UserCard
  user={userData}
  isActive={true}
  onClick={handleClick}
/>

API

参数 说明 类型 默认值
user 用户信息 Object 必填
isActive 是否激活 boolean false
onClick 点击回调 function -

设计稿

[链接到Figma设计稿]


---

## 🧪 **八、测试规范**

### **1. 测试文件结构**

src/
├── components/
│ └── UserCard/
│ ├── index.jsx # 组件
│ └── index.test.js # 测试文件
└── utils/
├── format.js
└── format.test.js # 对应测试


### **2. 测试优先级**
```javascript
// 1. 工具函数必须测试（100%覆盖）
// format.test.js
describe('formatDate', () => {
  it('应该正确格式化日期', () => {
    expect(formatDate('2023-01-01')).toBe('2023年1月1日');
  });
});

// 2. 公共组件必须测试
// UserCard.test.js
describe('UserCard', () => {
  it('应该渲染用户信息', () => {
    const user = { name: '张三', avatar: 'url' };
    render(<UserCard user={user} />);
    expect(screen.getByText('张三')).toBeInTheDocument();
  });
});

// 3. 业务逻辑复杂处要测试
// 4. Bug修复后要加测试防止回归

🚨 九、常见问题处理流程

1. 遇到问题怎么办？

## 问题解决流程

1. **自查**（30分钟）
   - 检查控制台错误
   - 检查网络请求
   - 检查本地数据

2. **问同事**（30分钟）
   - 截图+错误信息
   - 描述复现步骤
   - 说明已尝试的方法

3. **提Issue**（如果还是解决不了）
   - 标题：[模块]问题描述
   - 内容：问题+环境+截图+复现步骤
   - 标签：bug/help/question

2. 代码冲突解决流程

# 1. 先拉取最新代码
git fetch origin
git checkout develop
git pull origin develop

# 2. 回到自己分支
git checkout feature/my-feature
git merge develop

# 3. 解决冲突（优先保留同事的代码）
# 有疑问直接找同事沟通！

# 4. 提交
git add .
git commit -m "fix: 解决合并冲突"

🏆 十、新人上手清单

第1天：环境搭建

- [ ] 安装 Node.js (v16+)
- [ ] 安装 Git
- [ ] 配置 SSH Key
- [ ] 克隆项目代码
- [ ] 安装依赖：npm install
- [ ] 启动项目：npm start
- [ ] 访问本地：http://localhost:3000

第1周：熟悉项目

- [ ] 阅读 README.md
- [ ] 查看项目结构
- [ ] 运行所有测试：npm test
- [ ] 了解 Git 分支策略
- [ ] 熟悉代码规范文档
- [ ] 完成第一个简单任务（如修改文案）

第1月：融入团队

- [ ] 参加每日站会
- [ ] 参与 Code Review
- [ ] 独立完成一个功能模块
- [ ] 熟悉部署流程
- [ ] 了解监控告警系统

📋 十一、协作检查清单

代码提交前检查

# 运行检查脚本
npm run lint      # 代码规范检查
npm run test      # 运行测试
npm run build     # 确保能构建成功

# 手动检查
- [ ] 控制台没有 warning
- [ ] 没有 console.log 调试代码
- [ ] 注释清晰
- [ ] 函数不超过50行
- [ ] 组件 props 有默认值
- [ ] 错误处理完善

功能完成后检查

- [ ] 功能测试通过
- [ ] 移动端适配
- [ ] 浏览器兼容
- [ ] 性能测试（内存、加载速度）
- [ ] 文档更新
- [ ] 告知相关同事

🎯 记住这几点就够了

协作三要：

  1. 要沟通 - 提前说，主动问
  2. 要规范 - 按规矩来，不搞特殊
  3. 要文档 - 写清楚，留记录

协作三不要：

  1. 不要沉默 - 有问题立刻说
  2. 不要独狼 - 代码要 review
  3. 不要拖延 - 今日事今日毕

最重要的一句话：

"写代码时想想：如果同事明天要改这段代码，他能看懂吗？"

🚀 立即行动清单

  1. 今天：把这份规范发给团队所有人
  2. 本周：检查一个项目是否符合规范
  3. 本月：建立团队的 Code Review 文化
  4. 永远：写代码时想着下一个维护的人

好的协作不是管出来的，是习惯出来的。从今天开始培养好习惯！

posted @ 2025-12-22 15:59  XiaoZhengTou  阅读(27)  评论(0)    收藏  举报