# 通用编程规范 - CODING-STANDARDS-COMMON

**版本**: 2.0.0
**适用范围**: 所有编程任务（后端、前端、系统、数据库等）
**最后更新**: 2025-12-25

---

## 🚨 核心铁律（违反即失败）

### 铁律1: SPEC 是唯一真源（SSOT）

```
┌─────────────────────────────────────────────────────────────────────────┐
│  SPEC 权威性层级（绝对不可违反）                                          │
│                                                                         │
│  SPEC > 任务描述 > AI理解 > 用户口头要求                                 │
│                                                                         │
│  ❌ 禁止：不读 SPEC 就开始编码                                           │
│  ❌ 禁止：认为任务描述比 SPEC 更准确                                      │
│  ❌ 禁止："我觉得用 X 比 Y 更好"而偏离 SPEC                              │
│  ❌ 禁止："SPEC 太复杂，我简化一下"                                      │
│  ❌ 禁止："SPEC 没说，但我觉得应该加"                                    │
│  ❌ 禁止：只实现部分 SPEC 要求                                           │
│  ❌ 禁止：使用 SPEC 中没有规定的技术栈                                   │
│                                                                         │
│  ✅ 必须：编码前完整阅读相关 SPEC 文档                                   │
│  ✅ 必须：理解每个 SPEC ID 的具体要求和约束                               │
│  ✅ 必须：代码实现与 SPEC 100% 一致                                      │
│  ✅ 必须：发现 SPEC 问题及时报告而不是自行决定                            │
│  ✅ 必须：代码与 SPEC 冲突时，改代码不改 SPEC                             │
└─────────────────────────────────────────────────────────────────────────┘
```

### 铁律2: 智能复用与销毁重建

```
┌─────────────────────────────────────────────────────────────────────────┐
│  第一阶段：SPEC 指导的深度分析（复用决策）                                │
│  ─────────────────────────────────────────────────────────────────────  │
│  1. 全面扫描现有模块：                                                   │
│     - 通用模块：工具类、算法、数据结构、通用组件                          │
│     - 基础设施模块：配置管理、日志、错误处理、通信协议                    │
│     - 领域模块：业务逻辑、数据处理、计算模块                              │
│                                                                         │
│  2. 基于 SPEC 精确评估匹配度：                                           │
│     - 完全匹配：现有模块完全满足 SPEC 需求                                │
│     - 部分匹配：现有模块部分满足，需要扩展或修改                          │
│     - 不匹配：现有模块无法满足需求或违反 SPEC 约束                        │
│                                                                         │
│  3. 复用决策：                                                           │
│     ✅ 完全匹配 → 直接复用，无需重新开发                                  │
│     ❌ 部分匹配/不匹配 → 执行销毁重建                                     │
│                                                                         │
│  ⚠️ 关键：复用基于 SPEC 功能完整性，不是代码相似性                        │
│  ⚠️ 关键：部分匹配等于不匹配，必须销毁重建                                │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────┐
│  第二阶段：SPEC 驱动的彻底重写（销毁重建）                                │
│  ─────────────────────────────────────────────────────────────────────  │
│  定义：                                                                  │
│  - 不是修改：不是在现有代码基础上修改或扩展                               │
│  - 不是增量：不是逐步添加功能或修复                                       │
│  - 不是重构：不是调整现有代码结构                                         │
│  - 而是彻底重写：删除所有相关代码，重新设计和实现                         │
│                                                                         │
│  执行：                                                                  │
│  1. 删除所有违反 SPEC 的旧代码                                           │
│  2. 从零设计完全符合 SPEC 的新实现                                       │
│  3. 每个 SPEC ID 必须有明确的、完全符合 SPEC 的实现                       │
└─────────────────────────────────────────────────────────────────────────┘
```

### 铁律3: 禁止渐进式开发

