// 失败 { "success": false, "error": { "code": "USER_NOT_FOUND", "message": "用户不存在" } } ```
### 数据库选型指南
类型 | 选型 | 适用场景
---|---|---
关系型 | PostgreSQL | 复杂查询、事务要求高
关系型 | MySQL | 简单CRUD、读多写少
文档 | MongoDB | 灵活schema、日志存储
缓存 | Redis | 分布式缓存、消息队列
时序 | InfluxDB | 监控数据、IoT
### 认证方案选型
方案 | 适用场景 | 复杂度
---|---|---
JWT | 无状态API、分布式 | ⭐⭐
Session | 单体应用、简单场景 | ⭐
OAuth2 | 第三方登录、SSO | ⭐⭐⭐⭐
API Key | 服务间调用 | ⭐
* * *
## 使用说明
当你说"开发后端"时，老王会问你：
1. **用什么语言？** (Python/Node.js/Go/Java)
2. **什么场景？** (CRUD API/微服务/实时通信/数据处理)
3. **什么数据库？** (PostgreSQL/MySQL/MongoDB/Redis)
然后老王会切换到对应语言的专家模式，给你最专业的建议！
* * *
## 最佳实践（通用）
### 1\. 环境变量管理
```bash
# .env.example
DATABASE_URL=postgresql://user:pass@localhost:5432/db REDIS_URL=redis://localhost:6379 JWT_SECRET=your-secret-key LOG_LEVEL=info ```
### 2\. 日志规范
```javascript // 结构化日志 logger.info('user_login', { userId: 123, ip: '192.168.1.1', userAgent: 'Mozilla/5.0...' }) ```
### 3\. 错误处理
* 统一错误码和错误信息
* 敏感信息不要暴露给客户端
* 记录完整的错误堆栈到日志
### 4\. API限流
* 防止DDoS攻击
* 公开API必须限流
* 使用Redis实现滑动窗口
### 5\. 数据验证
* 永远不要信任用户输入
* 参数类型、长度、格式校验
* SQL注入防护
### 6\. ⚠️ 优雅关闭机制（防止内存泄漏）
**非常重要！** 所有后端服务必须正确实现优雅关闭！
#### FastAPI (Python) 示例
```python from contextlib import asynccontextmanager from fastapi import FastAPI
@asynccontextmanager async def lifespan(app: FastAPI): # 启动时执行 await init_database() print("Application started")
yield # 应用运行
# 关闭时执行 - 必须清理资源！
print("Shutting down...")
await database.dispose()
await redis.close()
print("Graceful shutdown completed")
app = FastAPI(lifespan=lifespan) ```
#### NestJS (Node.js) 示例
```typescript import { NestFactory } from '@nestjs/core'; import { AppModule } from './app.module';
async function bootstrap() { const app = await NestFactory.create(AppModule);
// 监听关闭信号 app.enableShutdownHooks();
await app.listen(3000); }
bootstrap(); ```
#### Gin (Go) 示例
```go func main() { r := gin.Default()
// 优雅关闭
srv := &http.Server{
Addr: ":8080",
Handler: r,
}
go func() {
if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
log.Fatalf("listen: %s\n", err)
}
}()
// 等待中断信号
quit := make(chan os.Signal, 1)
signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
<-quit
// 优雅关闭
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
if err := srv.Shutdown(ctx); err != nil {
log.Fatal("Server forced to shutdown:", err)
}
} ```
#### Spring Boot (Java) 示例
```java @Component public class ShutdownConfig { @PreDestroy public void onShutdown() { // 清理资源 dataSource.close(); executor.shutdown(); } } ```
**优雅关闭的关键点** ：
1. 捕获SIGTERM/SIGINT信号
2. 停止接受新请求
3. 等待现有请求完成（设置超时）
4. 关闭数据库连接池
5. 关闭Redis/Kafka等外部连接
6. 清理临时文件
7. 刷新日志缓冲区
* * *
### 7\. ⚠️ 文档同步规范（非常重要！）
后端开发完成后，**必须同步更新相关文档** ，保持代码与文档一致！
#### 必须维护的文档
##### 1\. 进度文档 (`docs/backend/progress.md`)
记录后端开发进度、已完成API、待办事项。
**更新时机** ：
* 完成新API端点时
* 修改数据库模型时
* 完成里程碑时（如单元测试通过）
* 技术栈升级时
**文档格式参考** ：
# 后端开发进度
> 最后更新：YYYY-MM-DD
> 状态：开发中 (X%完成)
## 已完成功能
### 核心架构
| 模块 | 状态 | 说明 |
|------|------|------|
| FastAPI应用 | ✅ | 异步框架，自动文档 |
### API端点
| 方法 | 路径 | 状态 | 说明 |
|------|------|------|------|
| GET | `/api/articles` | ✅ | 文章列表（分页、筛选） |
## 待完成功能
### 优先级 P1
- [ ] JWT认证中间件
## 代码统计
| 类型 | 数量 |
|------|------|
| API端点 | 13 |
##### 2\. API参考文档 (`docs/backend/api-reference.md`)
记录后端API接口、请求格式、响应格式。
**更新时机** ：
* 新增/修改API端点时
* 请求/响应字段变化时
* 错误码新增时
* 认证机制变化时
**必须包含** ：
* 服务地址配置（开发/生产环境）
* 通用响应格式（成功/失败/分页）
* 每个API的详细说明：
* 方法和路径
* 请求参数（Query/Path/Body）
* 响应格式（带示例）
* 错误码说明
* 数据模型定义
* 调用示例（Python/cURL/JavaScript）
##### 3\. README.md (`backend/README.md`)
后端项目入口文档，快速上手指南。
**必须包含** ：
* 项目简介
* 技术栈版本
* 快速启动命令（安装依赖/运行测试/启动服务）
* 目录结构
* 开发注意事项
* 与前端的对接说明（CORS、端口等）
* 优雅关闭说明
#### 文档同步检查清单
后端开发完成后，问自己：
* 我更新了 `docs/backend/progress.md` 吗？
* 新API记录在 `docs/backend/api-reference.md` 了吗？
* README.md 里的依赖版本是最新的吗？
* 数据库模型变化后，更新文档了吗？
* 环境变量变化记录在案了吗？
* API端口/CORS配置更新了吗？
#### 文档与代码同步原则
1. **先更新文档再提交代码** \- 确保文档反映最新状态
2. **API变化立即同步** \- 后端API变了，文档必须立刻更新（前端同学等着用呢）
3. **配置变化记录在案** \- 端口、环境变量、CORS等配置要写进文档
4. **定期Review文档** \- 每周检查一次文档是否过时
5. **删除死文档** \- 不存在的API从文档中移除
#### 文档命名规范
文档类型 | 路径 | 命名格式
---|---|---
后端进度 | `docs/backend/progress.md` | 固定文件名
后端API参考 | `docs/backend/api-reference.md` | 固定文件名
前端进度 | `docs/frontend/progress.md` | 固定文件名
前端API参考 | `docs/frontend/api-reference.md` | 固定文件名
技术设计 | `docs/plans/YYYY-MM-DD-*.md` | 按日期命名
数据库变更 | `docs/database/migrations/*.md` | 按版本命名
#### API文档模板参考
### POST /api/articles
创建文章
**请求头**：
Content-Type: application/json Authorization: Bearer {token}
**请求体**：
```json
{
"title": "文章标题（必填）",
"content": "Markdown正文（必填）",
"category_id": 1
}
**验证规则** ：
* `title`: 1-255字符
* `content`: 最少1字符
**响应（200）** ：
{
"code": 0,
"message": "success",
"data": {
"id": 1,
"title": "文章标题",
"created_at": "2026-01-14T00:00:00Z"
}
}
**错误响应** ：
状态码 | 说明
---|---
400 | 参数验证失败
401 | 未认证
---
**告诉老王你想用什么技术栈，我给你找对应的专家！**
Weekly Installs
42
Repository
[aaaaqwq/claude-…e-skills](https://github.com/aaaaqwq/claude-code-skills "aaaaqwq/claude-code-skills")
GitHub Stars
11
First Seen
Jan 22, 2026
Security Audits
[Gen Agent Trust HubFail](/aaaaqwq/claude-code-skills/backend-development/security/agent-trust-hub)[SocketPass](/aaaaqwq/claude-code-skills/backend-development/security/socket)[SnykWarn](/aaaaqwq/claude-code-skills/backend-development/security/snyk)
Installed on
codex33
opencode32
gemini-cli32
cursor32
claude-code29
github-copilot29
