Claude Code 专业开发手册

Enterprise-Grade AI-Assisted Development Guide
Version: 2.0 Pro Edition | 2026-03 | For Professional Development Teams

作者团队: Claude AI Engineering Team
目标读者: 资深开发者、技术负责人、架构师
文档规模: 10,000+ 字 | 15+架构图 | 完整实战案例

📑 快速导航

章节	核心内容
第一部分	AI 编程方法论
第二部分	Claude Code 工具体系
第三部分	工程实践
第四部分	工程化能力
第五部分	团队协作
第六部分	架构设计
第七部分	SaaS 实战案例

第一部分：AI 编程方法论

1.1 AI 编程时代的软件开发模式

1.1.1 范式转变：从代码编写到意图表达

graph TB
    subgraph Traditional["传统开发范式"]
        T1[学习语法] --> T2[编写代码]
        T2 --> T3[调试bug]
        T3 --> T4[重构优化]
        T4 --> T5[文档编写]
    end

    subgraph AI["AI辅助开发范式"]
        A1[表达意图] --> A2[AI生成方案]
        A2 --> A3[人工审核]
        A3 --> A4[迭代优化]
        A4 --> A5[自动文档]
    end

    subgraph Metrics["效能对比"]
        M1[开发速度: 3-5x]
        M2[代码质量: ↑30%]
        M3[学习曲线: ↓60%]
        M4[维护成本: ↓40%]
    end

    Traditional -.演变.-> AI
    AI --> Metrics

    style Traditional fill:#FFE6E6
    style AI fill:#E6F3FF
    style Metrics fill:#90EE90

核心理念转变：

维度	传统模式	AI辅助模式	提升幅度
思维方式	How (如何实现)	What (做什么)	认知负担 ↓50%
技能要求	语法熟练度	架构设计能力	专业度 ↑
时间分配	80%编码 + 20%思考	30%编码 + 70%设计	创造力 ↑300%
代码质量	依赖个人经验	AI最佳实践 + 人工审核	一致性 ↑↑↑
学习曲线	陡峭且漫长	平缓但持续	上手速度 ↑5x
团队效能	线性扩展	指数级增长	产出 ↑3-10x

1.1.2 AI Coding 完整工作流

flowchart TD
    Start([需求产生]) --> Think{需求类型?}

    Think -->|新功能| Design[架构设计]
    Think -->|Bug修复| Debug[问题分析]
    Think -->|重构| Refactor[代码审查]

    Design --> Prompt1[编写Prompt]
    Debug --> Prompt2[描述问题]
    Refactor --> Prompt3[重构策略]

    Prompt1 --> Generate[Claude生成代码]
    Prompt2 --> Generate
    Prompt3 --> Generate

    Generate --> Review{人工审核}

    Review -->|优秀| Accept[接受代码]
    Review -->|良好| Refine[细化需求]
    Review -->|不佳| Rethink[重新思考]

    Refine --> Prompt1
    Rethink --> Think

    Accept --> Test[运行测试]

    Test --> TestResult{测试结果}
    TestResult -->|通过| Commit[提交代码]
    TestResult -->|失败| AIDebug[AI辅助调试]

    AIDebug --> Generate

    Commit --> Deploy[部署]
    Deploy --> Monitor[监控]

    Monitor --> Feedback{反馈}
    Feedback -->|问题| Debug
    Feedback -->|优化| Refactor
    Feedback -->|正常| End([完成])

    style Generate fill:#B3D9FF
    style Review fill:#FFFFB3
    style Test fill:#D9FFB3
    style Deploy fill:#FFB3D9
    style End fill:#90EE90

1.1.3 开发者角色演进

mindmap
  root((AI时代开发者))
    架构师
      系统设计
      技术选型
      性能优化
      安全审查
    产品经理
      需求分析
      功能规划
      优先级管理
      用户体验
    代码审查员
      质量把关
      最佳实践
      性能评估
      安全验证
    Prompt工程师
      精准表达
      上下文管理
      迭代优化
      模式总结

1.2 Claude Code 工作机制深度解析

1.2.1 系统架构全景图

graph TB
    subgraph UserLayer["用户层"]
        CLI[Claude CLI]
        Editor[IDE/Editor]
        Terminal[Terminal]
    end

    subgraph CoreEngine["核心引擎"]
        Parser[命令解析器]
        ContextMgr[上下文管理器]
        LLM[Claude AI 模型]
        Executor[执行引擎]
        Security[安全沙箱]
    end

    subgraph ToolIntegration["工具集成层"]
        Git[Git系统]
        FileSystem[文件系统]
        Shell[Shell命令]
        MCP[MCP服务器]
        WebSearch[Web搜索]
    end

    subgraph External["外部服务"]
        AnthropicAPI[Anthropic API]
        GitHub[GitHub]
        Database[(数据库)]
        Cloud[云服务]
    end

    CLI --> Parser
    Parser --> ContextMgr
    ContextMgr --> LLM
    LLM --> Executor
    Executor --> Security

    Security --> Git
    Security --> FileSystem
    Security --> Shell
    Security --> MCP

    LLM <--> AnthropicAPI
    MCP <--> GitHub
    MCP <--> Database
    MCP <--> Cloud

    ContextMgr <-.监听.-> FileSystem
    Executor -.输出.-> Terminal

    style LLM fill:#4DA6FF
    style ContextMgr fill:#FF9999
    style Security fill:#FFD700
    style Executor fill:#99FF99

1.2.2 上下文理解与管理机制

sequenceDiagram
    participant User
    participant CLI
    participant Context as 上下文管理器
    participant FileSystem
    participant Git
    participant LLM as Claude AI

    User->>CLI: 启动项目
    CLI->>Context: 初始化上下文

    Context->>FileSystem: 扫描项目结构
    FileSystem-->>Context: 返回文件树

    Context->>Git: 读取Git历史
    Git-->>Context: 返回提交记录

    Context->>Context: 构建依赖图谱
    Context->>Context: 生成语义索引

    User->>CLI: 发送请求
    CLI->>Context: 获取相关上下文

    Context->>Context: 智能选择文件
    Context->>LLM: 发送上下文+请求

    LLM->>LLM: 分析需求
    LLM-->>CLI: 返回方案

    CLI-->>User: 显示方案
    User->>CLI: 确认执行

    CLI->>FileSystem: 执行修改
    FileSystem-->>Context: 更新上下文

    Note over Context: 增量更新，避免重新扫描

1.2.3 智能上下文选择算法

// Claude Code 上下文选择伪代码
interface ContextSelectionStrategy {
  // 1. 基于相关性评分
  scoreByRelevance(file: File, query: string): number

  // 2. 基于依赖关系
  scoreByDependency(file: File, currentFiles: File[]): number

  // 3. 基于修改频率
  scoreByModificationFrequency(file: File): number

  // 4. 基于代码相似度
  scoreBySimilarity(file: File, query: string): number
}

function selectContextFiles(
  query: string,
  projectFiles: File[],
  maxTokens: number
): File[] {
  const scored = projectFiles.map(file => ({
    file,
    score: calculateCompositeScore(file, query)
  }))

  // 按分数排序
  scored.sort((a, b) => b.score - a.score)

  // 选择文件直到达到token限制
  const selected: File[] = []
  let tokenCount = 0

  for (const { file } of scored) {
    const fileTokens = estimateTokens(file)
    if (tokenCount + fileTokens <= maxTokens) {
      selected.push(file)
      tokenCount += fileTokens
    } else {
      break
    }
  }

  return selected
}

function calculateCompositeScore(file: File, query: string): number {
  return (
    0.4 * scoreByRelevance(file, query) +
    0.3 * scoreByDependency(file) +
    0.2 * scoreByRecency(file) +
    0.1 * scoreByImportance(file)
  )
}

1.2.4 执行流程与安全机制

flowchart TD
    Command[接收命令] --> Parse[解析命令]
    Parse --> Risk{风险评估}

    Risk -->|低风险| Auto[自动执行]
    Risk -->|中风险| Confirm[请求确认]
    Risk -->|高风险| Block[阻止执行]

    Confirm --> User{用户决策}
    User -->|允许一次| Once[单次执行]
    User -->|总是允许| Whitelist[加入白名单]
    User -->|拒绝| Cancel[取消]
    User -->|总是拒绝| Blacklist[加入黑名单]

    Auto --> Sandbox[安全沙箱]
    Once --> Sandbox
    Whitelist --> UpdatePolicy[更新策略]
    UpdatePolicy --> Sandbox

    Sandbox --> Execute[执行命令]
    Execute --> Monitor[监控执行]

    Monitor --> Success{执行结果}
    Success -->|成功| UpdateContext[更新上下文]
    Success -->|失败| Error[错误处理]

    Error --> Log[记录日志]
    Error --> Rollback[回滚更改]

    UpdateContext --> Return[返回结果]

    Block --> Log
    Cancel --> Log
    Blacklist --> UpdatePolicy

    style Risk fill:#FFE699
    style Sandbox fill:#B3FFB3
    style Execute fill:#B3D9FF

风险等级分类：

风险等级配置:
  低风险 (自动执行):
    - git status
    - git log
    - git diff
    - npm install
    - cat, ls, pwd
    - echo, printf

  中风险 (请求确认):
    - git commit
    - git push
    - npm publish
    - 文件修改 (create, edit, delete)
    - 数据库迁移

  高风险 (强制确认或阻止):
    - rm -rf /
    - sudo commands
    - chmod 777
    - DROP DATABASE
    - 系统文件修改

  绝对禁止:
    - dd 命令
    - fork bombs
    - :(){ :|:& };:

1.3 Prompt 工程体系

1.3.1 Prompt设计框架：CLEAR原则

mindmap
  root((CLEAR Framework))
    C: Contextual
      提供充分背景
      说明项目类型
      技术栈信息
      相关约束条件
    L: Logical
      步骤清晰
      逻辑连贯
      优先级明确
      因果关系
    E: Explicit
      明确期望
      具体要求
      输出格式
      质量标准
    A: Actionable
      可执行任务
      具体操作
      明确交付物
      验收标准
    R: Reviewable
      可验证输出
      测试标准
      审查要点
      成功指标

1.3.2 高效Prompt模板库

模板1: 功能开发完整模板

## 需求概述
创建 [功能名称] 功能，用于 [业务目标]