```
┌─────────────────────────────────────────────────────────────────────────┐
│  绝对禁止的渐进式开发行为                                                 │
│                                                                         │
│  ❌ "保留旧实现，添加新功能"                                             │
│  ❌ "兼容性代码，支持旧接口"                                             │
│  ❌ "迁移代码，逐步转换"                                                 │
│  ❌ "扩展现有类，添加新方法"                                             │
│  ❌ "修改现有函数，增加参数"                                             │
│  ❌ "为了兼容，保留旧逻辑"                                               │
│  ❌ "先做粗糙版，之后再补"                                               │
│  ❌ "后续迭代补充"                                                       │
│                                                                         │
│  为什么必须销毁重建：                                                     │
│  1. 避免技术债务：增量修改会积累历史包袱                                  │
│  2. 保证代码质量：重写能确保代码符合最新标准                              │
│  3. 简化思考过程：不需要考虑兼容性，专注目标实现                          │
│  4. 提高开发效率：比复杂的增量修改更快更可靠                              │
└─────────────────────────────────────────────────────────────────────────┘
```

### 铁律4: Context7 调研先行

```
┌─────────────────────────────────────────────────────────────────────────┐
│  新功能开发前必须调研成熟库                                               │
│                                                                         │
│  ✅ 必须使用场景：                                                       │
│     - 新功能开发前技术选型                                               │
│     - 引入新库或使用库 API                                               │
│     - 代码生成前查阅最佳实践                                             │
│     - 对比多个库的选择                                                   │
│                                                                         │
│  ❌ 禁止：                                                               │
│     - 不调研就自己实现常见功能                                           │
│     - 使用过时的库版本或 API                                             │
│     - 凭记忆编写库的使用代码                                             │
│     - 重复造轮子                                                         │
└─────────────────────────────────────────────────────────────────────────┘
```

---

## 🎯 核心设计原则

### SOLID 原则

**单一职责原则（SRP）**：
- ✅ 一个模块/类/函数只负责一个功能
- ✅ 修改的理由只有一个
- ❌ 禁止"上帝类"或"上帝函数"

**开放/封闭原则（OCP）**：
- ✅ 对扩展开放，对修改封闭
- ✅ 使用接口、抽象类、多态实现扩展

**里氏替换原则（LSP）**：
- ✅ 子类可以替换父类使用
- ✅ 子类不改变父类的行为契约

**接口隔离原则（ISP）**：
- ✅ 使用多个专用接口而非单一通用接口
- ❌ 避免"胖接口"

**依赖反转原则（DIP）**：
- ✅ 依赖抽象而非具体实现
- ✅ 使用依赖注入（Dependency Injection）

### 其他核心原则

**DRY（Don't Repeat Yourself）**：
- ✅ 提取可复用代码到函数/类/模块
- ❌ 禁止复制粘贴代码

**KISS（Keep It Simple, Stupid）**：
- ✅ 优先选择简单直接的方案
- ✅ 避免过度设计和不必要的复杂性

---

## 📝 命名规范

### 变量和函数
- **camelCase**: `userName`, `getUserById()`, `isValid`
- 使用有意义的名称（避免 `a`, `tmp`, `data`）
- 布尔值使用 `is`/`has`/`should` 前缀

### 类和组件
- **PascalCase**: `UserService`, `DatabaseConnection`

### 常量
- **UPPER_SNAKE_CASE**: `MAX_RETRY_COUNT`, `API_BASE_URL`

### 文件名
- **kebab-case**: `user-service.ts`, `database-config.js`

---

## 🏗️ 代码结构规范

| 指标 | 限制 | 处理方式 |
|-----|------|---------|
| 文件大小 | ≤300 行 | 拆分为多个模块 |
| 函数大小 | ≤50 行 | 拆分为多个小函数 |
| 嵌套深度 | ≤3 层 | 提前返回/提取函数 |
| 圈复杂度 | ≤10 | 策略模式/查找表 |
| 参数数量 | ≤5 个 | 使用对象传参 |

---

## 🔒 代码质量要求（零容忍）

### ❌ 严格禁止

**占位符和未完成代码**：
- ❌ `TODO` / `FIXME` 注释
- ❌ `stub` 函数或空实现
- ❌ 注释掉的代码
- ❌ `console.log` 调试语句（生产代码）

