backend-dev-guidelines

用途

本技能用于在 Node.js/Express/TypeScript 微服务（如 blog-api、auth-service、notifications-service）中建立一致的开发规范与最佳实践。当进行以下工作时会自动激活：创建或修改路由、端点、API；构建控制器、服务、仓储；实现中间件（认证、校验、错误处理）；使用 Prisma 进行数据库操作；使用 Sentry 进行错误追踪；使用 Zod 进行输入校验；配置管理；后端测试与重构。

架构与目录结构

采用分层架构，请求自上而下流经各层：

HTTP Request
    ↓
Routes (routing only)
    ↓
Controllers (request handling)
    ↓
Services (business logic)
    ↓
Repositories (data access)
    ↓
Database (Prisma)

关键原则：每一层只承担一项职责。

目录结构示例：

service/src/
├── config/              # UnifiedConfig
├── controllers/         # Request handlers
├── services/            # Business logic
├── repositories/        # Data access
├── routes/              # Route definitions
├── middleware/          # Express middleware
├── types/               # TypeScript types
├── validators/          # Zod schemas
├── utils/               # Utilities
├── tests/               # Tests
├── instrument.ts        # Sentry (FIRST IMPORT)
├── app.ts               # Express setup
└── server.ts            # HTTP server

命名约定：控制器用 PascalCase（UserController.ts）；服务用 camelCase（userService.ts）；路由用 camelCase + Routes（userRoutes.ts）；仓储用 PascalCase + Repository（UserRepository.ts）。

核心原则（7 条关键规则）

路由只负责路由，控制器负责控制。禁止在路由中写业务逻辑，应委托给控制器：

// ❌ 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));

所有控制器继承 BaseController：

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');
        }
    }
}

所有错误上报 Sentry：

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

使用 unifiedConfig，绝不使用 process.env：

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

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

用 Zod 校验所有输入：

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

数据访问使用仓储模式（Service → Repository → Database）：

const users = await userRepository.findActive();

要求完整测试：

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

常用导入

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

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

// Database
import { PrismaClient } from '@prisma/client';
import type { Prisma } from '@prisma/client';

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

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

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

快速参考

HTTP 状态码：200 成功；201 已创建；400 错误请求；401 未授权；403 禁止；404 未找到；500 服务器错误。

服务模板：Blog API（成熟）可作为 REST API 模板；Auth Service（成熟）可作为认证模式模板。

应避免的反模式：路由中写业务逻辑；直接使用 process.env；缺少错误处理；无输入校验；到处直接使用 Prisma；用 console.log 代替 Sentry。

新功能与新微服务检查清单

新后端功能：路由（定义清晰，委托给控制器）；控制器（继承 BaseController）；服务（含依赖注入的业务逻辑）；仓储（复杂时使用）；校验（Zod schema）；Sentry（错误追踪）；测试（单元 + 集成）；配置（使用 unifiedConfig）。

新微服务：目录结构（见 architecture-overview.md）；Sentry 的 instrument.ts；unifiedConfig 设置；BaseController 类；中间件栈；错误边界；测试框架。

导航与资源文件

需要理解架构读 architecture-overview.md；创建路由/控制器读 routing-and-controllers.md；组织业务逻辑读 services-and-repositories.md；校验输入读 validation-patterns.md；添加错误追踪读 sentry-and-monitoring.md；创建中间件读 middleware-guide.md；数据库访问读 database-patterns.md；管理配置读 configuration.md；处理异步/错误读 async-and-errors.md；编写测试读 testing-guide.md；查看示例读 complete-examples.md。

资源文件涵盖：分层架构、请求生命周期、关注点分离；路由定义、BaseController、错误处理；服务模式、依赖注入、仓储模式、缓存；Zod schema、校验、DTO 模式；Sentry 初始化、错误捕获、性能监控；认证、审计、错误边界、AsyncLocalStorage；PrismaService、仓储、事务、优化；UnifiedConfig、环境配置、密钥；异步模式、自定义错误、asyncErrorWrapper；单元/集成测试、mock、覆盖率；完整示例与重构指南。

技能介绍

用途