backend-dev-guidelines

后端开发准则

目的

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

何时使用本技能

在以下场景中工作时自动激活：

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

---

快速开始

新后端功能检查清单

• 路由：定义清晰，委托给控制器
• 控制器：继承 BaseController
• 服务：使用 DI 的业务逻辑
• 仓库：数据库访问（如果复杂）
• 校验：Zod schema
• Sentry：错误跟踪
• 测试：单元测试 + 集成测试
• 配置：使用 unifiedConfig

新微服务检查清单

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

---

架构概览

分层架构

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

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

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

---

目录结构

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 条关键规则）

1. 路由只负责路由，控制器负责控制

// ❌ 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. 所有控制器都继承 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

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

// ✅ ALWAYS
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. 使用仓库模式进行数据访问

// Service → Repository → Database
const users = await userRepository.findActive();

7. 必须进行全面测试

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

---

导航指南

需要...	阅读此文档
理解架构	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

---

资源文件

architecture-overview.md

分层架构、请求生命周期、关注点分离

routing-and-controllers.md

路由定义、BaseController、错误处理、示例

services-and-repositories.md

服务模式、DI、仓库模式、缓存

validation-patterns.md

Zod schema、验证、DTO 模式

sentry-and-monitoring.md

Sentry 初始化、错误捕获、性能监控

middleware-guide.md

认证、审计、错误边界、AsyncLocalStorage

database-patterns.md

PrismaService、仓库、事务、优化

configuration.md

UnifiedConfig、环境配置、密钥

async-and-errors.md

异步模式、自定义错误、asyncErrorWrapper

testing-guide.md

单元/集成测试、模拟、覆盖率

complete-examples.md

完整示例、重构指南

---

相关技能

• database-verification - 验证列名和 schema 一致性
• error-tracking - Sentry 集成模式
• skill-developer - 用于创建和管理技能的元技能

---

技能状态：COMPLETE ✅ 行数：< 500 ✅ 渐进式披露：11 个资源文件 ✅