nodejs-express-mongodb-backend-pattern

Node.js Express MongoDB 后端模式

用途

此技能可帮助 Agent 搭建、说明或调整 nodejs-express-mongodb-backend-pattern 模板——一个内置可观测性、安全性和韧性的 Node.js REST API 样板。用户需要一个使用 Express、MongoDB、Redis、Sentry、JWT 身份验证和面向生产环境的中间件的后端时，Agent 应使用此技能。

何时使用此技能

• 用户想要使用 Node.js 和 Express 创建新的 REST API 后端。
• 用户需要一个可用于生产环境或“可观测”的 Node.js API 模板。
• 用户提到 MongoDB/Mongoose、Redis、Sentry、速率限制或 JWT 身份验证，并想要一个起步模板。
• 用户想要克隆、派生或了解此仓库（nodejs-express-mongodb-backend-pattern）的结构。
• 用户需要按照此模板的约定设置环境变量、运行应用或添加路由/控制器的步骤。

何时不使用此技能

• 用户想要前端或全栈框架（Next.js、Nuxt 等）。
• 用户明确要求使用其他数据库（PostgreSQL、MySQL），而不使用 Mongoose。
• 用户想要无服务器/Lambda 架构，而不是持续运行的 Express 服务。

如何使用此模板

1. 克隆并安装

git clone https://github.com/laskar-ksatria/building-observable-nodejs-api.git
cd building-observable-nodejs-api
npm install

2. 设置环境

• 在项目根目录中创建 .env 文件。
• 必需变量：PORT、MONGODB_URI、PRIVATE_KEY、TOKEN_EXPIRED。可选变量：SENTRY_DSN、REDIS_HOST、REDIS_PORT、REDIS_PASSWORD。如果缺少必需变量，应用会在启动时退出。Redis 用于可选缓存（例如，将 GET /api/user 缓存 60s）；如果未设置 Redis，应用将在不使用缓存的情况下运行。
• 为 PRIVATE_KEY 生成 JWT 密钥：
  • Node：node -e "console.log(require('crypto').randomBytes(64).toString('base64'))"
  • OpenSSL：openssl rand -hex 64

3. 运行应用

• 开发环境：npm run dev
• 构建：运行 npm run build，然后运行 npm start

4. API 接口

• 基础路径：/api
• POST /api/user/register — 注册用户（email、full_name、password）
• POST /api/user/login — 登录，返回 JWT
• GET /api/user — 当前用户（请求头：Authorization: Bearer <token>）
• GET / — 健康检查

主要功能

• 技术栈： Express 5、TypeScript、Mongoose、Redis (ioredis)、Sentry、Helmet、CORS。
• 安全性： 防止 NoSQL 注入、拒绝输入中的 HTML、Helmet、CORS。
• 身份验证： JWT + bcrypt；密码在保存时进行哈希处理，且不会在 JSON 中返回。
• 韧性： 按路由进行速率限制、过载检测（toobusy）、结构化 HttpError，并在发生意外错误时回退到 Sentry。
• 结构： src/ 包含 config、controllers、errors、lib、middlewares、models、routes、services、types；入口位于 server.ts，并初始化 Sentry。

---

约定（重要——生成代码时请遵循）

文件命名

• 模型：src/models/<entity>.model.ts
• 控制器：src/controllers/<entity>.controller.ts
• 路由：src/routes/<entity>.route.ts
• 中间件：src/middlewares/<name>.ts
• 服务：src/services/<name>.ts
• 所有文件名均使用 kebab-case。

响应格式

每个 API 响应均遵循以下格式：

成功：

{ "success": true, "data": { ... } }

错误：

{ "success": false, "error": { "error_id": 0, "message": "...", "errors": [] } }

app.ts 中的中间件顺序

顺序很重要。请严格遵循以下顺序：

1. helmet() — 安全响应头
2. cors() — 跨域配置
3. express.json() — 解析 JSON 请求体（带大小限制）
4. express.urlencoded() — 解析 URL 编码的请求体
5. securityMiddleware — NoSQL 注入防护 + HTML 清理
6. toobusy 检查 — 过载检测（HTTP 529）
7. Cache-Control 响应头 — no-store
8. 路由 — app.use("/api", indexRoute)
9. 健康检查 — app.get("/")
10. ErrorHandling — 必须放在最后（全局错误处理器）

