backend-patterns

backend-patterns Skill 多维度简评

类别：后端开发 / 架构 仓库：affaan-m/everything-claude-code 维护者：affaan-m（Anthropic 黑客马拉松获胜者） 含金量：经过 10+ 个月构建真实产品演化

一、核心定位与价值

这不是”AI 写的后端模板”——这是Anthropic 黑客马拉松获胜者在他真实生产项目中使用 10 个月后沉淀下来的后端架构最佳实践。

它的价值在于：

• ✅ 真实战场验证：不是 demo，是 10000+ 行生产代码
• ✅ 跨语言适用：Node.js / Python / Go / Java 都用得上
• ✅ 覆盖完整 SDLC：从 API 设计到部署监控
• ✅ 可量化：每条规则都有反例和正例

二、SKILL.md 标准结构

---
name: backend-patterns
description: Backend architecture patterns, API design, database optimization,
  and server-side best practices. Use when designing or implementing backend services.
license: MIT
---

完整 SKILL.md 包含：

1. Overview - 概述与适用场景
2. When to Use - 何时触发
3. Patterns - 具体的模式集合
4. Anti-Patterns - 反模式
5. Examples - 完整示例代码
6. References - 详细参考

三、12 大核心模式

模式 1：REST API 资源命名

原则：资源用名词复数，不是动词

✅ GET    /api/v1/users
✅ POST   /api/v1/users
✅ GET    /api/v1/users/:id
✅ PUT    /api/v1/users/:id
✅ PATCH  /api/v1/users/:id
✅ DELETE /api/v1/users/:id

❌ GET    /api/v1/getUsers
❌ POST   /api/v1/createUser
❌ GET    /api/v1/userList

模式 2：状态码语义化

模式 3：分页策略

Cursor-based（推荐用于大数据）：

GET /api/v1/users?cursor=eyJpZCI6MTAwfQ&limit=20

Response:
{
  "data": [...],
  "next_cursor": "eyJpZCI6MTIwfQ",
  "has_more": true
}

Offset-based（适合小数据）：

GET /api/v1/users?page=1&page_size=20

Response:
{
  "data": [...],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 1523,
    "total_pages": 77
  }
}

模式 4：过滤 / 排序

GET /api/v1/users?status=active&role=admin&sort=-created_at,name

支持的查询参数：
- 字段=值：精确匹配
- 字段[in]=a,b,c：包含
- 字段[gt]=10：大于
- 字段[between]=10,20：范围
- sort=-field,field：负号降序

模式 5：统一错误响应

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "邮箱格式不正确",
    "details": [
      {
        "field": "email",
        "code": "INVALID_FORMAT",
        "message": "邮箱必须包含 @"
      }
    ],
    "request_id": "req_abc123",
    "timestamp": "2026-06-15T12:34:56Z"
  }
}

关键：

• code：机器可读（PROGRAMMABLE）
• message：人类可读
• details：字段级错误
• request_id：用于追踪
• 不要泄露内部栈

模式 6：API 版本控制

3 种策略对比：

推荐：URL Path（最常用、最易理解）

模式 7：速率限制（Rate Limiting）

// 滑动窗口示例（伪代码）
const WINDOW = 60 * 1000;  // 1 分钟
const MAX_REQUESTS = 100;

function rateLimit(userId) {
  const key = `rate:${userId}`;
  const requests = redis.lrange(key, 0, -1);

  // 清理过期
  const now = Date.now();
  redis.lrem(key, 0, `${now - WINDOW}`);

  if (requests.length >= MAX_REQUESTS) {
    throw new RateLimitError('请求过于频繁，请稍后重试', {
      'X-RateLimit-Limit': MAX_REQUESTS,
      'X-RateLimit-Remaining': 0,
      'Retry-After': Math.ceil(WINDOW / 1000)
    });
  }

  redis.lpush(key, now);
  redis.expire(key, Math.ceil(WINDOW / 1000));
}

响应头：

• X-RateLimit-Limit：总配额
• X-RateLimit-Remaining：剩余
• X-RateLimit-Reset：重置时间
• Retry-After：重试等待秒数

