backend-dev-guidelines by claudiodearaujo/izacenter
npx skills add https://github.com/claudiodearaujo/izacenter --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 个资源文件 ✅
每周安装次数
1
代码仓库
GitHub 星标数
1
首次出现
今天
安全审计
安装于
zencoder1
amp1
cline1
openclaw1
opencode1
cursor1
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 | database-patterns.md |
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
1
Repository
GitHub Stars
1
First Seen
Today
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
zencoder1
amp1
cline1
openclaw1
opencode1
cursor1
Android 整洁架构指南:模块化设计、依赖注入与数据层实现
1,100 周安装
SQL性能优化助手 - 专业SQL查询调优与索引策略优化工具
8,600 周安装
Vue Router 最佳实践指南:导航守卫、路由生命周期与常见陷阱解决方案
9,200 周安装
后台代理状态通知 - 避免轮询浪费,高效处理AI代理进度更新
205 周安装
网站设计审查工具 - 自动检测并修复HTML/CSS/JS、React、Vue等框架的视觉与布局问题
8,900 周安装
.NET/C# 最佳实践指南:代码规范、设计模式、依赖注入与AI集成
8,900 周安装
Playwright MCP 测试生成工具 - 自动生成 TypeScript 端到端测试代码
9,000 周安装
| Manage config | configuration.md |
| Handle async/errors | async-and-errors.md |
| Write tests | testing-guide.md |
| See examples | complete-examples.md |