Agent skill
backend
Backend development patterns for services, error handling, logging, caching. Use when building backend services, APIs, or microservices.
Stars
163
Forks
31
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/skills/other/backend
SKILL.md
后端开发模式
本技能提供后端服务开发的最佳实践和模式，支持多语言按需加载。
触发条件
- 构建后端服务
- 设计服务架构
- 实现业务逻辑层
- 配置中间件
- 处理错误和日志
- 性能优化（数据库、缓存、并发）
语言专属模式
根据项目技术栈，加载对应的语言专属文件：
| 技术栈 | 加载文件 | 框架 |
|---|---|---|
| Python | python.md |
FastAPI, Django, Flask |
| TypeScript/Node.js | typescript.md |
Express, NestJS, Fastify |
| Java | java.md |
Spring Boot, Quarkus |
| Go | go.md |
Gin, Echo, Fiber |
| C# | csharp.md |
ASP.NET Core |
| Rust | rust.md |
Axum, Actix-web, Rocket |
加载方式: 检测项目中的 pyproject.toml/package.json/pom.xml/go.mod/Cargo.toml 等文件确定技术栈。
通用架构模式
分层架构
┌─────────────────────────────────────┐
│ Controller 层 │ 处理 HTTP 请求/响应
├─────────────────────────────────────┤
│ Service 层 │ 业务逻辑
├─────────────────────────────────────┤
│ Repository 层 │ 数据访问
├─────────────────────────────────────┤
│ Model 层 │ 数据模型
└─────────────────────────────────────┘
通用目录结构
src/
├── controllers/ # 控制器（或 routes/handlers）
├── services/ # 业务逻辑
├── repositories/ # 数据访问（或 dal/）
├── models/ # 数据模型（或 entities/）
├── middlewares/ # 中间件
├── utils/ # 工具函数
├── config/ # 配置
└── types/ # 类型定义（如适用）
通用最佳实践
1. 错误处理原则
┌─────────────────────────────────────────────────────┐
│ 错误处理金字塔 │
├─────────────────────────────────────────────────────┤
│ 业务错误 (400-499) │
│ ├─ ValidationError (400) 输入验证失败 │
│ ├─ UnauthorizedError (401) 未认证 │
│ ├─ ForbiddenError (403) 无权限 │
│ └─ NotFoundError (404) 资源不存在 │
├─────────────────────────────────────────────────────┤
│ 系统错误 (500-599) │
│ ├─ InternalError (500) 服务器内部错误 │
│ ├─ ServiceUnavailable (503) 服务不可用 │
│ └─ GatewayTimeout (504) 网关超时 │
└─────────────────────────────────────────────────────┘
原则:
- 自定义错误类继承基础错误
- 统一错误响应格式
- 区分可操作错误和程序错误
- 记录足够的上下文用于调试
2. 日志规范
日志级别:
| 级别 | 用途 | 示例 |
|---|---|---|
| ERROR | 需要立即关注的错误 | 数据库连接失败 |
| WARN | 潜在问题 | 重试成功、降级处理 |
| INFO | 重要业务事件 | 用户登录、订单创建 |
| DEBUG | 开发调试信息 | 变量值、执行路径 |
结构化日志字段:
json
{
"timestamp": "2025-01-22T10:00:00Z",
"level": "info",
"message": "用户登录成功",
"requestId": "uuid",
"userId": "123",
"duration": 45
}
3. 缓存策略
| 策略 | 适用场景 | TTL 建议 |
|---|---|---|
| Cache-Aside | 读多写少 | 5-60 分钟 |
| Write-Through | 强一致性要求 | 短 TTL |
| Write-Behind | 写多读少 | 根据业务 |
缓存键命名:
{service}:{entity}:{id}
{service}:{entity}:list:{hash}
4. API 设计原则
- RESTful 资源导向
- 版本控制
/api/v1/... - 统一响应格式
- 幂等性 PUT/DELETE 操作
- 分页 大列表查询
5. 安全检查清单
- 输入验证（白名单优先）
- SQL/NoSQL 注入防护
- 认证令牌安全存储
- 敏感数据加密
- 速率限制
- CORS 配置
通用代码模式
统一响应格式
成功响应:
{
"success": true,
"data": { ... },
"meta": { "total": 100, "page": 1 }
}
错误响应:
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "邮箱格式不正确"
}
}
健康检查端点
GET /health
{
"status": "ok",
"timestamp": "2025-01-22T10:00:00Z",
"services": {
"database": { "status": "ok" },
"redis": { "status": "ok" }
}
}
优雅关闭
1. 收到 SIGTERM 信号
2. 停止接受新请求
3. 等待进行中的请求完成（超时时间内）
4. 关闭数据库连接
5. 关闭其他资源
6. 退出进程
语言专属内容
详细的语言专属实现请参考：
- Python: python.md - FastAPI/Django/Flask
- TypeScript: typescript.md - Express/NestJS
- Java: java.md - Spring Boot
- Go: go.md - Gin/Echo
- C#: csharp.md - ASP.NET Core
- Rust: rust.md - Axum/Actix-web/Rocket
专项优化
- 性能优化: performance.md - 数据库、缓存、并发优化
Python 进阶
- 设计模式: python-patterns.md - KISS、组合、策略模式
- 类型提示: python-types.md - Protocol、泛型、TypeGuard
- 可观测性: python-observability.md - 日志、指标、追踪
Maintenance
- Sources: 各语言官方文档, 12-Factor App
- Last updated: 2025-01-22
- Pattern: 通用清单 + 按需加载语言专属
记住: 后端代码的质量标准是可维护性——类型安全、错误处理、日志追踪缺一不可。
Didn't find tool you were looking for?