software-backend

软件后端工程

将此技能用于后端服务的实现与审查：API 边界、身份验证、数据访问、作业、缓存、可观测性和生产环境加固。如果主要问题是平台选择、系统拓扑或 API 契约设计（不涉及实现），请尽早转交。

快速参考

需求	默认方向
公共 HTTP API	使用 REST，并明确契约和超时
内部 TS 单体仓库 API	当端到端类型安全很重要时使用 tRPC
高吞吐量内部 RPC	默认使用 Connect；仅当不需要兼容浏览器和 gRPC-Web 时才使用普通 gRPC
复杂的、以客户端需求为导向的读取	GraphQL
关系型数据	使用 PostgreSQL，并配备迁移和连接池
后台工作	使用队列，并采用幂等处理程序和 DLQ 策略
浏览器身份验证	使用 OIDC（采用 PKCE 的授权码模式）和 httpOnly Cookie
服务身份验证	平台支持时，优先使用工作负载身份（云 IAM、SPIFFE），而非长期静态凭证；不支持时（多云、第三方、遗留系统），使用短期令牌或签名的服务凭证
缓存	明确 TTL 和失效规则
可观测性	使用关联 ID、追踪、结构化日志和饱和度指标

转交其他技能

• 仅涉及前端的工作 -> software-frontend
• 基础设施配置和集群设计 -> ops-devops-platform
• 不涉及实现的 API 契约设计 -> dev-api-design
• BaaS 平台选择（数据/身份验证层） -> software-baas-platforms
• PaaS 托管平台选择（计算层：Vercel、Fly.io、Railway、Render、Cloudflare Workers、Deno Deploy） -> software-paas-hosting
• SQL 调优和索引深度分析 -> data-sql-optimization
• 架构设计和迁移编排 -> software-database-design
• WebSockets、SSE 和实时传输设计 -> software-realtime
• 安全审查和威胁建模 -> software-security-appsec
• 更广泛的系统架构 -> software-architecture-design
• C#/.NET 后端服务（ASP.NET Core、EF Core、Minimal API） -> software-csharp-backend

---

工作流

1. 确认真正的约束：延迟、团队技能、运行时、合规性、数据模型或交付速度。
2. 根据约束选择传输方式和框架，而不是盲目追逐潮流。
3. 定义边界：
   • 请求和响应契约
   • 身份验证和授权规则
   • 错误模型
   • 幂等性和速率限制
4. 定义数据路径：
   • 架构和迁移
   • 事务边界
   • 连接池和查询预算
   • 缓存和失效规则
5. 定义异步路径：
   • 队列语义
   • 重试责任归属
   • 去重和 DLQ
6. 完成前加入可运维性保障：
   • 超时和取消
   • 健康检查
   • 结构化日志和追踪
   • 部署和回滚预期

---

技术选型

根据最关键的运行约束进行选择：

• TypeScript 占比较高的团队 -> 保留仓库现有的框架和 ORM；对于新服务，使用 Fastify 加 Drizzle（与 Fastify/Drizzle 模板匹配），对于 DI 密集型 CRUD 应用，使用 NestJS 加 Prisma；对于边缘或多运行时目标，使用 Hono
• 需要经过审计的 SQL 和可预测的并发 -> 使用 Go 和 sqlc/pgx
• 依赖 Python 生态或与 ML 相邻 -> 使用 FastAPI 和 SQLAlchemy
• 重视内存安全和明确性 -> 使用 Rust、Axum 和 SQLx
• 以边缘或无服务器为首选 -> 使用轻量、无状态的处理程序，并为 CPU 和超时设置严格预算

如果实际需求是“以更少的自定义服务代码快速交付身份验证、存储和实时功能”，请先使用 软件 BaaS 平台。

---

后端不可妥协的要求

变更正确性约定。

对于每个可能被外部重试的变更操作，在选择传输方式或框架之前，先定义幂等性范围、事务边界、授权时机和可观察的终态。在可能的情况下，将幂等性记录与业务写入一起持久化；区分“尚未尝试”“已提交”和“结果未知”。重试必须返回原始结果或安全地恢复，绝不能重复产生效果。

