nodejs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Node.js Backend Patterns

Node.js 后端模式

Purpose

用途

Core patterns for building scalable Node.js backend applications with TypeScript, emphasizing clean architecture, error handling, and testability.

用于使用TypeScript构建可扩展Node.js后端应用的核心模式，强调清晰架构、错误处理和可测试性。

When to Use This Skill

何时使用该技能

Building Node.js backend services
Implementing async/await patterns
Error handling and logging
Configuration management
Testing backend code
Layered architecture (routes → controllers → services → repositories)

构建Node.js后端服务
实现async/await模式
错误处理与日志记录
配置管理
后端代码测试
分层架构（路由 → 控制器 → 服务 → 仓库）

Quick Start

快速开始

Layered Architecture

分层架构

src/
├── api/
│   ├── routes/         # HTTP route definitions
│   ├── controllers/    # Request/response handling
│   ├── services/       # Business logic
│   └── repositories/   # Data access
├── middleware/         # Express middleware
├── types/             # TypeScript types
├── config/            # Configuration
└── utils/             # Utilities

Flow: Route → Controller → Service → Repository → Database

src/
├── api/
│   ├── routes/         # HTTP路由定义
│   ├── controllers/    # 请求/响应处理
│   ├── services/       # 业务逻辑
│   └── repositories/   # 数据访问
├── middleware/         # Express中间件
├── types/             # TypeScript类型定义
├── config/            # 配置文件
└── utils/             # 工具函数

流程： 路由 → 控制器 → 服务 → 仓库 → 数据库

Async/Await Error Handling

Async/Await错误处理

Basic Pattern

基础模式

typescript

async function fetchUser(id: string): Promise<User> {
  try {
    const user = await db.user.findUnique({ where: { id } });
    if (!user) {
      throw new Error('User not found');
    }
    return user;
  } catch (error) {
    console.error('Error fetching user:', error);
    throw error;
  }
}

typescript

async function fetchUser(id: string): Promise<User> {
  try {
    const user = await db.user.findUnique({ where: { id } });
    if (!user) {
      throw new Error('User not found');
    }
    return user;
  } catch (error) {
    console.error('Error fetching user:', error);
    throw error;
  }
}

Async Controller Pattern

异步控制器模式

typescript

class UserController {
  async getUser(req: Request, res: Response): Promise<void> {
    try {
      const { id } = req.params;
      const user = await this.userService.getById(id);

      res.json({
        success: true,
        data: user,
      });
    } catch (error) {
      console.error('Error in getUser:', error);
      res.status(500).json({
        success: false,
        error: 'Failed to fetch user',
      });
    }
  }
}

typescript

class UserController {
  async getUser(req: Request, res: Response): Promise<void> {
    try {
      const { id } = req.params;
      const user = await this.userService.getById(id);

      res.json({
        success: true,
        data: user,
      });
    } catch (error) {
      console.error('Error in getUser:', error);
      res.status(500).json({
        success: false,
        error: 'Failed to fetch user',
      });
    }
  }
}

Promise.all for Parallel Operations

并行操作的Promise.all

typescript

async function getUserDashboard(userId: string) {
  try {
    const [user, posts, followers] = await Promise.all([
      userService.getById(userId),
      postService.getByUser(userId),
      followerService.getByUser(userId),
    ]);

    return { user, posts, followers };
  } catch (error) {
    console.error('Error loading dashboard:', error);
    throw error;
  }
}

typescript

async function getUserDashboard(userId: string) {
  try {
    const [user, posts, followers] = await Promise.all([
      userService.getById(userId),
      postService.getByUser(userId),
      followerService.getByUser(userId),
    ]);

    return { user, posts, followers };
  } catch (error) {
    console.error('Error loading dashboard:', error);
    throw error;
  }
}

TypeScript Patterns

TypeScript模式

Request/Response Types

请求/响应类型

typescript

// Request body
interface CreateUserRequest {
  email: string;
  name: string;
  password: string;
}

// Response
interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: string;
  message?: string;
}

// Usage
async function createUser(
  req: Request<{}, {}, CreateUserRequest>,
  res: Response<ApiResponse<User>>
): Promise<void> {
  const { email, name, password } = req.body;

  const user = await userService.create({ email, name, password });

  res.json({
    success: true,
    data: user,
  });
}

typescript

// 请求体
interface CreateUserRequest {
  email: string;
  name: string;
  password: string;
}

