Git 管理

Git 管理是 AI Builder 项目开发中的重要环节，提供版本控制、代码协作、分支管理等功能。合理的 Git 管理策略能够确保代码质量、支持团队协作、便于版本回滚。

概述

AI Builder 的 Git 管理包含以下核心功能：

• 📝 版本控制：记录代码变更历史和版本信息
• 🌿 分支管理：支持多分支开发和合并策略
• 👥 团队协作：多人协作开发和代码审查
• 🔄 自动同步：与云端环境自动同步代码
• 🚀 CI/CD 集成：持续集成和自动部署

Git 仓库初始化

1. 创建仓库

在 AI Builder 中初始化：

# AI Builder 会自动为项目创建 Git 仓库
# 项目创建时选择「启用 Git 管理」

手动初始化本地仓库：

# 进入项目目录
cd your-project

# 初始化 Git 仓库
git init

# 添加远程仓库
git remote add origin https://github.com/your-username/your-project.git

# 设置默认分支
git branch -M main

# 首次提交
git add .
git commit -m "Initial commit: AI Builder project setup"
git push -u origin main

2. 仓库结构

标准项目结构：

your-project/
├── .git/                 # Git 配置目录
├── .gitignore           # 忽略文件配置
├── README.md            # 项目说明文档
├── package.json         # 项目依赖配置
├── src/                 # 源代码目录
│   ├── components/      # 组件目录
│   ├── pages/          # 页面目录
│   ├── utils/          # 工具函数
│   └── styles/         # 样式文件
├── functions/           # 云函数目录
│   ├── user/           # 用户相关函数
│   └── task/           # 任务相关函数
├── database/           # 数据库配置
├── docs/               # 文档目录
└── tests/              # 测试文件

3. .gitignore 配置

推荐的 .gitignore 文件：

# Dependencies
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# Production builds
/dist
/build
*.tgz
*.tar.gz

# Environment variables
.env
.env.local
.env.development.local
.env.test.local
.env.production.local

# IDE files
.vscode/
.idea/
*.swp
*.swo
*~

# OS generated files
.DS_Store
.DS_Store?
._*
.Spotlight-V100
.Trashes
ehthumbs.db
Thumbs.db

# Logs
logs
*.log

# Runtime data
pids
*.pid
*.seed
*.pid.lock

# Coverage directory used by tools like istanbul
coverage/

# Temporary folders
tmp/
temp/

# CloudBase specific
.tcb_env
.cloudbase/

# AI Builder specific
.aibuilder/
*.aibuilder.cache

分支管理策略

1. Git Flow 工作流

主要分支：