类别	规则
API	对于可能发生重试的变更端点，必须使用幂等键
API	列表端点必须明确支持分页（limit/cursor），并至少支持一个筛选条件
API	错误必须结构化且可供机器读取（RFC 9457 Problem Details）
API	健康检查端点必须将存活状态（/healthz）与就绪状态（/readyz）分开
数据	在宽表或高吞吐路径上，不得使用 SELECT *
数据	明确保留事务；不得使用隐式的环境事务
数据	新增或变更的查询计划在上线前必须使用 EXPLAIN ANALYZE 验证
数据	在需要可审计性的热点路径上，绕过 ORM 便利层
依赖项	每次出站调用都必须设置明确的超时；不得无限期等待框架默认行为
依赖项	重试只能由一个层负责（客户端与服务之间不得重复重试）
依赖项	添加缓存前必须记录缓存失效规则
依赖项	后台任务必须可安全重试且可观察（在开始/完成/失败时记录结构化日志）
运维	每个请求都必须携带关联 ID，并将其传递给所有下游调用
运维	跟踪、日志和指标中的标识符必须一致（不得使用不同的身份标识）
运维	慢速路径必须设定明确的延迟预算（以 p99 为目标，而不是“足够快”）
运维	部署流程必须包含回滚步骤和冒烟检查清单

---

多租户决策

对于存储多个客户数据的任何服务，都必须明确决定租户模式；应按租户层级选择，而非为整个产品只做一次选择。

• **模型：**共享架构 + 通过行级安全（RLS）强制执行 tenant_id（适用于大量小型租户；隔离取决于每条查询路径）/ 每租户一个架构（适用于中等数量的租户和一定程度的定制；迁移需要分批执行）/ 每租户一个数据库（适用于受监管或规模极大的租户，以及需要按租户恢复或满足数据驻留要求的场景；运维成本最高）。
• **租户上下文传递：**从已验证身份的主体中推导租户，绝不使用客户端提供的字段；在处理程序、任务和出站调用中传递租户上下文；在事务本地设置该上下文（兼容连接池器），未设置时默认拒绝；缓存键、幂等键、存储前缀和搜索索引都必须限定租户范围。
• **噪声邻居：**按租户设置速率限制、队列并发数和语句超时；为大型租户分配独立分区或设置限制。使用跨租户读取测试验证隔离性。

规则：rules/common/security.md 会在每次编码会话中加载此不变量。

详情、RLS SQL 和连接池陷阱： references/database-patterns.md。

---

负载与故障预算

对于每个下游依赖，都要限制正在处理的请求和排队的工作量。达到上限时，用 429 或 503 拒绝新工作，并在适用时提供 Retry-After；不要接收无法在调用方截止时间前完成的工作。传递取消信号，为响应预留时间，并在影响关键路径之前削减低优先级工作。指定唯一的重试责任方、重试预算、带抖动的指数退避策略，以及幂等性约定；在负载下测试依赖变慢或故障时的表现，观察 p99、内存和队列深度能否恢复。有关弹性测试设计和故障预算审查，请加载 qa-resilience。

作业运行时选择

当服务已运行 PostgreSQL、作业量符合经过测量的数据库容量，且可以通过短事务认领每项作业时，使用 PostgreSQL 支持的队列。当吞吐量、隔离性或运维责任足以证明引入另一个依赖合理时，使用托管消息代理或由 Redis 支持的工作进程。当作业必须在崩溃或长时间等待后恢复多步骤工作流时，使用持久化执行；选择前先检查该运行时的重试和历史记录语义。数据库队列需要 FOR UPDATE SKIP LOCKED、租约到期、幂等操作、毒性作业处理和队列深度监控。关于认领和 outbox 的替代方案，请参阅消息队列与后台作业。

---

性能与可靠性排查

服务变慢或不稳定时，请按以下顺序排查：

步骤	检查项	信号
1	查询行为和 N+1 问题	EXPLAIN 输出、ORM 查询日志显示重复的相同查询
2	索引和执行计划	大表上的顺序扫描；外键或筛选列缺少索引
3	连接池和队列深度	连接池等待时间持续偏长；空闲连接耗尽
4	超时和取消缺口	请求超出截止时间仍未结束；出站调用未传递上下文
5	缓存或读取方式优化机会	短时间内反复执行结果相同的查询；热门读取路径没有失效机制
6	运行时或层级限制	CPU 限流、内存压力、上游的速率限制标头