// 响应
interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: string;
  message?: string;
}

// 使用示例
async function createUser(
  req: Request<{}, {}, CreateUserRequest>,
  res: Response<ApiResponse<User>>
): Promise<void> {
  const { email, name, password } = req.body;

  const user = await userService.create({ email, name, password });

  res.json({
    success: true,
    data: user,
  });
}

Service Layer Types

服务层类型

typescript

interface IUserService {
  getById(id: string): Promise<User>;
  create(data: CreateUserDto): Promise<User>;
  update(id: string, data: UpdateUserDto): Promise<User>;
  delete(id: string): Promise<void>;
}

class UserService implements IUserService {
  async getById(id: string): Promise<User> {
    // Implementation
  }

  async create(data: CreateUserDto): Promise<User> {
    // Implementation
  }

  async update(id: string, data: UpdateUserDto): Promise<User> {
    // Implementation
  }

  async delete(id: string): Promise<void> {
    // Implementation
  }
}

typescript

interface IUserService {
  getById(id: string): Promise<User>;
  create(data: CreateUserDto): Promise<User>;
  update(id: string, data: UpdateUserDto): Promise<User>;
  delete(id: string): Promise<void>;
}

class UserService implements IUserService {
  async getById(id: string): Promise<User> {
    // 实现代码
  }

  async create(data: CreateUserDto): Promise<User> {
    // 实现代码
  }

  async update(id: string, data: UpdateUserDto): Promise<User> {
    // 实现代码
  }

  async delete(id: string): Promise<void> {
    // 实现代码
  }
}

Configuration Management

配置管理

Environment Variables

环境变量

typescript

// config/env.ts
import { z } from 'zod';

const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'production', 'test']),
  PORT: z.string().transform(Number),
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
  LOG_LEVEL: z.enum(['error', 'warn', 'info', 'debug']).default('info'),
});

export const env = envSchema.parse(process.env);

typescript

// config/env.ts
import { z } from 'zod';

const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'production', 'test']),
  PORT: z.string().transform(Number),
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
  LOG_LEVEL: z.enum(['error', 'warn', 'info', 'debug']).default('info'),
});

export const env = envSchema.parse(process.env);

Unified Config

统一配置

typescript

// config/index.ts
interface Config {
  server: {
    port: number;
    host: string;
  };
  database: {
    url: string;
  };
  auth: {
    jwtSecret: string;
    jwtExpiry: string;
  };
}

export const config: Config = {
  server: {
    port: parseInt(process.env.PORT || '3000'),
    host: process.env.HOST || 'localhost',
  },
  database: {
    url: process.env.DATABASE_URL || '',
  },
  auth: {
    jwtSecret: process.env.JWT_SECRET || '',
    jwtExpiry: process.env.JWT_EXPIRY || '7d',
  },
};

typescript

// config/index.ts
interface Config {
  server: {
    port: number;
    host: string;
  };
  database: {
    url: string;
  };
  auth: {
    jwtSecret: string;
    jwtExpiry: string;
  };
}

export const config: Config = {
  server: {
    port: parseInt(process.env.PORT || '3000'),
    host: process.env.HOST || 'localhost',
  },
  database: {
    url: process.env.DATABASE_URL || '',
  },
  auth: {
    jwtSecret: process.env.JWT_SECRET || '',
    jwtExpiry: process.env.JWT_EXPIRY || '7d',
  },
};

Layered Architecture

分层架构

Controller Layer

控制器层

typescript

// controllers/UserController.ts
export class UserController {
  constructor(private userService: UserService) {}

  async getById(req: Request, res: Response): Promise<void> {
    const { id } = req.params;
    const user = await this.userService.getById(id);

    res.json({
      success: true,
      data: user,
    });
  }

  async create(req: Request, res: Response): Promise<void> {
    const userData = req.body;
    const user = await this.userService.create(userData);

    res.status(201).json({
      success: true,
      data: user,
    });
  }
}

typescript

// controllers/UserController.ts
export class UserController {
  constructor(private userService: UserService) {}

  async getById(req: Request, res: Response): Promise<void> {
    const { id } = req.params;
    const user = await this.userService.getById(id);

    res.json({
      success: true,
      data: user,
    });
  }

  async create(req: Request, res: Response): Promise<void> {
    const userData = req.body;
    const user = await this.userService.create(userData);

    res.status(201).json({
      success: true,
      data: user,
    });
  }
}

