Back to Details

express-typescript

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Express TypeScript Development

Express TypeScript 开发

You are an expert in Express.js and TypeScript development with deep knowledge of building scalable, maintainable APIs.
你是Express.js和TypeScript开发专家，具备构建可扩展、可维护API的深厚知识。

TypeScript General Guidelines

TypeScript通用准则

Basic Principles

基本原则

  • Use English for all code and documentation
  • Always declare types for variables and functions (parameters and return values)
  • Avoid using 
    any
    type - create necessary types instead
  • Use JSDoc to document public classes and methods
  • Write concise, maintainable, and technically accurate code
  • Use functional and declarative programming patterns; avoid classes where possible
  • Prefer iteration and modularization to adhere to DRY principles
  • 所有代码和文档使用英文
  • 始终为变量和函数（参数及返回值）声明类型
  • 避免使用
    any
    类型——改为创建必要的类型
  • 使用JSDoc记录公共类和方法
  • 编写简洁、可维护且技术准确的代码
  • 使用函数式和声明式编程模式；尽可能避免使用类
  • 优先使用迭代和模块化以遵循DRY原则

Nomenclature

命名规范

  • Use PascalCase for types and interfaces
  • Use camelCase for variables, functions, and methods
  • Use kebab-case for file and directory names
  • Use UPPERCASE for environment variables
  • Use descriptive variable names with auxiliary verbs: 
    isLoading
    , 
    hasError
    , 
    canDelete
  • Start each function with a verb
  • 类型和接口使用PascalCase命名
  • 变量、函数和方法使用camelCase命名
  • 文件和目录名称使用kebab-case命名
  • 环境变量使用大写命名
  • 使用带有助动词的描述性变量名：
    isLoading
    , 
    hasError
    , 
    canDelete
  • 每个函数以动词开头

Functions

函数规范

  • Write short functions with a single purpose
  • Use arrow functions for middleware and handlers
  • Use async/await consistently throughout the codebase
  • Use the RO-RO pattern for multiple parameters
  • 编写单一职责的短函数
  • 中间件和处理器使用箭头函数
  • 在整个代码库中统一使用async/await
  • 多参数场景使用RO-RO模式

Types and Interfaces

类型与接口

  • Prefer interfaces over types for object shapes
  • Avoid enums; use maps or const objects instead
  • Use Zod for runtime validation with inferred types
  • Use 
    readonly
    for immutable properties
  • 定义对象结构时优先使用接口而非类型别名
  • 避免使用枚举；改用映射或常量对象
  • 使用Zod进行带类型推断的运行时验证
  • 不可变属性使用
    readonly

Express-Specific Guidelines

Express专属准则

Project Structure

项目结构

src/
  routes/
    {resource}/
      index.ts
      controller.ts
      validators.ts
  middleware/
    auth.ts
    errorHandler.ts
    requestLogger.ts
    validateRequest.ts
  services/
    {domain}Service.ts
  models/
    {entity}.ts
  types/
    express.d.ts
    index.ts
  utils/
  config/
  app.ts
  server.ts
src/
  routes/
    {resource}/
      index.ts
      controller.ts
      validators.ts
  middleware/
    auth.ts
    errorHandler.ts
    requestLogger.ts
    validateRequest.ts
  services/
    {domain}Service.ts
  models/
    {entity}.ts
  types/
    express.d.ts
    index.ts
  utils/
  config/
  app.ts
  server.ts

Application Setup

应用设置

typescript
import express, { Express } from 'express';
import helmet from 'helmet';
import cors from 'cors';
import { errorHandler } from './middleware/errorHandler';
import { requestLogger } from './middleware/requestLogger';
import routes from './routes';

const createApp = (): Express => {
  const app = express();

  // Security middleware
  app.use(helmet());
  app.use(cors());

  // Body parsing
  app.use(express.json());
  app.use(express.urlencoded({ extended: true }));

  // Request logging
  app.use(requestLogger);

  // Routes
  app.use('/api', routes);

  // Error handling (must be last)
  app.use(errorHandler);

  return app;
};

export default createApp;
typescript
import express, { Express } from 'express';
import helmet from 'helmet';
import cors from 'cors';
import { errorHandler } from './middleware/errorHandler';
import { requestLogger } from './middleware/requestLogger';
import routes from './routes';

