# nodejs-file-crud-api

**Repository Path**: sunyu-front/nodejs-file-crud-api

## Basic Information

- **Project Name**: nodejs-file-crud-api
- **Description**: 基于Node.js + Express的轻量级通用CRUD API服务，使用本地JSON文件作为数据存储，无需数据库即可快速搭建RESTful API。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-25
- **Last Updated**: 2026-01-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 文件存储CRUD API服务

基于Node.js + Express的轻量级通用CRUD API服务，使用本地JSON文件作为数据存储，无需数据库即可快速搭建RESTful API。

## 📋 项目简介

这是一个专为前端开发者设计的后端API解决方案，让你无需学习数据库知识即可拥有完整的增删改查接口。所有数据均以JSON文件形式存储在本地，简单易用，开箱即用。

### 核心特性
- 🚀 **零数据库依赖** - 使用本地JSON文件存储数据
- 🔄 **完整CRUD操作** - 支持创建、读取、更新、删除全功能
- 📁 **多实体支持** - 可同时管理用户、产品、文章等多种数据类型
- 🎯 **RESTful API设计** - 符合标准的API接口规范
- 🔒 **统一响应格式** - 标准化的成功/错误响应处理
- 📊 **自动分页** - 内置分页功能，支持条件查询
- ⚡ **快速部署** - 几分钟内即可搭建完整后端服务

## 🛠 技术栈

- **运行时**: Node.js
- **框架**: Express.js
- **存储**: 本地JSON文件
- **中间件**: CORS
- **工具**: 自定义WinFileUtil文件操作工具类

## 📁 项目结构

```
project-root/
├── config/
│   └── fileDB.config.js          # 数据存储配置
│   └── routes.js                 # 路由配置文件（新增）
├── controllers/
│   └── entityController.js       # 通用CRUD控制器
├── middlewares/
│   └── responseMiddleware.js     # 统一响应格式中间件
├── routes/
│   └── entityRoutes.js           # 通用路由定义
├── filedb/                       # 数据存储目录（自动生成）
│   ├── users.json               # 用户数据文件
│   └── products.json            # 产品数据文件（可选）
├── app.js                       # 应用入口文件
├── package.json                 # 项目配置
└── README.md                    # 项目说明
```

## ⚡ 快速开始

### 环境要求

- Node.js 14.0 或更高版本
- npm 或 yarn 包管理器

### 安装步骤

1. **克隆或创建项目**
```bash
# 如果你有项目代码
git clone <your-repo-url>
cd your-project-name

# 或者新建项目目录
mkdir my-crud-api
cd my-crud-api
```

2. **安装依赖**
```bash
npm install express cors
```

3. **创建项目文件**
按照之前的指导创建所有必要的文件：
- `package.json`
- `config/fileDB.config.js`
- `middlewares/responseMiddleware.js`
- `controllers/entityController.js`
- `routes/entityRoutes.js`
- `app.js`

4. **启动服务**
```bash
npm start
```

服务启动后，控制台将显示：
```
==============================================
🚀 文件存储CRUD API服务已启动!
📍 本地访问: http://localhost:3000
📍 健康检查: http://localhost:3000/health
📍 用户管理API: http://localhost:3000/api/users
==============================================
```

## 📚 API接口文档

### 基础信息
- **基础URL**: `http://localhost:3000/api`
- **数据格式**: JSON
- **字符编码**: UTF-8

### 用户管理接口 (示例)

#### 1. 获取用户列表
**GET** `/api/users`

**参数说明**:
| 参数名 | 类型 | 必填 | 说明 | 默认值 |
|--------|------|------|------|--------|
| page | number | 否 | 页码 | 1 |
| size | number | 否 | 每页条数 | 10 |
| emp_name | string | 否 | 姓名筛选 | - |
| email | string | 否 | 邮箱筛选 | - |

**示例请求**:
```bash
curl "http://localhost:3000/api/users?page=1&size=5&emp_name=张三"
```

**成功响应**:
```json
{
  "code": 200,
  "msg": "获取user列表成功",
  "data": {
    "pageNum": 1,
    "pageSize": 5,
    "total": 150,
    "totalPages": 30,
    "content": [
      {
        "id": "1643012345678abc123",
        "emp_name": "张三",
        "email": "zhangsan@example.com",
        "createTime": "2024-01-24T10:30:00.000Z",
        "updateTime": "2024-01-24T10:30:00.000Z"s
      }
    ]
  },
  "timestamp": 1643012345678
}
```

#### 2. 创建新用户
**POST** `/api/users`

**请求头**:
```
Content-Type: application/json
```

**请求体**:
```json
{
  "emp_name": "李四",
  "email": "lisi@example.com",
  "age": 28,
  "department": "技术部"
}
```

**成功响应**:
```json
{
  "code": 201,
  "msg": "创建user成功",
  "data": {
    "id": "1643012345678def456",
    "emp_name": "李四",
    "email": "lisi@example.com",
    "age": 28,
    "department": "技术部",
    "createTime": "2024-01-24T10:35:00.000Z",
    "updateTime": "2024-01-24T10:35:00.000Z"
  },
  "timestamp": 1643012345678
}
```

#### 3. 获取用户详情
**GET** `/api/users/{id}`

**示例请求**:
```bash
curl "http://localhost:3000/api/users/1643012345678abc123"
```

#### 4. 更新用户信息
**PUT** `/api/users/{id}`