Service Layer

服务层

typescript

// services/UserService.ts
export class UserService {
  constructor(private userRepository: UserRepository) {}

  async getById(id: string): Promise<User> {
    const user = await this.userRepository.findById(id);
    if (!user) {
      throw new Error('User not found');
    }
    return user;
  }

  async create(data: CreateUserDto): Promise<User> {
    // Business logic
    const hashedPassword = await this.hashPassword(data.password);

    return this.userRepository.create({
      ...data,
      password: hashedPassword,
    });
  }

  private async hashPassword(password: string): Promise<string> {
    // Hash implementation
    return password; // Placeholder
  }
}

typescript

// services/UserService.ts
export class UserService {
  constructor(private userRepository: UserRepository) {}

  async getById(id: string): Promise<User> {
    const user = await this.userRepository.findById(id);
    if (!user) {
      throw new Error('User not found');
    }
    return user;
  }

  async create(data: CreateUserDto): Promise<User> {
    // 业务逻辑
    const hashedPassword = await this.hashPassword(data.password);

    return this.userRepository.create({
      ...data,
      password: hashedPassword,
    });
  }

  private async hashPassword(password: string): Promise<string> {
    // 哈希实现
    return password; // 占位符
  }
}

Repository Layer

仓库层

typescript

// repositories/UserRepository.ts
export class UserRepository {
  async findById(id: string): Promise<User | null> {
    // Database query
    return db.user.findUnique({ where: { id } });
  }

  async create(data: CreateUserData): Promise<User> {
    return db.user.create({ data });
  }

  async update(id: string, data: UpdateUserData): Promise<User> {
    return db.user.update({
      where: { id },
      data,
    });
  }

  async delete(id: string): Promise<void> {
    await db.user.delete({ where: { id } });
  }
}

typescript

// repositories/UserRepository.ts
export class UserRepository {
  async findById(id: string): Promise<User | null> {
    // 数据库查询
    return db.user.findUnique({ where: { id } });
  }

  async create(data: CreateUserData): Promise<User> {
    return db.user.create({ data });
  }

  async update(id: string, data: UpdateUserData): Promise<User> {
    return db.user.update({
      where: { id },
      data,
    });
  }

  async delete(id: string): Promise<void> {
    await db.user.delete({ where: { id } });
  }
}

Dependency Injection

依赖注入

Basic DI Pattern

基础DI模式

typescript

// Composition root
const userRepository = new UserRepository();
const userService = new UserService(userRepository);
const userController = new UserController(userService);

export { userController };

typescript

// 组合根
const userRepository = new UserRepository();
const userService = new UserService(userRepository);
const userController = new UserController(userService);

export { userController };

Service Container

服务容器

typescript

// container.ts
class Container {
  private services: Map<string, any> = new Map();

  register<T>(name: string, factory: () => T): void {
    this.services.set(name, factory());
  }

  get<T>(name: string): T {
    const service = this.services.get(name);
    if (!service) {
      throw new Error(`Service ${name} not found`);
    }
    return service;
  }
}

export const container = new Container();

// Register services
container.register('userRepository', () => new UserRepository());
container.register('userService', () => new UserService(
  container.get('userRepository')
));
container.register('userController', () => new UserController(
  container.get('userService')
));

typescript

// container.ts
class Container {
  private services: Map<string, any> = new Map();

  register<T>(name: string, factory: () => T): void {
    this.services.set(name, factory());
  }

  get<T>(name: string): T {
    const service = this.services.get(name);
    if (!service) {
      throw new Error(`Service ${name} not found`);
    }
    return service;
  }
}

export const container = new Container();

// 注册服务
container.register('userRepository', () => new UserRepository());
container.register('userService', () => new UserService(
  container.get('userRepository')
));
container.register('userController', () => new UserController(
  container.get('userService')
));

Error Handling

错误处理

Custom Error Classes

自定义错误类

typescript

export class AppError extends Error {
  constructor(
    public message: string,
    public statusCode: number = 500,
    public isOperational: boolean = true
  ) {
    super(message);
    Object.setPrototypeOf(this, AppError.prototype);
  }
}

export class NotFoundError extends AppError {
  constructor(resource: string) {
    super(`${resource} not found`, 404);
  }
}

export class ValidationError extends AppError {
  constructor(message: string) {
    super(message, 400);
  }
}