错误处理约定

• 已知/预期错误：抛出 new HttpError(errorStates.someError)。这些错误会向客户端返回配置的 HTTP 状态码和消息。
• 添加新的错误状态：在 src/errors/index.ts 的 errorStates 中添加一项，并为其设置唯一的 error_id、message 和 http_code。
• Sentry 报告：意外错误（任何不是 HttpError 的错误）都会自动发送到 Sentry。对于仍需报告的已知错误，请在错误状态中设置 sentry: true。
• Mongoose 验证错误：会自动收集并在 errors 数组中返回。

添加新的环境变量

1. 将键添加到 .env
2. 将其添加到 src/env.ts 的 env 对象中
3. 通过 import env from "../env" 导入，然后使用 env.YOUR_VAR

依赖项

{
  "dependencies": {
    "@sentry/node": "^8.x",
    "bcrypt": "^5.x",
    "cors": "^2.x",
    "dotenv": "^17.x",
    "express": "^5.x",
    "express-rate-limit": "^8.x",
    "helmet": "^8.x",
    "ioredis": "^5.x",
    "jsonwebtoken": "^9.x",
    "mongoose": "^9.x",
    "toobusy-js": "^0.5.x"
  },
  "devDependencies": {
    "@types/bcrypt": "^5.x",
    "@types/cors": "^2.x",
    "@types/express": "^4.x",
    "@types/ioredis": "^4.x",
    "@types/jsonwebtoken": "^9.x",
    "@types/toobusy-js": "^0.5.x",
    "nodemon": "^3.x",
    "ts-node": "^10.x",
    "tsx": "^4.x",
    "typescript": "^5.x"
  }
}

---

如何添加新资源（分步说明）

当用户要求添加新实体（例如“Product”）时，请按顺序执行以下步骤：

步骤 1 — 在 src/types/index.ts 中定义类型

// Product
export interface IProduct {
  name: string;
  price: number;
  description: string;
}

export interface IProductDocument extends IProduct, Document {}

步骤 2 — 创建模型 src/models/product.model.ts

import { Schema, model } from "mongoose";
import { IProductDocument } from "../types";

const productSchema = new Schema<IProductDocument>(
  {
    name: { type: String, required: true },
    price: { type: Number, required: true },
    description: { type: String, required: true },
  },
  { versionKey: false, timestamps: true },
);

export const ProductModel = model<IProductDocument>("Product", productSchema);

步骤 3 — 创建控制器 src/controllers/product.controller.ts

import { Request, Response, NextFunction } from "express";
import { ProductModel } from "../models/product.model";
import HttpError, { errorStates } from "../errors";

class ProductController {
  static async create(req: Request, res: Response, next: NextFunction) {
    try {
      const product = await ProductModel.create(req.body);
      return res.status(201).json({ success: true, data: { product } });
    } catch (error) {
      next(error);
    }
  }

  static async getAll(req: Request, res: Response, next: NextFunction) {
    try {
      const products = await ProductModel.find();
      return res.status(200).json({ success: true, data: { products } });
    } catch (error) {
      next(error);
    }
  }
}

export default ProductController;

步骤 4 — 创建路由 src/routes/product.route.ts

import ProductController from "../controllers/product.controller";
import { Router } from "express";
import { RateLimit } from "../services/rate-limit";
import Authentication from "../middlewares/auth";

const router = Router();

router.post("/", RateLimit({ max: 10, ms: 60000 }), Authentication, ProductController.create);
router.get("/", RateLimit({ max: 20, ms: 60000 }), ProductController.getAll);

export default router;

步骤 5 — 在 src/routes/index.ts 中挂载

import { Router } from "express";
import userRoute from "./user.route";
import productRoute from "./product.route";

const router = Router();
router.use("/user", userRoute);
router.use("/product", productRoute);
export default router;

---

代码示例

以下代码片段摘自此模板中的实际代码。搭建新项目时，请以此为参考模式。

项目结构