• main/master：生产环境分支，稳定版本
• develop：开发分支，集成最新功能
• feature/*：功能分支，开发新功能
• release/*：发布分支，准备发布版本
• hotfix/*：热修复分支，紧急修复

分支操作示例：

# 创建并切换到开发分支
git checkout -b develop

# 创建功能分支
git checkout -b feature/user-authentication develop

# 功能开发完成后合并到 develop
git checkout develop
git merge --no-ff feature/user-authentication
git branch -d feature/user-authentication

# 创建发布分支
git checkout -b release/1.0.0 develop

# 发布完成后合并到 main 和 develop
git checkout main
git merge --no-ff release/1.0.0
git tag -a v1.0.0 -m "Release version 1.0.0"

git checkout develop
git merge --no-ff release/1.0.0
git branch -d release/1.0.0

2. GitHub Flow 工作流

简化的分支策略：

# 从 main 分支创建功能分支
git checkout main
git pull origin main
git checkout -b feature/task-management

# 开发并提交
git add .
git commit -m "Add task creation functionality"
git push origin feature/task-management

# 创建 Pull Request
# 代码审查通过后合并到 main
# 删除功能分支
git checkout main
git pull origin main
git branch -d feature/task-management

3. 分支命名规范

功能分支：

feature/user-login
feature/task-management
feature/data-export

修复分支：

bugfix/login-error
bugfix/data-validation
hotfix/security-patch

发布分支：

release/1.0.0
release/1.1.0
release/2.0.0-beta

提交规范

1. 提交信息格式

Conventional Commits 规范：

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

提交类型：

• feat：新功能
• fix：修复 Bug
• docs：文档更新
• style：代码格式调整
• refactor：代码重构
• test：测试相关
• chore：构建过程或辅助工具的变动

提交示例：

# 新功能
git commit -m "feat(auth): add user login functionality"

# Bug 修复
git commit -m "fix(task): resolve task deletion error"

# 文档更新
git commit -m "docs: update API documentation"

# 代码重构
git commit -m "refactor(utils): optimize date formatting function"

# 破坏性变更
git commit -m "feat(api): change user authentication method

BREAKING CHANGE: API endpoint /auth/login now requires email instead of username"

2. 提交最佳实践

提交频率：

# 小而频繁的提交
git add src/components/TaskCard.js
git commit -m "feat(task): add task card component"

git add src/components/TaskCard.css
git commit -m "style(task): add task card styling"

git add src/pages/TaskList.js
git commit -m "feat(task): integrate task card in task list"

提交前检查：

# 检查代码状态
git status

# 查看变更内容
git diff

# 分阶段添加文件
git add -p  # 交互式添加

# 提交前运行测试
npm test
npm run lint

# 提交
git commit -m "feat(task): add task filtering functionality"

代码协作

1. Pull Request 流程

创建 Pull Request：

# 推送功能分支
git push origin feature/user-profile

# 在 GitHub/GitLab 创建 Pull Request
# 填写 PR 模板

PR 模板示例：

## 变更描述

### 功能说明
- 添加用户个人资料页面
- 实现头像上传功能
- 支持个人信息编辑

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

### 测试
- [x] 单元测试通过
- [x] 集成测试通过
- [x] 手动测试完成

### 截图
![用户资料页面](./screenshots/user-profile.png)

### 相关 Issue
Closes #123

### 检查清单
- [x] 代码符合项目规范
- [x] 添加了必要的测试
- [x] 更新了相关文档
- [x] 通过了所有检查

2. 代码审查

审查要点：

// 代码质量检查
// ✅ 好的代码
const createTask = async (taskData) => {
  // 参数验证
  if (!taskData.title || taskData.title.trim() === '') {
    throw new Error('任务标题不能为空');
  }
  
  // 数据处理
  const task = {
    ...taskData,
    id: generateId(),
    createdAt: new Date(),
    status: 'pending'
  };
  
  // 保存到数据库
  return await db.collection('tasks').add(task);
};

// ❌ 需要改进的代码
const createTask = (data) => {
  // 缺少参数验证
  // 缺少错误处理
  // 变量命名不清晰
  let t = { ...data, id: Math.random() };
  db.collection('tasks').add(t);
};

审查评论示例：

## 代码审查意见

### 总体评价
代码整体结构清晰，功能实现正确。有几个小建议：

### 具体建议

**src/components/TaskCard.js:25**
```suggestion
// 建议添加 PropTypes 类型检查
import PropTypes from 'prop-types';

TaskCard.propTypes = {
  task: PropTypes.object.isRequired,
  onEdit: PropTypes.func.isRequired,
  onDelete: PropTypes.func.isRequired
};

src/utils/dateFormat.js:10

// 建议使用更健壮的日期格式化
const formatDate = (date) => {
  if (!date) return '';
  return new Intl.DateTimeFormat('zh-CN').format(new Date(date));
};

测试覆盖

请为新增的 TaskCard 组件添加单元测试。

文档

建议更新 README.md 中的组件使用说明。

### 3. 冲突解决

**合并冲突处理**：
```bash
# 更新本地分支
git checkout feature/user-profile
git fetch origin
git rebase origin/main

# 如果有冲突，手动解决
# 编辑冲突文件，保留需要的代码

# 标记冲突已解决
git add .
git rebase --continue

# 推送更新
git push --force-with-lease origin feature/user-profile

冲突解决示例：

// 冲突文件内容
<<<<<<< HEAD
const API_URL = 'https://api.production.com';
=======
const API_URL = 'https://api.staging.com';
>>>>>>> feature/user-profile

// 解决后的内容
const API_URL = process.env.NODE_ENV === 'production' 
  ? 'https://api.production.com'
  : 'https://api.staging.com';

版本管理

1. 语义化版本

版本号格式：MAJOR.MINOR.PATCH

• MAJOR：不兼容的 API 修改
• MINOR：向下兼容的功能性新增
• PATCH：向下兼容的问题修正

版本示例：

# 修复 Bug
git tag v1.0.1

# 新增功能
git tag v1.1.0

# 重大更新
git tag v2.0.0

# 预发布版本
git tag v1.1.0-beta.1
git tag v1.1.0-rc.1

2. 发布管理

自动化发布脚本：

#!/bin/bash
# scripts/release.sh

set -e

# 获取当前版本
CURRENT_VERSION=$(node -p "require('./package.json').version")
echo "当前版本: $CURRENT_VERSION"

# 获取新版本号
echo "请输入新版本号 (当前: $CURRENT_VERSION):"
read NEW_VERSION

# 验证版本号格式
if ! [[ $NEW_VERSION =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
  echo "错误: 版本号格式不正确"
  exit 1
fi

# 更新版本号
npm version $NEW_VERSION --no-git-tag-version

# 构建项目
echo "构建项目..."
npm run build

# 运行测试
echo "运行测试..."
npm test

# 提交变更
git add .
git commit -m "chore: bump version to $NEW_VERSION"

# 创建标签
git tag -a v$NEW_VERSION -m "Release version $NEW_VERSION"

# 推送到远程
git push origin main
git push origin v$NEW_VERSION

echo "版本 $NEW_VERSION 发布完成!"

3. 变更日志

CHANGELOG.md 格式：

# 变更日志

所有重要的项目变更都会记录在此文件中。

格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)，
版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。

## [未发布]

### 新增
- 用户个人资料页面
- 任务标签功能

### 修改
- 优化任务列表性能
- 改进移动端适配

### 修复
- 修复登录状态丢失问题
- 解决任务删除确认对话框显示异常

## [1.1.0] - 2024-01-15

### 新增
- 任务分类管理功能
- 数据导出功能
- 暗色主题支持

### 修改
- 重构用户认证模块
- 优化数据库查询性能

### 修复
- 修复任务截止日期显示错误
- 解决文件上传失败问题

### 移除
- 移除过时的 API 接口

## [1.0.0] - 2024-01-01

### 新增
- 初始版本发布
- 用户注册登录功能
- 任务管理基础功能
- 响应式界面设计

CI/CD 集成

1. GitHub Actions

工作流配置：

# .github/workflows/ci.yml
name: CI/CD Pipeline

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    
    strategy:
      matrix:
        node-version: [14.x, 16.x, 18.x]
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Setup Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v3
      with:
        node-version: ${{ matrix.node-version }}
        cache: 'npm'
    
    - name: Install dependencies
      run: npm ci
    
    - name: Run linter
      run: npm run lint
    
    - name: Run tests
      run: npm test -- --coverage
    
    - name: Upload coverage to Codecov
      uses: codecov/codecov-action@v3
  
  build:
    needs: test
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '18.x'
        cache: 'npm'
    
    - name: Install dependencies
      run: npm ci
    
    - name: Build project
      run: npm run build
    
    - name: Upload build artifacts
      uses: actions/upload-artifact@v3
      with:
        name: build-files
        path: dist/
  
  deploy:
    needs: build
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Download build artifacts
      uses: actions/download-artifact@v3
      with:
        name: build-files
        path: dist/
    
    - name: Deploy to CloudBase
      env:
        TCB_ENV: ${{ secrets.TCB_ENV }}
        TCB_SECRET_ID: ${{ secrets.TCB_SECRET_ID }}
        TCB_SECRET_KEY: ${{ secrets.TCB_SECRET_KEY }}
      run: |
        npm install -g @cloudbase/cli
        tcb login --apiKeyId $TCB_SECRET_ID --apiKey $TCB_SECRET_KEY
        tcb hosting:deploy dist/ -e $TCB_ENV
        tcb functions:deploy -e $TCB_ENV

2. 自动化测试

测试配置：

// jest.config.js
module.exports = {
  testEnvironment: 'jsdom',
  setupFilesAfterEnv: ['<rootDir>/src/setupTests.js'],
  moduleNameMapping: {
    '\\.(css|less|scss|sass)$': 'identity-obj-proxy',
    '^@/(.*)$': '<rootDir>/src/$1'
  },
  collectCoverageFrom: [
    'src/**/*.{js,jsx}',
    '!src/index.js',
    '!src/serviceWorker.js',
    '!src/**/*.test.{js,jsx}'
  ],
  coverageThreshold: {
    global: {
      branches: 80,
      functions: 80,
      lines: 80,
      statements: 80
    }
  }
};

测试脚本：

{
  "scripts": {
    "test": "jest",
    "test:watch": "jest --watch",
    "test:coverage": "jest --coverage",
    "test:ci": "jest --ci --coverage --watchAll=false"
  }
}

常见问题

Q: 如何处理大文件的版本控制？

A: 使用 Git LFS (Large File Storage) 来管理大文件，避免仓库体积过大。

Q: 团队成员的 Git 配置不一致怎么办？

A: 使用 .editorconfig 和 .gitattributes 文件统一配置，设置代码格式化规则。

Q: 如何回滚到之前的版本？

A: 使用 git revert 或 git reset 命令，建议在生产环境使用 revert 保持历史记录。

Q: 分支太多导致混乱怎么办？

A: 定期清理已合并的分支，建立分支命名规范，使用分支保护规则。

下一步

完成 Git 管理配置后，可以进行资源管理和监控：

📊 配置资源管理 →

或者返回查看其他开发流程：

🚀 查看应用发布 →