// Usage
async function getUser(id: string): Promise<User> {
  const user = await userRepository.findById(id);
  if (!user) {
    throw new NotFoundError('User');
  }
  return user;
}

typescript

export class AppError extends Error {
  constructor(
    public message: string,
    public statusCode: number = 500,
    public isOperational: boolean = true
  ) {
    super(message);
    Object.setPrototypeOf(this, AppError.prototype);
  }
}

export class NotFoundError extends AppError {
  constructor(resource: string) {
    super(`${resource} not found`, 404);
  }
}

export class ValidationError extends AppError {
  constructor(message: string) {
    super(message, 400);
  }
}

// 使用示例
async function getUser(id: string): Promise<User> {
  const user = await userRepository.findById(id);
  if (!user) {
    throw new NotFoundError('User');
  }
  return user;
}

Async Error Wrapper

异步错误包装器

typescript

type AsyncHandler = (
  req: Request,
  res: Response,
  next: NextFunction
) => Promise<void>;

export const asyncHandler = (fn: AsyncHandler) => {
  return (req: Request, res: Response, next: NextFunction) => {
    Promise.resolve(fn(req, res, next)).catch(next);
  };
};

// Usage
router.get('/users/:id', asyncHandler(async (req, res) => {
  const user = await userService.getById(req.params.id);
  res.json({ data: user });
}));

typescript

type AsyncHandler = (
  req: Request,
  res: Response,
  next: NextFunction
) => Promise<void>;

export const asyncHandler = (fn: AsyncHandler) => {
  return (req: Request, res: Response, next: NextFunction) => {
    Promise.resolve(fn(req, res, next)).catch(next);
  };
};

// 使用示例
router.get('/users/:id', asyncHandler(async (req, res) => {
  const user = await userService.getById(req.params.id);
  res.json({ data: user });
}));

Best Practices

最佳实践

1. Always Use Async/Await

1. 始终使用Async/Await

typescript

// ✅ Good: async/await
async function getUser(id: string): Promise<User> {
  const user = await userRepository.findById(id);
  return user;
}

// ❌ Avoid: Promise chains
function getUser(id: string): Promise<User> {
  return userRepository.findById(id)
    .then(user => user)
    .catch(error => throw error);
}

typescript

// ✅ 推荐：async/await
async function getUser(id: string): Promise<User> {
  const user = await userRepository.findById(id);
  return user;
}

// ❌ 避免：Promise链式调用
function getUser(id: string): Promise<User> {
  return userRepository.findById(id)
    .then(user => user)
    .catch(error => throw error);
}

2. Layer Separation

2. 分层分离

typescript

// ✅ Good: Separated layers
// Controller handles HTTP
// Service handles business logic
// Repository handles data access

// ❌ Avoid: Business logic in controllers
class UserController {
  async create(req: Request, res: Response) {
    // ❌ Don't put business logic here
    const hashedPassword = await hash(req.body.password);
    const user = await db.user.create({...});
    res.json(user);
  }
}

typescript

// ✅ 推荐：分层分离
// 控制器处理HTTP请求
// 服务处理业务逻辑
// 仓库处理数据访问

// ❌ 避免：控制器中包含业务逻辑
class UserController {
  async create(req: Request, res: Response) {
    // ❌ 不要在此处放置业务逻辑
    const hashedPassword = await hash(req.body.password);
    const user = await db.user.create({...});
    res.json(user);
  }
}

3. Type Everything

3. 全面类型定义

typescript

// ✅ Good: Full type coverage
async function updateUser(
  id: string,
  data: UpdateUserDto
): Promise<User> {
  return userService.update(id, data);
}

// ❌ Avoid: any types
async function updateUser(id: any, data: any): Promise<any> {
  return userService.update(id, data);
}

typescript

// ✅ 推荐：完整类型覆盖
async function updateUser(
  id: string,
  data: UpdateUserDto
): Promise<User> {
  return userService.update(id, data);
}

// ❌ 避免：使用any类型
async function updateUser(id: any, data: any): Promise<any> {
  return userService.update(id, data);
}

Additional Resources

额外资源

For more patterns, see:

async-and-errors.md - Advanced error handling
testing-guide.md - Comprehensive testing
architecture-patterns.md - Architecture details

如需了解更多模式，请查看：

async-and-errors.md - 高级错误处理
testing-guide.md - 全面测试指南
architecture-patterns.md - 架构细节