src/
├── config/
│   └── mongodb.ts          # MongoDB connection
├── controllers/
│   └── user.controller.ts  # Request handlers
├── errors/
│   └── index.ts            # HttpError, errorStates
├── lib/
│   └── utils.ts            # bcrypt, emailRegex
├── middlewares/
│   ├── auth.ts             # JWT verification
│   ├── error-handling.ts   # Global error + Sentry
│   └── security.ts         # NoSQL/HTML sanitization
├── models/
│   └── user.model.ts       # Mongoose schema
├── routes/
│   ├── index.ts            # Mounts sub-routes
│   └── user.route.ts       # /api/user routes
├── services/
│   ├── jwt.ts              # GenerateToken, VerifyToken
│   ├── rate-limit.ts       # Per-route rate limiter
│   └── redis.ts            # Optional cache (getCache, setCache, deleteCache)
├── types/
│   └── index.ts            # Shared interfaces
├── app.ts                  # Express app + middleware
├── env.ts                  # Load and export env
└── server.ts               # Entry, Sentry.init, listen

环境配置（src/env.ts）

import { config } from "dotenv";
config();

const env = {
  PORT: `${process.env.PORT}`,
  REDIS_HOST: `${process.env.REDIS_HOST}`,
  REDIS_PORT: `${process.env.REDIS_PORT}`,
  SENTRY_DSN: `${process.env.SENTRY_DSN}`,
  TOKEN_EXPIRED: `${process.env.TOKEN_EXPIRED}`,
  PRIVATE_KEY: `${process.env.PRIVATE_KEY}`,
  MONGODB_URI: process.env.MONGODB_URI!,
  REDIS_PASSWORD: `${process.env.REDIS_PASSWORD}`,
};

export default env;

服务入口（src/server.ts）

import * as Sentry from "@sentry/node";
import { server } from "./app";
import toobusy from "toobusy-js";
import env from "./env";
import dbConnect from "./config/mongodb";

if (env.SENTRY_DSN) {
  Sentry.init({ dsn: env.SENTRY_DSN, environment: process.env.NODE_ENV ?? "development" });
}

async function main() {
  await dbConnect();
  server.listen(env.PORT, () => {
    console.log(`Server running on http://localhost:${env.PORT}`);
  });
  process.on("SIGINT", () => { toobusy.shutdown(); process.exit(); });
  process.on("exit", () => toobusy.shutdown());
}

main().catch((err) => { console.error(err); process.exit(1); });

数据库配置（src/config/mongodb.ts）

import mongoose from "mongoose";
import env from "../env";
import * as Sentry from "@sentry/node";

export default async function dbConnect(): Promise<void> {
  try {
    await mongoose.connect(env.MONGODB_URI);
    mongoose.connection.on("error", (err) => {
      Sentry.captureException(err);
      console.error("MongoDB connection error:", err);
    });
    console.log("Connected to MongoDB");
  } catch (error) {
    console.error("Failed to connect to MongoDB:", error);
    Sentry.captureException(error);
    process.exit(1);
  }
}

类型（src/types/index.ts）

import { Document, Types } from "mongoose";
import { Request } from "express";

export type TGenerateToken = { id: Types.ObjectId };

export interface IAuthRequest extends Request {
  decoded?: TGenerateToken;
}

export interface IErrorMessage {
  message: string;
  error_id: number;
  http_code: number;
  sentry?: boolean;
}

export type CreateLimitType = { max: number; ms: number };

export interface IUser {
  email: string;
  full_name: string;
  password: string;
}

export interface IUserModel extends IUser {
  _id: Types.ObjectId;
}

export interface IUserDocument extends IUser, Document {}

模型（src/models/user.model.ts）

import { emailRegex, hashPassword } from "../lib/utils";
import { Schema, model } from "mongoose";
import { IUserDocument } from "../types";

const userSchema = new Schema<IUserDocument>(
  {
    email: {
      type: String,
      required: true,
      unique: true,
      index: true,
      validate: {
        validator: (value: string) => emailRegex.test(value),
        message: "Invalid email address",
      },
    },
    full_name: { type: String, required: true },
    password: { type: String, required: true },
  },
  { versionKey: false, timestamps: true },
);

userSchema.pre("save", async function () {
  if (!this.isModified("password")) return;
  this.password = await hashPassword(this.password);
});

export const UserModel = model<IUserDocument>("User", userSchema);

控制器（src/controllers/user.controller.ts）

