Node.js Backend Engineering

定位

像老到、代码洁癖但不炫技的全栈工程师一样设计 Node.js 后端：先理解业务语言和变化方向，再选择最小足够的结构；先保护数据、权限、幂等和可观测性，再谈模式；先让一个真实用例闭环，再抽象。

架构不是目录名。架构是边界、依赖方向、状态一致性、故障语义和演进路径。

代码细节、语法洁癖、类型写法和局部重构交给 nodejs-code-style。本 Skill 负责系统组织、架构选择、DDD/ports-adapters/CQRS/事件/生命周期等后端工程判断。

工作流

1. 读现状。
   • 找入口：HTTP/RPC/CLI/queue/cron/webhook。
   • 找核心对象：用户、任务、订单、集合、额度、支付、消息、文件等。
   • 找副作用：DB、缓存、队列、第三方、邮件、对象存储、AI 调用。
   • 找风险：权限、租户、额度、幂等、事务、重试、迁移、部署顺序。
2. 选架构形态。
   • 先用下面的“选择路由器”，不要默认套 DDD 或 Clean Architecture。
   • 一个系统可以组合多种形态，但每个用例只能有一个清晰主组织方式。
3. 定边界。
   • 入口层做协议适配和校验。
   • 用例层编排业务动作和事务语义。
   • 领域层表达规则、不变量、状态流转。
   • repository/client/gateway 隔离外部世界。
   • runtime 层处理配置、日志、指标、健康检查、启动关闭。
4. 垂直落地。
   • 按一个用户可感知的用例完成：契约、schema、service/domain、repository/client、错误、日志、测试。
   • 不把大规模重构和新行为混成一个 diff。
5. 验证和记录。
   • 跑最小必要验证：type-check、test、lint、build、局部 smoke。
   • 架构方向影响长期演进时，写 ADR 或更新已有设计文档。

架构选择路由器

组合方式

常见优雅组合：

• vertical slice + code style：多数业务功能的默认落地方式。
• vertical slice + DDD：复杂用例内部用 aggregate/value object 保护规则。
• hexagonal + external clients：第三方、DB、队列、AI provider 通过 adapter 隔离。
• DDD + domain events + outbox：跨 aggregate/module 副作用需要最终一致性。
• CQRS + read model：写侧保护不变量，读侧为查询体验和性能服务。
• strangler + ADR：老系统逐步替换，每个阶段记录取舍和回滚路径。

避免组合成“全家桶架构”。每加一层，必须能说清楚它降低了什么复杂度。

默认依赖方向

route/controller/worker -> use-case/application service -> domain rules
                                  |                         ^
                                  v                         |
                         repository/client/gateway --------+

原则：

• domain 不依赖框架、DB、HTTP、env、logger。
• service/use-case 不接具体 HTTP context，不返回 response。
• repository 管持久化和 JSON blob 边界，不调用第三方 API。
• client/gateway 管第三方协议、认证、超时、重试、错误映射，不改本地业务状态。
• worker/consumer 只管消息接收、ack/retry 策略和分发。

DDD 使用门槛

DDD 适合复杂业务，不适合装饰普通 CRUD。满足多个条件再用：

• 业务专家和代码需要共享一套稳定语言。
• 状态流转和不变量比数据表更重要。
• 一个操作内必须保护一致性边界。
• 规则散落导致重复 bug 或沟通成本高。
• 模块边界和团队边界正在变得重要。

如果只是增删改查、字段映射或简单列表查询，优先保持简单。

文件组织

优先按业务能力组织，而不是默认按技术层堆目录。已有项目是 layer-first 时，不强行大改；在现有结构里保持边界即可。

好名字：

• billing
• quotaReservation
• taskExecution
• creatorLookup
• collectionResult

警惕：

• utils
• helpers
• common
• manager
• core
• processor 但什么都处理

硬规则

• 不把业务逻辑塞进 route、queue consumer、middleware 或脚本入口。
• 不让 service 依赖具体 HTTP framework request/context。
• 不让第三方 response、DB JSON blob、AI provider 原始输出传遍业务层。
• 不在没有幂等和重试设计前修改 ack/retry/DLQ 语义。
• 不把安全、鉴权、额度、租户隔离、数据写入只交给前端、prompt、注释或约定。
• 不为单测提前抽一堆 interface；生产边界需要时再抽。
• 不写吞错后返回空结果的兜底，除非业务明确允许且可观测。
• 不用 DDD、Clean、CQRS、Repository 这些词掩盖贫血模型和无意义跳转。

按需读取

• references/architecture-decision-router.md：架构形态选择、组合和反组合。
• references/ddd-tactical-modeling.md：Bounded Context、Ubiquitous Language、Aggregate、Value Object、Domain Event、ACL。
• references/ports-adapters-and-clean-boundaries.md：Hexagonal/Clean 边界、port/adapter 何时抽、何时别抽。
• references/code-organization.md：目录、文件职责、导出边界、feature-first 与 layer-first。
• references/design-patterns.md：Strategy、Adapter、Repository、State Machine、Pipeline、Outbox 等模式选择。
• references/lifecycle-operations.md：配置、日志、指标、AsyncLocalStorage、AbortSignal、queue、cache、shutdown。
• references/real-code-patterns.md：use case、aggregate、repository port、client adapter、domain event/outbox 代码样例。
• references/evolution-and-decisions.md：ADR、strangler、增量迁移、重构与行为变更分离。
• references/review-checklist.md：后端工程评审清单。
• references/research-notes.md：参考资料和取舍来源。