[根目录](../CLAUDE.md) > **utils**

---

# utils - 工具函数模块

> 最后更新：2026-01-06 15:26:54

---

## 变更记录 (Changelog)

### 2026-01-06
- 初始化模块文档
- 识别当前包含时间格式化工具函数

---

## 模块职责

**当前职责**：提供通用的工具函数，当前仅包含日期时间格式化功能。

**扩展方向**：
- 封装 API 请求方法（`wx.request`）
- 添加数据验证与格式化工具
- 添加本地存储管理工具
- 添加常用业务逻辑工具函数

---

## 入口与启动

### 模块路径
- **物理路径**：`utils/util.js`
- **导出方式**：CommonJS `module.exports`

### 引入方式
```javascript
const util = require('../../utils/util.js')

// 使用工具函数
const formattedTime = util.formatTime(new Date())
```

---

## 对外接口

### 当前提供的工具函数

#### 1. formatTime(date)
**功能**：将日期对象格式化为 `YYYY/MM/DD HH:mm:ss` 格式

**参数**：
- `date`：Date 对象

**返回值**：
- 格式化的时间字符串，例如：`'2026/01/06 15:26:54'`

**示例**：
```javascript
const now = new Date()
const formatted = util.formatTime(now)
console.log(formatted) // 输出：2026/01/06 15:26:54
```

---

## 关键依赖与配置

### 依赖文件
| 文件 | 用途 |
|------|------|
| `util.js` | 工具函数实现 |

### 外部依赖
- 无外部依赖（纯 JavaScript 实现）

---

## 数据模型

### formatTime 实现细节
```javascript
const formatTime = date => {
  const year = date.getFullYear()
  const month = date.getMonth() + 1
  const day = date.getDate()
  const hour = date.getHours()
  const minute = date.getMinutes()
  const second = date.getSeconds()

  return `${[year, month, day].map(formatNumber).join('/')} ${[hour, minute, second].map(formatNumber).join(':')}`
}

const formatNumber = n => {
  n = n.toString()
  return n[1] ? n : `0${n}`
}
```

---

## 测试与质量

### 测试覆盖
- **手动测试**：在 `pages/logs` 中使用正常
- **单元测试**：暂无

### 边界情况
- 月份补零（1 → 01）
- 时分秒补零（8 → 08）

---

## 常见问题 (FAQ)

### Q: 如何添加新的工具函数？
A: 在 `util.js` 中添加函数并导出：
```javascript
// 添加新函数
const formatPrice = price => {
  return `¥${price.toFixed(2)}`
}

// 在 module.exports 中导出
module.exports = {
  formatTime,
  formatPrice  // 新增
}
```

### Q: 是否需要拆分为多个文件？
A: 当前项目规模小，单文件足够。随着功能增加，建议拆分为：
- `utils/api.js`：API 请求封装
- `utils/storage.js`：本地存储管理
- `utils/validator.js`：数据验证
- `utils/format.js`：格式化工具

---

## 相关文件清单

```
utils/
├── util.js         # 工具函数实现（20 行）
└── CLAUDE.md       # 本文档
```

---

## 下一步建议

### 推荐新增工具函数

#### 1. API 请求封装（`utils/request.js`）
```javascript
const BASE_URL = 'http://localhost:3000/api'

function request(url, data = {}, method = 'GET') {
  return new Promise((resolve, reject) => {
    wx.request({
      url: `${BASE_URL}${url}`,
      data,
      method,
      success: res => resolve(res.data),
      fail: err => reject(err)
    })
  })
}

module.exports = { request }
```

#### 2. 价格格式化（扩展 `util.js`）
```javascript
const formatPrice = (price, unit = '元/吨') => {
  return `${price.toFixed(2)} ${unit}`
}

const formatNumberWithComma = num => {
  return num.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ',')
}
```

#### 3. 本地存储管理（`utils/storage.js`）
```javascript
const STORAGE_KEYS = {
  SEARCH_HISTORY: 'search_history',
  USER_FAVORITES: 'user_favorites'
}

function getStorage(key) {
  return wx.getStorageSync(key) || []
}

function setStorage(key, data) {
  wx.setStorageSync(key, data)
}

module.exports = { STORAGE_KEYS, getStorage, setStorage }
```

---

**模块状态**：可用，待扩展
**优先级**：中（API 封装为高优先级）
**预估工作量**：1-2 小时（封装常用工具函数）