name: 后端开发指南 description: 针对Node.js/Express/TypeScript微服务的全面后端开发指南。适用于创建路由、控制器、服务、仓库、中间件，或使用Express APIs、Prisma数据库访问、Sentry错误跟踪、Zod验证、unifiedConfig、依赖注入或异步模式时使用。涵盖分层架构（路由→控制器→服务→仓库）、BaseController模式、错误处理、性能监控、测试策略以及从旧模式迁移。

后端开发指南

目的

在现代Node.js/Express/TypeScript模式下，为后端微服务（如blog-api、auth-service、notifications-service）建立一致性和最佳实践。

何时使用此技能

自动激活时：

创建或修改路由、端点、APIs
构建控制器、服务、仓库
实现中间件（认证、验证、错误处理）
使用Prisma进行数据库操作
使用Sentry进行错误跟踪
使用Zod进行输入验证
配置管理
后端测试和重构

快速入门

新后端功能检查清单

[ ] 路由：清晰定义，委托给控制器
[ ] 控制器：扩展BaseController
[ ] 服务：使用依赖注入的业务逻辑
[ ] 仓库：数据库访问（如果复杂）
[ ] 验证：Zod模式
[ ] Sentry：错误跟踪
[ ] 测试：单元 + 集成测试
[ ] 配置：使用unifiedConfig

新微服务检查清单

[ ] 目录结构（参见architecture-overview.md）
[ ] instrument.ts用于Sentry
[ ] unifiedConfig设置
[ ] BaseController类
[ ] 中间件栈
[ ] 错误边界
[ ] 测试框架

架构概述

分层架构

HTTP请求
    ↓
路由（仅路由）
    ↓
控制器（请求处理）
    ↓
服务（业务逻辑）
    ↓
仓库（数据访问）
    ↓
数据库（Prisma）

关键原则：每一层有一个职责。

参见architecture-overview.md获取完整细节。

目录结构

service/src/
├── config/              # UnifiedConfig
├── controllers/         # 请求处理器
├── services/            # 业务逻辑
├── repositories/        # 数据访问
├── routes/              # 路由定义
├── middleware/          # Express中间件
├── types/               # TypeScript类型
├── validators/          # Zod模式
├── utils/               # 工具
├── tests/               # 测试
├── instrument.ts        # Sentry（首先导入）
├── app.ts               # Express设置
└── server.ts            # HTTP服务器

命名约定：

控制器：PascalCase - UserController.ts
服务：camelCase - userService.ts
路由：camelCase + Routes - userRoutes.ts
仓库：PascalCase + Repository - UserRepository.ts

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

1. 路由仅路由，控制器控制

// ❌ 永远不要：在路由中放业务逻辑
router.post('/submit', async (req, res) => {
    // 200行逻辑
});

// ✅ 总是：委托给控制器
router.post('/submit', (req, res) => controller.submit(req, res));

2. 所有控制器扩展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');
        }
    }
}

3. 所有错误发送到Sentry

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

4. 使用unifiedConfig，永不使用process.env

// ❌ 永远不要
const timeout = process.env.TIMEOUT_MS;

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

5. 使用Zod验证所有输入

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

6. 使用仓库模式进行数据访问

// 服务 → 仓库 → 数据库
const users = await userRepository.findActive();

7. 需要全面测试

describe('UserService', () => {
    it('应该创建用户', async () => {
        expect(user).toBeDefined();
    });
});

常见导入

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

// 验证
import { z } from 'zod';

// 数据库
import { PrismaClient } from '@prisma/client';
import type { Prisma } from '@prisma/client';

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

// 配置
import { config } from './config/unifiedConfig';

// 中间件
import { SSOMiddlewareClient } from './middleware/SSOMiddleware';
import { asyncErrorWrapper } from './middleware/errorBoundary';

快速参考

HTTP状态码

代码	使用案例
200	成功
201	已创建
400	错误请求
401	未认证
403	禁止访问
404	未找到
500	服务器错误

服务模板

博客API（✅ 成熟） - 作为REST APIs的模板 认证服务（✅ 成熟） - 作为认证模式的模板

要避免的反模式

❌ 在路由中放业务逻辑 ❌ 直接使用process.env ❌ 缺少错误处理 ❌ 没有输入验证 ❌ 到处直接使用Prisma ❌ 使用console.log而不是Sentry

导航指南

需要…	阅读这个
理解架构	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