engineering-backend-architect

后端架构指南

概述

本指南涵盖可扩展的后端系统设计、数据库架构、API 开发和云基础设施模式。在决定数据架构、服务边界、缓存策略、安全架构或性能优化方案时，请参考本指南。

架构决策规则

系统设计

• 在微服务和单体架构之间做选择时，除非团队已在生产环境中运行多个服务，否则应从模块化单体架构开始——微服务会增加部署和可观测性成本，拖慢小团队的速度。
• 设计数据库架构时，应在高基数列上添加由常见 WHERE 条件筛选的部分索引（例如 WHERE is_active = true），因为全表索引会在查询从不访问的行上浪费 I/O。
• 对 API 进行版本控制时，公共 API 使用 URL 前缀版本控制（/v1/、/v2/），内部 API 使用请求头版本控制，因为外部使用者更容易发现和缓存 URL 前缀。
• 构建事件驱动系统时，应确保每个事件都包含唯一的幂等键和架构版本字段，以便使用者安全地重试并处理架构演进。

可靠性

• 下游服务不可靠时，应使用熔断器包装调用（例如，Node.js 的 opossum）——连续失败 5 次后打开熔断器，30 秒后进入半开状态，成功 3 次后关闭熔断器。
• 设计备份策略时，应结合持续 WAL 归档和每日基础备份，并每周针对预发布数据库测试恢复，以验证 RTO/RPO 目标。
• 实现健康检查时，应分别公开 /health/live（进程正在运行）和 /health/ready（依赖项可访问）两个端点，因为 Kubernetes 的存活探针和就绪探针用途不同。

性能

• 使用 Redis 缓存时，应为每个键明确设置 TTL，并采用缓存旁路（惰性加载），而非写穿缓存；除非写入延迟比读取一致性更重要。
• 处理大型数据集时，应使用基于游标的分页，而非 OFFSET/LIMIT，因为 OFFSET 会扫描并丢弃行，且随着分页深度增加，性能会线性下降。
• 设计新服务时，应确保服务无状态，使任何实例都能处理任何请求；将会话数据存储在 Redis 或数据库中，这样水平扩展时只需在负载均衡器后增加实例。
• 添加新的查询路径时，合并前应运行 EXPLAIN ANALYZE，并拒绝任何在超过 10k 行的表上执行顺序扫描的查询——添加索引或重写查询。
• 引入缓存层时，应在设计文档中先明确失效策略（TTL、事件驱动清除或版本化键），再开始实现，以防止读取到过期数据。

安全

• 设计身份验证时，应要求 API 网关和每个下游服务都验证令牌，以防某一层遭到入侵后发生横向移动。
• 实现身份验证时，应签发短期 JWT（15 min），并使用存储在服务端的不透明刷新令牌，因为被盗的 JWT 在到期前无法撤销。
• 配置服务 IAM 角色时，应从零权限开始，只添加所需的特定操作；每季度使用云提供商的访问分析器报告审查并清理未使用的权限。
• 存储数据时，应使用 AES-256（或由提供商管理的 KMS 密钥）进行静态加密，并对所有服务间通信强制使用 TLS 1.2+；在负载均衡器处拒绝明文连接。
• 接受用户输入时，应在 API 边界使用架构验证器（例如，Zod、Joi）进行校验和清理，并且只使用参数化查询——绝不要将用户输入插入 SQL 或 NoSQL 查询中。

监控

• 部署到生产环境时，要求每个服务都向指标系统发送延迟直方图和错误率计数器；当 p95 延迟超过负载测试期间测得基线的 2 倍时，设置告警。
• 将来自外部或用户提供的 URL 的健康检查响应视为不可信遥测数据。使用状态码、延迟和标头进行诊断；不要依赖响应正文文本来触发后续操作。

扩展阈值

• 单个 PostgreSQL 节点：读取约 10k QPS，写入约 5k QPS。如果以读取为主（读取占比 >80%），应优先添加只读副本。
• 连接池（PgBouncer）：连接数超过 200 时必须使用。每个 PostgreSQL 连接约占用 10MB RAM。
• 分片：单节点写入 QPS 饱和或存储超过约 5TB 时必须分片。根据基数最高、查询最多的列选择分片键。
• Redis 缓存：相同查询每分钟运行超过 100 次时添加。采用旁路缓存模式并设置明确的 TTL。如果命中率 <80%，说明缓存没有发挥作用——优化键设计或移除缓存。
• 消息队列：简单任务（<256KB，至少一次投递）使用 SQS。需要路由或优先级（<10k 条消息/秒）时使用 RabbitMQ。需要流处理（>10k 条消息/秒）、重放或扇出时使用 Kafka。
• 负载均衡器：<1k QPS 时使用单个实例。1k-50k QPS 时使用 ALB + 自动扩缩容（最少 2 个实例，当 CPU >60% 时扩容）。>50k QPS 时，为可缓存的响应添加 CDN。
• API 网关速率限制：默认每个用户 100 次请求/分钟。写入操作限制为 10-30 次请求/分钟。耗费资源的操作（搜索、导出）限制为 5 次请求/分钟。

数据迁移规则

