nestjs-features-performance

NestJS 特性、扩展与性能

选择生命周期与关注点相匹配的 NestJS 原语。先诊断限制资源，再优化或分布式部署系统。

执行前冲突检查

编辑文件或运行任何会更改状态的命令前，先协调当前有效指令。只读检查可以继续。

前提条件

检查仓库说明、已安装的版本、引导程序／传输和部署配置、测试、运维契约以及基准测量。保留用户更改；在选择优化或交付操作前，确认生命周期、证据、环境和授权。仅在决策范围重叠时，阅读其他有效技能。

主要职责

此技能负责 Nest 生命周期、API／错误／安全契约、测试层、性能证据、可靠性、可观测性和运行时交付。若已安装且相关，请与以下技能协调：

• nestjs-architecture-principles：模块、依赖、数据和事务边界。
• nestjs-oop-design-patterns：对象职责、不变量和模式。
• nestjs-professional-software-engineering：实现和验证。
• nestjs-code-audit：只读质量证据和去重报告。
• nestjs-feature-audit：特定分支的路线图门槛和功能报告。
• nestjs-git-commit-pr-message：经授权的 Git 发布和 CI 后续处理。

这些是决策边界，而非必需依赖。将工作移交给其他工作流时，仍须保留领域职责。

冲突测试

检查是否存在互不兼容的编辑／契约、命令顺序或副作用、职责冲突，以及未满足的版本、证据、授权或仓库前提。按明确的用户意图、仓库契约、经验证的运行时限制，再到职责范围最窄的所有者，依次解决。每项决策只指定一位负责人；不要为满足互不兼容的建议而创建并行设计。若仍存在重大冲突，请在更改前暂停，并询问所缺的最少信息。审计必须保持只读；明确的修复授权仅适用于独立的实现阶段。

确定运行时基线

在建议或更改行为之前：

1. 阅读已安装的 NestJS／Node 版本、引导代码、适配器、模块、传输方式、持久化客户端、缓存／队列设置和部署清单。
2. 跟踪一个有代表性的请求、消息或作业，了解其经过守卫、管道、拦截器、处理器、提供者、持久化层和外部调用的完整路径。
3. 识别当前症状和证据：延迟百分位数、吞吐量、错误率、事件循环延迟、CPU、堆／GC、数据库耗时、连接池饱和度、外部延迟或队列积压。
4. 定义目标和工作负载。“让它更快”不是可衡量的验收标准。
5. 根据官方文档和仓库版本，检查框架与库的 API。

不要仅凭代码表面形式就声称性能有所提升。必须在具有代表性的工作负载下测量更改前后的表现。

将行为放入正确的 NestJS 功能中

请使用 references/feature-selection.md。

通用 HTTP 生命周期：

request
  -> middleware
  -> guards
  -> interceptors (before)
  -> pipes
  -> controller/resolver + providers
  -> interceptors (after, reverse order)
  -> exception filters for uncaught errors
  -> response

默认原则：

• 中间件： 原始协议预处理和关联上下文。
• 守卫： 针对执行上下文做出身份验证／授权决策。
• 管道： 输入验证与转换。
• 拦截器： 处理处理程序执行前后的行为、响应映射、计时、追踪或兼容的缓存。
• 异常过滤器： 最终的协议专属错误映射。
• 装饰器： 声明式元数据或提取已确立的上下文，不执行隐式 I/O。
• 提供程序／应用操作： 业务行为与编排。
• 队列／工作进程： 持久化、延迟处理、突发性或资源密集型工作。
• 事件： 已完成且有独立响应的事实；明确选择进程内传递还是持久化传递。

如需 API 和传输方面的指导，请加载 references/api-runtime.md。当相关风险在考虑范围内时，请参阅相应的规则手册：错误处理、安全、测试、API 设计和部署。

根据资源诊断性能

请使用 references/performance-diagnosis.md。

选择补救措施前，先对主要瓶颈进行分类：

