# Node.js + Express + TypeScript 后端开发最佳实践
## 引言
构建企业级后端应用需要考虑诸多方面，包括架构设计、性能优化、安全性等。本规则将帮助你掌握 Node.js + Express + TypeScript 技术栈的最佳实践，构建可靠的后端服务。
## 核心原则
### 1. 项目结构设计
#### 问题描述
不合理的项目结构会导致代码难以维护和扩展。
#### 最佳实践
1. 采用分层架构
2. 遵循关注点分离
3. 实现模块化设计
```typescript
// 推荐的项目结构
src/
├── config/ // 配置文件
│ ├── database.ts
│ └── app.ts
├── controllers/ // 控制器层
│ └── UserController.ts
├── services/ // 服务层
│ └── UserService.ts
├── models/ // 数据模型
│ └── User.ts
├── middlewares/ // 中间件
│ ├── auth.ts
│ └── error.ts
├── routes/ // 路由定义
│ └── user.ts
├── utils/ // 工具函数
│ └── logger.ts
└── app.ts // 应用入口
// 控制器示例
import { Request, Response, NextFunction } from 'express';
import { UserService } from '../services/UserService';
export class UserController {
constructor(private userService: UserService) {}
async getUser(req: Request, res: Response, next: NextFunction) {
try {
const user = await this.userService.findById(req.params.id);
res.json(user);
} catch (error) {
next(error);
}
}
}
```
### 2. API 设计规范
#### 问题描述
不规范的 API 设计会影响接口的可用性和可维护性。
#### 最佳实践
1. 遵循 RESTful 设计原则
2. 统一响应格式
3. 版本控制
```typescript
// API 路由定义示例
import { Router } from 'express';
import { UserController } from '../controllers/UserController';
const router = Router();
const userController = new UserController(new UserService());
router.get('/v1/users/:id', userController.getUser);
router.post('/v1/users', userController.createUser);
router.put('/v1/users/:id', userController.updateUser);
router.delete('/v1/users/:id', userController.deleteUser);
// 统一响应格式
interface ApiResponse<T> {
success: boolean;
data?: T;
error?: {
code: string;
message: string;
};
meta?: {
page?: number;
limit?: number;
total?: number;
};
}
// 响应处理中间件
const responseHandler = (req: Request, res: Response, next: NextFunction) => {
res.success = function(data: any, meta?: any) {
res.json({
success: true,
data,
meta
});
};
next();
};
```
### 3. 数据库操作优化
#### 问题描述
不当的数据库操作会导致性能问题和数据一致性问题。
#### 最佳实践
1. 使用 ORM 或查询构建器
2. 实现数据验证
3. 优化查询性能
```typescript
// 使用 Prisma 的数据库操作示例
import { PrismaClient } from '@prisma/client';
export class UserService {
constructor(private prisma: PrismaClient) {}
async findById(id: string) {
return this.prisma.user.findUnique({
where: { id },
include: {
posts: true,
profile: true
}
});
}
async create(data: CreateUserDto) {
// 数据验证
await this.validateUserData(data);
// 事务处理
return this.prisma.$transaction(async (tx) => {
const user = await tx.user.create({
data: {
...data,
profile: {
create: data.profile
}
}
});
await tx.userLog.create({
data: {
userId: user.id,
action: 'CREATE'
}
});
return user;
});
}
}
```
### 4. 错误处理机制
#### 问题描述
不完善的错误处理会导致应用不稳定和调试困难。
#### 最佳实践
1. 实现全局错误处理
2. 自定义错误类型
3. 规范错误日志
```typescript
// 自定义错误类
export class AppError extends Error {
constructor(
public statusCode: number,
public code: string,
message: string
) {
super(message);
this.name = 'AppError';
}
}
// 错误处理中间件
export const errorHandler = (
err: Error,
req: Request,
res: Response,
next: NextFunction
) => {
if (err instanceof AppError) {
return res.status(err.statusCode).json({
success: false,
error: {
code: err.code,
message: err.message
}
});
}
// 未知错误处理
console.error(err);
return res.status(500).json({
success: false,
error: {
code: 'INTERNAL_ERROR',
message: 'An unexpected error occurred'
}
});
};
```
### 5. 中间件配置
#### 问题描述
中间件配置不当会影响应用的安全性和性能。
#### 最佳实践
1. 合理配置安全中间件
2. 实现请求验证
3. 优化性能中间件
```typescript
import express from 'express';
import helmet from 'helmet';
import rateLimit from 'express-rate-limit';
import compression from 'compression';
export function configureMiddleware(app: express.Application) {
// 安全中间件
app.use(helmet());
// 请求限制
app.use(rateLimit({
windowMs: 15 * 60 * 1000, // 15分钟
max: 100 // 限制每个IP 100次请求
}));
// 压缩响应
app.use(compression());
// 请求解析
app.use(express.json({ limit: '10kb' }));
app.use(express.urlencoded({ extended: true, limit: '10kb' }));
// CORS 配置
app.use(cors({
origin: process.env.ALLOWED_ORIGINS?.split(','),
methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
credentials: true
}));
}
```
## 实践检查清单
1. 项目配置
- [ ] 环境变量管理
- [ ] 配置文件分离
- [ ] 日志系统配置
2. 安全措施
- [ ] 输入验证
- [ ] XSS 防护
- [ ] CSRF 防护
- [ ] 速率限制
3. 性能优化
- [ ] 数据库索引
- [ ] 缓存策略
- [ ] 异步操作处理
4. 可维护性
- [ ] 代码文档
- [ ] 单元测试
- [ ] API 文档
## 性能优化
1. 数据库优化
- 使用适当的索引
- 优化查询语句
- 实现数据缓存
2. 应用性能
- 异步操作处理
- 响应压缩
- 静态资源优化
## 常见陷阱
1. 安全隐患
- 避免敏感信息泄露
- 防止 SQL 注入
- 保护用户数据
2. 性能问题
- 避免 N+1 查询
- 处理内存泄漏
- 优化大量并发
3. 可维护性问题
- 避免代码重复
- 保持代码简洁
- 编写测试用例
## 结论
Node.js + Express + TypeScript 技术栈为构建后端应用提供了强大的工具和生态系统。通过遵循本规则提供的最佳实践，你可以构建出高质量、可维护的后端服务。
记住：
1. 保持代码整洁和模块化
2. 重视安全性和性能
3. 编写完善的测试
4. 持续优化和改进
祝你编码愉快！