backend-engineering

后端工程方法论

后端工程是构建应用底层服务端系统的技艺，涵盖 API、服务、数据访问、集成，以及让架构落地的运行时行为。本方法论涵盖 software-architecture 中目标设计之后、qa-methodology 中质量验证之前的实现工作；如果必须先对当前系统进行逆向工程，请使用 software-architecture-analysis。它让运行时边界、事务行为、消息处理和共存衔接点变得可执行，但不负责周边架构或迁移决策。

后端工程师的职责范围

你负责	你不负责
API 实现——REST/gRPC/GraphQL 端点、请求验证、响应格式化、错误处理、中间件链	API 契约由 api-design-and-evolution 负责；服务拆分和目标边界由 software-architecture 负责
服务逻辑——业务规则、工作流编排、状态管理、后台作业处理	部署流水线和基础设施——由 platform-engineering 负责
事件驱动实现——领域事件发布、outbox/inbox 协调、处理程序幂等性、重放和故障路径	事件契约的所有权和交付语义——由 api-design-and-evolution 负责
服务内部的迁移衔接点——适配器、可选路径、权威性检查和实现交接	跨系统迁移生命周期和切换决策权——由 migration-engineering 负责
数据库访问模式——查询设计、连接管理、事务边界、N+1 检测、分页	数据平台和模型策略由 data-architect 负责；模式和流水线操作由 data-engineering 负责
集成代码——第三方 API 客户端、webhook 处理程序、消息队列生产者和消费者	代码审查和质量门禁——由 qa-methodology 负责
服务级可观测性埋点——结构化日志、指标、追踪钩子	可观测性基础设施和可靠性策略由 platform-engineering 和 site-reliability-engineering 负责
服务级测试——业务逻辑单元测试、API 契约集成测试	测试策略和自动化——由 qa-methodology 负责

参考文件

参考文件	加载时机
references/api-patterns.md	设计或实现 API 端点时 — 资源建模、版本控制、分页、错误响应格式、请求验证
references/service-patterns.md	组织服务逻辑时 — 整洁／六边形／分层架构、依赖注入、中间件组合、请求生命周期、后台任务
references/event-driven-service-implementation.md	实现事件驱动的应用流程时 — 领域事件、工作单元、事务性 outbox/inbox、幂等处理程序、重试／重放、可观测性和故障处理
references/migration-coexistence-patterns.md	确保新旧实现能够安全共存时 — 适配器、绞杀者模式交接、防腐边界、双路径、权威性和移除条件
references/database-testing.md	数据库访问模式（连接池、查询优化、N+1 检测、分页策略、事务边界、读写分离、复制延迟）和服务级测试（业务逻辑单元测试、使用测试容器／WireMock 对 API 契约进行集成测试、使用 Pact 进行契约测试、测试夹具、CI 集成）
references/integration-patterns.md	与外部系统集成时 — 带退避的重试、熔断器、幂等键、Webhook 验证、消息队列消费者
references/error-handling.md	系统化处理错误时 — 分类（客户端错误与服务器错误）、结构化响应、异常处理模式、可观测性关联
references/source-index.md	本综合内容的来源和归属说明；审查范围或来源边界时加载

模板

模板	使用时机
templates/service-design-record.md	设计或重构服务时 — 在一份便于审查的记录中涵盖结构、API 表面、数据访问、错误处理和测试计划
templates/error-handling-taxonomy.md	定义或审查服务的错误契约时 — 分类、响应格式、重试／幂等策略和错误路径测试

脚本

脚本	使用时机
scripts/n1-query-spotter.py	扫描 Python 源代码，查找潜在的 N+1 查询模式（循环内类似查询的调用）；使用 --json 可生成适用于 CI 的输出，发现问题时以状态码 1 退出

相关技能

• programming-principles — DDD 负责有界上下文、聚合、领域语言、仓储和领域建模指导。本技能将这些决策应用于实现衔接处，而非重复该目录中的内容。
• api-design-and-evolution — 负责事件／消息契约、交付语义、兼容性和面向消费者的 API 决策。
• migration-engineering — 负责跨系统迁移分类、兼容窗口、对账、切换、恢复、弃用和清理。本技能仅实现服务本地的共存衔接处。
• software-architecture — 负责服务拆分和目标边界策略；后端工程负责实现已批准的边界。
• data-engineering — 负责架构迁移和流水线运维；应用代码可以提供这些运维所用的仓储或事务接口。
• secure-software-engineering — 负责威胁建模、授权、机密、不可信输入和安全验收证据。
• release-engineering — 负责渐进式交付、制品晋级、发布门禁和回滚机制。
• postgres — 负责诊断数据库问题中的 PostgreSQL 侧问题：配置审查、索引和查询计划问题、清理／膨胀、备份／PITR、复制和故障转移。应用层数据访问模式由此处负责；引擎层运维则交由该技能处理。
• supabase — 负责基于 Supabase 构建：迁移、RLS、Auth、Storage 和 Edge Functions。若要评估 Agent 执行 Supabase 任务的能力，请使用其 agent evals harness reference。

核心原则

接口就是契约 — API 边界是服务级契约。每个端点签名、请求架构、响应格式和错误代码都是对消费者的承诺。破坏性变更是协作协调问题，而不是版本升级。

业务逻辑是重心 — 将业务规则与框架关注点、传输协议和基础设施细节隔离。结构良好的服务能够适应 HTTP 库、数据库驱动程序和部署平台的变更。

在合适的位置处理错误 — 在有足够上下文、能够妥善处理错误的边界处捕获错误。捕获过早会丢失上下文；捕获过晚则无法恢复。

为失败而设计，而不只是为成功而设计 — 每次外部调用都可能失败。每个数据库连接都可能断开。每条消息都可能重复。幂等性、重试和优雅降级不是优化项，而是必需项。

在合适的层级测试 — 业务逻辑使用单元测试。API 契约使用集成测试。服务边界使用契约测试。每个层级都能发现不同类别的故障。

实现决策路径

1. 命名有界上下文、聚合/不变量边界和事实来源。对于 DDD 选择，请使用 programming-principles，而不是在此重建其目录。
2. 将传输层、代理、数据库、时钟和供应商相关事项置于由应用层或面向领域的代码拥有的端口之后。由基础设施层实现这些端口。
3. 对于会更改持久状态并发出事实的命令，加载聚合、调用领域行为，并在一个工作单元中提交状态和 outbox 记录。 不要让事务在网络调用期间保持打开状态。
4. 对于传入消息，在边界处验证信封，在消费者的职责范围内进行去重，应用处理程序，并仅在其持久化效果提交后确认消息。加载事件引用，以便进行重放和有毒消息判定。
5. 如果新旧路径并存，记录每项操作的权威路径、比较输出的方式，以及允许移交或移除的证据。加载迁移参考以了解实现衔接点；将迁移生命周期交由其他负责人处理。
6. 为领域/应用行为添加单元测试，并为事务、outbox、inbox、重复消息、重试、重放和恢复行为添加边界集成测试。

退出标准

当实现具备明确的依赖方向、事务和权责边界、已分类的故障/重试行为、可观测的消息或并存路径、针对重复和故障场景的专项测试，以及指向每项范围外决策对应相邻负责方的清晰链接时，此技能即告完成。