backend-dev-guidelines by davila7/claude-code-templates
npx skills add https://github.com/davila7/claude-code-templates --skill backend-dev-guidelines在使用现代 Node.js/Express/TypeScript 模式的后端微服务(blog-api、auth-service、notifications-service)中建立一致性和最佳实践。
在以下场景中自动激活:
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
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.tscamelCase - userService.tscamelCase + Routes - userRoutes.tsPascalCase + Repository - UserRepository.ts// ❌ 禁止:在路由中编写业务逻辑
router.post('/submit', async (req, res) => {
// 200 行逻辑代码
});
// ✅ 始终:委托给控制器
router.post('/submit', (req, res) => controller.submit(req, res));
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');
}
}
}
try {
await operation();
} catch (error) {
Sentry.captureException(error);
throw error;
}
// ❌ 禁止
const timeout = process.env.TIMEOUT_MS;
// ✅ 始终
import { config } from './config/unifiedConfig';
const timeout = config.timeouts.default;
const schema = z.object({ email: z.string().email() });
const validated = schema.parse(req.body);
// 服务 → 仓库 → 数据库
const users = await userRepository.findActive();
describe('UserService', () => {
it('should create user', 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';
| 代码 | 使用场景 |
|---|---|
| 200 | 成功 |
| 201 | 已创建 |
| 400 | 错误请求 |
| 401 | 未授权 |
| 403 | 禁止访问 |
| 404 | 未找到 |
| 500 | 服务器错误 |
博客 API (✅ 成熟) - 用作 REST API 的模板
认证服务 (✅ 成熟) - 用作认证模式的模板
❌ 在路由中编写业务逻辑
❌ 直接使用 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 |
分层架构、请求生命周期、关注点分离
路由定义、BaseController、错误处理、示例
服务模式、依赖注入、仓库模式、缓存
Zod 模式、验证、DTO 模式
Sentry 初始化、错误捕获、性能监控
认证、审计、错误边界、AsyncLocalStorage
PrismaService、仓库、事务、优化
UnifiedConfig、环境配置、密钥
异步模式、自定义错误、asyncErrorWrapper
单元/集成测试、模拟、覆盖率
完整示例、重构指南
技能状态:已完成 ✅
代码行数:< 500 ✅
渐进式披露:11 个资源文件 ✅
每周安装数
229
仓库
GitHub 星标数
22.6K
首次出现
Jan 25, 2026
安全审计
安装于
opencode196
gemini-cli185
codex180
github-copilot173
claude-code164
cursor154
Establish consistency and best practices across backend microservices (blog-api, auth-service, notifications-service) using modern Node.js/Express/TypeScript patterns.
Automatically activates when working on:
HTTP Request
↓
Routes (routing only)
↓
Controllers (request handling)
↓
Services (business logic)
↓
Repositories (data access)
↓
Database (Prisma)
Key Principle: Each layer has ONE responsibility.
See architecture-overview.md for complete details.
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
Naming Conventions:
PascalCase - UserController.tscamelCase - userService.tscamelCase + Routes - userRoutes.tsPascalCase + Repository - UserRepository.ts// ❌ 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));
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');
}
}
}
try {
await operation();
} catch (error) {
Sentry.captureException(error);
throw error;
}
// ❌ NEVER
const timeout = process.env.TIMEOUT_MS;
// ✅ ALWAYS
import { config } from './config/unifiedConfig';
const timeout = config.timeouts.default;
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';
| Code | Use Case |
|---|---|
| 200 | Success |
| 201 | Created |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 500 | Server Error |
Blog API (✅ Mature) - Use as template for REST APIs Auth Service (✅ Mature) - Use as template for authentication patterns
❌ Business logic in routes ❌ Direct process.env usage ❌ Missing error handling ❌ No input validation ❌ Direct Prisma everywhere ❌ console.log instead of Sentry
| 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 |
Layered architecture, request lifecycle, separation of concerns
Route definitions, BaseController, error handling, examples
Service patterns, DI, repository pattern, caching
Zod schemas, validation, DTO pattern
Sentry init, error capture, performance monitoring
Auth, audit, error boundaries, AsyncLocalStorage
PrismaService, repositories, transactions, optimization
UnifiedConfig, environment configs, secrets
Async patterns, custom errors, asyncErrorWrapper
Unit/integration tests, mocking, coverage
Full examples, refactoring guide
Skill Status : COMPLETE ✅ Line Count : < 500 ✅ Progressive Disclosure : 11 resource files ✅
Weekly Installs
229
Repository
GitHub Stars
22.6K
First Seen
Jan 25, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
opencode196
gemini-cli185
codex180
github-copilot173
claude-code164
cursor154
OWASP 十大安全风险防范指南:Web应用安全漏洞与代码示例
824 周安装
| database-patterns.md |
| Manage config | configuration.md |
| Handle async/errors | async-and-errors.md |
| Write tests | testing-guide.md |
| See examples | complete-examples.md |