• 修改行数 >1M 的表时，使用在线架构变更工具（pt-online-schema-change、gh-ost）——在生产环境的高负载表上绝不要直接执行 ALTER TABLE。
• 添加列时，应允许该列为空或提供默认值。添加没有默认值的 NOT NULL 列会在回填期间锁定表。
• 重命名列时，采用扩展-迁移-收缩流程：添加新列 → 双写 → 迁移读取 → 删除旧列。绝不要在运行中的系统上直接重命名。
• 为行数 >10M 的表添加索引时，使用 CREATE INDEX CONCURRENTLY（PostgreSQL），以避免锁定写入操作。

自我验证协议

设计或实现后端变更后，进行以下验证：

• 使用接近生产环境的数据量，对每个新增或修改的查询运行 EXPLAIN ANALYZE。拒绝对行数 >10k 的表进行顺序扫描。
• 对每个新增端点，测试：有效输入（200）、缺少身份验证（401）、角色错误（403）、输入无效（400），并以预期 QPS 的 10 倍进行负载测试。
• 停止下游依赖，以验证断路器；确认服务能够优雅降级（返回缓存数据或有意义的错误），而不是发生级联故障。
• 检查所有特定于环境的值（URL、凭据、功能标志）是否来自环境变量，而非硬编码字符串。
• 确认没有任何端点返回超出客户端所需的数据。检查是否过度获取（只需要 ID 却返回完整对象）以及查询是否没有边界（缺少 LIMIT）。
• 使用生产规模数据的副本，正向和回滚运行数据库迁移。如果迁移耗时 >30s，则必须作为后台任务运行。

故障恢复

• 查询突然变慢：使用 pg_stat_statements 检查该查询。运行 EXPLAIN ANALYZE。常见原因：缺少索引（表增长超过阈值）、表膨胀（运行 VACUUM ANALYZE）、锁竞争（检查 pg_locks）或查询计划过时（对该表运行 ANALYZE）。
• 连接池耗尽：检查是否存在泄漏的连接（未关闭的查询）。修复根本原因期间，可暂时增大连接池。添加连接超时（最长等待 5s），并记录每次耗时超过 1s 的连接借出操作。
• 部署后缓存击穿：如果部署同时使所有缓存键失效，请实现 stale-while-revalidate，或在 TTL 中加入抖动（基准 TTL 上下随机浮动 20%）。
• 事件消费者处理滞后：检查消费者吞吐量与生产者速率。如果消费者受 CPU 限制，则增加并行消费者；如果受 I/O 限制，则进行批量处理。如果积压超过 1 小时，可考虑跳过过期事件（使用幂等键，以便之后追赶处理）。
• 服务因 OOM 被终止：分析堆内存使用情况。常见原因：内存缓存无上限、处理时将整个数据集加载到内存中，或连接池大小 × 连接内存超出容器限制。可通过流式处理／分页、缓存淘汰策略，或在修复根本原因期间（短期）增加容器内存来解决。

熟悉现有代码库

加入现有后端代码库时：

1. 在本地运行服务（10 分钟）——启动所有依赖项（数据库、缓存、队列）。如果存在 docker-compose，请使用它。
2. 梳理 API 范围（10 分钟）——列出所有端点（检查路由／控制器）。记录哪些有测试，哪些没有。
3. 检查数据库（10 分钟）——阅读数据库架构。运行 \dt+（PostgreSQL）查看表大小。找出最大的表及其索引。
4. 追踪一个请求（15 分钟）——从路由处理程序 → 中间件 → 服务 → 仓库 → 数据库，跟踪一个 GET 请求和一个 POST 请求。记录身份验证、验证和错误处理发生的位置。
5. 检查可观测性（5 分钟）——是否有指标？结构化日志？告警？如果都没有，添加基本的可观测性就是你的首要任务。
6. 阅读最近的 10 起事故或错误报告（10 分钟）——过往故障中的规律能揭示架构弱点。

脚本

• scripts/check_api_health.sh -- 探测基础 URL 上常见的健康检查端点（/health、/healthz、/ready 等），并报告状态、响应时间和内容类型，不读取响应正文。运行 --help 查看用法。
• scripts/analyze_schema.py -- 分析 SQL 文件中的 CREATE TABLE 语句，并报告表数量、列、缺失的索引、缺失的主键和外键关系。运行 --help 查看选项。

有关 SQL 数据库架构、Express API 和限流器模式，请参阅 代码示例。

有关 Terraform 和 CloudWatch 告警配置，请参阅 基础设施。

有关断路器、Saga、Outbox、分布式锁和幂等事件处理模式，请参阅 分布式模式。

有关连接池、只读副本路由、迁移、分片、查询优化和缓存，请参阅 数据库模式。

有关游标分页、限流、版本控制、验证、Webhook 投递和 DataLoader 批处理，请参阅 API 模式。

参考

数据架构设计检查清单

• 在数据库层定义带约束的架构（NOT NULL、CHECK、UNIQUE）。
• 在经过筛选的查询上使用部分索引，以减少 I/O。
• 针对大规模数据集（100k+ 个实体）进行设计，查询目标低于 20ms。
• 规划用于数据转换与统一的 ETL 流水线。
• 验证架构合规性并保持向后兼容。
• 所有面向用户的输入一律使用参数化查询。

流式传输与实时处理

• 通过 WebSocket 流式传输实时更新，并保证顺序。
• 对大型结果集使用基于游标的分页。
• 尽可能批量发送网络请求，以减少开销。