backend-dev-guidelines

Backend Development Guidelines - Node.js Backend Standards

Skills Overview

Provides enterprise-grade backend development standards for Node.js + Express + TypeScript microservices, including layered architecture design, BaseController pattern, dependency injection, Prisma repositories, Zod validation, Sentry error tracking, and other production-grade best practices.

Applicable Scenarios

1. Production-grade Node.js Microservice Development

When you need to build backend services that handle real-world traffic in production, these standards ensure code predictability, observability, and maintainability. By enforcing a layered architecture and strict error handling, common architectural debt and maintenance pitfalls are avoided.

2. Unifying Team Backend Development Standards

Suitable for backend teams collaborating with multiple members. By unifying directory structure, naming conventions, and development patterns, code review costs are reduced, new members ramp up quickly, and all services adhere to the same quality standards.

3. TypeScript + Express Tech Stack Projects

Designed specifically for projects using TypeScript and the Express framework, making full use of strong typing and object-oriented features, combined with ecosystem tools like Prisma ORM and Zod validation to build a type-safe backend system.

Core Features

1. Enforced Layered Architecture

Strictly define the data flow Routes → Controllers → Services → Repositories → Database, prohibiting cross-layer calls and leakage between layers. The routing layer only handles route dispatching, controllers coordinate, services process business logic, and repositories encapsulate data access. Architectural constraints ensure single responsibility, easy testing, and maintainability.

2. Backend Feasibility & Risk Index (BFRI) Evaluation System

Before implementing any backend feature, evaluate feasibility across five dimensions (architectural fit, business complexity, data risk, operational risk, testability), compute a risk index, and guide decision-making. BFRI ≥ 6 can be implemented directly, 3-5 requires additional testing and monitoring, and below 0 must be redesigned.

3. Production-grade Observability and Error Handling

Require all errors to be tracked via Sentry; prohibit using console.log or silent failures. Use BaseController to centralize error handling and response formats, combined with unifiedConfig for centralized configuration management, ensuring all critical paths in production are observable and monitorable.

Frequently Asked Questions

What is BFRI? How to use the Backend Feasibility & Risk Index?

BFRI (Backend Feasibility & Risk Index) is a framework for quantitatively assessing the implementation risk of backend features. Score each of five dimensions—architectural fit, business complexity, data risk, operational risk, and testability—on a 1-5 scale, and calculate the score using the formula: (Architectural fit + Testability) − (Complexity + Data Risk + Operational Risk). Scores 6–10 can be implemented directly, 3–5 require additional testing and monitoring, 0–2 need refactoring or isolation, and below 0 must be redesigned.

Why can't the routing layer contain business logic?

The sole responsibility of the routing layer is to dispatch HTTP requests to the appropriate controller; any business logic should be implemented in the service layer. Benefits of this design include easier unit testing (controllers and services can be tested independently), reduced code duplication, support for multi-protocol reuse (the same service can be invoked by HTTP and WebSocket), and lower maintenance costs. Including business logic in routes is an explicitly prohibited anti-pattern in these standards.

What are the advantages of unifiedConfig centralized configuration management compared to using process.env directly?

unifiedConfig is the project's single source of configuration. Compared to directly using process.env, it offers: type safety (TypeScript type definitions), centralized management (all configuration maintained in one place), environment separation (development/test/production configurations isolated), default value handling, and configuration validation. Direct use of process.env can lead to typos, inconsistent types, and scattered configuration—an explicitly prohibited anti-pattern in these standards.