backend-dev-guidelines

Node.js/Express/TypeScript微服务综合后端开发指南。当您需要创建路由、控制器、服务、存储库、中间件，或在Express API、Drizzle ORM数据库访问、PostgreSQL/RDS、AWS Lambda处理器、SQS消费者、S3操作、Sentry错误追踪、Zod验证、unifiedConfig、依赖注入，或异步模式下开展工作时，可使用此指南。指南涵盖分层架构（路由→控制器→服务→存储库）、BaseController模式、错误处理、性能监控，以及通过Playwright进行测试策略的制定。

SKILL.md

--- frontmatter

name: backend-dev-guidelines
description: Comprehensive backend development guide for Node.js/Express/TypeScript microservices. Use when creating routes, controllers, services, repositories, middleware, or working with Express APIs, Drizzle ORM database access, PostgreSQL/RDS, AWS Lambda handlers, SQS consumers, S3 operations, Sentry error tracking, Zod validation, unifiedConfig, dependency injection, or async patterns. Covers layered architecture (routes → controllers → services → repositories), BaseController pattern, error handling, performance monitoring, testing strategies with Playwright.

Backend Development Guidelines

Purpose

Establish consistency and best practices across backend services using modern Node.js/Express/TypeScript patterns with AWS infrastructure (Lambda, SQS, S3, RDS).

When to Use This Skill

Automatically activates when working on:

•Creating or modifying routes, endpoints, APIs
•Building controllers, services, repositories
•Implementing middleware (auth, validation, error handling)
•Database operations with Drizzle ORM (PostgreSQL/RDS)
•AWS Lambda handlers
•SQS message consumers
•S3 file operations
•Error tracking with Sentry
•Input validation with Zod
•Configuration management
•Backend testing with Playwright

Quick Start

New Backend Feature Checklist

• Route: Clean definition, delegate to controller
• Controller: Extend BaseController
• Service: Business logic with DI
• Repository: Database access (if complex)
• Validation: Zod schema
• Sentry: Error tracking
• Tests: Unit + integration tests
• Config: Use unifiedConfig

New Microservice Checklist

Architecture Overview

Layered Architecture

code

HTTP Request / Lambda Event / SQS Message
    ↓
Routes/Handlers (routing only)
    ↓
Controllers (request handling)
    ↓
Services (business logic)
    ↓
Repositories (data access)
    ↓
Database (Drizzle ORM → PostgreSQL/RDS)

Key Principle: Each layer has ONE responsibility.

See architecture-overview.md for complete details.

Directory Structure

code

service/src/
├── config/              # UnifiedConfig
├── controllers/         # Request handlers
├── services/            # Business logic
├── repositories/        # Data access
├── routes/              # Route definitions
├── handlers/            # Lambda handlers
├── consumers/           # SQS consumers
├── middleware/          # Express middleware
├── db/                  # Drizzle schema & migrations
│   ├── schema.ts        # Drizzle table definitions
│   ├── index.ts         # DB connection
│   └── migrations/      # SQL migrations
├── types/               # TypeScript types
├── validators/          # Zod schemas
├── utils/               # Utilities
├── tests/               # Playwright tests
├── instrument.ts        # Sentry (FIRST IMPORT)
├── app.ts               # Express setup
└── server.ts            # HTTP server

Naming Conventions:

•Controllers: PascalCase - UserController.ts
•Services: camelCase - userService.ts
•Routes: camelCase + Routes - userRoutes.ts
•Repositories: PascalCase + Repository - UserRepository.ts

Core Principles (7 Key Rules)

1. Routes Only Route, Controllers Control

typescript

// ❌ NEVER: Business logic in routes
router.post('/submit', async (req, res) => {
    // 200 lines of logic
});

// ✅ ALWAYS: Delegate to controller
router.post('/submit', (req, res) => controller.submit(req, res));

2. All Controllers Extend BaseController

typescript