在了解真正的瓶颈之前，不要添加缓存。

---

生产就绪检查清单

• 对于已变更的部分，Backend Non-Negotiables 中的每一项均已满足
• 为每个队列使用方定义 DLQ 策略（毒性消息如何处理）

导航

核心参考资料

• references/operational-playbook.md — 核心后端模式：任务流程、API、身份验证、错误、缓存、断路器
• references/backend-best-practices.md — 为此技能新增技术栈模板的元指南；仅在编写模板时阅读，不要在后端实现工作期间阅读
• references/edge-deployment-guide.md
• references/infrastructure-economics.md
• references/database-patterns.md
• references/message-queues-background-jobs.md
• references/rpc-and-transport-patterns.md
• references/go-best-practices.md
• references/rust-best-practices.md
• references/python-best-practices.md
• references/nodejs-best-practices.md
• C#/.NET -> software-csharp-backend（由其负责 C#/.NET 后端指南）
• data/sources.json

共享审查工具

在相应工作流步骤处于活动状态时阅读以下内容之一，不要提前阅读：

• backend-api-review-checklist.md — 在 Production Readiness Checklist 步骤阅读
• secure-code-review-checklist.md — 任务包含安全审查交接时阅读
• auth-utilities.md — 实现身份验证时阅读（工作流步骤 3）
• error-handling.md — 定义错误模型时阅读（工作流步骤 3）
• config-validation.md — 设置环境/配置时阅读
• resilience-utilities.md — 定义重试、超时或异步路径时阅读（工作流步骤 5-6）
• logging-utilities.md — 接入结构化日志时阅读（工作流步骤 6）
• testing-utilities.md — 为限定范围的切片编写测试时阅读
• observability-utilities.md — 接入跟踪和指标时阅读（工作流步骤 6）

模板

根据此任务在 Technology Selection 中作出的选择，加载对应模板，不要加载整套模板：

• template-nodejs-prisma-postgres.md — NestJS/以 CRUD 为主的 TS 默认模板
• template-nodejs-fastify-drizzle-postgres.md — Fastify/Drizzle TS 默认模板
• template-go-fiber-gorm.md — Go，以 ORM 为主
• template-go-chi-sqlc-pgx.md — Go，经过审计的 SQL
• template-rust-axum-seaorm.md — Rust，以 ORM 为主
• template-rust-axum-sqlx.md — Rust，显式 SQL
• template-python-fastapi-sqlalchemy.md — Python/与 ML 相邻
• 其他技术栈：Django REST、Express、Spring Boot
• 企业级 .NET（C#）模板 -> software-csharp-backend/assets

相关技能

调用以下任一基础技能前先通过筛选： 每项基础技能都包含 When to Apply / When to Skip 部分。如果任务符合跳过条件，请改用其中指定的基础技能，不要引入任务不需要的原语。

• software-architecture-design
• software-security-appsec
• ops-devops-platform
• qa-resilience
• qa-testing-strategy
• foundations-queueing-theory — Little 定律、M/M/c 和 Kingman 公式，用于消息队列和限流器设计中的队列容量规划
• foundations-distributed-systems — CAP、一致性模型、法定人数规划，以及服务网格和 RPC 模式的幂等性契约
• foundations-reliability-theory — MTBF/MTTR、可用性组合，以及面向 SLO 的后端设计中的错误预算计算
• software-code-review
• dev-api-design
• data-sql-optimization

经验循环

如果之前的决策或注意事项与当前任务相关，请查阅 learnings.consolidated.md（如果存在）；仅在需要查看历史记录或没有其他文件可用时，才查阅 learnings.md。否则，请跳过这两个文件。

应用相关经验后，如果你遇到了值得记住的模式、值得避免的错误，或令人意外的领域事实，请通过 agents-skills-feedback-loop/scripts/append_learning.py 向 learnings.md 追加一条带日期的条目。不要修改 SKILL.md 本身。