## 技术上下文
- **项目类型**: [Web应用/API服务/CLI工具/库]
- **技术栈**:
  - 语言: [TypeScript/Python/Go]
  - 框架: [React/Express/FastAPI]
  - 数据库: [PostgreSQL/MongoDB/Redis]
  - ORM: [Prisma/TypeORM/SQLAlchemy]
- **当前架构**: [简要说明]

## 功能规格

### 用户故事
作为 [用户角色]，我想要 [功能]，以便 [目标]

### 接口设计
```http
POST /api/v1/[resource]
Content-Type: application/json

Request:
{
  "field1": "value",
  "field2": 123
}

Response (200):
{
  "success": true,
  "data": { ... },
  "meta": { ... }
}

Error (400/401/500):
{
  "success": false,
  "error": "错误消息",
  "code": "ERROR_CODE"
}

业务逻辑

输入验证
处理流程
- 步骤1: [描述]
- 步骤2: [描述]
- 步骤3: [描述]
副作用/事件
- 发送通知: [条件]
- 更新缓存: [策略]
- 触发webhook: [时机]

数据模型

model [ModelName] {
  id        String   @id @default(cuid())
  field1    String
  field2    Int
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

错误处理

场景	HTTP状态码	错误码	处理方式
验证失败	400	VALIDATION_ERROR	返回详细字段错误
未授权	401	UNAUTHORIZED	要求登录
资源不存在	404	NOT_FOUND	友好提示
服务器错误	500	INTERNAL_ERROR	记录日志，通用消息

测试要求

单元测试覆盖率 > 80%
集成测试关键场景
测试用例：
- 成功路径: [描述]
- 验证失败: [描述]
- 边界情况: [描述]

非功能需求

性能: 响应时间 < [100ms]
安全: [SQL注入防护/XSS防护/CSRF Token]
可观测性: [日志/指标/追踪]
容错: [重试机制/降级策略]

交付标准

#### 模板2: Bug修复专用模板

```markdown
## Bug报告

### 基本信息
- **优先级**: [P0紧急/P1高/P2中/P3低]
- **影响范围**: [用户数/功能模块]
- **发现时间**: [日期时间]
- **环境**: [生产/测试/开发]

### 问题描述
[清晰简洁地描述问题]

### 复现步骤
1. 前置条件: [数据状态/用户权限]
2. 操作步骤:
   - 步骤1: [具体操作]
   - 步骤2: [具体操作]
   - 步骤3: [具体操作]
3. 触发条件: [特定输入/时间/状态]

### 期望行为
[应该发生什么]

### 实际行为
[实际发生了什么]

### 错误信息

[完整的错误堆栈/日志]

### 环境信息
- **版本**: [应用版本号]
- **浏览器/客户端**: [Chrome 120 / iOS 17]
- **设备**: [Desktop / iPhone 15]
- **数据库**: [PostgreSQL 15.2]
- **依赖版本**: [Node 20.10 / React 18.2]

### 相关代码
@file: [文件路径]
```typescript
// 问题代码片段
[相关代码，约10-20行]

假设原因

[初步分析的可能原因]

影响评估

用户影响: [描述]
数据完整性: [是否影响]
安全风险: [是否存在]
临时解决方案: [如果有]

修复要求

根因分析
修复方案设计
防止类似问题的改进
测试策略
回归测试清单

#### 模板3: 代码重构模板

```markdown
## 重构计划

### 重构目标
[为什么要重构这段代码]

### 问题分析
**代码异味:**
- [ ] 重复代码 (DRY违反)
- [ ] 过长函数 (> 50行)
- [ ] 过大类 (> 300行)
- [ ] 过长参数列表 (> 5个)
- [ ] 发散式变化
- [ ] 散弹式修改
- [ ] 中间人
- [ ] 数据泥团

**具体问题:**
1. [问题1描述]
2. [问题2描述]

@file: [文件路径]
```typescript
// 当前代码
[需要重构的代码]

重构策略

设计模式: [策略模式/工厂模式/观察者模式]

重构技法:

Extract Method (提取方法)
Extract Class (提取类)
Move Method (移动方法)
Replace Conditional with Polymorphism (以多态取代条件)
Introduce Parameter Object (引入参数对象)
Replace Magic Number with Symbolic Constant (以符号常量取代魔法数)

约束条件

API兼容性: 必须保持向后兼容
性能要求: 不能降低性能
测试覆盖: 保持或提高测试覆盖率
渐进式重构: 分多个PR完成

重构步骤

准备阶段
- 确保有充分的测试覆盖
- 创建重构分支
- 设置性能基准
执行阶段
- 第一步: [具体操作]
- 第二步: [具体操作]
- 每步后运行测试
验证阶段
- 所有测试通过
- 性能对比
- 代码审查
- 集成测试

验证标准

### 1.3.3 高级Prompt技巧

#### 技巧1: 链式思考 (Chain of Thought)

请按以下步骤思考和实现用户认证系统：

【步骤1: 需求分析】

分析认证场景
识别安全要求
确定技术约束

【步骤2: 架构设计】

选择认证方案 (JWT/Session)
设计数据模型
规划安全策略

【步骤3: 技术选型】

加密库选择
Token存储方案
中间件设计

【步骤4: 实现计划】

数据库schema
认证中间件
API端点
错误处理

【步骤5: 测试策略】

单元测试
集成测试
安全测试

对每一步，请：

说明思考过程
列出可选方案
给出推荐理由
提供代码示例

#### 技巧2: 少样本学习 (Few-Shot Learning)

我需要创建API端点处理器，请遵循以下模式：

【示例1: 获取资源】

export async function getUser(req: Request, res: Response) {
  try {
    const { id } = req.params

    const user = await userService.findById(id)

    if (!user) {
      return res.status(404).json({
        success: false,
        error: 'User not found',
      })
    }

    res.json({
      success: true,
      data: user,
    })
  } catch (error) {
    logger.error('Get user error:', error)
    res.status(500).json({
      success: false,
      error: 'Internal server error',
    })
  }
}

【示例2: 创建资源】

export async function createUser(req: Request, res: Response) {
  try {
    const userData = req.body

    const validationError = validateUser(userData)
    if (validationError) {
      return res.status(400).json({
        success: false,
        error: validationError,
      })
    }

    const user = await userService.create(userData)

    res.status(201).json({
      success: true,
      data: user,
    })
  } catch (error) {
    logger.error('Create user error:', error)
    res.status(500).json({
      success: false,
      error: 'Internal server error',
    })
  }
}

现在请按照相同的模式创建以下端点：

updateProduct - 更新产品
deleteProduct - 删除产品
listProducts - 分页列表（支持搜索和过滤）

要求：

保持相同的错误处理模式
使用相同的响应格式
添加适当的日志记录
包含参数验证

#### 技巧3: 角色扮演提示

你是一位拥有15年经验的资深全栈架构师，专精于：

高并发系统设计
微服务架构
DevOps最佳实践
安全工程

现在需要设计一个日活千万级的社交媒体平台。

请从以下角度给出方案：

【架构师视角】

系统整体架构
技术栈选型
扩展性设计
容错策略

【安全专家视角】

认证授权方案
数据加密策略
DDoS防护
漏洞防范

【DevOps工程师视角】

CI/CD流程
容器编排
监控告警
灾备方案

【性能优化专家视角】

缓存策略
数据库优化
CDN配置
负载均衡

对每个方案，请提供：

技术选型及理由
具体实现方案
潜在风险及应对
成本评估

---

## 1.4 AI 协作开发流程

### 1.4.1 完整开发生命周期

```mermaid
graph TB
    subgraph Phase1["阶段1: 需求与设计"]
        P1A[需求收集] --> P1B[AI辅助分析]
        P1B --> P1C[架构设计]
        P1C --> P1D[任务拆分]
    end

    subgraph Phase2["阶段2: 开发实现"]
        P2A[AI生成代码] --> P2B[人工审查]
        P2B --> P2C[本地测试]
        P2C --> P2D[AI重构优化]
    end

    subgraph Phase3["阶段3: 质量保证"]
        P3A[AI生成测试] --> P3B[自动化测试]
        P3B --> P3C[代码审查]
        P3C --> P3D[性能测试]
    end

    subgraph Phase4["阶段4: 部署运维"]
        P4A[AI生成部署脚本] --> P4B[CI/CD执行]
        P4B --> P4C[灰度发布]
        P4C --> P4D[监控告警]
    end

    subgraph Feedback["持续改进"]
        F1[用户反馈]
        F2[性能指标]
        F3[错误日志]
        F4[AI分析建议]
    end

    Phase1 --> Phase2
    Phase2 --> Phase3
    Phase3 --> Phase4
    Phase4 --> Feedback

    Feedback -.迭代.-> Phase1

    style Phase1 fill:#E6F3FF
    style Phase2 fill:#FFF0E6
    style Phase3 fill:#E6FFE6
    style Phase4 fill:#FFE6F0
    style Feedback fill:#F0E6FF

1.4.2 人机协作三种模式

graph LR
    subgraph Mode1["模式1: AI First"]
        A1[用户需求] --> A2[AI完整方案]
        A2 --> A3[人工快速审核]
        A3 --> A4[直接部署]
    end

    subgraph Mode2["模式2: Human First"]
        H1[人工架构设计] --> H2[AI实现细节]
        H2 --> H3[人工整合]
        H3 --> H4[迭代优化]
    end

    subgraph Mode3["模式3: Pair Programming"]
        PP1[问题分析] --> PP2[AI建议方案]
        PP2 --> PP3[人工调整]
        PP3 --> PP4[AI实现]
        PP4 --> PP5[人工审查]
        PP5 -.循环.-> PP1
    end

    style Mode1 fill:#90EE90
    style Mode2 fill:#FFD700
    style Mode3 fill:#87CEEB

选择指南：

模式	适用场景	开发者投入	AI贡献度	风险等级
AI First	CRUD操作、标准化功能	20%	80%	低
Human First	复杂业务逻辑、核心算法	70%	30%	高
Pair Programming	重构、学习新技术、创新功能	50%	50%	中

第二部分：Claude Code 工具体系

2.1 CLI工具完全指南

2.1.1 安装方式对比