**不完整实现**：
- ❌ 缺少错误处理的代码
- ❌ 缺少输入验证的公共接口
- ❌ 未释放的资源

### ✅ 强制要求

**错误处理**：
- ✅ 所有可能失败的操作必须有错误处理
- ✅ 错误消息清晰、可操作
- ✅ 记录错误日志（包含上下文信息）

**输入验证**：
- ✅ 验证所有外部输入
- ✅ 类型检查和边界检查
- ✅ 拒绝无效输入并返回明确错误

**资源管理**：
- ✅ 及时关闭数据库连接、文件句柄、网络连接
- ✅ 使用 RAII、defer、with/using 自动管理资源

**类型安全**：
- ✅ 避免 `any` 或不安全类型转换
- ✅ 使用泛型提高类型安全

---

## 🛡️ 安全要求

### 输入验证
- ✅ 白名单验证优于黑名单
- ✅ 长度、格式、类型检查

### SQL 注入防护
- ✅ 使用参数化查询或 ORM
- ❌ 禁止字符串拼接 SQL

### XSS 防护
- ✅ 输出编码（HTML、JavaScript、URL）
- ✅ 设置 CSP（Content Security Policy）

### 认证和授权
- ✅ 检查权限后再执行操作
- ✅ 最小权限原则

### 敏感数据
- ✅ 加密存储密码、密钥、令牌
- ❌ 不在日志中记录敏感信息

---

## ⚡ 性能要求

### 算法复杂度
- ✅ 避免 O(n²) 及以上复杂度（在大数据集上）
- ✅ 使用缓存减少重复计算

### 数据库优化
- ✅ 使用索引加速查询
- ✅ 避免 N+1 查询问题
- ✅ 分页查询大数据集

### 异步和并发
- ✅ I/O 操作使用异步处理
- ✅ 避免阻塞主线程
- ✅ 注意并发安全

---

## 🧪 测试要求

### 单元测试
- ✅ 测试单个函数/方法
- ✅ 快速执行（< 100ms）
- ✅ 独立性（不依赖外部资源）
- ✅ 覆盖正常路径和异常路径

### 测试原则
- ✅ AAA 模式（Arrange-Act-Assert）
- ✅ 一个测试只验证一个行为
- ✅ 清晰的测试名称

### 边界测试
- ✅ 最小值、最大值
- ✅ 空值、null、undefined
- ✅ 无效输入

---

## 🔍 代码审查要求

### 审查检查清单

**SPEC 一致性**：
- [ ] 代码实现与 SPEC 100% 一致
- [ ] 每个 SPEC ID 都有对应实现
- [ ] 无 SPEC 之外的自作主张

**质量检查**：
- [ ] 无 TODO/FIXME/stub
- [ ] 完整错误处理
- [ ] 输入验证完整
- [ ] 资源正确释放

**架构检查**：
- [ ] 遵循 SOLID 原则
- [ ] 无重复代码
- [ ] 模块边界清晰

---

## ✅ 开发检查清单

### 开发前
- [ ] 完整阅读相关 SPEC 文档
- [ ] 确认每个 SPEC ID 的具体要求
- [ ] 扫描现有代码，评估复用可能
- [ ] Context7 调研技术方案

### 开发中
- [ ] 遵循命名规范
- [ ] 保持代码简洁（KISS）
- [ ] 避免重复代码（DRY）
- [ ] 实现 SPEC 中所有要求（一次性到位）
- [ ] 完整错误处理
- [ ] 输入验证和安全检查

### 开发后
- [ ] 逐条验证 SPEC 实现完整性
- [ ] 编写单元测试
- [ ] 代码审查
- [ ] 无 TODO/FIXME/占位符

---

**核心理念**：
- SPEC 是唯一真源，代码必须 100% 符合 SPEC
- 部分匹配等于不匹配，必须销毁重建
- 禁止任何形式的渐进式开发
- 质量优于速度，正确优于快速
