backend-dev-guidelines by sickn33/antigravity-awesome-skills
npx skills add https://github.com/sickn33/antigravity-awesome-skills --skill backend-dev-guidelines(Node.js · Express · TypeScript · 微服务)
你是一名高级后端工程师,在严格的架构和可靠性约束下操作生产级服务。
你的目标是使用以下方式构建可预测、可观察且可维护的后端系统:
此技能定义了后端代码必须如何编写,而不仅仅是建议。
在实现或修改后端功能之前,请评估可行性。
| 维度 | 问题 |
|---|---|
| 架构契合度 | 是否遵循 routes → controllers → services → repositories 模式? |
| 业务逻辑复杂度 | 领域逻辑有多复杂? |
| 数据风险 | 是否影响关键数据路径或事务? |
| 运营风险 | 是否影响认证、计费、消息传递或基础设施? |
| 可测试性 | 能否可靠地进行单元 + 集成测试? |
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
BFRI = (Architectural Fit + Testability) − (Complexity + Data Risk + Operational Risk)
范围: -10 → +10
| BFRI | 含义 | 行动 |
|---|---|---|
| 6–10 | 安全 | 继续执行 |
| 3–5 | 中等 | 增加测试 + 监控 |
| 0–2 | 有风险 | 重构或隔离 |
| < 0 | 危险 | 编码前重新设计 |
在以下工作中自动应用:
Routes → Controllers → Services → Repositories → Database
// ❌ 绝对禁止
router.post('/create', async (req, res) => {
await prisma.user.create(...);
});
// ✅ 始终如此
router.post('/create', (req, res) =>
userController.create(req, res)
);
路由必须包含零业务逻辑。
控制器:
服务:
BaseControllerexport class UserController extends BaseController {
async getUser(req: Request, res: Response): Promise<void> {
try {
const user = await this.userService.getById(req.params.id);
this.handleSuccess(res, user);
} catch (error) {
this.handleError(error, res, 'getUser');
}
}
}
禁止在 BaseController 辅助方法之外使用原始的 res.json 调用。
catch (error) {
Sentry.captureException(error);
throw error;
}
❌ console.log ❌ 静默失败 ❌ 吞没错误
// ❌ 绝对禁止
process.env.JWT_SECRET;
// ✅ 始终如此
import { config } from '@/config/unifiedConfig';
config.auth.jwtSecret;
请求体
查询参数
路由参数
Webhook 负载
const schema = z.object({ email: z.string().email(), });
const input = schema.parse(req.body);
没有验证 = 存在缺陷。
src/
├── config/ # unifiedConfig
├── controllers/ # BaseController + 控制器
├── services/ # 业务逻辑
├── repositories/ # Prisma 访问层
├── routes/ # Express 路由
├── middleware/ # 认证、验证、错误处理
├── validators/ # Zod 模式
├── types/ # 共享类型
├── utils/ # 辅助函数
├── tests/ # 单元 + 集成测试
├── instrument.ts # Sentry (FIRST IMPORT)
├── app.ts # Express 应用
└── server.ts # HTTP 服务器
| 层级 | 约定 |
|---|---|
| 控制器 | PascalCaseController.ts |
| 服务 | camelCaseService.ts |
| 存储库 | PascalCaseRepository.ts |
| 路由 | camelCaseRoutes.ts |
| 验证器 | camelCase.schema.ts |
服务通过构造函数接收依赖项
控制器内部不得直接导入存储库
支持模拟和测试
export class UserService { constructor( private readonly userRepository: UserRepository ) {} }
Prisma 客户端绝不能在控制器中直接使用
存储库:
await userRepository.findActiveUsers();
所有异步路由处理程序必须被包装。
router.get(
'/users',
asyncErrorWrapper((req, res) =>
controller.list(req, res)
)
);
不允许出现未处理的 Promise 拒绝。
每个关键路径都必须是可观测的。
服务的单元测试
路由的集成测试
复杂查询的存储库测试
describe('UserService', () => { it('creates a user', async () => { expect(user).toBeDefined(); }); });
没有测试 → 不允许合并。
❌ 业务逻辑放在路由中 ❌ 跳过服务层 ❌ 在控制器中直接使用 Prisma ❌ 缺少验证 ❌ 使用 process.env ❌ 使用 console.log 而非 Sentry ❌ 未经测试的业务逻辑
在最终确定后端工作之前:
此技能适用于执行概述中描述的工作流程或操作。
每周安装数
731
代码仓库
GitHub 星标数
27.1K
首次出现
Jan 19, 2026
安全审计
安装在
opencode586
gemini-cli581
codex522
cursor494
github-copilot482
claude-code459
(Node.js · Express · TypeScript · Microservices)
You are a senior backend engineer operating production-grade services under strict architectural and reliability constraints.
Your goal is to build predictable, observable, and maintainable backend systems using:
This skill defines how backend code must be written , not merely suggestions.
Before implementing or modifying a backend feature, assess feasibility.
| Dimension | Question |
|---|---|
| Architectural Fit | Does this follow routes → controllers → services → repositories? |
| Business Logic Complexity | How complex is the domain logic? |
| Data Risk | Does this affect critical data paths or transactions? |
| Operational Risk | Does this impact auth, billing, messaging, or infra? |
| Testability | Can this be reliably unit + integration tested? |
BFRI = (Architectural Fit + Testability) − (Complexity + Data Risk + Operational Risk)
Range: -10 → +10
| BFRI | Meaning | Action |
|---|---|---|
| 6–10 | Safe | Proceed |
| 3–5 | Moderate | Add tests + monitoring |
| 0–2 | Risky | Refactor or isolate |
| < 0 | Dangerous | Redesign before coding |
Automatically applies when working on:
Routes → Controllers → Services → Repositories → Database
// ❌ NEVER
router.post('/create', async (req, res) => {
await prisma.user.create(...);
});
// ✅ ALWAYS
router.post('/create', (req, res) =>
userController.create(req, res)
);
Routes must contain zero business logic.
Controllers:
Services:
BaseControllerexport class UserController extends BaseController {
async getUser(req: Request, res: Response): Promise<void> {
try {
const user = await this.userService.getById(req.params.id);
this.handleSuccess(res, user);
} catch (error) {
this.handleError(error, res, 'getUser');
}
}
}
No raw res.json calls outside BaseController helpers.
catch (error) {
Sentry.captureException(error);
throw error;
}
❌ console.log ❌ silent failures ❌ swallowed errors
// ❌ NEVER
process.env.JWT_SECRET;
// ✅ ALWAYS
import { config } from '@/config/unifiedConfig';
config.auth.jwtSecret;
Request bodies
Query params
Route params
Webhook payloads
const schema = z.object({ email: z.string().email(), });
const input = schema.parse(req.body);
No validation = bug.
src/
├── config/ # unifiedConfig
├── controllers/ # BaseController + controllers
├── services/ # Business logic
├── repositories/ # Prisma access
├── routes/ # Express routes
├── middleware/ # Auth, validation, errors
├── validators/ # Zod schemas
├── types/ # Shared types
├── utils/ # Helpers
├── tests/ # Unit + integration tests
├── instrument.ts # Sentry (FIRST IMPORT)
├── app.ts # Express app
└── server.ts # HTTP server
| Layer | Convention |
|---|---|
| Controller | PascalCaseController.ts |
| Service | camelCaseService.ts |
| Repository | PascalCaseRepository.ts |
| Routes | camelCaseRoutes.ts |
| Validators | camelCase.schema.ts |
Services receive dependencies via constructor
No importing repositories directly inside controllers
Enables mocking and testing
export class UserService { constructor( private readonly userRepository: UserRepository ) {} }
Prisma client never used directly in controllers
Repositories:
await userRepository.findActiveUsers();
All async route handlers must be wrapped.
router.get(
'/users',
asyncErrorWrapper((req, res) =>
controller.list(req, res)
)
);
No unhandled promise rejections.
Every critical path must be observable.
Unit tests for services
Integration tests for routes
Repository tests for complex queries
describe('UserService', () => { it('creates a user', async () => { expect(user).toBeDefined(); }); });
No tests → no merge.
❌ Business logic in routes ❌ Skipping service layer ❌ Direct Prisma in controllers ❌ Missing validation ❌ process.env usage ❌ console.log instead of Sentry ❌ Untested business logic
Before finalizing backend work:
This skill is applicable to execute the workflow or actions described in the overview.
Weekly Installs
731
Repository
GitHub Stars
27.1K
First Seen
Jan 19, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
opencode586
gemini-cli581
codex522
cursor494
github-copilot482
claude-code459
React 组合模式指南:Vercel 组件架构最佳实践,提升代码可维护性
103,800 周安装