模式 8：JWT 认证

// Token 签发
function issueToken(user) {
  return jwt.sign(
    { sub: user.id, role: user.role },
    process.env.JWT_SECRET,
    { expiresIn: '1h', issuer: 'myapp' }
  );
}

// Token 验证
function verifyToken(token) {
  try {
    return jwt.verify(token, process.env.JWT_SECRET, {
      issuer: 'myapp',
      algorithms: ['HS256']  // 防止算法混淆攻击
    });
  } catch (e) {
    throw new UnauthorizedError('Invalid token');
  }
}

// 中间件
function authMiddleware(req, res, next) {
  const authHeader = req.headers.authorization;
  if (!authHeader?.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'Missing Authorization header' });
  }

  const token = authHeader.slice(7);
  try {
    req.user = verifyToken(token);
    next();
  } catch (e) {
    return res.status(401).json({ error: 'Invalid token' });
  }
}

关键安全实践：

• ✅ HTTPS only
• ✅ HttpOnly cookie（避免 XSS）
• ✅ 短 access token + 长 refresh token
• ✅ 算法白名单（防止 alg: none）
• ✅ issuer + audience 校验

模式 9：数据库 Schema 设计原则

-- ✅ 软删除 + 审计字段
CREATE TABLE users (
  id BIGSERIAL PRIMARY KEY,
  email VARCHAR(255) NOT NULL UNIQUE,
  password_hash VARCHAR(255) NOT NULL,
  name VARCHAR(100) NOT NULL,
  status VARCHAR(20) NOT NULL DEFAULT 'active',
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  deleted_at TIMESTAMPTZ
);

CREATE INDEX idx_users_email ON users(email) WHERE deleted_at IS NULL;
CREATE INDEX idx_users_created_at ON users(created_at DESC);

审计字段：

• created_at：创建时间
• updated_at：更新时间（trigger 自动维护）
• deleted_at：软删除（NULL = 未删除）

索引原则：

• WHERE 子句常用字段建索引
• 复合索引按选择性排序
• 部分索引：WHERE deleted_at IS NULL

模式 10：缓存策略

Cache-Aside（最常用）：
1. 读：先查 Redis，未命中则查 DB，写入 Redis
2. 写：更新 DB，删除 Redis（lazy invalidation）
3. TTL：根据数据更新频率

写穿透（Write-Through）：
- 同步写 DB + Redis
- 强一致，但性能差

写回（Write-Behind）：
- 异步写 DB
- 高性能，但可能丢失

Cache Stampede 防护：
- singleflight：同一 key 只查一次 DB
- 随机 TTL：避免雪崩

模式 11：消息队列

// Kafka 示例
async function publishEvent(topic, payload) {
  await producer.send({
    topic,
    messages: [{
      key: payload.id,
      value: JSON.stringify(payload),
      headers: {
        'content-type': 'application/json',
        'event-type': payload.type,
        'trace-id': getTraceId()
      }
    }]
  });
}

// Consumer：幂等消费
async function processMessage(message) {
  const { id, type, data } = JSON.parse(message.value.toString());

  // 幂等键：检查是否已处理
  if (await redis.sismember('processed:events', id)) {
    console.log(`Event ${id} already processed, skip`);
    return;
  }

  await handleEvent(type, data);

  // 标记已处理（成功后才标记）
  await redis.sadd('processed:events', id);
}

幂等性关键：

• 业务 ID 作为幂等键
• 数据库唯一索引
• Redis SETNX 临时锁
• 处理成功后才提交 offset

模式 12：可观测性

日志（Logging）：
- 结构化：JSON 格式
- 字段：timestamp、level、service、trace_id、message、context
- 工具：Loki / ELK / CloudWatch

指标（Metrics）：
- RED：Rate（请求率）、Errors（错误率）、Duration（延迟）
- USE：Utilization、Saturation、Errors
- 工具：Prometheus + Grafana