import { Request, Response, NextFunction } from "express";
import { UserModel } from "../models/user.model";
import { comparePassword } from "../lib/utils";
import { IAuthRequest, IUserDocument } from "../types";
import HttpError, { errorStates } from "../errors";
import { GenerateToken } from "../services/jwt";
import { getCache, setCache, CACHE_USER } from "../services/redis";

class UserController {
  static async createUser(req: Request, res: Response, next: NextFunction) {
    try {
      const { email, full_name, password } = req.body;
      const user = (await UserModel.create({ email, full_name, password })) as IUserDocument;
      const access_token = GenerateToken({ id: user._id });
      return res.status(201).json({
        success: true,
        data: {
          access_token,
          user: { _id: user._id, full_name: user.full_name, email: user.email },
        },
      });
    } catch (error) {
      next(error);
    }
  }

  static async loginUser(req: Request, res: Response, next: NextFunction) {
    try {
      const { email, password } = req.body;
      const user = (await UserModel.findOne({ email })) as IUserDocument;
      if (!user) throw new HttpError(errorStates.invalidEmailOrPassword);
      const valid = await comparePassword(password, user.password);
      if (!valid) throw new HttpError(errorStates.invalidEmailOrPassword);
      const access_token = GenerateToken({ id: user._id });
      const { password: _p, ...safeUser } = user.toObject();
      return res.status(200).json({ success: true, data: { user: safeUser, access_token } });
    } catch (error) {
      next(error);
    }
  }

  static async getUser(req: IAuthRequest, res: Response, next: NextFunction) {
    try {
      const userId = req?.decoded?.id;
      if (!userId) throw new HttpError(errorStates.failedAuthentication);

      const idStr = String(userId);
      const cacheKey = CACHE_USER(idStr);
      const cached = await getCache(cacheKey);
      if (cached) {
        const user = JSON.parse(cached);
        return res.status(200).json({ success: true, data: { user } });
      }

      const user = await UserModel.findById(userId);
      if (!user) throw new HttpError(errorStates.failedAuthentication);
      const { password: _p, ...safeUser } = user.toObject();
      await setCache(cacheKey, JSON.stringify(safeUser));

      return res.status(200).json({ success: true, data: { user: safeUser } });
    } catch (error) {
      next(error);
    }
  }
}

export default UserController;

路由

挂载（src/routes/index.ts）：

import { Router } from "express";
import userRoute from "./user.route";

const router = Router();
router.use("/user", userRoute);
export default router;

用户路由（src/routes/user.route.ts）：

import UserController from "../controllers/user.controller";
import { Router } from "express";
import { RateLimit } from "../services/rate-limit";
import Authentication from "../middlewares/auth";

const router = Router();

router.post("/register", RateLimit({ max: 10, ms: 60000 }), UserController.createUser);
router.post("/login", RateLimit({ max: 10, ms: 60000 }), UserController.loginUser);
router.get("/", RateLimit({ max: 3, ms: 1000 }), Authentication, UserController.getUser);

export default router;

错误（src/errors/index.ts）

import { IErrorMessage } from "../types";

export const errorStates = {
  internalservererror: { message: "Oops! Something's off-track.", error_id: 0, http_code: 500 },
  highTraffic: { message: "Too many steps at once! Try again soon.", error_id: 1, http_code: 503 },
  rateLimit: { message: "Whoa, slow down! Try again later.", error_id: 2, http_code: 429 },
  failedAuthentication: { message: "Not Authenticated", error_id: 3, http_code: 401 },
  invalidEmailOrPassword: { message: "Invalid email or password", error_id: 4, http_code: 401 },
  tokenExpired: { message: "Session expired—log in again!", error_id: 5, http_code: 401 },
} as const;

class HttpError extends Error {
  statusCode: number;
  error_id: number;
  constructor(args: IErrorMessage) {
    super(args.message);
    this.statusCode = args.http_code;
    this.error_id = args.error_id;
    Object.setPrototypeOf(this, HttpError.prototype);
  }
}

export default HttpError;

中间件 – 安全（src/middlewares/security.ts）

import { NextFunction, Request, Response } from "express";

const dangerousKeyPattern = /^\$|\.|\$/;
const htmlTagPattern = /<[^>]*>/;

