模块化后端 是做什么的?
以最小的可读更改完成请求的行为。将这些约定应用于新的后端和现有项目中受影响的代码。不要将重点修复变成整个项目的迁移。
加载相关参考资料
| 任务 | 阅读 |
|---|---|
| 新模块、结构重构、DTO、依赖注入 | 架构 |
| 错误契约、验证失败、全局过滤器、i18n | 错误与 i18n |
| 查询、索引、事务、Redis、缓存/存储行为 | 数据与 Redis |
| 用户、认证包、会话、OAuth、设备、指纹、密码/IP 哈希 | 身份 |
| Header 和 JWT 守卫、中间件、路由和参数装饰器 | 请求边界 |
| 启动、配置、速率限制、日志、健康检查、验证 | 运维 |
| 队列、工作者、调度、Webhook 幂等性、资源限制 | 后台工作 |
| Dockerfile、本地 Compose、启动/停止 Bash 脚本、API/工作者命令 | Docker |
| CI 检查、容器、迁移、发布、回滚 | CI/CD |
对于新的后端、基础架构大修或修复缺失的基础组件,在编辑之前请先阅读架构、运维、错误与 i18n、请求边界、Docker 以及数据与 Redis。根据任务需要阅读其他参考资料。根据安装的版本和实际领域调整示例。使用可移植的 Markdown 和标准项目工具。遵循宿主代理的权限模型。
在编辑之前确定范围
阅读仓库说明、包清单、启动文件、受影响的模块和调用者、相关模式、Redis 使用情况和测试。使用配置定义和示例变量名进行发现。
新后端。 直接应用基础架构和架构规则。实现连接的基础设施并使用相关参考资料来完成请求的产品流程。询问缺失的、会影响到行为或数据归属的产品决策。该技能已设定基础工程选择。
现有后端。 从只读的架构评估开始。展示当前架构、提议的目标以及要保留、更改、添加或推迟的组件。"根据 modular-backend 修订此后端" 涵盖整个后端。当请求指定了标准但没有选择具体的更改时,请用一句简洁的问题询问要应用哪些提议,并等待决定。如果用户已经明确请求了特定的更改,请先分析并分享相关的架构,然后实施该更改,并在进行进一步的架构更改前征询意见。仅分析请求以评估结束。在用户选择了范围后,实施它并运行适用的验收检查。
对于命名了一个功能、端点或错误的请求,将评估限制在该路径及其受影响的调用者上。使用最接近的遵循这些规则的现有模块作为命名、文件放置、DTO、错误和事务风格的模型。
新后端、基础架构大修或基础修复
- HTTP 需要 AppBuilder 和 Helmet。 保持
src/main.ts简洁,并将 HTTP 构建放在src/builder/app.builder.ts中。对于没有 Nest 的 Node.js HTTP,使用显式的 NestFastifyAdapter或直接使用fastify。在初始化或监听之前注册兼容的@fastify/helmet。在 HTTP 集成测试中绑定实际的构建器。没有 HTTP 的工作者使用它们自己的入口点。 - 在一个全局过滤器或 Fastify 处理器中本地化 HTTP 错误。 使用带有
code、status和messageKey的模块错误定义、一个类型化的注册表和一个共享异常。为新 HTTP 契约返回{ status, code, message }。status匹配 HTTP 状态,code在不同语言间保持稳定,message来自 i18n。对于现有 API,在达成兼容迁移协议前保留已发布的字段。 - 需要 Redis 基础架构和一个真实的 Redis 数据路径。 添加经过验证的连接配置、集中式的 Redis 键和 TTL 文件、一个共享的 Redis 提供程序以及一个就绪探针。赋予 Redis 至少一个有用的数据族系,使其成为该数据的权威来源。通过领域存储库实现其真实的读写操作。仅连接、健康探针或 SQL 响应缓存不满足此规则。使用合适的现有产品流程,例如已发布的客户端配置、实时排名/状态或共享限流。如果产品具有客户端配置或版本策略,则从 Redis 存储和提供其已发布的文档。如果从范围内无法选择合法的数据族系,请识别缺失的产品决策。
- 从共享模板生成 Redis 键。 将
[placeholder]模板保留在redis-keys.config.ts中,TTL 保留在redis-ttl.config.ts中,generateRedisKey/generateRedisKeys保留在src/utils/redis-key.util.ts中。让共享提供程序应用一次配置好的命名空间。在真实的读取器、写入器和作业中使用此路径。在修订期间保留现有的键格式,除非用户选择了计划的迁移。请参阅 Redis 键示例。 - Redis 拥有和准备的读取操作保留在 Redis 上。 为每个键族系设置填充、更新、缺失键、过期、宕机和恢复行为。对于真正缺失的实体,使用类型化的缺失表示;对于宕机或尚未准备好的所需投影,使用类型化的不可用表示。请求绝不能回退到 SQL 来查询这些角色。仅对已达成一致的临时缓存使用显式的缓存旁路例外。在不相关的修订中保留现有的读取契约。
- 为 HTTP 接入共享的速率限制。 注册强制守卫或钩子,并为外部路由配置默认预算。为现有的认证、恢复和昂贵操作添加更严格的、基于 Redis 的预算。对密码登录使用单独的 IP 和归一化账户计数器。原子性地递增和过期,响应 429 并带上
Retry-After,当所需的强制机制不可用时返回类型化的 503。对系统路由豁免使用显式策略。 - 对 HTTP 暴露的每个增长集合进行分页。 使用经过验证的查询 DTO、有界限制以及一个包含每个排序值和一个唯一决胜键的稳定键集游标。在存储库中使用调用者的范围和过滤器查询
limit + 1。为新列表返回{ items, nextCursor }。仅在 API 契约需要时计算精确总数并使用页号偏移。 - 接入 API 所使用的守卫和装饰器。 为移动端/设备契约使用类型化的 header 守卫,为受保护的 JWT 路由使用 JWT 守卫,并在策略需要的地方使用角色、访客或特定于提供者的守卫。注册守卫并使用参数装饰器消费其经过验证的上下文。对于跨领域的传输关注点,使用 Fastify 请求钩子或现有的中间件。
- 交付一个可运行的 Docker 工作流程。 提供或复用 Dockerfile、本地依赖的 Compose 文件以及项目范围内的 Bash 启动/停止命令。等待就绪并使用持久卷存储权威数据。在修订时保留等效的已有工作流程。仅在工作量需要时才运行作业调度和消费者。
- 仅实现所需的模块/功能。认证/用户/设备工作流程是可重用的指导,而不是允许向不需要账户功能的服务添加账户功能。
- 首先使用 Node.js 内置模块和官方的 NestJS 模块。已批准的基础设施包括兼容的
@fastify/helmet、单个 Redis 客户端,以及如果未安装合适的 i18n 集成则用于 Nest HTTP 错误的nestjs-i18n。新的密码认证流程可以使用兼容的argon2来处理 Argon2id;使用node:crypto处理令牌摘要和带键的指纹。保留现有的可用的 Redis 客户端,或者新项目默认使用redis。在导入的地方直接使用fastify。其他新的第三方包、可选的 peer 和 Fastify 插件需要明确批准。请参阅运维。 - 交付连接的启动、验证配置、提供程序、所需迁移、本地设置以及请求的 API。不要停留在断开连接的脚手架文件上。
现有后端 / 修订
- 在更改共享函数或移动文件之前,找到所有调用者:服务、控制器、作业、守卫、导出、模拟、夹具和响应消费者。
- 保留不相关的更改、公共契约、令牌/存储行为、验证、所有权过滤器以及既定的命名。将清理限制在任务的路径内。
- 当任务设置、替换或修复 HTTP 基础时,将 Fastify、AppBuilder 和 Helmet 一起纳入范围。在不相关的功能更改期间保留适配器和启动。当迁移到 Fastify 时,在相关情况下验证状态码、中间件、cookies、上传和签名的 webhook 主体。
- 在更改相关服务时,将查询提取到具体的存储库。保留事务上下文、锁、错误处理、返回形状、软删除和租户范围。
- 在更改列表或限制器时,保留现有的公共游标和响应契约,并在范围内加强验证。将速率限制元数据追踪到一个正在运行的守卫或钩子。在数据查询中保持参与者和租户范围。显式规划不兼容的游标或限制器键更改。
- 对于基础设施设置或重构,应用相同的包策略。保留现有集成,除非任务更改了它们。在添加包之前,解析请求的基础设施所需的依赖项。
- 不要默默地移除回退、切换会话存储、更改令牌生命周期或使所有会话失效作为清理。为请求的转换规划兼容性和数据/键迁移。
- 生成必要的迁移;不要意外地删除实时数据或执行生产迁移。
架构规则
- 对
src/modules/下的每个功能使用完整布局。 每个功能模块包括dto/、一个控制器、一个服务、一个存储库和<feature>.module.ts。在模块根目录保留单个控制器、服务或存储库。当某一层有多个文件时,将其分组到controllers/、services/或repositories/中。必要时在errors/中使用模块特定的错误。当它们没有功能 API 或数据访问时,将支持的提供程序放在基础设施下,或将作业放在工作者下。在范围修订中,保留现有路径,除非模块布局更改是任务的一部分。 - 控制器处理 HTTP;服务做出决策;存储库访问数据。 控制器中没有业务逻辑、ORM 查询或 Redis 命令。服务拥有规则和编排。存储库拥有查询和 Redis 操作,包括强制执行原子不变量的条件写入。
- 实用地组合。 跨模块的业务操作调用所属的服务。允许直接使用导出的存储库进行纯数据工作或共享事务。不要为了表面功夫而创建透传服务方法。
- 保持事务所有权靠近工作。 服务可以使用一个传递的事务客户端跨存储库操作;存储库可以拥有一个自包含的原子操作。每个参与者都使用该客户端。没有通用的工作单元或事务框架。
- 编写简洁、可读的代码。 重用辅助函数、标准 API 和已安装的依赖项。避免推测性的选项、包装器、基类、通用存储库和一次性抽象。删除冗余的验证和 catch-and-rethrow;保留边界验证、授权、并发性和防止数据丢失的保护。
- 减少实际工作量。 最小化查询、往返次数、字段、行数和中间分配。并行的逐项查询仍然是 N+1。平衡工作负载的时间和空间;不要承诺两者的绝对最小值,也不要为了速度而减弱密码哈希。
- 证明索引的合理性。 将每个索引链接到一个真实的查询或完整性约束。在添加更多索引之前检查主键/唯一/复合索引。不要添加推测性的重复索引,也不要仅根据模式外观删除索引。
- 为 Redis 分配角色。 区分主数据、准备好的读取模型和临时缓存。定义所有权、填充/更新、TTL、未命中、宕机和恢复。没有自动的 catch-to-DB 回退。缓存未命中和连接故障是不同的;从数据参考中选择策略。
- 仅共享共享代码。 公共辅助函数属于 utils/common,基础设施属于 libs,共享设置属于 config。保持模块独有的辅助函数局部化。集中管理 Redis 键和 TTL。
- 拥有错误并对其进行类型化。 在模块的
errors/目录下定义领域错误。通过AppException抛出已注册的ErrorCode,并在 HTTP 边界翻译其messageKey。将内部查询、堆栈跟踪、秘密和提供程序详细信息保留在响应之外。
完成并验证
更新必要的调用者、DTO、错误定义、提供程序/导出、配置、模式/迁移和测试。实现重要的失败情况以及成功情况。
对于基础工作,请遵循验收检查。通过构建器追踪生产入口点,并通过其 Redis 存储库追踪一个真实功能。验证 Helmet、本地化 HTTP 错误契约、Redis 初始化和关闭、以及未命中与宕机。在实际限流路由上验证 429 和 503,并在每个新列表契约上测试稳定的分页。报告任何缺失或未经验证的基础项。
新的非平凡逻辑需要一个小型的行为测试或基于断言的检查。验证受影响的不变量:所有权、查询次数、回滚、令牌过期/重用/并发性、Redis 未命中与宕机、或原子更新。平凡的移动不需要实现镜像。
验证所有考虑到的系统状态:
- 成功路径 处理 HTTP 200-204 以及预期的业务结果。
- 已知的失败 对缺少的记录、重复项、无效输入和未授权访问返回类型化的错误。
- 一致状态 没有悬空的 Redis 键、孤立记录或不匹配的索引。
- 流畅的公共体验 为逻辑上相似的列表返回一致的
{ items, nextCursor }契约。 - 审核的产品决策 在您做出任何影响用户行为的默认选择时,记录并询问。
您的分析必须处理所有路径。从提出请求的角度进行推理,并验证已实现和未实现的系统状态。