graph TD
    Start[选择安装方式] --> Check{系统环境}

    Check -->|macOS/Linux| Unix[Unix系统]
    Check -->|Windows| Win[Windows系统]
    Check -->|有Node环境| Node[Node.js环境]

    Unix --> Method1[原生安装器<br/>推荐]
    Unix --> Method2[Homebrew]

    Win --> Method3[原生安装器<br/>推荐]
    Win --> Method4[WSL + 原生]

    Node --> Method5[npm全局安装]

    Method1 --> Verify[验证安装]
    Method2 --> Verify
    Method3 --> Verify
    Method4 --> Verify
    Method5 --> Verify

    Verify --> Config[配置环境]
    Config --> Ready[准备就绪]

    style Method1 fill:#90EE90
    style Method3 fill:#90EE90
    style Ready fill:#FFD700

详细安装命令：

# ============= macOS/Linux =============

# 方式1: 原生安装器 (推荐) ⭐
curl -sL https://install.anthropic.com | sh

# 方式2: Homebrew
brew tap anthropics/tap
brew install claude-code

# 方式3: 从源码构建 (开发者)
git clone https://github.com/anthropics/claude-code
cd claude-code
make install

# ============= Windows =============

# 方式1: PowerShell安装器 (推荐) ⭐
iwr -useb https://install.anthropic.com/win | iex

# 方式2: Scoop
scoop bucket add anthropics https://github.com/anthropics/scoop-bucket
scoop install claude-code

# 方式3: Chocolatey
choco install claude-code

# ============= 跨平台 =============

# npm全局安装 (需要Node.js 18+)
npm install -g @anthropic-ai/claude-code

# pnpm
pnpm add -g @anthropic-ai/claude-code

# yarn
yarn global add @anthropic-ai/claude-code

# ============= Docker =============
docker pull anthropics/claude-code:latest
docker run -it anthropics/claude-code

2.1.2 环境配置最佳实践

# ~/.bashrc 或 ~/.zshrc

# 1. 基础配置
export CLAUDE_HOME="$HOME/.claude"
export CLAUDE_MODEL="claude-sonnet-4-6"  # 默认模型

# 2. API配置 (企业用户)
export ANTHROPIC_API_KEY="sk-ant-..."
export ANTHROPIC_API_URL="https://api.anthropic.com"  # 可自定义

# 3. 网络配置 (企业代理)
export HTTPS_PROXY="http://proxy.company.com:8080"
export HTTP_PROXY="http://proxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1,.company.local"

# 4. 性能优化
export CLAUDE_CACHE_SIZE="500MB"  # 缓存大小
export CLAUDE_MAX_CONTEXT="200000"  # 最大上下文tokens
export CLAUDE_PARALLEL_REQUESTS="5"  # 并行请求数

# 5. 开发模式
export CLAUDE_DEBUG="false"  # 生产环境关闭
export CLAUDE_LOG_LEVEL="info"  # debug|info|warn|error
export CLAUDE_LOG_FILE="$CLAUDE_HOME/logs/claude.log"

# 6. 安全配置
export CLAUDE_AUTO_ALLOW=""  # 空=不自动允许任何命令
export CLAUDE_REQUIRE_CONFIRM="git push,npm publish,rm -rf"

# 7. 别名设置 (提高效率)
alias c='claude'
alias ctest='claude /test'
alias clint='claude /lint --fix'
alias cdeploy='claude /deploy'

# 8. 项目特定配置 (可选)
export CLAUDE_PROJECT_CONFIG=".claude/config.json"

2.1.3 命令速查表 (完整版)

# ========== 会话管理 ==========
claude                       # 启动交互模式
claude "prompt"              # 单次查询
claude -c                    # 继续上次会话
claude --model opus          # 指定模型启动

/help [command]              # 帮助信息
/exit, Ctrl+D                # 退出
/clear                       # 清空历史 (节省token)
/compact                     # 压缩历史 (保留要点)
/reset                       # 完全重置

# ========== 项目初始化 ==========
claude init                  # 交互式初始化
claude init --template react # 使用模板
claude init --config config.yaml  # 配置文件

/init                        # 项目内初始化
/structure                   # 显示项目结构
/analyze                     # 深度分析项目

# ========== 代码操作 ==========
/edit <file>                 # 编辑文件
/create <file>               # 创建文件
/read <file>                 # 读取文件
/delete <file>               # 删除文件
/move <src> <dest>           # 移动文件

# ========== 开发工具 ==========
/lint                        # 代码检查
/lint --fix                  # 自动修复
/format                      # 格式化代码
/test                        # 运行测试
/test --watch                # 监听模式
/test --coverage             # 覆盖率报告
/build                       # 构建项目
/build --prod                # 生产构建

# ========== Git集成 ==========
/git status                  # Git状态
/git log                     # 提交历史
/git diff                    # 查看改动
/git commit "msg"            # 提交
/git push                    # 推送
/branch                      # 分支列表
/checkout <branch>           # 切换分支
/review-pr 123               # 审查PR

# ========== MCP服务器 ==========
/mcp list                    # 列出服务器
/mcp add github              # 添加GitHub
/mcp add postgres            # 添加PostgreSQL
/mcp remove <name>           # 移除服务器
/mcp status                  # 服务器状态

# ========== 配置管理 ==========
/model                       # 查看/切换模型
/config                      # 显示配置
/config set <key> <value>    # 设置配置
/permissions                 # 权限管理
/status                      # 系统状态
/context                     # 上下文信息
/cost                        # 使用成本

# ========== 调试诊断 ==========
/doctor                      # 健康检查
/debug                       # 调试模式
/verbose                     # 详细输出
/logs                        # 查看日志
/logs --tail                 # 实时日志

# ========== 文档生成 ==========
/document                    # 生成文档
/document api                # API文档
/readme                      # 生成README
/changelog                   # 生成CHANGELOG

# ========== 工作流 ==========
/workflow list               # 列出工作流
/workflow run ci             # 运行CI
/workflow create             # 创建工作流

# ========== 自定义命令 ==========
/alias <name> <command>      # 创建别名
/alias list                  # 列出别名
/unalias <name>              # 删除别名

# ========== 高级功能 ==========
/refactor <file>             # 重构代码
/optimize                    # 性能优化建议
/security-audit              # 安全审计
/dependencies                # 依赖分析
/migrate                     # 迁移辅助

2.2 项目初始化体系

2.2.1 技术栈决策树

graph TD
    Start[新项目] --> Type{项目类型?}

    Type -->|Web应用| WebType{前后端分离?}
    Type -->|移动应用| Mobile[移动端]
    Type -->|桌面应用| Desktop[桌面端]
    Type -->|CLI工具| CLI[命令行]
    Type -->|库/框架| Library[库/SDK]

    WebType -->|是| Frontend[前端框架选择]
    WebType -->|否| Fullstack[全栈框架]

    Frontend --> React[React]
    Frontend --> Vue[Vue]
    Frontend --> Svelte[Svelte]

    React --> ReactMeta{需要SSR?}
    ReactMeta -->|是| Next[Next.js]
    ReactMeta -->|否| Vite[Vite + React]

    Vue --> VueMeta{需要SSR?}
    VueMeta -->|是| Nuxt[Nuxt.js]
    VueMeta -->|否| ViteVue[Vite + Vue]

    Fullstack --> Remix[Remix]
    Fullstack --> Astro[Astro]

    Mobile --> MobileType{跨平台?}
    MobileType -->|是| ReactNative[React Native]
    MobileType -->|否| Native[Swift/Kotlin]

    Desktop --> Electron[Electron]
    Desktop --> Tauri[Tauri]

    CLI --> CLILang{语言选择}
    CLILang --> Go[Go]
    CLILang --> Rust[Rust]
    CLILang --> Node[Node.js]

    style Next fill:#90EE90
    style ReactNative fill:#90EE90
    style Tauri fill:#90EE90
    style Go fill:#90EE90

2.2.2 智能项目脚手架

# 交互式项目初始化
$ claude init

Claude: 我将帮你创建新项目，请回答几个问题：

┌─────────────────────────────────────────┐
│  1. 项目类型是什么？                    │
│                                         │
│  ○ Web Application (全栈/前端)         │
│  ○ API Service (后端服务)              │
│  ○ Mobile App (移动应用)               │
│  ○ CLI Tool (命令行工具)               │
│  ○ Library/Package (开发库)            │
│  ○ Monorepo (多包仓库)                 │
└─────────────────────────────────────────┘
选择: 1

┌─────────────────────────────────────────┐
│  2. 前端框架？                          │
│                                         │
│  ● React (推荐)                         │
│  ○ Vue                                  │
│  ○ Svelte                               │
│  ○ Angular                              │
│  ○ Solid.js                             │
└─────────────────────────────────────────┘
选择: React

┌─────────────────────────────────────────┐
│  3. 需要服务端渲染(SSR)?                │
│                                         │
│  ● 是 - Next.js (推荐)                  │
│  ○ 否 - Vite                            │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│  4. TypeScript严格模式？                │
│                                         │
│  ● 是 (强烈推荐)                        │
│  ○ 否                                   │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│  5. UI组件库？                          │
│                                         │
│  ● Tailwind CSS + shadcn/ui             │
│  ○ Material-UI                          │
│  ○ Ant Design                           │
│  ○ Chakra UI                            │
│  ○ 自定义                               │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│  6. 状态管理？                          │
│                                         │
│  ● Zustand (轻量级)                     │
│  ○ Redux Toolkit                        │
│  ○ Jotai                                │
│  ○ Recoil                               │
│  ○ 不需要                               │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│  7. 后端技术栈？                        │
│                                         │
│  ● Node.js + Express                    │
│  ○ Node.js + NestJS                     │
│  ○ Python + FastAPI                     │
│  ○ Go + Gin                             │
│  ○ 仅前端 (无后端)                      │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│  8. 数据库选择？                        │
│                                         │
│  ● PostgreSQL + Prisma ORM              │
│  ○ MongoDB + Mongoose                   │
│  ○ MySQL + TypeORM                      │
│  ○ SQLite                               │
│  ○ 不需要数据库                         │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│  9. 认证方案？                          │
│                                         │
│  ● NextAuth.js (推荐)                   │
│  ○ JWT + Passport                       │
│  ○ Clerk                                │
│  ○ Auth0                                │
│  ○ 自定义                               │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│  10. 包管理器？                         │
│                                         │
│  ● pnpm (最快)                          │
│  ○ npm                                  │
│  ○ yarn                                 │
└─────────────────────────────────────────┘

Claude: 正在生成项目...