瓶颈	证据	常见的首选措施
事件循环阻塞	事件循环延迟／利用率较高、CPU 回调热点	移除同步操作；限制输入；卸载 CPU 密集型工作
数据库	查询缓慢、N+1、连接池等待、锁、扫描行数过多	优化查询结构／索引；限制结果；缩短事务
外部 I/O	依赖调用链跨度占据主要延迟	设置截止时间、复用连接、限制重试、控制并发
内存／GC	堆增长、GC 暂停、OOM／重启	移除对象滞留；流式处理／限制数据；分析内存分配
序列化／日志记录	响应越大，CPU 开销或负载大小越高	选择字段；分页／流式处理；减少热点路径日志记录
容量	单实例性能稳定，但副本已饱和	使用无状态进程和安全依赖进行水平扩展

在证据明确瓶颈且已了解兼容性成本之前，不要切换到 Fastify、添加 Redis、引入工作线程或拆分服务。

扩展规则

请使用 references/scaling-reliability.md。

1. 保持 Web 副本无状态；将共享会话、锁、作业状态和协调工作转移到适当的外部系统。
2. 优先使用默认的单例提供程序。请求作用域会沿注入链传播，并增加每个请求的分配；仅在确有生命周期需求时使用。
3. 限制所有集合、页面、批次、队列并发数、重试次数、负载、上传内容和超时。
4. 确保作业和消息消费者具备幂等性。要假设消息可能重复投递，也可能发生部分失败。
5. 对瞬时故障使用带抖动的指数退避；绝不要盲目重试验证、授权或不变量错误。
6. 添加背压。拒绝、丢弃、暂停或排队处理负载，而不是任由内存和延迟无限增长。
7. 当面向用户的进程与后台工作在容量特征上有所不同时，应将二者分开。
8. 将缓存视为派生状态。定义键命名空间、TTL、失效机制、惊群行为和安全回退方案。
9. 关闭前先排空：停止接受工作，将就绪状态标记为未就绪，完成正在处理的工作或安全地重新排队，然后关闭资源。
10. 根据服务级别目标和饱和信号扩展，不要仅依据平均 CPU 使用率。

实施工作流

添加或更改功能

1. 找到正确的生命周期阶段和现有的仓库约定。
2. 明确契约、范围和失败行为。
3. 实现最小化的提供程序/组件，并在最小且适用的范围内绑定。
4. 隔离测试其行为，并在边界处测试其顺序/连接方式。
5. 当公共契约或运维契约发生变化时，更新 OpenAPI/schema、配置验证、遥测和文档。

设计或修复错误处理

1. 梳理所有入口点、当前公共错误契约、过滤器绑定、适配器/供应商错误、客户端依赖项以及部分副作用。
2. 对预期的业务、验证、身份/访问、冲突、暂时性、永久性、取消/超时和未知故障进行分类，不要解析错误消息。
3. 定义由应用程序负责的类型/结果，并在基础设施适配器处转换供应商错误，同时保留安全的原因信息。
4. 分别映射每个 HTTP、GraphQL、RPC/gRPC、WebSocket 或工作进程边界；保留一个不包含敏感信息的未知错误回退。
5. 在添加恢复逻辑之前，定义截止时间、取消、重试/幂等性、确认、事务和结果未知时的处理方式。
6. 绑定范围最小且正确的 NestJS 过滤器/处理程序，并根据适用情况验证混合模式、网关、适配器、流和进程致命错误路径。
7. 测试稳定契约、副作用、可观测性归属、敏感数据缺失以及重启/恢复行为。

优化慢速路径

1. 使用受控基准测试或跟踪进行复现。
2. 记录基线百分位数、吞吐量、错误和资源饱和度。
3. 对主要路径进行性能分析。
4. 每次只更改一个限制因素。
5. 使用相同的工作负载重复测试并进行比较。
6. 运行正确性和故障测试；更快但不正确的行为属于回归。
7. 记录容量限制和回滚信号。

规划扩展能力

1. 明确工作负载特征、SLO、一致性、持久性和成本约束。
2. 估算单实例容量，并找出共享依赖项的限制。
3. 根据实际资源边界，选择纵向调优、副本、工作进程、队列、分区或服务拆分。
4. 在增加容量之前，设计过载和部分故障的处理方式。
5. 根据风险，通过适当的负载、浸泡、突发和故障测试验证方案。

