senior-backend

高级后端工程师

概述

设计并实现健壮、可扩展的后端系统，重点关注 API 设计、服务架构、数据管理和卓越运营。本技能涵盖 RESTful 和 GraphQL API 模式、消息驱动架构、缓存策略、速率限制、健康检查，以及基于 OpenTelemetry 的全面可观测性。

开始时宣布：“我正在使用 senior-backend 技能进行后端系统设计与实现。”

---

阶段 1：API 设计

目标： 在编写实现代码之前定义契约。

操作

1. 定义资源模型及其关系
2. 设计端点结构（REST）或架构（GraphQL）
3. 确定身份验证和授权策略
4. 定义速率限制和节流策略
5. 创建 API 文档（OpenAPI/GraphQL 架构）

API 风格决策表

因素	REST	GraphQL	gRPC
不同数据需求的多个使用方	不太适合	非常适合	不太适合
简单的 CRUD 操作	非常适合	功能过剩	功能过剩
实时订阅	需要额外添加 WebSocket	内置	内置（流式传输）
服务间通信	适合	功能过剩	非常适合
公共 API	非常适合	适合	不太适合（工具支持）
带宽受限的移动设备	有过度获取数据的风险	非常适合	非常适合

停止 — 未满足以下条件前，不要进入阶段 2：

• 已定义资源模型
• 已记录端点结构或架构
• 已选择身份验证策略
• API 契约可供审查（OpenAPI/GraphQL 架构）

---

阶段 2：实现

目标： 构建职责分离清晰的服务层。

操作

1. 建立层次清晰的项目结构
2. 实现数据访问层（repositories/DAOs）
3. 构建包含业务逻辑的服务层
4. 创建 API 控制器/解析器
5. 添加中间件（身份验证、日志记录、错误处理、CORS）
6. 实现缓存策略

RESTful URL 结构

GET    /api/v1/users              # List users (paginated)
GET    /api/v1/users/:id          # Get single user
POST   /api/v1/users              # Create user
PUT    /api/v1/users/:id          # Full update
PATCH  /api/v1/users/:id          # Partial update
DELETE /api/v1/users/:id          # Delete user
GET    /api/v1/users/:id/orders   # Nested resources
POST   /api/v1/users/:id/activate # State transitions

HTTP 状态码决策表

代码	含义	适用场景
200	成功	GET、PUT、PATCH 请求成功
201	已创建	POST 请求成功并创建了资源
204	无内容	DELETE 请求成功
400	错误请求	验证错误
401	未授权	缺少身份验证信息或身份验证无效
403	禁止访问	身份验证有效，但权限不足
404	未找到	资源不存在
409	冲突	存在重复项或状态冲突
422	无法处理的实体	输入在语义上无效
429	请求过多	超出速率限制
500	内部服务器错误	服务器发生意外故障

响应格式

// Success (single)
{ "data": { "id": "123", "name": "Alice" }, "meta": { "requestId": "req_abc123" } }

// Success (collection)
{ "data": [...], "meta": { "page": 1, "pageSize": 20, "totalCount": 150, "totalPages": 8 } }

// Error
{ "error": { "code": "VALIDATION_ERROR", "message": "Invalid input", "details": [...] } }

缓存策略决策表

策略	说明	适用场景
Cache-Aside	应用检查缓存，未命中时回退到数据库	通用场景
Write-Through	同时写入缓存和数据库	强一致性
Write-Behind	写入缓存，再异步写入数据库	高写入吞吐量
Read-Through	缓存未命中时从数据库加载	透明缓存

停止 — 未满足以下条件前，不要进入阶段 3：

• 项目结构遵循分层架构
• 在入口处执行输入验证（Zod、Joi、class-validator）
• 错误处理会返回结构化错误响应
• 已实现缓存策略并制定失效方案

---

阶段 3：加固

目标： 为服务投入生产运行做好准备。

操作

1. 添加全面的错误处理
2. 实现健康检查和就绪探针
3. 设置可观测性（跟踪、指标、日志）
4. 对关键路径进行负载测试
5. 编写运维场景的运行手册

健康检查端点

// GET /health — lightweight liveness check
{ "status": "healthy" }

// GET /health/ready — readiness with dependency checks
{
  "status": "healthy",
  "checks": {
    "database": { "status": "healthy", "latency": "5ms" },
    "redis": { "status": "healthy", "latency": "2ms" },
    "queue": { "status": "healthy", "latency": "8ms" }
  },
  "uptime": "72h15m",
  "version": "1.4.2"
}