✓ 创建项目目录结构
✓ 初始化Git仓库
✓ 生成package.json
✓ 安装依赖 (这可能需要几分钟...)
✓ 配置TypeScript
✓ 设置ESLint + Prettier
✓ 配置Tailwind CSS
✓ 生成基础代码
✓ 创建示例组件
✓ 设置Prisma
✓ 生成环境变量模板
✓ 创建README.md
✓ 初始化CLAUDE.md配置

🎉 项目创建成功！

项目结构:
my-app/
├── apps/
│   ├── web/          # Next.js前端
│   └── api/          # Express后端
├── packages/
│   ├── ui/           # 共享UI组件
│   ├── config/       # 共享配置
│   └── types/        # TypeScript类型
├── prisma/           # 数据库Schema
├── docs/             # 文档
└── CLAUDE.md         # Claude Code配置

下一步:
1. cd my-app
2. cp .env.example .env  # 配置环境变量
3. npx prisma migrate dev  # 运行数据库迁移
4. pnpm dev  # 启动开发服务器

访问: http://localhost:3000

2.2.3 项目模板库

# 可用模板列表
templates:
  # Web应用
  - name: "next-app-pro"
    description: "Next.js 15 + TypeScript + Tailwind + Prisma"
    stack:
      - Next.js 15
      - TypeScript 5
      - Tailwind CSS 4
      - Prisma ORM
      - NextAuth.js
      - React Query
      - Zustand

  - name: "react-spa"
    description: "Vite + React + TypeScript SPA"
    stack:
      - Vite 5
      - React 18
      - TypeScript
      - React Router
      - TanStack Query

  # API服务
  - name: "express-api"
    description: "Express + TypeScript + Prisma API"
    stack:
      - Express 5
      - TypeScript
      - Prisma
      - JWT Auth
      - Swagger

  - name: "nestjs-api"
    description: "NestJS企业级API"
    stack:
      - NestJS 10
      - TypeScript
      - Prisma/TypeORM
      - Passport
      - GraphQL (可选)

  - name: "fastapi"
    description: "Python FastAPI高性能API"
    stack:
      - FastAPI
      - SQLAlchemy
      - Pydantic
      - JWT Auth

  # 全栈
  - name: "t3-stack"
    description: "T3 Stack (Next.js + tRPC + Prisma)"
    stack:
      - Next.js
      - tRPC
      - Prisma
      - NextAuth
      - Tailwind

  # 移动应用
  - name: "react-native-app"
    description: "React Native跨平台应用"
    stack:
      - React Native
      - Expo
      - TypeScript
      - Navigation

  # CLI工具
  - name: "cli-tool-ts"
    description: "Node.js CLI工具"
    stack:
      - TypeScript
      - Commander.js
      - Inquirer

  - name: "cli-tool-go"
    description: "Go CLI工具"
    stack:
      - Go 1.21+
      - Cobra
      - Viper

  # Monorepo
  - name: "turborepo"
    description: "Turborepo多包管理"
    stack:
      - Turborepo
      - Next.js + Express
      - Shared packages
      - pnpm workspaces

2.3 文件结构最佳实践

2.3.1 现代化前端项目结构

modern-frontend/
├── .github/                    # GitHub配置
│   ├── workflows/
│   │   ├── ci.yml
│   │   ├── deploy.yml
│   │   └── pr-check.yml
│   └── PULL_REQUEST_TEMPLATE.md
│
├── public/                     # 静态资源
│   ├── images/
│   ├── fonts/
│   └── locales/               # i18n翻译文件
│
├── src/
│   ├── app/                   # 应用入口
│   │   ├── App.tsx
│   │   ├── router.tsx
│   │   └── providers.tsx
│   │
│   ├── features/              # 功能模块 (Feature-Sliced Design)
│   │   ├── auth/
│   │   │   ├── api/          # API调用
│   │   │   │   ├── login.ts
│   │   │   │   └── register.ts
│   │   │   ├── components/   # 特定组件
│   │   │   │   ├── LoginForm.tsx
│   │   │   │   └── RegisterForm.tsx
│   │   │   ├── hooks/        # 特定hooks
│   │   │   │   └── useAuth.ts
│   │   │   ├── store/        # 状态管理
│   │   │   │   └── authStore.ts
│   │   │   ├── types/        # 类型定义
│   │   │   │   └── auth.types.ts
│   │   │   ├── utils/        # 工具函数
│   │   │   │   └── validation.ts
│   │   │   └── index.ts      # 导出
│   │   │
│   │   ├── dashboard/
│   │   ├── user-profile/
│   │   └── settings/
│   │
│   ├── shared/                # 共享资源
│   │   ├── ui/               # 通用UI组件
│   │   │   ├── Button/
│   │   │   │   ├── Button.tsx
│   │   │   │   ├── Button.test.tsx
│   │   │   │   ├── Button.stories.tsx
│   │   │   │   └── index.ts
│   │   │   ├── Input/
│   │   │   ├── Modal/
│   │   │   └── index.ts
│   │   │
│   │   ├── lib/              # 工具库
│   │   │   ├── api-client.ts
│   │   │   ├── storage.ts
│   │   │   └── utils.ts
│   │   │
│   │   ├── hooks/            # 通用hooks
│   │   │   ├── useDebounce.ts
│   │   │   ├── useMediaQuery.ts
│   │   │   └── useLocalStorage.ts
│   │   │
│   │   ├── types/            # 全局类型
│   │   │   ├── api.types.ts
│   │   │   └── common.types.ts
│   │   │
│   │   ├── constants/        # 常量
│   │   │   ├── routes.ts
│   │   │   ├── config.ts
│   │   │   └── api-endpoints.ts
│   │   │
│   │   └── styles/           # 全局样式
│   │       ├── globals.css
│   │       └── theme.ts
│   │
│   ├── assets/               # 资源文件
│   │   ├── images/
│   │   └── icons/
│   │
│   └── main.tsx              # 入口文件
│
├── tests/                    # 测试
│   ├── unit/
│   ├── integration/
│   └── e2e/
│
├── docs/                     # 文档
│   ├── architecture.md
│   ├── api.md
│   └── deployment.md
│
├── scripts/                  # 脚本
│   ├── build.sh
│   └── deploy.sh
│
├── .env.example              # 环境变量模板
├── .eslintrc.js              # ESLint配置
├── .prettierrc               # Prettier配置
├── tsconfig.json             # TypeScript配置
├── vite.config.ts            # Vite配置
├── tailwind.config.js        # Tailwind配置
├── package.json
├── pnpm-lock.yaml
├── README.md
└── CLAUDE.md                 # Claude Code配置

2.3.2 企业级后端项目结构

enterprise-backend/
├── src/
│   ├── app.ts                # Express应用配置
│   ├── server.ts             # 服务器入口
│   │
│   ├── config/               # 配置管理
│   │   ├── database.ts       # 数据库配置
│   │   ├── redis.ts          # Redis配置
│   │   ├── logger.ts         # 日志配置
│   │   ├── queue.ts          # 队列配置
│   │   └── env.ts            # 环境变量
│   │
│   ├── modules/              # 业务模块
│   │   ├── users/
│   │   │   ├── users.controller.ts
│   │   │   ├── users.service.ts
│   │   │   ├── users.repository.ts
│   │   │   ├── users.model.ts
│   │   │   ├── users.dto.ts
│   │   │   ├── users.validator.ts
│   │   │   ├── users.routes.ts
│   │   │   ├── users.test.ts
│   │   │   └── index.ts
│   │   │
│   │   ├── auth/
│   │   ├── posts/
│   │   └── notifications/
│   │
│   ├── shared/               # 共享模块
│   │   ├── middleware/
│   │   │   ├── auth.middleware.ts
│   │   │   ├── error.middleware.ts
│   │   │   ├── logger.middleware.ts
│   │   │   ├── rate-limit.middleware.ts
│   │   │   └── validate.middleware.ts
│   │   │
│   │   ├── services/
│   │   │   ├── email.service.ts
│   │   │   ├── storage.service.ts
│   │   │   ├── cache.service.ts
│   │   │   ├── queue.service.ts
│   │   │   └── notification.service.ts
│   │   │
│   │   ├── utils/
│   │   │   ├── crypto.ts
│   │   │   ├── validation.ts
│   │   │   ├── pagination.ts
│   │   │   └── formatter.ts
│   │   │
│   │   ├── types/
│   │   │   ├── express.d.ts
│   │   │   ├── common.types.ts
│   │   │   └── api.types.ts
│   │   │
│   │   ├── errors/
│   │   │   ├── AppError.ts
│   │   │   ├── NotFoundError.ts
│   │   │   └── ValidationError.ts
│   │   │
│   │   └── constants/
│   │       ├── errors.ts
│   │       ├── messages.ts
│   │       └── config.ts
│   │
│   ├── database/             # 数据库
│   │   ├── migrations/
│   │   ├── seeds/
│   │   └── prisma/
│   │       ├── schema.prisma
│   │       └── migrations/
│   │
│   ├── jobs/                 # 后台任务
│   │   ├── email-queue.ts
│   │   ├── cleanup.ts
│   │   └── analytics.ts
│   │
│   └── docs/                 # API文档
│       └── swagger/
│           └── openapi.yaml
│
├── tests/
│   ├── unit/
│   ├── integration/
│   └── e2e/
│
├── scripts/
│   ├── seed.ts
│   ├── migrate.ts
│   └── deploy.sh
│
├── docs/
│   ├── architecture.md
│   ├── api.md
│   └── database-schema.md
│
├── .env.example
├── .dockerignore
├── Dockerfile
├── docker-compose.yml
├── package.json
├── tsconfig.json
├── jest.config.js
├── README.md
└── CLAUDE.md

2.3.3 Monorepo结构 (Turborepo)