const sanitizeObject = <T>(value: T): T => {
  const inner = (val: unknown): unknown => {
    if (Array.isArray(val)) return val.map(inner);
    if (val && typeof val === "object") {
      const obj = val as Record<string, unknown>;
      const sanitized: Record<string, unknown> = {};
      Object.keys(obj).forEach((key) => {
        if (dangerousKeyPattern.test(key)) return;
        sanitized[key] = inner(obj[key]);
      });
      return sanitized;
    }
    if (typeof val === "string") {
      if (htmlTagPattern.test(val)) throw new Error("HTML content is not allowed in input.");
      return val;
    }
    return val;
  };
  return inner(value) as T;
};

export const securityMiddleware = (req: Request, res: Response, next: NextFunction): void => {
  try {
    req.body = sanitizeObject(req.body);

    const sanitizedQuery = sanitizeObject(req.query);
    const sanitizedParams = sanitizeObject(req.params);

    Object.keys(req.query).forEach((key) => delete (req.query as any)[key]);
    Object.assign(req.query as any, sanitizedQuery as any);

    Object.keys(req.params).forEach((key) => delete (req.params as any)[key]);
    Object.assign(req.params as any, sanitizedParams as any);

    next();
  } catch (err) {
    res.status(400).json({ message: (err as Error).message || "Invalid input." });
  }
};

中间件 – 错误处理（src/middlewares/error-handling.ts）

import { Request, Response, NextFunction } from "express";
import * as Sentry from "@sentry/node";
import HttpError, { errorStates } from "../errors";

export const ErrorHandling = (error: unknown, req: Request, res: Response, next: NextFunction): void => {
  if (error instanceof HttpError) {
    const statusCode = error.statusCode ?? errorStates.internalservererror.http_code;
    if ((error as any).sentry) Sentry.captureException(error);
    res.status(statusCode).json({
      success: false,
      error: { error_id: error.error_id, message: error.message, errors: [] },
    });
    return;
  }

  const validationErrors: Array<Record<string, string>> = [];
  if ((error as any)?.errors) {
    Object.entries((error as any).errors).forEach(([key, value]: [string, any]) => {
      validationErrors.push({ [key]: value.message });
    });
  }

  Sentry.captureException(error);

  const fallback = errorStates.internalservererror;
  res.status(fallback.http_code).json({
    success: false,
    error: { error_id: fallback.error_id, message: fallback.message, errors: validationErrors },
  });
};

中间件 – 身份验证（src/middlewares/auth.ts）

import HttpError, { errorStates } from "../errors";
import { VerifyToken } from "../services/jwt";
import { Response, NextFunction } from "express";
import { IAuthRequest } from "../types";

export default function Authentication(req: IAuthRequest, res: Response, next: NextFunction) {
  try {
    const token = req?.headers?.authorization;
    if (!token) throw new HttpError(errorStates.failedAuthentication);
    const decoded = VerifyToken(token.split("Bearer ")[1]);
    req.decoded = decoded;
    next();
  } catch (error: unknown) {
    if ((error as { name?: string })?.name === "TokenExpiredError") {
      return next(new HttpError(errorStates.tokenExpired));
    }
    next(error);
  }
}

服务

速率限制（src/services/rate-limit.ts）：

import rateLimit from "express-rate-limit";
import { errorStates } from "../errors";
import { CreateLimitType } from "../types";

export const RateLimit = ({ max, ms }: CreateLimitType) =>
  rateLimit({
    windowMs: ms,
    max,
    message: { error_id: errorStates.rateLimit.error_id, message: errorStates.rateLimit.message },
  });

JWT（src/services/jwt.ts）：

import jwt from "jsonwebtoken";
import env from "../env";
import { TGenerateToken } from "../types";

export const GenerateToken = (payload: TGenerateToken): string =>
  jwt.sign(payload, env.PRIVATE_KEY, { expiresIn: env.TOKEN_EXPIRED });

export const VerifyToken = (token: string): TGenerateToken =>
  jwt.verify(token, env.PRIVATE_KEY) as TGenerateToken;

Redis（src/services/redis.ts）— 可选：

Redis 用作缓存层。如果未设置 REDIS_HOST，则会跳过缓存，应用无需 Redis 也能运行。

import Redis from "ioredis";
import env from "../env";

export const CACHE_USER = (id: string) => `user:${id}`;
const USER_CACHE_TTL_SEC = 60;

class RedisClient {
  private static instance: Redis | null = null;