**请求体**:
```json
{
  "emp_name": "李四修改后",
  "email": "lisi_updated@example.com",
  "age": 29
}
```

#### 5. 删除用户
**DELETE** `/api/users/{id}`

**成功响应**:
```json
{
  "code": 200,
  "msg": "删除user成功",
  "data": null,
  "timestamp": 1643012345678
}
```

### 其他通用接口

#### 健康检查
**GET** `/health`

#### 服务首页
**GET** `/`

## 🔧 配置说明

### 数据存储配置
修改 `config/fileDB.config.js` 调整数据存储位置：

```javascript
const path = require('path');

const fileDBConfig = {
  // 数据文件存储根目录
  DATA_BASE_DIR: path.join(__dirname, '..', 'filedb'),
  
  // 其他配置项...
};

module.exports = fileDBConfig;
```

### 服务器配置
在 `app.js` 中修改端口号：

```javascript
const PORT = process.env.PORT || 3000; // 修改默认端口
```

## 💡 扩展新数据实体

要添加新的数据管理功能（如产品管理），只需在 `app.js` 中添加一行路由：

```javascript
// 添加产品管理路由
app.use('/api/products', require('./routes/entityRoutes')('product'));
```

重启服务后，即可使用以下接口：
- `GET /api/products` - 获取产品列表
- `POST /api/products` - 创建产品
- `GET /api/products/{id}` - 获取产品详情
- `PUT /api/products/{id}` - 更新产品
- `DELETE /api/products/{id}` - 删除产品

数据将自动存储在 `filedb/products.json` 文件中。

## 🐛 常见问题

### Q1: 服务启动失败，端口被占用怎么办？
**A**: 修改 `app.js` 中的端口号，或终止占用端口的进程。

### Q2: 数据文件存储在哪里？
**A**: 默认在项目根目录的 `filedb` 文件夹下，每个实体对应一个JSON文件。

### Q3: 如何备份数据？
**A**: 直接备份 `filedb` 目录下的所有JSON文件即可。

### Q4: 支持文件上传吗？
**A**: 当前版本专注于JSON数据CRUD，如需文件上传功能可参考Multer等中间件扩展。

### Q5: 如何部署到生产环境？
**A**: 建议使用PM2等进程管理器：
```bash
npm install -g pm2
pm2 start app.js --name my-crud-api
```

## 🔒 数据安全建议

1. **敏感数据加密**: 对密码等敏感字段进行加密存储
2. **API权限控制**: 添加API密钥或JWT认证机制
3. **输入验证**: 增强请求数据的验证和清理
4. **定期备份**: 定期备份filedb目录下的数据文件

## 📈 性能优化

1. **数据量较大时**: 确保使用分页查询，避免一次性加载大量数据
2. **频繁读取**: 可添加内存缓存机制减少文件IO操作
3. **文件监控**: 使用 `fs.watch` 监控数据文件变化，实现实时更新

## 🚀 开发建议

### 前端集成示例
使用axios进行封装(src/utils/request.js)：

```javascript
import axios from 'axios'

// 创建axios实例
const service = axios.create({
  // axios中请求配置有baseURL选项，表示请求URL公共部分
  baseURL: 'http://localhost:3000',
  // 超时
  timeout: 10000
})

// 添加请求拦截器
service.interceptors.request.use(function (config) {
  // 在发送请求之前做些什么
  return config
}, function (error) {
  // 对请求错误做些什么
  return Promise.reject(error)
})

// 添加响应拦截器
service.interceptors.response.use(function (response) {
  // 2xx 范围内的状态码都会触发该函数。
  // 对响应数据做点什么
  return response.data
}, function (error) {
  // 超出 2xx 范围的状态码都会触发该函数。
  // 对响应错误做点什么
  return Promise.reject(error)
})

export default service

```

封装接口api   user.js

```javascript
import request from '@/utils/request'

/**
 * 获取用户列表
 * @param {Object} params - 查询参数
 * @param {number} [params.page=1] - 页码
 * @param {number} [params.size=10] - 每页条数
 * @returns {Promise} 请求Promise
 */
export function getUserList (params = {}) {
  return request({
    url: '/api/users',
    method: 'get',
    params: {
      page: 1,
      size: 10,
      ...params
    }
  })
}

/**
 * 创建新用户
 * @param {Object} userData - 用户数据
 * @returns {Promise} 请求Promise
 */
export function addUser (userData) {
  return request({
    url: '/api/users',
    method: 'post',
    headers: {
      'Content-Type': 'application/json'
    },
    data: userData
  })
}

/**
 * 获取用户详情
 * @param {string} id - 用户ID
 * @returns {Promise} 请求Promise
 */
export function getUserDetail (id) {
  return request({
    url: `/api/users/${id}`,
    method: 'get'
  })
}

/**
 * 更新用户信息
 * @param {string} id - 用户ID
 * @param {Object} updateData - 更新数据
 * @returns {Promise} 请求Promise
 */
export function updateUser (id, updateData) {
  return request({
    url: `/api/users/${id}`,
    method: 'put',
    headers: {
      'Content-Type': 'application/json'
    },
    data: updateData
  })
}

/**
 * 删除用户
 * @param {string} id - 用户ID
 * @returns {Promise} 请求Promise
 */
export function deleteUser (id) {
  return request({
    url: `/api/users/${id}`,
    method: 'delete'
  })
}

```