my-monorepo/
├── apps/                     # 应用程序
│   ├── web/                  # Next.js Web应用
│   │   ├── src/
│   │   ├── public/
│   │   ├── package.json
│   │   ├── next.config.js
│   │   └── tsconfig.json
│   │
│   ├── mobile/               # React Native应用
│   │   ├── src/
│   │   ├── ios/
│   │   ├── android/
│   │   └── package.json
│   │
│   ├── admin/                # 管理后台
│   │   └── ...
│   │
│   └── docs/                 # 文档站点
│       └── ...
│
├── services/                 # 后端服务
│   ├── api-gateway/          # API网关
│   │   ├── src/
│   │   ├── Dockerfile
│   │   └── package.json
│   │
│   ├── auth-service/         # 认证服务
│   ├── user-service/         # 用户服务
│   └── notification-service/ # 通知服务
│
├── packages/                 # 共享包
│   ├── ui/                   # UI组件库
│   │   ├── src/
│   │   │   ├── Button/
│   │   │   ├── Input/
│   │   │   └── index.ts
│   │   ├── package.json
│   │   └── tsconfig.json
│   │
│   ├── shared/               # 共享代码
│   │   ├── src/
│   │   │   ├── types/
│   │   │   ├── utils/
│   │   │   └── constants/
│   │   └── package.json
│   │
│   ├── api-client/           # API客户端
│   │   ├── src/
│   │   └── package.json
│   │
│   ├── config/               # 共享配置
│   │   ├── eslint/
│   │   ├── typescript/
│   │   ├── tailwind/
│   │   └── package.json
│   │
│   └── database/             # 数据库Schema
│       ├── prisma/
│       └── package.json
│
├── tools/                    # 开发工具
│   ├── generators/           # 代码生成器
│   └── scripts/              # 脚本
│
├── .github/
│   └── workflows/
│
├── docs/                     # 项目文档
├── pnpm-workspace.yaml       # pnpm工作区配置
├── turbo.json                # Turborepo配置
├── package.json
├── tsconfig.base.json        # 基础TS配置
├── README.md
└── CLAUDE.md

第三部分：工程实践

3.1 前端开发实践

3.1.1 React 18+ 现代化开发

组件设计原则

typescript

// ❌ 反模式：单一巨型组件
function UserDashboard() {
  const [user, setUser] = useState(null)
  const [posts, setPosts] = useState([])
  const [comments, setComments] = useState([])
  const [loading, setLoading] = useState(true)

  useEffect(() => {
    // 100+ 行混乱的数据获取逻辑
  }, [])

  return (
    <div>
      {/* 300+ 行复杂的JSX */}
    </div>
  )
}

// ✅ 最佳实践：组合式组件
function UserDashboard() {
  const { user, loading } = useUser()

  if (loading) return <DashboardSkeleton />
  if (!user) return <Navigate to="/login" />

  return (
    <DashboardLayout user={user}>
      <Suspense fallback={<Spinner />}>
        <UserProfile user={user} />
        <UserContent userId={user.id} />
        <UserActivity userId={user.id} />
      </Suspense>
    </DashboardLayout>
  )
}

// 单一职责组件
function UserProfile({ user }: { user: User }) {
  return (
    <Card>
      <Avatar src={user.avatar} size="lg" />
      <UserInfo name={user.name} email={user.email} />
      <UserStats followers={user.followers} following={user.following} />
      <EditProfileButton userId={user.id} />
    </Card>
  )
}

自定义Hooks最佳实践

typescript

