backend-patterns

backend-patterns 快速入门

来自 Anthropic 黑客马拉松获奖项目的后端模式合集，让 AI 写后端时直接套用生产级套路。

这是什么？解决什么问题？

backend-patterns 是 affaan-m/everything-claude-code 仓库下的一个 Skill，和 affaanm-backend-patterns 是”同名不同 slug”的关系——两者本质上是同一类能力的不同入口。

backend-patterns 这个 slug 是社区的”通用版”，被收录在 affaan-m/everything-claude-code 主仓，侧重”可直接复用的生产级后端模式”；而 affaanm-backend-patterns 是”Anthropic 黑客马拉松获奖作品”那个独立宣传页面 slug。两者都指向 affaan-m/everything-claude-code 仓库。

这个 Skill 解决的问题，和 affaanm-backend-patterns 完全一致：让 AI 写后端时不再写”教科书式”的简单实现，默认按 10+ 真实生产配置里沉淀的架构模式产出代码，包括：

• API 设计：REST 命名规范、统一错误响应、版本号策略、限流。
• 数据库优化：索引选择、N+1 查询规避、事务边界、迁移策略。
• 服务架构：分层（controller / service / repository）、依赖注入、配置中心。
• 可观测性：结构化日志、trace_id、metrics 埋点、健康检查端点。
• 韧性设计：超时、重试、熔断、降级、限流、幂等。

它适合的场景：中大型后端项目的架构定型、AI 写新需求时希望遵循团队已有规范、Code Review 时希望 AI 主动指出”教科书式实现”的风险。

准备工作

1. 一个支持 Skill 加载的 AI 编程助手（Claude Code / Cursor / Cline 等）。
2. 项目里已经有清晰的分层结构，或者愿意按 Skill 的建议从零开始组织。
3. Clone 仓库：

git clone https://github.com/affaan-m/everything-claude-code.git

4. 软链 Skill：

ln -s everything-claude-code/skills/backend-patterns ~/.claude/skills/backend-patterns

3 步快速上手

第 1 步：安装 Skill

按上面的命令软链完成后，重启 AI 助手，Skill 自动生效。

第 2 步：验证安装

向 AI 发送请求：

“请用 backend-patterns 给我一段 FastAPI 用户登录接口代码，要求分层清晰、带 trace_id 日志、超时与重试。”

如果 AI 输出包含 controller / service / repository 三层，日志里嵌入 X-Request-ID，外部 HTTP 调用带 tenacity 重试装饰器，说明 Skill 加载成功。

第 3 步：用 Skill 跑第一个任务

让 AI 按 Skill 模式生成一个 Node.js + Express 的健康检查端点 + 用户列表接口：

// controllers/userController.js
import { userService } from '../services/userService.js';

export const userController = {
  async list(req, res) {
    const { page = 1, pageSize = 20 } = req.query;
    const result = await userService.list({
      page: Number(page),
      pageSize: Number(pageSize),
    });
    res.json({ code: 0, data: result });
  },
};

// services/userService.js
import { userRepository } from '../repositories/userRepository.js';
import { logger } from '../lib/logger.js';

export const userService = {
  async list({ page, pageSize }) {
    const traceId = logger.getTraceId();
    logger.info('user.list.start', { page, pageSize, traceId });
    const [items, total] = await userRepository.paginate({ page, pageSize });
    logger.info('user.list.end', { count: items.length, traceId });
    return { items, total, page, pageSize };
  },
};

// repositories/userRepository.js
import { db } from '../lib/db.js';

export const userRepository = {
  async paginate({ page, pageSize }) {
    const offset = (page - 1) * pageSize;
    return await db.transaction(async (trx) => {
      const items = await trx('users')
        .select('id', 'email', 'created_at')
        .orderBy('id', 'desc')
        .limit(pageSize)
        .offset(offset);
      const [{ count }] = await trx('users').count('id as count');
      return [items, Number(count)];
    });
  },
};

Skill 会主动提醒 AI：

• controller 不直接操作数据库。
• service 注入 trace_id，日志可串联。
• repository 用事务 + 索引，避免 N+1。
• 统一响应结构 {code, data, message}。

常见踩坑

1. 业务逻辑散落在 controller。一个 endpoint 写 100 行业务代码，后续改起来牵一发动全身，Skill 明确反对。
2. 数据库查询没 LIMIT。分页接口忘了 LIMIT 20，生产环境单次返回 100 万行，直接 OOM。
3. 日志格式不统一。console.log 混杂 logger.info，grep 不到关键事件，Skill 建议统一结构化日志。
4. 缺 trace_id。排障时无法串联一个请求经过的所有服务，这是 SRE 必抓的硬性要求。
5. 数据库连接未复用。每个请求里 new Pool()，浪费连接资源，Skill 建议单例 + 依赖注入。
6. 错误处理用字符串 return。return { error: "..." } 无法被全局错误处理拦截，Skill 推荐用异常类 + 中间件统一处理。

初级用法

用法 1：搭新项目的目录骨架。让 AI 按 backend-patterns 的分层模板，生成一个新项目的完整目录结构 + 基础中间件。

用法 2：重构老的”大泥球”controller。把一个 300 行的 controller 贴给 AI，让它按 Skill 拆成 controller + service + repository 三层。

用法 3：统一错误响应格式。让 AI 帮你设计全局 ErrorResponse 和异常处理中间件，前端就能用统一的格式解析错误。

高级玩法

玩法 1：CQRS 模式。对读多写少的场景，把 query 和 command 拆到不同 service，query 可以走读副本、cache，command 走主库。

玩法 2：Outbox 模式。解决”本地事务 + 消息发送”的数据一致性问题，先写 outbox 表，异步 worker 投递到 MQ。

玩法 3：多租户隔离。在 repository 层强制注入 tenant_id 过滤条件，避免越权访问。Skill 建议用 ORM event 或 framework middleware 实现。

小技巧

1. 依赖注入用类型注解。TypeScript 严格模式下，AI 生成代码时类型提示能避免很多低级错误。
2. Pydantic / Zod schema 双向分离。入参（UserCreate）和出参（UserOut）分开，避免内部字段泄露到 API。
3. 日志用结构化格式。logger.info("user_registered", { userId, email })，方便后续接 ELK / Loki。
4. 慢查询埋点。在 ORM event 里监听 before_query_execute，记录 > 100ms 的查询，定期 review。
5. 健康检查端点必须包含依赖项。不只是返回 200 OK，还要检查 DB / Redis / MQ 是否可达，这是 K8s liveness/readiness 的标配。