export class UserController extends BaseController {
    async getUser(req: Request, res: Response): Promise<void> {
        try {
            const user = await this.userService.findById(req.params.id);
            this.handleSuccess(res, user);
        } catch (error) {
            this.handleError(error, res, 'getUser');
        }
    }
}

3. All Errors to Sentry

typescript

try {
    await operation();
} catch (error) {
    Sentry.captureException(error);
    throw error;
}

4. Use unifiedConfig, NEVER process.env

typescript

// ❌ NEVER
const timeout = process.env.TIMEOUT_MS;

// ✅ ALWAYS
import { config } from './config/unifiedConfig';
const timeout = config.timeouts.default;

5. Validate All Input with Zod

typescript

const schema = z.object({ email: z.string().email() });
const validated = schema.parse(req.body);

6. Use Repository Pattern with Drizzle ORM

typescript

// Service → Repository → Database (Drizzle)
import { db } from '@/db';
import { users } from '@/db/schema';
import { eq } from 'drizzle-orm';

const activeUsers = await db.select().from(users).where(eq(users.active, true));

7. Comprehensive Testing Required

typescript

describe('UserService', () => {
    it('should create user', async () => {
        expect(user).toBeDefined();
    });
});

Common Imports

typescript

// Express
import express, { Request, Response, NextFunction, Router } from 'express';

// Validation
import { z } from 'zod';

// Database (Drizzle ORM)
import { drizzle } from 'drizzle-orm/node-postgres';
import { eq, and, or, desc, asc } from 'drizzle-orm';
import * as schema from './db/schema';

// AWS SDK v3
import { S3Client, GetObjectCommand, PutObjectCommand } from '@aws-sdk/client-s3';
import { SQSClient, SendMessageCommand } from '@aws-sdk/client-sqs';
import type { APIGatewayProxyHandler, SQSHandler } from 'aws-lambda';

// Sentry
import * as Sentry from '@sentry/node';

// Config
import { config } from './config/unifiedConfig';

// Middleware
import { SSOMiddlewareClient } from './middleware/SSOMiddleware';
import { asyncErrorWrapper } from './middleware/errorBoundary';

Quick Reference

HTTP Status Codes

Code	Use Case
200	Success
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	Server Error

Service Templates

Blog API (✅ Mature) - Use as template for REST APIs Auth Service (✅ Mature) - Use as template for authentication patterns

Anti-Patterns to Avoid

❌ Business logic in routes/handlers ❌ Direct process.env usage ❌ Missing error handling ❌ No input validation ❌ Raw SQL queries (use Drizzle) ❌ console.log instead of Sentry ❌ Synchronous S3/SQS operations without error handling

Navigation Guide

Need to...	Read this
Understand architecture	architecture-overview.md
Create routes/controllers	routing-and-controllers.md
Organize business logic	services-and-repositories.md
Validate input	validation-patterns.md
Add error tracking	sentry-and-monitoring.md
Create middleware	middleware-guide.md
Database access	database-patterns.md
Manage config	configuration.md
Handle async/errors	async-and-errors.md
Write tests	testing-guide.md
See examples	complete-examples.md

Related Skills

•database-verification - Verify column names and schema consistency
•error-tracking - Sentry integration patterns
•skill-developer - Meta-skill for creating and managing skills

Skill Status: COMPLETE ✅ Line Count: < 500 ✅ Progressive Disclosure: 11 resource files ✅

Backend Development Guidelines

Purpose

When to Use This Skill

Quick Start

New Backend Feature Checklist

New Microservice Checklist

Architecture Overview

Layered Architecture

Directory Structure

Core Principles (7 Key Rules)

1. Routes Only Route, Controllers Control

2. All Controllers Extend BaseController

3. All Errors to Sentry

4. Use unifiedConfig, NEVER process.env

5. Validate All Input with Zod

6. Use Repository Pattern with Drizzle ORM

7. Comprehensive Testing Required

Common Imports

Quick Reference

HTTP Status Codes

Service Templates

Anti-Patterns to Avoid

Navigation Guide

Resource Files

Related Skills