// ✅ 封装复杂业务逻辑
function useUser(userId?: string) {
  const [user, setUser] = useState<User | null>(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState<Error | null>(null)

  useEffect(() => {
    if (!userId) {
      setLoading(false)
      return
    }

    let cancelled = false

    const fetchUser = async () => {
      try {
        setLoading(true)
        const data = await api.users.get(userId)

        if (!cancelled) {
          setUser(data)
          setError(null)
        }
      } catch (err) {
        if (!cancelled) {
          setError(err as Error)
        }
      } finally {
        if (!cancelled) {
          setLoading(false)
        }
      }
    }

    fetchUser()

    return () => {
      cancelled = true
    }
  }, [userId])

  const refetch = useCallback(() => {
    if (userId) {
      setLoading(true)
      api.users.get(userId).then(setUser)
    }
  }, [userId])

  return { user, loading, error, refetch }
}

// ✅ 表单管理Hook
function useForm<T extends Record<string, any>>(
  initialValues: T,
  validationSchema?: z.ZodSchema<T>
) {
  const [values, setValues] = useState<T>(initialValues)
  const [errors, setErrors] = useState<Partial<Record<keyof T, string>>>({})
  const [touched, setTouched] = useState<Partial<Record<keyof T, boolean>>>({})
  const [isSubmitting, setIsSubmitting] = useState(false)

  const handleChange = (name: keyof T) => (
    e: React.ChangeEvent<HTMLInputElement>
  ) => {
    setValues(prev => ({ ...prev, [name]: e.target.value }))
    setTouched(prev => ({ ...prev, [name]: true }))
  }

  const validate = useCallback(() => {
    if (!validationSchema) return true

    try {
      validationSchema.parse(values)
      setErrors({})
      return true
    } catch (err) {
      if (err instanceof z.ZodError) {
        const fieldErrors: Partial<Record<keyof T, string>> = {}
        err.errors.forEach(error => {
          const path = error.path[0] as keyof T
          fieldErrors[path] = error.message
        })
        setErrors(fieldErrors)
      }
      return false
    }
  }, [values, validationSchema])

  const handleSubmit = (onSubmit: (values: T) => Promise<void>) =>
    async (e: React.FormEvent) => {
      e.preventDefault()

      if (!validate()) return

      setIsSubmitting(true)
      try {
        await onSubmit(values)
      } finally {
        setIsSubmitting(false)
      }
    }

  const reset = () => {
    setValues(initialValues)
    setErrors({})
    setTouched({})
  }

  return {
    values,
    errors,
    touched,
    isSubmitting,
    handleChange,
    handleSubmit,
    reset,
  }
}

性能优化实战

typescript

// 1. React.memo + 自定义比较
const ExpensiveComponent = React.memo(
  ({ data, onAction }: Props) => {
    console.log('Rendering ExpensiveComponent')

    return (
      <div>
        {/* 复杂渲染逻辑 */}
      </div>
    )
  },
  (prevProps, nextProps) => {
    // 自定义比较逻辑
    return (
      prevProps.data.id === nextProps.data.id &&
      prevProps.data.updatedAt === nextProps.data.updatedAt
    )
  }
)

// 2. useMemo - 缓存计算结果
function ProductList({ products, filters }: Props) {
  // 缓存过滤和排序结果
  const filteredProducts = useMemo(() => {
    let result = products

    if (filters.search) {
      result = result.filter(p =>
        p.name.toLowerCase().includes(filters.search.toLowerCase())
      )
    }

    if (filters.category) {
      result = result.filter(p => p.category === filters.category)
    }

    if (filters.sortBy) {
      result = [...result].sort((a, b) => {
        switch (filters.sortBy) {
          case 'price-asc':
            return a.price - b.price
          case 'price-desc':
            return b.price - a.price
          case 'name':
            return a.name.localeCompare(b.name)
          default:
            return 0
        }
      })
    }

    return result
  }, [products, filters])

  // 缓存统计信息
  const stats = useMemo(() => ({
    total: filteredProducts.length,
    averagePrice: filteredProducts.reduce((sum, p) => sum + p.price, 0) /
                  filteredProducts.length,
    categories: new Set(filteredProducts.map(p => p.category)).size,
  }), [filteredProducts])

  return (
    <div>
      <ProductStats stats={stats} />
      <ProductGrid products={filteredProducts} />
    </div>
  )
}

// 3. useCallback - 稳定的回调引用
function TodoList({ todos }: { todos: Todo[] }) {
  const [filter, setFilter] = useState<'all' | 'active' | 'completed'>('all')

  // 稳定的回调，避免子组件重新渲染
  const handleToggle = useCallback((id: string) => {
    updateTodo(id, todo => ({ ...todo, completed: !todo.completed }))
  }, [])

  const handleDelete = useCallback((id: string) => {
    deleteTodo(id)
  }, [])

  const filteredTodos = useMemo(() => {
    switch (filter) {
      case 'active':
        return todos.filter(t => !t.completed)
      case 'completed':
        return todos.filter(t => t.completed)
      default:
        return todos
    }
  }, [todos, filter])

  return (
    <div>
      <FilterBar value={filter} onChange={setFilter} />
      {filteredTodos.map(todo => (
        <TodoItem
          key={todo.id}
          todo={todo}
          onToggle={handleToggle}
          onDelete={handleDelete}
        />
      ))}
    </div>
  )
}

// 4. 虚拟滚动 - 大列表优化
import { FixedSizeList as List } from 'react-window'

function VirtualizedList({ items }: { items: Item[] }) {
  const Row = ({ index, style }: { index: number; style: React.CSSProperties }) => (
    <div style={style}>
      <ItemCard item={items[index]} />
    </div>
  )

  return (
    <List
      height={600}
      itemCount={items.length}
      itemSize={100}
      width="100%"
    >
      {Row}
    </List>
  )
}

// 5. Code Splitting
const AdminPanel = lazy(() => import('./AdminPanel'))
const Analytics = lazy(() => import('./Analytics'))

function App() {
  const { user } = useAuth()

  return (
    <Suspense fallback={<PageLoader />}>
      <Routes>
        <Route path="/" element={<Home />} />
        <Route
          path="/admin"
          element={user?.role === 'admin' ? <AdminPanel /> : <Navigate to="/" />}
        />
        <Route path="/analytics" element={<Analytics />} />
      </Routes>
    </Suspense>
  )
}

3.1.2 状态管理 - Zustand

typescript

import { create } from 'zustand'
import { devtools, persist } from 'zustand/middleware'

interface AuthState {
  user: User | null
  token: string | null
  isAuthenticated: boolean

  // Actions
  login: (email: string, password: string) => Promise<void>
  logout: () => void
  refreshToken: () => Promise<void>
  updateProfile: (data: Partial<User>) => Promise<void>
}

export const useAuthStore = create<AuthState>()(
  devtools(
    persist(
      (set, get) => ({
        user: null,
        token: null,
        isAuthenticated: false,

        login: async (email, password) => {
          try {
            const response = await api.auth.login({ email, password })

            set({
              user: response.user,
              token: response.token,
              isAuthenticated: true,
            })

            // 设置axios默认header
            api.setAuthToken(response.token)

            // 启动token刷新定时器
            startTokenRefresh()
          } catch (error) {
            set({ user: null, token: null, isAuthenticated: false })
            throw error
          }
        },

        logout: () => {
          set({ user: null, token: null, isAuthenticated: false })
          api.setAuthToken(null)
          stopTokenRefresh()
        },

        refreshToken: async () => {
          try {
            const response = await api.auth.refresh()
            set({ token: response.token })
            api.setAuthToken(response.token)
          } catch (error) {
            get().logout()
          }
        },

        updateProfile: async (data) => {
          const updatedUser = await api.users.update(get().user!.id, data)
          set({ user: updatedUser })
        },
      }),
      {
        name: 'auth-storage',
        partialize: (state) => ({
          token: state.token,
          user: state.user,
        }),
      }
    )
  )
)

// 使用
function LoginPage() {
  const login = useAuthStore(state => state.login)
  const [loading, setLoading] = useState(false)

  const handleSubmit = async (email: string, password: string) => {
    setLoading(true)
    try {
      await login(email, password)
      navigate('/dashboard')
    } catch (error) {
      toast.error('登录失败')
    } finally {
      setLoading(false)
    }
  }

  return <LoginForm onSubmit={handleSubmit} loading={loading} />
}

3.1.3 数据获取 - React Query

typescript

import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'

// 查询单个用户
export function useUser(userId: string) {
  return useQuery({
    queryKey: ['user', userId],
    queryFn: () => api.users.get(userId),
    staleTime: 5 * 60 * 1000, // 5分钟内不会重新获取
    enabled: !!userId,
  })
}

// 查询用户列表（带分页）
export function useUsers(params?: {
  page?: number
  limit?: number
  search?: string
}) {
  return useQuery({
    queryKey: ['users', params],
    queryFn: () => api.users.list(params),
    keepPreviousData: true, // 翻页时保持旧数据
  })
}

// 创建用户
export function useCreateUser() {
  const queryClient = useQueryClient()

  return useMutation({
    mutationFn: (data: CreateUserDto) => api.users.create(data),

    onMutate: async (newUser) => {
      // 取消正在进行的查询
      await queryClient.cancelQueries({ queryKey: ['users'] })

      // 保存之前的数据以便回滚
      const previousUsers = queryClient.getQueryData(['users'])

      // 乐观更新
      queryClient.setQueryData(['users'], (old: any) => ({
        ...old,
        data: [...old.data, { id: 'temp', ...newUser }],
      }))

      return { previousUsers }
    },

    onError: (err, newUser, context) => {
      // 回滚
      if (context?.previousUsers) {
        queryClient.setQueryData(['users'], context.previousUsers)
      }
      toast.error('创建失败')
    },

    onSuccess: (data) => {
      // 更新缓存
      queryClient.setQueryData(['user', data.id], data)

      // 使列表查询失效
      queryClient.invalidateQueries({ queryKey: ['users'] })

      toast.success('创建成功')
    },
  })
}

// 更新用户
export function useUpdateUser() {
  const queryClient = useQueryClient()

  return useMutation({
    mutationFn: ({ id, data }: { id: string; data: UpdateUserDto }) =>
      api.users.update(id, data),

    onSuccess: (updatedUser) => {
      // 更新单个用户缓存
      queryClient.setQueryData(['user', updatedUser.id], updatedUser)

      // 更新列表中的用户
      queryClient.setQueriesData<any>(['users'], (old) => {
        if (!old) return old
        return {
          ...old,
          data: old.data.map((user: User) =>
            user.id === updatedUser.id ? updatedUser : user
          ),
        }
      })

      toast.success('更新成功')
    },
  })
}

// 删除用户
export function useDeleteUser() {
  const queryClient = useQueryClient()

  return useMutation({
    mutationFn: (userId: string) => api.users.delete(userId),

    onSuccess: (_, deletedUserId) => {
      // 移除单个用户缓存
      queryClient.removeQueries({ queryKey: ['user', deletedUserId] })

      // 使列表失效
      queryClient.invalidateQueries({ queryKey: ['users'] })

      toast.success('删除成功')
    },
  })
}

// 无限滚动
export function useInfiniteUsers(search?: string) {
  return useInfiniteQuery({
    queryKey: ['users', 'infinite', search],
    queryFn: ({ pageParam = 1 }) =>
      api.users.list({ page: pageParam, limit: 20, search }),
    getNextPageParam: (lastPage) => {
      if (lastPage.page < lastPage.totalPages) {
        return lastPage.page + 1
      }
      return undefined
    },
  })
}

// 使用示例
function UserList() {
  const [search, setSearch] = useState('')
  const { data, isLoading, error } = useUsers({ page: 1, limit: 10, search })
  const createUser = useCreateUser()
  const deleteUser = useDeleteUser()

  if (isLoading) return <Skeleton />
  if (error) return <ErrorMessage error={error} />

  return (
    <div>
      <SearchBar value={search} onChange={setSearch} />

      <button onClick={() => createUser.mutate({ name: 'New User', email: 'new@example.com' })}>
        Create User
      </button>

      {data?.data.map(user => (
        <UserCard
          key={user.id}
          user={user}
          onDelete={() => deleteUser.mutate(user.id)}
        />
      ))}

      <Pagination
        current={data?.page}
        total={data?.totalPages}
        onChange={(page) => {/* 处理分页 */}}
      />
    </div>
  )
}

3.2 后端开发实践

3.2.1 Express + TypeScript 分层架构

mermaid

graph TB
    Client[HTTP Client] --> Router[Router层]
    Router --> Controller[Controller层<br/>处理HTTP请求/响应]
    Controller --> Service[Service层<br/>业务逻辑]
    Service --> Repository[Repository层<br/>数据访问]
    Repository --> Database[(Database)]

    Controller -.使用.-> Middleware[Middleware<br/>认证/验证/日志]
    Service -.使用.-> ExternalAPI[External APIs]
    Service -.使用.-> Queue[Message Queue]
    Service -.使用.-> Cache[Redis Cache]

    style Controller fill:#FFE6E6
    style Service fill:#E6F3FF
    style Repository fill:#E6FFE6

Controller层 - HTTP处理

typescript

import { Request, Response, NextFunction } from 'express'
import { UserService } from '../services/user.service'
import { CreateUserDto, UpdateUserDto, UserQueryDto } from '../dtos/user.dto'
import { NotFoundError } from '../errors'

export class UsersController {
  constructor(private readonly userService: UserService) {}

  async getUsers(req: Request, res: Response, next: NextFunction) {
    try {
      const query: UserQueryDto = {
        page: Number(req.query.page) || 1,
        limit: Number(req.query.limit) || 10,
        search: req.query.search as string,
        role: req.query.role as string,
        sortBy: req.query.sortBy as string,
        order: (req.query.order as 'asc' | 'desc') || 'desc',
      }

      const result = await this.userService.findAll(query)

      res.json({
        success: true,
        data: result.users,
        meta: {
          page: result.page,
          limit: result.limit,
          total: result.total,
          totalPages: Math.ceil(result.total / result.limit),
        },
      })
    } catch (error) {
      next(error)
    }
  }

  async getUser(req: Request, res: Response, next: NextFunction) {
    try {
      const { id } = req.params
      const user = await this.userService.findById(id)

      if (!user) {
        throw new NotFoundError('User not found')
      }

      res.json({
        success: true,
        data: user,
      })
    } catch (error) {
      next(error)
    }
  }

  async createUser(req: Request, res: Response, next: NextFunction) {
    try {
      const userData: CreateUserDto = req.body
      const user = await this.userService.create(userData)

      res.status(201).json({
        success: true,
        data: user,
      })
    } catch (error) {
      next(error)
    }
  }

  async updateUser(req: Request, res: Response, next: NextFunction) {
    try {
      const { id } = req.params
      const updateData: UpdateUserDto = req.body

      const user = await this.userService.update(id, updateData)

      res.json({
        success: true,
        data: user,
      })
    } catch (error) {
      next(error)
    }
  }

  async deleteUser(req: Request, res: Response, next: NextFunction) {
    try {
      const { id } = req.params
      await this.userService.delete(id)

      res.status(204).send()
    } catch (error) {
      next(error)
    }
  }
}

Service层 - 业务逻辑

typescript

import { UserRepository } from '../repositories/user.repository'
import { EmailService } from './email.service'
import { CacheService } from './cache.service'
import { QueueService } from './queue.service'
import { CreateUserDto, UpdateUserDto, UserQueryDto } from '../dtos/user.dto'
import { hashPassword, comparePassword } from '../utils/crypto'
import { ConflictError, NotFoundError } from '../errors'

export class UserService {
  constructor(
    private readonly userRepo: UserRepository,
    private readonly emailService: EmailService,
    private readonly cacheService: CacheService,
    private readonly queueService: QueueService
  ) {}

  async findAll(query: UserQueryDto) {
    const cacheKey = `users:list:${JSON.stringify(query)}`

    // 尝试从缓存获取
    const cached = await this.cacheService.get(cacheKey)
    if (cached) {
      return cached
    }

    // 从数据库查询
    const result = await this.userRepo.findAll(query)

    // 缓存结果
    await this.cacheService.set(cacheKey, result, 300) // 5分钟

    return result
  }

  async findById(id: string) {
    const cacheKey = `user:${id}`

    // 检查缓存
    const cached = await this.cacheService.get(cacheKey)
    if (cached) return cached

    // 从数据库获取
    const user = await this.userRepo.findById(id)

    if (!user) {
      throw new NotFoundError('User not found')
    }

    // 缓存用户信息
    await this.cacheService.set(cacheKey, user, 600) // 10分钟

    return user
  }

  async create(data: CreateUserDto) {
    // 1. 验证邮箱唯一性
    const existing = await this.userRepo.findByEmail(data.email)
    if (existing) {
      throw new ConflictError('Email already exists')
    }

    // 2. 哈希密码
    const hashedPassword = await hashPassword(data.password)

    // 3. 创建用户
    const user = await this.userRepo.create({
      ...data,
      password: hashedPassword,
    })

    // 4. 发送欢迎邮件（异步）
    await this.queueService.add('send-email', {
      type: 'welcome',
      to: user.email,
      data: { name: user.name },
    })

    // 5. 清除列表缓存
    await this.cacheService.deletePattern('users:list:*')

    return user
  }

  async update(id: string, data: UpdateUserDto) {
    // 检查用户存在
    const user = await this.findById(id)

    // 如果更新邮箱，检查唯一性
    if (data.email && data.email !== user.email) {
      const existing = await this.userRepo.findByEmail(data.email)
      if (existing) {
        throw new ConflictError('Email already exists')
      }
    }

    // 更新用户
    const updatedUser = await this.userRepo.update(id, data)

    // 更新缓存
    await this.cacheService.set(`user:${id}`, updatedUser, 600)
    await this.cacheService.deletePattern('users:list:*')

    return updatedUser
  }

  async delete(id: string) {
    // 检查用户存在
    await this.findById(id)

    // 删除用户
    await this.userRepo.delete(id)

    // 清除缓存
    await this.cacheService.delete(`user:${id}`)
    await this.cacheService.deletePattern('users:list:*')
  }

  async authenticate(email: string, password: string) {
    const user = await this.userRepo.findByEmail(email)

    if (!user) {
      throw new NotFoundError('Invalid credentials')
    }

    const isValid = await comparePassword(password, user.password)

    if (!isValid) {
      throw new NotFoundError('Invalid credentials')
    }

    // 更新最后登录时间
    await this.userRepo.update(user.id, {
      lastLoginAt: new Date(),
    })

    return user
  }
}

Repository层 - 数据访问

typescript

import { PrismaClient, Prisma } from '@prisma/client'
import { CreateUserDto, UpdateUserDto, UserQueryDto } from '../dtos/user.dto'

export class UserRepository {
  constructor(private readonly prisma: PrismaClient) {}

  async findAll(query: UserQueryDto) {
    const {
      page = 1,
      limit = 10,
      search,
      role,
      sortBy = 'createdAt',
      order = 'desc',
    } = query

    const where: Prisma.UserWhereInput = {}

    // 搜索条件
    if (search) {
      where.OR = [
        { name: { contains: search, mode: 'insensitive' } },
        { email: { contains: search, mode: 'insensitive' } },
      ]
    }

    // 角色过滤
    if (role) {
      where.role = role
    }

    // 并行执行查询和计数
    const [users, total] = await Promise.all([
      this.prisma.user.findMany({
        where,
        skip: (page - 1) * limit,
        take: limit,
        orderBy: { [sortBy]: order },
        select: {
          id: true,
          name: true,
          email: true,
          avatar: true,
          role: true,
          createdAt: true,
          updatedAt: true,
          // 排除敏感字段
          password: false,
        },
      }),
      this.prisma.user.count({ where }),
    ])

    return {
      users,
      total,
      page,
      limit,
    }
  }

  async findById(id: string) {
    return this.prisma.user.findUnique({
      where: { id },
      select: {
        id: true,
        name: true,
        email: true,
        avatar: true,
        role: true,
        createdAt: true,
        updatedAt: true,
        lastLoginAt: true,
        password: false,
      },
    })
  }

  async findByEmail(email: string) {
    return this.prisma.user.findUnique({
      where: { email },
    })
  }

  async create(data: CreateUserDto & { password: string }) {
    return this.prisma.user.create({
      data,
      select: {
        id: true,
        name: true,
        email: true,
        avatar: true,
        role: true,
        createdAt: true,
        password: false,
      },
    })
  }

  async update(id: string, data: UpdateUserDto) {
    return this.prisma.user.update({
      where: { id },
      data,
      select: {
        id: true,
        name: true,
        email: true,
        avatar: true,
        role: true,
        updatedAt: true,
        password: false,
      },
    })
  }

  async delete(id: string) {
    await this.prisma.user.delete({
      where: { id },
    })
  }
}

第四部分：工程化能力

4.1 自动化测试体系

4.1.1 CI/CD测试集成

name: CI Pipeline

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

jobs:
  test:
    runs-on: ubuntu-latest

    services:
      postgres:
        image: postgres:15
        env:
          POSTGRES_DB: test_db
          POSTGRES_USER: test
          POSTGRES_PASSWORD: test
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        ports:
          - 5432:5432

      redis:
        image: redis:7-alpine
        options: >-
          --health-cmd "redis-cli ping"
          --health-interval 10s
        ports:
          - 6379:6379

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'pnpm'

      - name: Install pnpm
        run: npm install -g pnpm

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Lint
        run: pnpm lint

      - name: Type check
        run: pnpm type-check

      - name: Run Prisma migrations
        run: pnpm prisma migrate deploy
        env:
          DATABASE_URL: postgresql://test:test@localhost:5432/test_db

      - name: Unit tests
        run: pnpm test:unit --coverage

      - name: Integration tests
        run: pnpm test:integration
        env:
          DATABASE_URL: postgresql://test:test@localhost:5432/test_db
          REDIS_URL: redis://localhost:6379

      - name: E2E tests
        run: pnpm test:e2e
        env:
          DATABASE_URL: postgresql://test:test@localhost:5432/test_db

      - name: Upload coverage
        uses: codecov/codecov-action@v3
        with:
          files: ./coverage/coverage-final.json
          flags: unittests
          name: codecov-umbrella

4.2 代码重构模式

4.2.1 重构决策树

graph TD
    Start[代码审查] --> Smell{发现代码异味?}

    Smell -->|是| Analyze[分析问题类型]
    Smell -->|否| Monitor[持续监控]

    Analyze --> Type{异味类型}

    Type -->|重复代码| Extract[提取方法/组件]
    Type -->|长方法| Split[拆分函数]
    Type -->|大类| Decompose[分解类]
    Type -->|长参数| ParamObject[引入参数对象]
    Type -->|条件复杂| Polymorphism[多态替换]

    Extract --> Test[运行测试]
    Split --> Test
    Decompose --> Test
    ParamObject --> Test
    Polymorphism --> Test

    Test --> Pass{测试通过?}
    Pass -->|是| Review[代码审查]
    Pass -->|否| Rollback[回滚重试]

    Review --> Approved{审查通过?}
    Approved -->|是| Commit[提交合并]
    Approved -->|否| Refine[改进]

    Refine --> Test
    Rollback --> Analyze

    style Smell fill:#FFFFB3
    style Test fill:#B3D9FF
    style Commit fill:#B3FFB3

4.3 性能优化实战

4.3.1 前端性能优化

// 1. 代码分割 (Code Splitting)
// 路由级别分割
const Dashboard = lazy(() => import('./pages/Dashboard'))
const AdminPanel = lazy(() => import('./pages/AdminPanel'))
const Analytics = lazy(() => import('./pages/Analytics'))

function App() {
  return (
    <Suspense fallback={<PageLoader />}>
      <Routes>
        <Route path="/dashboard" element={<Dashboard />} />
        <Route path="/admin" element={<AdminPanel />} />
        <Route path="/analytics" element={<Analytics />} />
      </Routes>
    </Suspense>
  )
}

// 2. 资源预加载
function HomePage() {
  useEffect(() => {
    // 预加载可能访问的页面
    const preloadDashboard = () => import('./pages/Dashboard')

    // 空闲时预加载
    if ('requestIdleCallback' in window) {
      requestIdleCallback(preloadDashboard)
    } else {
      setTimeout(preloadDashboard, 1000)
    }
  }, [])

  return <div>...</div>
}

// 3. 图片优化
import Image from 'next/image'

function ProductCard({ product }) {
  return (
    <Image
      src={product.image}
      alt={product.name}
      width={300}
      height={200}
      loading="lazy"
      placeholder="blur"
      sizes="(max-width: 768px) 100vw, 300px"
    />
  )
}

// 4. 虚拟化长列表
import { useVirtualizer } from '@tanstack/react-virtual'

function VirtualList({ items }) {
  const parentRef = useRef(null)

  const virtualizer = useVirtualizer({
    count: items.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 80,
  })

  return (
    <div ref={parentRef} style={{ height: '600px', overflow: 'auto' }}>
      <div style={{ height: `${virtualizer.getTotalSize()}px`, position: 'relative' }}>
        {virtualizer.getVirtualItems().map(virtualItem => (
          <div
            key={virtualItem.key}
            style={{
              position: 'absolute',
              top: 0,
              left: 0,
              width: '100%',
              height: `${virtualItem.size}px`,
              transform: `translateY(${virtualItem.start}px)`,
            }}
          >
            <ItemCard item={items[virtualItem.index]} />
          </div>
        ))}
      </div>
    </div>
  )
}

4.3.2 后端性能优化

// 1. 数据库连接池
import { Pool } from 'pg'

const pool = new Pool({
  host: process.env.DB_HOST,
  database: process.env.DB_NAME,
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  max: 20,  // 最大连接数
  idleTimeoutMillis: 30000,
  connectionTimeoutMillis: 2000,
})

// 2. Redis缓存层
import Redis from 'ioredis'

const redis = new Redis({
  host: process.env.REDIS_HOST,
  port: 6379,
  maxRetriesPerRequest: 3,
  enableReadyCheck: true,
  lazyConnect: true,
})

// 缓存装饰器
function Cacheable(ttl: number = 300) {
  return function (
    target: any,
    propertyKey: string,
    descriptor: PropertyDescriptor
  ) {
    const originalMethod = descriptor.value

    descriptor.value = async function (...args: any[]) {
      const cacheKey = `${propertyKey}:${JSON.stringify(args)}`

      // 尝试从缓存获取
      const cached = await redis.get(cacheKey)
      if (cached) {
        return JSON.parse(cached)
      }

      // 执行方法
      const result = await originalMethod.apply(this, args)

      // 缓存结果
      await redis.setex(cacheKey, ttl, JSON.stringify(result))

      return result
    }

    return descriptor
  }
}

// 使用
class ProductService {
  @Cacheable(600)  // 10分钟缓存
  async getProduct(id: string) {
    return prisma.product.findUnique({ where: { id } })
  }
}

// 3. 批量操作优化
async function batchUpdatePrices(updates: { id: string; price: number }[]) {
  // 使用事务批量更新
  await prisma.$transaction(
    updates.map(({ id, price }) =>
      prisma.product.update({
        where: { id },
        data: { price },
      })
    )
  )
}

// 4. 并发请求限制
import pLimit from 'p-limit'

const limit = pLimit(5)  // 最多5个并发

async function processItems(items: Item[]) {
  const promises = items.map(item =>
    limit(() => processItem(item))
  )

  return Promise.all(promises)
}

4.4 安全开发实践

4.4.1 输入验证与防护

// 1. SQL注入防护
// ❌ 危险
const query = `SELECT * FROM users WHERE email = '${userInput}'`

// ✅ 安全 - 使用参数化查询
const user = await prisma.user.findUnique({
  where: { email: userInput }
})

// 2. XSS防护
import DOMPurify from 'isomorphic-dompurify'

export function sanitizeHtml(dirty: string) {
  return DOMPurify.sanitize(dirty, {
    ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'a', 'p', 'br', 'ul', 'li'],
    ALLOWED_ATTR: ['href', 'target'],
  })
}