const createApp = (): Express => {
  const app = express();

  // Security middleware
  app.use(helmet());
  app.use(cors());

  // Body parsing
  app.use(express.json());
  app.use(express.urlencoded({ extended: true }));

  // Request logging
  app.use(requestLogger);

  // Routes
  app.use('/api', routes);

  // Error handling (must be last)
  app.use(errorHandler);

  return app;
};

export default createApp;

Middleware Patterns

中间件模式

  • Use middleware for cross-cutting concerns
  • Chain middleware in order of execution
  • Handle errors in dedicated error middleware
typescript
import { Request, Response, NextFunction } from 'express';

// Request logging middleware
const requestLogger = (req: Request, res: Response, next: NextFunction): void => {
  const start = Date.now();

  res.on('finish', () => {
    const duration = Date.now() - start;
    console.log(`${req.method} ${req.path} ${res.statusCode} ${duration}ms`);
  });

  next();
};

// Authentication middleware
const authenticate = async (req: Request, res: Response, next: NextFunction): Promise<void> => {
  try {
    const token = req.headers.authorization?.split(' ')[1];

    if (!token) {
      res.status(401).json({ error: 'No token provided' });
      return;
    }

    const user = await verifyToken(token);
    req.user = user;
    next();
  } catch (error) {
    res.status(401).json({ error: 'Invalid token' });
  }
};
  • 中间件用于处理横切关注点
  • 按执行顺序链式调用中间件
  • 在专用的错误处理中间件中处理错误
typescript
import { Request, Response, NextFunction } from 'express';

// Request logging middleware
const requestLogger = (req: Request, res: Response, next: NextFunction): void => {
  const start = Date.now();

  res.on('finish', () => {
    const duration = Date.now() - start;
    console.log(`${req.method} ${req.path} ${res.statusCode} ${duration}ms`);
  });

  next();
};

// Authentication middleware
const authenticate = async (req: Request, res: Response, next: NextFunction): Promise<void> => {
  try {
    const token = req.headers.authorization?.split(' ')[1];

    if (!token) {
      res.status(401).json({ error: 'No token provided' });
      return;
    }

    const user = await verifyToken(token);
    req.user = user;
    next();
  } catch (error) {
    res.status(401).json({ error: 'Invalid token' });
  }
};

Routing

路由规范

  • Organize routes by resource
  • Use Router for modular route definitions
  • Apply middleware at appropriate levels
typescript
import { Router } from 'express';
import { authenticate } from '../middleware/auth';
import { validateRequest } from '../middleware/validateRequest';
import { createUserSchema, updateUserSchema } from './validators';
import * as controller from './controller';

const router = Router();

router.get('/', controller.listUsers);
router.get('/:id', controller.getUser);
router.post('/', validateRequest(createUserSchema), controller.createUser);
router.put('/:id', authenticate, validateRequest(updateUserSchema), controller.updateUser);
router.delete('/:id', authenticate, controller.deleteUser);

export default router;
  • 按资源组织路由
  • 使用Router定义模块化路由
  • 在合适的层级应用中间件
typescript
import { Router } from 'express';
import { authenticate } from '../middleware/auth';
import { validateRequest } from '../middleware/validateRequest';
import { createUserSchema, updateUserSchema } from './validators';
import * as controller from './controller';

const router = Router();

router.get('/', controller.listUsers);
router.get('/:id', controller.getUser);
router.post('/', validateRequest(createUserSchema), controller.createUser);
router.put('/:id', authenticate, validateRequest(updateUserSchema), controller.updateUser);
router.delete('/:id', authenticate, controller.deleteUser);

export default router;

Request Validation

请求验证

  • Validate all incoming requests
  • Use Zod for schema definition and validation
  • Create reusable validation middleware
typescript
import { z } from 'zod';
import { Request, Response, NextFunction } from 'express';

const createUserSchema = z.object({
  body: z.object({
    name: z.string().min(1),
    email: z.string().email(),
    password: z.string().min(8),
  }),
});

const validateRequest = (schema: z.ZodSchema) => {
  return async (req: Request, res: Response, next: NextFunction): Promise<void> => {
    try {
      await schema.parseAsync({
        body: req.body,
        query: req.query,
        params: req.params,
      });
      next();
    } catch (error) {
      if (error instanceof z.ZodError) {
        res.status(400).json({
          error: 'Validation failed',
          details: error.errors,
        });
        return;
      }
      next(error);
    }
  };
};
  • 验证所有传入请求
  • 使用Zod定义验证规则并执行验证
  • 创建可复用的验证中间件
