# 代码encapsulation

## 规则（Rules）

# 代码封装规范

## 适用对象和范围

本规范适用于所有通用Node.js代码封装场景，包括函数封装、类封装、模块封装和NPM包封装。

---

## 1. 命名规范

**规则**：函数名使用小驼峰（camelCase），变量/参数使用小写蛇形（snake_case），类名使用大驼峰（PascalCase），常量使用全大写蛇形（SCREAMING_SNAKE_CASE），文件名使用小写蛇形。

| 类型 | 规范 | 示例 |
|:----|:-----|:-----|
| 函数名 | camelCase | `formatAmount`、`getUserList` |
| 变量/参数 | snake_case | `user_list`、`max_length` |
| 类名 | PascalCase | `CacheManager`、`HttpClient` |
| 常量 | SCREAMING_SNAKE_CASE | `MAX_RETRY_COUNT` |
| 文件名 | snake_case | `cache_manager.js` |

**违反后果**：命名不一致导致代码可读性差。

---

## 2. 注释规范

**规则**：函数和类必须使用JSDoc格式注释。

```javascript
/**
 * 格式化金额
 * @param {number} amount - 金额
 * @param {string} currency - 货币符号
 * @return {string} 格式化后的金额字符串
 */
```

**违反后果**：缺少JSDoc注释导致IDE无法提供类型提示。

---

## 3. 导出规范

**规则**：必须使用 `module.exports` 或 `exports.xxx` 导出模块。

**违反后果**：导出方式不规范导致模块无法被正确引用。

---

## 4. 框架无关规范

**规则**：通用模块禁止引入框架特定的API（如 `$.xxx`、`$.utils`）。

**违反后果**：引入框架API导致模块失去通用性，只能在特定框架下使用。

## 方法（Methods）

# 代码封装方法

## 前置条件

- [ ] 已明确需要封装的功能逻辑
- [ ] 已确定封装形式（函数/类/模块/NPM包）

---

## 流程概览

```
分析功能需求 → 选择封装形式 → 编写封装代码 → 导出模块 → 验证可用性
```

---

## 详细步骤

### 步骤1：分析功能需求

明确需要封装的功能逻辑和输入输出。

### 步骤2：选择封装形式

根据复杂度选择：
- 简单工具函数 → 函数封装
- 有状态对象 → 类封装
- 相关功能集合 → 模块封装
- 跨项目复用 → NPM包封装

### 步骤3：编写封装代码

按照所选封装形式编写代码，包含JSDoc注释。

### 步骤4：导出模块

使用 `module.exports` 导出。

### 步骤5：验证可用性

确保模块可被正确引用和调用。

---

## 产出物说明

| 封装形式 | 产出物 |
|---------|--------|
| 函数封装 | 包含函数的 `.js` 文件 |
| 类封装 | 包含类的 `.js` 文件 |
| 模块封装 | 包含多个导出项的 `.js` 文件 |
| NPM包封装 | 包含 `package.json` 的完整包目录 |

## 技巧（Tips）

# 代码封装技巧

## 1. 单一职责原则

**适用场景**：决定是否将功能拆分为独立模块时。

**具体做法**：每个模块只做一件事，如果模块功能超过一个，考虑拆分。

**注意事项**：模块粒度过细会导致文件过多，过粗则复用性差。

---

## 2. 使用默认参数简化调用

**适用场景**：函数参数较多且大部分有默认值时。

**示例**：
```javascript
function createUser({ name, email, role = 'user', status = 'active' }) {
  // 使用解构默认值
}
```

**注意事项**：使用对象参数代替多个位置参数，提高可读性。

---

## 3. 常见问题速查

| 问题 | 原因 | 解决方案 |
|------|------|---------|
| 模块导出后为undefined | 导出方式错误 | 检查 `module.exports` |
| 循环依赖 | 模块互相引用 | 重构模块结构，引入中间层 |
| 全局变量污染 | 未使用模块作用域 | 使用 `const/let` 代替 `var` |