# Node.js + Express: 构建RESTful API的工程实践
## 一、环境配置与项目初始化
### 1.1 Node.js开发环境搭建
我们推荐使用Node.js 18 LTS版本，该版本提供长期支持并包含ES2022特性。通过以下命令验证环境：
```bash
node -v # 输出应为v18.x.x
npm -v # 输出应为9.x.x
```
使用Express-generator快速搭建项目骨架：
```bash
npx express-generator --no-view api-server
cd api-server && npm install
```
### 1.2 依赖管理策略
核心依赖清单应包含：
```json
"dependencies": {
"express": "^4.18.2",
"body-parser": "^1.20.2",
"mongoose": "^7.4.3",
"joi": "^17.9.2",
"winston": "^3.10.0"
}
```
通过分层架构组织项目目录：
```
├── config/ # 环境配置
├── controllers/ # 业务逻辑
├── models/ # 数据模型
├── routes/ # 路由定义
├── middleware/ # 自定义中间件
└── app.js # 入口文件
```
## 二、RESTful路由设计与实现
### 2.1 符合REST规范的端点设计
在routes/users.js中定义典型CRUD路由：
```javascript
const router = require('express').Router();
// 获取用户列表
router.get('/', async (req, res) => {
try {
const users = await User.find().limit(100);
res.json(users);
} catch (error) {
res.status(500).json({ message: error.message });
}
});
// 创建新用户
router.post('/', validateUser, async (req, res) => {
const newUser = new User(req.body);
const savedUser = await newUser.save();
res.status(201).location(`/users/${savedUser.id}`).json(savedUser);
});
```
### 2.2 版本控制最佳实践
在入口文件配置多版本路由：
```javascript
app.use('/api/v1', require('./routes/v1'));
app.use('/api/v2', require('./routes/v2'));
```
建议遵循语义化版本控制（Semantic Versioning），当进行不兼容的API修改时升级主版本号。
## 三、中间件深度应用
### 3.1 内置中间件组合
合理配置中间件顺序：
```javascript
app.use(express.json()); // 解析JSON请求体
app.use(express.urlencoded({ extended: true })); // 处理表单数据
app.use(compression()); // 启用响应压缩
app.use(helmet()); // 安全防护头设置
```
### 3.2 自定义中间件开发
创建请求日志中间件：
```javascript
function requestLogger(req, res, next) {
const start = Date.now();
res.on('finish', () => {
const duration = Date.now() - start;
logger.info(`${req.method} ${req.originalUrl} - ${res.statusCode} [${duration}ms]`);
});
next();
}
```
## 四、数据验证与错误处理
### 4.1 使用Joi进行参数校验
定义用户创建校验规则：
```javascript
const userSchema = Joi.object({
username: Joi.string().alphanum().min(3).max(30).required(),
email: Joi.string().email().required(),
age: Joi.number().integer().min(18).max(100)
});
```
在路由中集成验证：
```javascript
router.post('/', (req, res, next) => {
const { error } = userSchema.validate(req.body);
if (error) return res.status(422).json({
error: error.details.map(d => d.message)
});
next();
});
```
### 4.2 统一错误处理机制
创建错误处理中间件：
```javascript
app.use((err, req, res, next) => {
const statusCode = err.statusCode || 500;
res.status(statusCode).json({
error: {
code: statusCode,
message: process.env.NODE_ENV === 'development'
? err.message
: 'Internal Server Error'
}
});
});
```
## 五、安全防护与性能优化
### 5.1 安全加固措施
配置Helmet中间件：
```javascript
app.use(helmet({
contentSecurityPolicy: {
directives: {
defaultSrc: ["'self'"],
scriptSrc: ["'self'", "trusted.cdn.com"]
}
},
hsts: {
maxAge: 63072000, // 2年有效期
includeSubDomains: true
}
}));
```
### 5.2 性能调优实践
启用Redis缓存示例：
```javascript
const redis = require('redis');
const client = redis.createClient();
function cacheMiddleware(duration) {
return (req, res, next) => {
const key = req.originalUrl;
client.get(key, (err, data) => {
if (data) {
res.send(JSON.parse(data));
} else {
res.sendResponse = res.send;
res.send = (body) => {
client.setex(key, duration, body);
res.sendResponse(body);
}
next();
}
});
};
}
```
## 六、部署与监控
### 6.1 PM2生产部署配置
创建ecosystem.config.js：
```javascript
module.exports = {
apps: [{
name: 'api-server',
script: './app.js',
instances: 'max',
exec_mode: 'cluster',
env: {
NODE_ENV: 'production',
PORT: 3000
}
}]
};
```
### 6.2 监控指标收集
集成Prometheus监控：
```javascript
const prometheus = require('prom-client');
const collectDefaultMetrics = prometheus.collectDefaultMetrics;
collectDefaultMetrics({ timeout: 5000 });
app.get('/metrics', async (req, res) => {
res.set('Content-Type', prometheus.register.contentType);
res.end(await prometheus.register.metrics());
});
```
---
**技术标签**：Node.js RESTfulAPI Express框架 API开发 后端工程 中间件 性能优化 Web安全
