---
name: coding-style
description: "团队通用代码风格与质量底线规范。适用于所有业务逻辑与新组件开发，保障代码可读性与健壮性。"
globs: ["*"]
alwaysApply: true
updated: 2026-05-22
---

# 团队通用代码风格与质量底线规范

> [!IMPORTANT]
> 优秀的 AI 助手不仅要实现功能，更要写出符合团队工程品味的高质量代码。无论您使用何种语言编程，在编写或重构代码时均需严格遵守以下标准。

## 1. 健壮的错误处理 (Robust Error Handling)

- **禁止静默失败**：绝对不允许生成裸 `try-except` 或裸 `try-catch` 从而吞掉异常。必须确保所有被拦截的异常都得到妥善处理（记录带上下文的日志、触发重试或优雅回退）。
- **保留异常链**：在抛出新异常时，必须使用合适的异常链语法（如 Python 的 `raise NewError(...) from exc` 或 JS/TS 的 `new Error(..., { cause: err })`），保留原始错误栈。
- **详尽日志**：记录异常日志时，必须附带关键的上下文参数，以便于人类工程师在生产环境中排查问题。

---

## 2. 单一职责与逻辑清晰 (Single Responsibility & Low Complexity)

- **函数行数限制**：除必要的配置数组或数据映射外，单个函数/方法的实现代码行数原则上**不超过 50 行**。如果超出，AI 应当主动进行子模块的合理拆分。
- **控制逻辑深度**：函数的嵌套层级（如嵌套的 `if`、`for` 循环）**严禁超过 3 层**。如果嵌套过深，应优先采用“提前返回 (Guard Clauses)”的模式简化逻辑流。
- **无状态优先**：在处理纯数据转换或计算时，优先使用无副作用的纯函数（Pure Functions）。

---

## 3. 标准化文档与注释 (Standard Documentation)

AI 在编写新函数或复杂类时，必须生成规范的文档注释：
- **JavaScript / TypeScript**：严格采用 **JSDoc** 规范，标明参数类型（TS 中可省去但在复杂泛型中需清晰）、参数说明及返回值。
- **Python**：严格采用 **Google Style Docstrings**，清晰描述 Args、Returns 和 Raises。
- **逻辑注释**：对于代码中非常规的黑科技逻辑、性能折衷（Workaround）或复杂算法，必须在关键代码行上方附带简明扼要的解释性注释。

---

## 4. 测试驱动与可测试性 (Testability)

- **可测试设计**：编写业务逻辑时，必须通过依赖注入（Dependency Injection）等解耦设计，使函数易于编写单元测试。
- **同步更新测试**：当修改或新增核心业务逻辑时，AI 应当在回复中主动生成或修改对应的测试用例（如 Jest、Pytest）。

---

## 5. 代码对比示例

### ❌ 错误示例（逻辑臃肿、裸吞异常、缺乏注释）

```typescript
// 缺点：逻辑多层嵌套、直接吞异常、缺乏文档、行数臃肿
function process(u: any, i: any) {
  if (u != null) {
    if (u.isActive) {
      try {
        let price = u.getPrice();
        if (price > 100) {
          for (let item of i) {
            if (item.id === u.id) {
              item.val = item.val * 0.9;
              db.save(item);
            }
          }
        }
      } catch (e) {
        // 严重问题：裸吞异常，导致故障无法感知
      }
    }
  }
}
```

###  正确方向（职责分离、提前返回、标准 JSDoc、健壮错误处理）

```typescript
interface User {
  id: string;
  isActive: boolean;
  getPrice(): number;
}

interface Item {
  id: string;
  val: number;
}

/**
 * 针对符合高消费条件的活跃用户，批量计算并应用其专属折扣
 * 
 * @param {User} user - 目标用户对象
 * @param {Item[]} items - 待结算的商品列表
 * @returns {Promise<void>}
 * @throws {DatabaseError} 当折扣数据入库失败时抛出异常
 */
async function applyBulkDiscountForPremiumUser(user: User, items: Item[]): Promise<void> {
  // 遵循规则 2：使用卫语句提前返回，降低嵌套层级，代码更清晰
  if (!user?.isActive) return;
  
  const originalPrice = user.getPrice();
  const DISCOUNT_THRESHOLD = 100;
  if (originalPrice <= DISCOUNT_THRESHOLD) return;

  // 遵循规则 2：逻辑抽取为单一职责函数
  await discountMatchingItems(user.id, items);
}

/**
 * 更新与用户 ID 匹配的商品价格并同步至数据库
 */
async function discountMatchingItems(userId: string, items: Item[]): Promise<void> {
  const DISCOUNT_RATE = 0.9;

  for (const item of items) {
    if (item.id !== userId) continue;

    try {
      item.val *= DISCOUNT_RATE;
      await db.save(item);
      logger.info(`Successfully applied discount for item ${item.id}`, { userId, newVal: item.val });
    } catch (err) {
      // 遵循规则 1：记录带上下文的日志，保留异常链，拒绝静默失败
      logger.error(`Failed to save discounted item ${item.id} to database`, { userId, error: err });
      throw new DatabaseError(`Unable to save discounted pricing for user ${userId}`, { cause: err });
    }
  }
}
```