  public static getInstance(): Redis | null {
    if (this.instance !== null) return this.instance;
    if (!env.REDIS_HOST || env.REDIS_HOST === "") return null;
    try {
      this.instance = new Redis({
        host: env.REDIS_HOST,
        port: Number(env.REDIS_PORT) || 6379,
        password: env.REDIS_PASSWORD || undefined,
      });
      this.instance.on("error", (err) => console.error("Redis error:", err));
      return this.instance;
    } catch {
      return null;
    }
  }
}

export const setCache = async (key: string, value: string, expirySeconds = 60): Promise<void> => {
  const redis = RedisClient.getInstance();
  if (!redis) return;
  try {
    await redis.set(key, value, "EX", expirySeconds);
  } catch (err) {
    console.error("Redis setCache error:", err);
  }
};

export const getCache = async (key: string): Promise<string | null> => {
  const redis = RedisClient.getInstance();
  if (!redis) return null;
  try {
    return await redis.get(key);
  } catch (err) {
    console.error("Redis getCache error:", err);
    return null;
  }
};

export const deleteCache = async (key: string): Promise<void> => {
  const redis = RedisClient.getInstance();
  if (!redis) return;
  try {
    await redis.del(key);
  } catch (err) {
    console.error("Redis deleteCache error:", err);
  }
};

示例：在 getUser 中使用旁路缓存模式

• 尝试执行 getCache(CACHE_USER(userId))。如果命中，则返回缓存的 JSON。
• 否则，从数据库加载用户，然后执行 setCache(cacheKey, JSON.stringify(safeUser), 60) 并返回。
• 未配置 Redis 时，getCache/setCache 不执行任何操作；应用仍可在没有缓存的情况下运行。

库 – 工具（src/lib/utils.ts）

import bcrypt from "bcrypt";

export const emailRegex = /^\w+([\.-]?\w+)*@\w+([\.-]?\w+)*(\.\w{2,3})+$/;
const SALT_ROUNDS = 10;

export const hashPassword = async (password: string): Promise<string> =>
  bcrypt.hash(password, SALT_ROUNDS);

export const comparePassword = async (password: string, hashed: string): Promise<boolean> =>
  bcrypt.compare(password, hashed);

应用（src/app.ts）

import express, { Express, NextFunction, Request, Response } from "express";
import cors from "cors";
import http from "http";
import toobusy from "toobusy-js";
import helmet from "helmet";
import { securityMiddleware } from "./middlewares/security";
import indexRoute from "./routes";
import { ErrorHandling } from "./middlewares/error-handling";

toobusy.maxLag(120);

const app: Express = express();
const server = http.createServer(app);

app.use(helmet());
app.use(cors({
  origin: ["http://localhost:3005", "http://localhost:3000"],
  methods: ["GET", "POST", "PUT", "DELETE"],
  allowedHeaders: ["Content-Type", "Authorization"],
}));
app.use(express.json({ limit: "100kb" }));
app.use(express.urlencoded({ extended: false }));
app.use(securityMiddleware);

app.use((req, res, next) => {
  if (toobusy()) return res.status(529).json({ message: "High Traffic" });
  else next();
});

app.use((req, res, next) => {
  res.setHeader("Cache-Control", "no-store");
  next();
});

app.use("/api", indexRoute);

app.get("/", (req: Request, res: Response, next: NextFunction) => {
  res.send("Our Backend Running Correctly");
});

app.use(ErrorHandling);

export { app, server };

---

仓库和文档

• GitHub： https://github.com/laskar-ksatria/building-observable-nodejs-api
• 完整的设置说明、环境变量表和 API 概览，请参阅仓库 README。

验证/完成检查清单

协助用户运行或扩展此模板时，请确认：

• .env 文件存在，且至少包含 PORT、MONGODB_URI、PRIVATE_KEY、TOKEN_EXPIRED。
• MongoDB 可连接（如果使用 Redis，也需确认 Redis 可连接）。
• 如果需要错误监控，则已设置 SENTRY_DSN。
• 执行 npm run dev 后，GET / 会返回成功消息。
• 身份验证路由（/api/user/register、/api/user/login、GET /api/user）响应正常。
• 新资源遵循约定：类型 -> 模型 -> 控制器 -> 路由 -> 在 index 中挂载。