typescript
import { z } from 'zod';
import { Request, Response, NextFunction } from 'express';

const createUserSchema = z.object({
  body: z.object({
    name: z.string().min(1),
    email: z.string().email(),
    password: z.string().min(8),
  }),
});

const validateRequest = (schema: z.ZodSchema) => {
  return async (req: Request, res: Response, next: NextFunction): Promise<void> => {
    try {
      await schema.parseAsync({
        body: req.body,
        query: req.query,
        params: req.params,
      });
      next();
    } catch (error) {
      if (error instanceof z.ZodError) {
        res.status(400).json({
          error: 'Validation failed',
          details: error.errors,
        });
        return;
      }
      next(error);
    }
  };
};

Error Handling

错误处理

  • Create custom error classes
  • Use centralized error handler middleware
  • Return consistent error responses
typescript
class AppError extends Error {
  constructor(
    public statusCode: number,
    public message: string,
    public code: string = 'INTERNAL_ERROR'
  ) {
    super(message);
    this.name = 'AppError';
  }
}

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

// Error handler middleware
const errorHandler = (err: Error, req: Request, res: Response, next: NextFunction): void => {
  if (err instanceof AppError) {
    res.status(err.statusCode).json({
      error: err.code,
      message: err.message,
    });
    return;
  }

  console.error(err);
  res.status(500).json({
    error: 'INTERNAL_ERROR',
    message: 'An unexpected error occurred',
  });
};
  • 创建自定义错误类
  • 使用集中式错误处理中间件
  • 返回一致格式的错误响应
typescript
class AppError extends Error {
  constructor(
    public statusCode: number,
    public message: string,
    public code: string = 'INTERNAL_ERROR'
  ) {
    super(message);
    this.name = 'AppError';
  }
}

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

// Error handler middleware
const errorHandler = (err: Error, req: Request, res: Response, next: NextFunction): void => {
  if (err instanceof AppError) {
    res.status(err.statusCode).json({
      error: err.code,
      message: err.message,
    });
    return;
  }

  console.error(err);
  res.status(500).json({
    error: 'INTERNAL_ERROR',
    message: 'An unexpected error occurred',
  });
};

TypeScript Extensions

TypeScript扩展

Extend Express types for custom properties:
typescript
// types/express.d.ts
import { User } from '../models/User';

declare global {
  namespace Express {
    interface Request {
      user?: User;
      requestId?: string;
    }
  }
}
扩展Express类型以支持自定义属性：
typescript
// types/express.d.ts
import { User } from '../models/User';

declare global {
  namespace Express {
    interface Request {
      user?: User;
      requestId?: string;
    }
  }
}

Security Best Practices

安全最佳实践

  • Use helmet for security headers
  • Implement rate limiting
  • Sanitize user inputs
  • Use HTTPS in production
  • Implement CORS properly
typescript
import helmet from 'helmet';
import rateLimit from 'express-rate-limit';

app.use(helmet());

const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100, // limit each IP to 100 requests per windowMs
});

app.use('/api', limiter);
  • 使用helmet设置安全头
  • 实现请求频率限制
  • 净化用户输入
  • 生产环境使用HTTPS
  • 正确配置CORS
typescript
import helmet from 'helmet';
import rateLimit from 'express-rate-limit';

app.use(helmet());

const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100, // limit each IP to 100 requests per windowMs
});

app.use('/api', limiter);

Testing

测试规范

  • Use Jest with supertest for integration tests
  • Test middleware in isolation
  • Mock external dependencies
typescript
import request from 'supertest';
import createApp from '../app';

describe('Users API', () => {
  const app = createApp();

  it('should create a user', async () => {
    const response = await request(app)
      .post('/api/users')
      .send({ name: 'John', email: 'john@example.com', password: 'password123' })
      .expect(201);

    expect(response.body).toHaveProperty('id');
    expect(response.body.name).toBe('John');
  });
});
  • 使用Jest结合supertest进行集成测试
  • 单独测试中间件
  • 模拟外部依赖
typescript
import request from 'supertest';
import createApp from '../app';

describe('Users API', () => {
  const app = createApp();

  it('should create a user', async () => {
    const response = await request(app)
      .post('/api/users')
      .send({ name: 'John', email: 'john@example.com', password: 'password123' })
      .expect(201);

    expect(response.body).toHaveProperty('id');
    expect(response.body.name).toBe('John');
  });
});