构建、部署或诊断生产环境

1. 确认源代码修订版本、不可变的制品/镜像摘要、目标环境和负责人。
2. 对比仓库意图、构建制品、预期部署和运行状态；不要仅凭配置文件推断线上状态。
3. 定义迁移/配置兼容性、发布策略、成功信号、中止阈值以及回滚或前向修复路径。
4. 通过仓库的交付机制应用经授权的最小变更。
5. 验证线上修订版本、就绪状态、有代表性的流量/工作、错误、延迟、饱和度、队列/依赖项以及排空行为。
6. 记录发布或事件证据，并将任何紧急偏差同步回声明状态。

生产就绪检查

在将功能称为生产就绪之前，请使用 references/production-readiness.md。至少验证配置、安全性、契约、资源限制、可观测性、健康状态/就绪状态、关闭和恢复。

参考路由

有关增强器的范围、生命周期、职责和经过测试的执行路径，请参阅 enhancer-composition.md。

任务	加载
选择中间件、守卫、管道、拦截器、过滤器、装饰器、事件、队列或调度器	feature-selection.md
构建 HTTP/GraphQL/WebSocket/SSE/微服务契约和测试	api-runtime.md
对故障进行分类、映射稳定错误，或设计过滤器和重试机制	error-handling.md
定义类型化错误/结果、公开代码、验证结构、Problem Details 或 HTTP 语义	error-taxonomy-contracts.md
为 HTTP、GraphQL、RPC/gRPC、WebSocket、工作进程或混合应用实现过滤器	exception-filters-transports.md
设计截止时间、取消、安全重试、致命进程处理、遥测或故障测试	failure-resilience-testing.md
审查身份验证、授权、验证、机密、输出或滥用控制	security.md
选择单元、模块、集成、契约、端到端或可靠性测试	testing.md
设计 DTO、响应、错误、分页、幂等性或版本控制	api-design.md
诊断延迟、CPU、事件循环、数据库、内存、缓存或 Fastify 选型	performance-diagnosis.md
添加副本、工作进程、队列、重试、幂等性、背压或分布式协调	scaling-reliability.md
设计构建、配置、迁移、健康检查、可观测性、发布或关闭控制	devops-deployment.md
构建 CI/CD、容器镜像、来源证明、推广或制品回滚	ci-cd-containers.md
配置或诊断 Kubernetes 工作负载、探针、资源、HPA、发布或终止	kubernetes-operations.md
定义 SLO、日志/指标/追踪、告警、仪表板、事件、备份或恢复	observability-sre.md
审查运维就绪情况和发布安全性	production-readiness.md

预期回复

对于性能／扩展性工作，请报告：

• 症状和目标
• 基线证据
• 主要限制因素
• 建议的更改及其权衡
• 正确性／故障风险
• 更改前后的验证计划

如果缺少证据，请提出在进行架构更改前所需的最小测量方案。

对于错误处理工作，请报告：

• **故障模型：**类别、稳定的代码／类型，以及预期行为与未知行为。
• **边界映射：**每个受影响入口点从应用到传输层的映射。
• **影响和韧性：**已提交／可能产生的副作用、截止时间、取消、重试／幂等性，以及恢复责任归属。
• **信息披露：**公开字段、脱敏、日志责任归属，以及敏感数据控制措施。
• **框架接线：**过滤器／处理程序范围、执行上下文、适配器／混合模式覆盖，以及致命进程行为。
• **验证：**契约、适配器、超时、重复、部分影响、隐私和重启测试。

对于 DevOps 工作，请报告：

• **发布标识：**源代码修订版本、制品／摘要、环境和负责人。
• **状态比较：**仓库意图、期望部署状态和观测到的运行时状态。
• **安全性：**迁移／配置兼容性、安全门禁和故障风险。
• **发布：**策略、成功／中止信号、观测窗口和容量影响。
• **验证：**线上修订版本、运行状况、代表性工作、遥测和排空。
• **恢复：**回滚或向前修复流程及其触发条件。