# express-study

**Repository Path**: gao-code/express-study

## Basic Information

- **Project Name**: express-study
- **Description**: express学习代码
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-25
- **Last Updated**: 2025-11-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Express Study API

一个基于 Express.js 和 MongoDB 的 RESTful API 项目，提供用户管理和服装管理功能。

## 📋 目录

- [功能特性](#功能特性)
- [技术栈](#技术栈)
- [项目结构](#项目结构)
- [快速开始](#快速开始)
- [API 文档](#api-文档)
- [环境要求](#环境要求)
- [开发](#开发)

## ✨ 功能特性

- ✅ RESTful API 设计
- ✅ MongoDB 数据库集成
- ✅ Swagger API 文档
- ✅ 错误处理中间件
- ✅ 用户管理（CRUD）
- ✅ 服装管理（CRUD）

## 🛠 技术栈

- **Node.js** - JavaScript 运行时环境
- **Express.js** (v5.1.0) - Web 应用框架
- **MongoDB** - NoSQL 数据库
- **Mongoose** (v9.0.0) - MongoDB 对象建模工具
- **Swagger** - API 文档生成工具
  - swagger-jsdoc
  - swagger-ui-express

## 📁 项目结构

```
express-study/
├── app.js                 # 应用入口文件
├── swagger.js             # Swagger 配置
├── error-middleware.js    # 错误处理中间件
├── package.json           # 项目依赖配置
├── models/                # 数据模型
│   ├── user.js           # 用户模型
│   └── cloth.js          # 服装模型
└── routes/                # 路由文件
    ├── user.js           # 用户路由
    └── cloth.js          # 服装路由
```

## 🚀 快速开始

### 1. 克隆项目

```bash
git clone <repository-url>
cd express-study
```

### 2. 安装依赖

```bash
npm install
```

### 3. 启动 MongoDB

确保 MongoDB 服务正在运行：

```bash
# macOS
brew services start mongodb-community

# Linux
sudo systemctl start mongod

# Windows
# 启动 MongoDB 服务
```

### 4. 配置数据库连接

在 `app.js` 中修改 MongoDB 连接字符串（如果需要）：

```javascript
mongoose.connect('mongodb://localhost:27017/express-study')
```

### 5. 启动应用

```bash
# 使用 nodemon（推荐，支持热重载）
nodemon app.js

# 或使用 node
node app.js
```

应用将在 `http://localhost:3000` 启动。

## 📚 API 文档

启动应用后，访问 Swagger UI 查看完整的 API 文档：

```
http://localhost:3000/api-docs
```

### API 端点

#### 用户管理 (`/api/users`)

- `POST /api/users` - 创建用户
- `GET /api/users` - 获取用户列表
- `GET /api/users/:id` - 获取单个用户
- `PUT /api/users/:id` - 更新用户
- `DELETE /api/users/:id` - 删除用户

#### 服装管理 (`/api/cloths`)

- `POST /api/cloths` - 新增服装
- `GET /api/cloths` - 查询所有服装（支持 `unique_id` 查询参数）
- `PUT /api/cloths/:unique_id` - 更新服装
- `DELETE /api/cloths/:unique_id` - 删除服装

### 请求示例

#### 创建用户

```bash
curl -X POST http://localhost:3000/api/users \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john_doe",
    "email": "john@example.com",
    "phone": 13800138000
  }'
```

#### 创建服装

```bash
curl -X POST http://localhost:3000/api/cloths \
  -H "Content-Type: application/json" \
  -d '{
    "unique_id": "cloth_001",
    "image_url": "https://example.com/image.jpg",
    "sales_count": 100,
    "gems_price": 50
  }'
```

## 🔧 环境要求

- Node.js >= 14.0.0
- MongoDB >= 4.0.0
- npm >= 6.0.0

## 💻 开发

### 数据模型

#### User（用户）

```javascript
{
  username: String (required, unique),
  email: String (required),
  phone: Number,
  createdAt: Date,
  updatedAt: Date
}
```

#### Cloth（服装）

```javascript
{
  unique_id: String (required, unique),
  image_url: String (required),
  sales_count: Number,
  gems_price: Number,
  created_at: Date
}
```

### 错误处理

项目使用自定义错误类 `AppError` 进行错误处理：

- 4xx 状态码 → `status: 'fail'`（客户端错误）
- 5xx 状态码 → `status: 'error'`（服务器错误）

### 开发建议

1. 使用 `nodemon` 进行开发，支持代码热重载
2. 查看 Swagger 文档了解 API 详细说明
3. 确保 MongoDB 服务正常运行
4. 使用 Postman 或 curl 测试 API 端点

## 📝 许可证

ISC

## 👤 作者

Express Study Project

---

如有问题或建议，欢迎提交 Issue 或 Pull Request。