backend-dev-guidelines

后端开发指南

目的

使用现代 Node.js/Express/TypeScript 模式，在各项后端服务中建立一致性并践行最佳实践。

本指南适用于使用 Prisma 和 Sentry 的 Node.js/Express/TypeScript 项目。技术栈不同？请调整架构原则，参见仓库根目录中的 CLAUDE_INTEGRATION_GUIDE.md。

何时使用此技能

在以下场景中自动启用：

• 创建或修改路由、端点、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 状态码

Code	用途
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 模式、验证、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 - 验证列名和架构一致性
• error-tracking - Sentry 集成模式
• skill-developer - 用于创建和管理技能的元技能

---

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