可观测性：RED 方法指标

指标	描述	实现方式
速率	每秒请求数	每次请求时递增计数器
错误	每秒错误率	每次发生错误时递增计数器
持续时间	延迟分布	直方图（p50、p95、p99）

结构化日志格式

{
  "timestamp": "2025-01-15T10:30:00.123Z",
  "level": "info",
  "message": "User created",
  "service": "user-service",
  "traceId": "abc123",
  "spanId": "def456",
  "userId": "usr_123",
  "duration": 45
}

限流算法决策表

算法	优点	缺点	适用场景
固定窗口	简单、内存占用低	窗口边界处会出现突发	内部 API
滑动窗口	分布平滑	内存占用较高	公共 API
令牌桶	可控制突发流量	略微复杂	行业标准
漏桶	输出恒定	不允许突发	严格限流

STOP — 完成加固的条件：

• 健康检查端点响应正常
• 已配置结构化日志
• 已导出指标（RED 方法）
• 已完成关键路径的负载测试
• 错误处理会返回适当的状态码

---

事件驱动架构模式

消息队列模式决策表

模式	用例	示例
发布/订阅	向多个消费者广播	用户注册 -> 邮件、分析、CRM
工作队列	在多个工作进程间分发任务	图像处理、PDF 生成
请求/响应	带响应的异步请求	价格计算服务
死信	处理失败消息	超出重试策略限制

事件架构

{
  "eventId": "evt_abc123",
  "eventType": "user.created",
  "timestamp": "2025-01-15T10:30:00Z",
  "version": "1.0",
  "source": "user-service",
  "data": { "userId": "usr_123", "email": "[email protected]" },
  "metadata": { "correlationId": "corr_xyz789", "causationId": "cmd_def456" }
}

---

GraphQL 反模式

反模式	问题	修复方法
N+1 查询	性能下降	使用 DataLoader 批量处理
无界查询	DoS 漏洞	强制执行深度和复杂度限制
解析器中过度获取	浪费数据库查询	仅选择请求的字段

---

反模式 / 常见错误

反模式	错误原因	正确做法
直接暴露数据库 ID	安全风险，与数据库耦合	使用 UUID 或带前缀的 ID
在请求路径中同步调用外部服务	单点故障、延迟	使用队列或熔断器实现异步调用
N+1 查询模式	性能随规模线性下降	预加载或使用 DataLoader
捕获并吞掉错误	静默失败，无法调试	记录日志并携带上下文向上抛出
在处理程序之间共享可变状态	竞态条件、行为不可预测	采用无状态请求处理
跳过输入验证	注入、数据损坏	始终在边界处验证
所有错误都返回通用 500	开发者体验差	使用明确的错误代码和消息
没有 API 版本控制	破坏性变更会影响所有使用方	从第一天起就进行版本控制（/v1/）

---

文档查询（Context7）

使用 mcp__context7__resolve-library-id，然后使用 mcp__context7__query-docs 获取最新文档。返回的文档优先于记忆中的知识。

• express — 用于中间件模式、路由或请求/响应 API
• fastify — 用于插件系统、钩子或架构验证
• nestjs — 用于装饰器、模块、提供者或守卫
• prisma — 用于架构语法、客户端 API 或迁移命令

---

集成点

技能	关联
senior-architect	架构决策指导后端服务边界的划分
security-review	后端安全遵循 OWASP 和身份验证模式
performance-optimization	后端性能通过缓存和查询调优提升
testing-strategy	后端测试策略定义集成测试方法
code-review	评审验证 API 设计和错误处理
acceptance-testing	API 行为成为验收标准
senior-fullstack	后端为全栈 tRPC 层提供服务

---

核心原则

• 从第一天起进行 API 版本控制（/v1/）
• 在边缘进行输入验证（Zod、Joi、class-validator）
• 为非 GET 端点使用幂等键
• 平稳关闭（排空连接，完成正在处理的请求）
• 为外部服务调用使用熔断器
• 数据库迁移应进行版本控制且可逆
• 将密钥存储在环境变量中，绝不写入代码

---

技能类型

灵活——根据项目上下文调整 API 风格和架构。强烈建议采用三阶段流程（设计、实现、加固）。对于生产服务，健康检查、结构化日志记录和错误处理是不可妥协的要求。