// React中自动转义
function Comment({ text }) {
  return <div>{text}</div>  // 自动转义
}

// 如需渲染HTML
function RichContent({ html }) {
  return <div dangerouslySetInnerHTML={{ __html: sanitizeHtml(html) }} />
}

// 3. CSRF防护
import csrf from 'csurf'

const csrfProtection = csrf({
  cookie: {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    sameSite: 'strict',
  },
})

app.use(csrfProtection)

app.get('/form', (req, res) => {
  res.render('form', { csrfToken: req.csrfToken() })
})

// 4. 速率限制
import rateLimit from 'express-rate-limit'

const apiLimiter = rateLimit({
  windowMs: 15 * 60 * 1000,  // 15分钟
  max: 100,  // 最多100个请求
  message: 'Too many requests from this IP',
  standardHeaders: true,
  legacyHeaders: false,
})

app.use('/api/', apiLimiter)

// 5. 密码安全
import bcrypt from 'bcrypt'

const SALT_ROUNDS = 10

export async function hashPassword(password: string): Promise<string> {
  return bcrypt.hash(password, SALT_ROUNDS)
}

export async function comparePassword(
  password: string,
  hash: string
): Promise<boolean> {
  return bcrypt.compare(password, hash)
}

第五部分：团队协作

5.1 Git 工作流