追踪（Tracing）：
- OpenTelemetry 标准
- 跨服务 trace_id 关联
- 工具：Jaeger / Zipkin / Tempo

四、6 大实战场景

场景 1：设计 SaaS API

用 backend-patterns 为我的 SaaS 设计完整 API：
- /api/v1/auth（注册、登录、刷新）
- /api/v1/users（CRUD）
- /api/v1/billing（订阅、发票）
- /api/v1/webhooks（事件回调）
- 错误格式、限流、JWT

场景 2：数据库 Schema 设计

设计一个电商系统的 schema：
- users / products / orders / payments / reviews
- 索引、约束、审计字段
- 软删除

场景 3：缓存架构

用 backend-patterns 设计 Redis 缓存策略：
- 哪些数据缓存
- TTL 设置
- 一致性保证
- 雪崩 / 穿透 / 击穿防护

场景 4：统一错误处理

设计错误处理中间件：
- 自定义错误类
- HTTP 状态码映射
- 用户友好提示
- 日志记录
- request_id 追踪

场景 5：异步任务系统

设计订单支付的异步流程：
- 任务队列选型（Kafka / RabbitMQ / BullMQ）
- 幂等性保证
- 重试策略（指数退避）
- 死信队列

场景 6：微服务拆分

我的单体应用想拆为微服务：
- 边界识别
- API 网关
- 服务间通信
- 数据一致性（Saga / 2PC）
- 可观测性

五、5 大反模式（必须避免）

反模式 1：上帝服务（God Service）

❌ 一个 service 10000+ 行
✅ 按业务边界拆分为多个 service

反模式 2：业务逻辑在 Controller

❌ controller 直接操作数据库
✅ controller 只做请求/响应转换，业务在 service 层

反模式 3：缺乏幂等性

❌ 重试导致重复扣款
✅ 每个操作有唯一 ID，重复请求返回原结果

反模式 4：同步调用链过长

❌ A → B → C → D → E（同步，5 秒延迟）
✅ 异步解耦，关键路径用消息队列

反模式 5：硬编码配置

❌ 数据库密码写在代码里
✅ 环境变量 + 密钥管理服务

六、安装

# Claude Code
/plugin marketplace add affaan-m/everything-claude-code
/plugin install backend-patterns@affaan-m

# 通用
npx skills add affaan-m/everything-claude-code --skill backend-patterns

七、6 条实战技巧

1. RESTful 而非 RPC：URL 用资源，不用动词
2. 错误格式统一：前端能稳定解析
3. 状态码语义化：404 vs 400 vs 422 区别使用
4. OpenAPI 规范：用 YAML 定义，自动生成文档
5. HATEOAS：超媒体链接（高级场景）
6. GraphQL 考虑：复杂关系用 GraphQL 更合适

参考资料

1. affaan-m/everything-claude-code GitHub
2. REST API 设计指南 - Microsoft
3. JWT 最佳实践 - IETF RFC 7519
4. OpenTelemetry 官方文档
5. Redis 缓存策略

八、5 条反合理化

九、与其他 Skill 配合

十、Q&A

Q: REST vs GraphQL 怎么选？ A: 简单 CRUD 用 REST；复杂关系、客户端多端用 GraphQL。

Q: JWT 还是 Session？ A: 移动 App 用 JWT（无状态），传统 Web 用 Session + Cookie。

Q: 错误信息返回堆栈吗？ A: 生产环境绝对不行。开发环境可以用 ?debug=true。

Q: API 网关必须吗？ A: 微服务必需，单体可省。

Q: gRPC 何时用？ A: 服务间高性能通信，移动 App 不适合（浏览器不支持）。

十一、总结

核心价值：

• 黑客马拉松冠军 10+ 个月实战沉淀
• 12 大模式覆盖完整后端架构
• 5 大反模式 + 6 大实战场景

适用人群：

• 所有后端工程师
• 全栈开发者
• 架构师
• Tech Lead

投入产出比：⭐⭐⭐⭐⭐（5/5）—— 必装。

配套文档：postgres-patterns 数据库 | clickhouse-io OLAP