# clwy-api

**Repository Path**: CSK89/clwy-api

## Basic Information

- **Project Name**: clwy-api
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-16
- **Last Updated**: 2026-08-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# clwy-api

基于 Express + MySQL 的 Node.js API 项目。

## 技术栈

- Node.js
- Express
- MySQL 8.3.0（Docker 运行）
- mysql2

## 项目结构

```
clwy-api/
├── bin/                # 启动脚本
├── config/
│   └── db.js           # 数据库连接配置
├── public/             # 静态资源
├── routes/
│   ├── index.js        # 首页路由
│   └── users.js        # 用户 CRUD 路由
├── sql/
│   └── init.sql        # 数据库初始化脚本
├── app.js              # Express 应用入口
├── docker-compose.yml  # Docker 配置
├── package.json
├── .env.example        # 环境变量示例
└── README.md
```

## 环境准备

### 1. 启动 MySQL

确保 Docker Desktop 已安装并运行，然后执行：

```bash
docker compose up -d
```

> 如果本地 3306 端口被占用，docker-compose.yml 中已将映射端口改为 `3307:3306`。

### 2. 初始化数据库

进入 MySQL 容器：

```bash
mysql -h 127.0.0.1 -P 3307 -u root -p890618
```

执行 [sql/init.sql](sql/init.sql) 中的 SQL：

```sql
CREATE DATABASE IF NOT EXISTS clwy_db
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_general_ci;

USE clwy_db;

CREATE TABLE IF NOT EXISTS users (
  id INT AUTO_INCREMENT PRIMARY KEY,
  name VARCHAR(100) NOT NULL,
  email VARCHAR(100),
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```

### 3. 安装依赖

```bash
npm install
```

### 4. 配置环境变量

复制示例文件：

```bash
cp .env.example .env
```

根据你的实际情况修改 `.env` 文件。

## 运行项目

```bash
npm start
```

服务默认运行在 http://127.0.0.1:3000

## 测试数据库连接

```bash
node test-db.js
```

正常应输出：

```text
✅ 数据库连接成功: 2026-08-16 xx:xx:xx
```

## API 接口

### 用户相关

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/` | 首页 |
| GET | `/users` | 获取所有用户 |
| GET | `/users/:id` | 获取单个用户 |
| POST | `/users` | 创建用户 |
| PUT | `/users/:id` | 更新用户 |
| DELETE | `/users/:id` | 删除用户 |

### 示例请求

#### 获取用户列表

```bash
curl http://127.0.0.1:3000/users
```

#### 创建用户

```bash
curl -X POST http://127.0.0.1:3000/users \
  -H "Content-Type: application/json" \
  -d '{"name":"张三","email":"zhangsan@example.com"}'
```

#### 更新用户

```bash
curl -X PUT http://127.0.0.1:3000/users/1 \
  -H "Content-Type: application/json" \
  -d '{"name":"李四","email":"lisi@example.com"}'
```

#### 删除用户

```bash
curl -X DELETE http://127.0.0.1:3000/users/1
```

## 数据库连接配置

数据库配置位于 [config/db.js](config/db.js)，默认参数：

| 参数 | 默认值 | 说明 |
|------|--------|------|
| host | 127.0.0.1 | MySQL 地址 |
| port | 3307 | 映射到宿主机的端口 |
| user | root | MySQL 用户名 |
| password | 890618 | MySQL 密码 |
| database | clwy_db | 数据库名 |

这些参数可以通过环境变量覆盖，环境变量名：`DB_HOST`、`DB_PORT`、`DB_USER`、`DB_PASSWORD`、`DB_NAME`。

## 常见问题

### 1. `docker` 命令找不到

确保 Docker Desktop 已安装，并且 PowerShell 的 PATH 包含：

```text
C:\Program Files\Docker\Docker\resources\bin
```

### 2. 拉取 MySQL 镜像失败

国内网络可能需要配置 Docker 镜像加速器。在 Docker Desktop → Settings → Docker Engine 中添加：

```json
{
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://docker.1panel.live",
    "https://hub.rat.dev"
  ]
}
```

### 3. 3306 端口被占用

已将 docker-compose.yml 中的端口映射改为 `3307:3306`。如果仍冲突，可再改为其他端口，例如 `3308:3306`。

### 4. 连接数据库失败

- 检查 MySQL 容器是否运行：`docker ps`
- 检查数据库是否已创建
- 检查 [config/db.js](config/db.js) 中的端口和密码是否正确

## 开发建议

- 生产环境请使用环境变量管理敏感信息，不要硬编码密码。
- 数据库操作使用连接池（已配置）。
- 建议为每个业务模块创建独立的路由文件。