5.1.1 Git Flow vs GitHub Flow

graph LR
    subgraph GitFlow["Git Flow - 复杂项目"]
        Master[master<br/>生产] --> Hotfix[hotfix/*<br/>紧急修复]
        Master --> Release[release/*<br/>发布准备]
        Release --> Develop[develop<br/>开发主分支]
        Develop --> Feature[feature/*<br/>功能开发]
        Hotfix --> Master
        Release --> Master
    end

    subgraph GitHubFlow["GitHub Flow - 敏捷项目"]
        Main[main<br/>生产] --> FB[feature-branch<br/>功能分支]
        FB --> PR[Pull Request<br/>代码审查]
        PR --> Main
    end

    style GitFlow fill:#FFE6E6
    style GitHubFlow fill:#E6FFE6

5.1.2 提交规范 (Conventional Commits)

# 提交格式
<type>(<scope>): <subject>

<body>

<footer>

# Type 类型
feat:     新功能
fix:      bug修复
docs:     文档更新
style:    代码格式（不影响功能）
refactor: 重构
perf:     性能优化
test:     测试相关
chore:    构建/工具链

# 示例
feat(auth): add JWT authentication

Implement JWT-based authentication system with refresh tokens.
- Add login/register endpoints
- Create auth middleware
- Add session management

Closes #123
BREAKING CHANGE: Old session-based auth removed

# 使用 commitlint
npm install --save-dev @commitlint/cli @commitlint/config-conventional

5.2 代码审查最佳实践

5.2.1 PR Review 清单

## 代码审查清单

### 功能性
- [ ] 代码实现了需求的所有功能
- [ ] 边界情况都被处理
- [ ] 错误处理完善
- [ ] 没有明显的bug

### 代码质量
- [ ] 代码可读性强
- [ ] 命名清晰有意义
- [ ] 函数职责单一
- [ ] 没有重复代码
- [ ] 注释合理（复杂逻辑有说明）

### 测试
- [ ] 有足够的单元测试
- [ ] 测试覆盖关键路径
- [ ] 所有测试通过
- [ ] 测试用例有意义

### 性能
- [ ] 没有明显的性能问题
- [ ] 数据库查询优化
- [ ] 没有N+1查询
- [ ] 适当使用缓存

### 安全
- [ ] 输入验证完善
- [ ] 没有SQL注入风险
- [ ] 没有XSS漏洞
- [ ] 敏感信息不在代码中

### 架构
- [ ] 符合项目架构规范
- [ ] 模块划分合理
- [ ] 依赖关系清晰
- [ ] 没有循环依赖

5.3 技术债务管理

5.3.1 技术债务追踪

// 使用 TODO 标记技术债务
/**
 * TODO[TECH-DEBT]: 重构用户认证逻辑
 *
 * 当前实现混合了业务逻辑和基础设施代码，需要分离：
 * 1. 提取认证service
 * 2. 使用依赖注入
 * 3. 添加集成测试
 *
 * Priority: P1 (高)
 * Estimate: 3 days
 * Issue: #456
 *
 * @deprecated 使用新的 AuthService
 */
function legacyLogin(email: string, password: string) {
  // 旧的实现...
}

// GitHub Issue 模板
/**
Technical Debt: 数据库查询优化

## 问题描述
UserService.getUsers() 存在N+1查询问题

## 影响
- 列表页加载时间过长 (>2s)
- 数据库负载高

## 解决方案
1. 使用 Prisma include 预加载
2. 实现DataLoader批量查询
3. 添加Redis缓存层

## 优先级
P1 - 高优先级

## 预估工作量
2天

## 相关文件
- src/services/user.service.ts
- src/repositories/user.repository.ts
*/

第六部分：架构设计

6.1 SaaS 应用架构

graph TB
    subgraph Frontend["前端层"]
        Web[Web应用<br/>Next.js]
        Mobile[移动应用<br/>React Native]
        Admin[管理后台<br/>React]
    end

    subgraph APIGateway["API网关层"]
        Gateway[API Gateway<br/>Kong/NGINX]
        Auth[认证服务<br/>OAuth2]
        RateLimit[速率限制]
    end

    subgraph Services["微服务层"]
        UserService[用户服务]
        PaymentService[支付服务]
        NotificationService[通知服务]
        AnalyticsService[分析服务]
    end

    subgraph Data["数据层"]
        PostgreSQL[(PostgreSQL<br/>主数据库)]
        Redis[(Redis<br/>缓存)]
        S3[(S3<br/>文件存储)]
        ElasticSearch[(ElasticSearch<br/>搜索)]
    end

    Web --> Gateway
    Mobile --> Gateway
    Admin --> Gateway

    Gateway --> Auth
    Gateway --> RateLimit
    Gateway --> UserService
    Gateway --> PaymentService

    UserService --> PostgreSQL
    UserService --> Redis
    PaymentService --> PostgreSQL
    NotificationService --> Redis
    AnalyticsService --> ElasticSearch

    UserService --> S3

    style Frontend fill:#E6F3FF
    style APIGateway fill:#FFE6E6
    style Services fill:#E6FFE6
    style Data fill:#FFE6F0

6.2 微服务架构

6.2.1 服务拆分原则

服务拆分策略:
  按业务领域:
    - 用户服务: 认证、授权、用户管理
    - 订单服务: 订单创建、支付、物流
    - 商品服务: 商品管理、库存、分类
    - 通知服务: 邮件、短信、推送

  按数据边界:
    - 每个服务独立数据库
    - 避免跨服务join
    - 事件驱动同步数据

  按团队:
    - 每个团队负责1-3个服务
    - 全栈式团队
    - Conway定律

6.3 DevOps 实践

6.3.1 Docker化

# Dockerfile - 多阶段构建
FROM node:20-alpine AS builder

WORKDIR /app

COPY package*.json ./
COPY pnpm-lock.yaml ./

RUN npm install -g pnpm
RUN pnpm install --frozen-lockfile

COPY . .
RUN pnpm build
RUN pnpm prune --prod

# 生产镜像
FROM node:20-alpine

WORKDIR /app

COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./

EXPOSE 3000

CMD ["node", "dist/server.js"]

第七部分：完整实战案例

7.1 构建AI SaaS应用

7.1.1 项目概述

目标：构建一个AI驱动的内容生成SaaS平台

技术栈：

前端：Next.js 15 + TypeScript + Tailwind
后端：Express + Prisma + PostgreSQL
AI：Claude API + Langchain
部署：Vercel + Railway

7.1.2 使用Claude Code开发

# 步骤1: 初始化项目
claude init --template saas-starter

# 步骤2: 对话式开发
claude> 创建AI内容生成SaaS应用

# 基础功能：
# 1. 用户注册登录（NextAuth）
# 2. AI内容生成界面
# 3. 生成历史记录
# 4. 订阅付费系统（Stripe）

# 技术要求：
# - 使用Next.js 15 App Router
# - Prisma + PostgreSQL
# - Claude API集成
# - Tailwind + shadcn/ui

Claude: 我将为你创建完整的SaaS应用...

[Claude开始生成项目结构和代码]

# 步骤3: 迭代开发
claude> 添加AI生成功能的流式响应

claude> 实现Stripe订阅系统

claude> 添加使用量追踪和限制

# 步骤4: 测试
/test

# 步骤5: 部署
/deploy production

7.1.3 完整项目结构

ai-saas-platform/
├── apps/
│   ├── web/                    # Next.js前端
│   │   ├── app/
│   │   │   ├── (auth)/
│   │   │   │   ├── login/
│   │   │   │   └── register/
│   │   │   ├── (dashboard)/
│   │   │   │   ├── dashboard/
│   │   │   │   ├── generate/
│   │   │   │   ├── history/
│   │   │   │   └── settings/
│   │   │   ├── api/
│   │   │   │   ├── auth/
│   │   │   │   ├── generate/
│   │   │   │   └── stripe/
│   │   │   └── layout.tsx
│   │   └── package.json
│   │
│   └── api/                    # Express后端（可选）
│       └── ...
│
├── packages/
│   ├── database/              # Prisma Schema
│   ├── ui/                    # 共享UI组件
│   └── config/                # 共享配置
│
└── CLAUDE.md                  # AI开发配置

🎯 总结与最佳实践

关键要点

AI First思维：先思考架构，让AI实现细节
迭代开发：小步快跑，持续优化
测试驱动：先写测试，保证质量
代码审查：人工把关，AI辅助
持续学习：跟进技术，优化工作流

下一步

🚀 开始你的第一个Claude Code项目
📚 深入学习Prompt工程
🔧 构建自己的开发工具链
🤝 分享经验，参与社区

文档版本: 2.0 Professional Edition
最后更新: 2026年3月
维护者: Claude AI Engineering Team

获取支持:

📖 官方文档: https://code.claude.com/docs
💬 GitHub讨论: https://github.com/anthropics/claude-code/discussions
📧 邮件支持: support@anthropic.com