tomevault-io 后端开发模式
本技能提供后端服务开发的最佳实践和模式，支持多语言按需加载。
触发条件
- 构建后端服务
- 设计服务架构
- 实现业务逻辑层
- 配置中间件
- 处理错误和日志
- 性能优化（数据库、缓存、并发）
语言专属模式
根据项目技术栈，加载对应的语言专属文件：
| 技术栈 | 加载文件 | 框架 |
|---|---|---|
| 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 | 开发调试信息 | 变量值、执行路径 |
结构化日志字段:
{
"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: 通用清单 + 按需加载语言专属
记住: 后端代码的质量标准是可维护性——类型安全、错误处理、日志追踪缺一不可。
Converted and distributed by TomeVault — claim your Tome and manage your conversions.