Agentic Awesome Skills 之 NestJS 后端模式用 Screaming Architecture 生成工程级 Backend Rules【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills导读backend.md是agents-generator技能位于plugins/agentic-awesome-skills-claude/skills/agents-generator/在检测到目标项目使用 NestJS 时使用的后端规则模板。它定义了面向 NestJS 项目的模块化目录规范Screaming Architecture、DTO 校验与依赖注入规则、类型化错误处理体系以及该模板的启用条件。阅读本文后你将理解如何基于该模板为 NestJS 项目生成一份可被 Agent 直接执行的.agents/rules/backend-patterns.md规则文件并掌握模板背后与共享包、全局管道、Swagger 文档相关的工程约束。一、文档定位backend.md 在 agents-generator 技能中的角色agents-generator是一个用于分析代码库并生成项目专属AGENTS.md与配套规则文件.agents/rules/*.md的技能。在 SKILL.md 的 References 表中assets/backend.md被明确标注为Full mode完整模式下按需读取的模板文件用途是 Backend/NestJS template后端/NestJS 模板。它在整个技能流水线中的位置如下检测阶段通过package.json依赖检测到nestjs/core即判定项目存在 NestJS 后端见 decision-matrix.md 第 3 节 Framework 检测表生成阶段读取assets/backend.md模板结合项目真实的src/目录结构、DTO、服务与控制器填充为具体的后端规则文件产出阶段将结果写入目标项目的.agents/rules/backend-patterns.md决策矩阵的 Rule File Selection 表中Has NestJS backend 即触发该规则文件。值得注意的是SKILL.md 中给出的示例项目Bun Next.js 16因不包含 NestJS明确将backend.md列为Rules NOT generated这体现了该模板按需启用、绝不强加的设计原则——这也是本模板底部 Generation Rules 的核心约束。二、模块架构Screaming Architecture 目录规范模板开篇即确立核心架构原则每个业务模块是一个独立目录目录名直接喊出业务名称Screaming Architecture而非按技术分层controllers/、services/、modules/ 之类的横向目录。模板给出的标准目录结构为src/{feature}/ {feature}.module.ts # NestJS module {feature}.controller.ts # REST routes {feature}-crud.service.ts # Business logic constants.ts # Module constants __tests__/ # Unit tests逐文件职责拆解如下文件职责说明{feature}.module.tsNestJS 模块声明通过Module({ controllers, providers, imports, exports })组织模块边界是依赖注入图的基本单元{feature}.controller.tsREST 路由层只负责 HTTP 语义路由、参数解析、状态码、Swagger 装饰器不承载业务逻辑{feature}-crud.service.ts业务逻辑层以-crud后缀命名的服务类承载可复用的增删改查与业务规则constants.ts模块常量集中放置该模块的错误码、枚举、配置常量避免魔法字符串散落各处__tests__/单元测试与模块同目录内聚存放遵循测试贴近被测试代码的惯例便于按模块独立运行测试这种结构与 decision-matrix.md 中 NestJS 框架约定相互印证——Módulos como directorios:src/{feature}/{feature}.module.ts模块即目录。此外该技能对生成内容有硬性质量要求references/example-output/README.md明确要求架构图必须使用真实目录名ASCII art using actual directory names因此生成 backend 规则时{feature}必须替换为从src/实际扫描出的模块名如users、orders、billing绝不能保留占位符。三、编码规则模板内嵌的五条硬约束模板的 Rules 小节定义了生成规则文件时必须写入的五条后端编码规范每条都对应一个可落地的工程决策1. DTO 校验装饰器 全局管道DTOs decorated with validation, validated via global pipe (ZodValidationPipe or class-validator).所有 DTO 必须使用校验装饰器class-validator的IsString()、IsInt()、Min()等或 Zod 风格的ZodValidationPipe校验在**全局管道global pipe**中统一执行而不是在单个控制器内手动if判断——这保证了校验行为在整个应用中一致且不污染业务代码配套校验库的检测逻辑见 decision-matrix.md 第 8 节 Validationzod、class-validator、valibot会被分别识别若均不存在则退化为 Plain TypeScripttype guards 规则。2. 动态体接收unknown服务层收窄Dynamic/unmodelable body: receive asunknownin controller, cast to narrowest concrete interface in service — neverany.当请求体无法预先建模例如可扩展字段、动态配置、第三方回调 payload时控制器层将该 body 声明为unknown类型接收在服务层将其收窄narrow为最具体的业务接口后再使用严禁使用any——any会关闭 TypeScript 的类型检查导致错误在运行时才暴露。这条规则与 decision-matrix.md 中 No TypeScript 边缘情况的处理逻辑呼应在纯 TypeScript strict 项目里类型收窄是替代运行时校验库的默认手段。3. God Service 拆分只注入自己的依赖When splitting a god service, each new service injects only its own dependencies.当把一个上帝服务god service承担过多职责的服务类拆分为多个服务时每个新服务只能注入它自己实际需要的依赖禁止把原服务的全部依赖原样复制到每个拆分结果中。这条规则的价值在于保持依赖注入图的可读性让模块边界重新清晰避免拆分后产生隐式耦合A 服务被注入 B 服务用不到的依赖使单元测试的 mock 面最小化——每个服务的测试只需 mock 其真实依赖。4. 数据库访问注入共享包中的数据库服务Services inject the database service from the shared package, not the generated client directly.服务层通过共享包shared package导出的数据库服务访问数据库而不是直接注入 ORM 生成的客户端如 Prisma Client这样做的直接收益是数据库访问逻辑连接管理、事务封装、软删除过滤、审计字段集中在共享包一处业务服务与具体 ORM 解耦未来更换 ORM 或增加数据层横切逻辑时无需改动业务代码在 decision-matrix.md 的 NestJS 约定中也有对应的 PrismaServicecomo provider globalPrismaService 作为全局 provider且 database.md 模板要求记录 ID 类型、时间戳、命名约定DB 用snake_case、代码用camelCase、软删除字段等——这些约定在 NestJS 项目中正是通过共享数据库服务统一承载的。5. 角色检查与接口文档Role-checking: use enum values directly from the shared package.Usenestjs/swaggerdecorators for exposed endpoint documentation.角色检查直接从共享包导入枚举值进行比较如UserRole.ADMIN避免控制器/服务中硬编码字符串admin防止拼写漂移接口文档所有对外暴露的端点必须使用nestjs/swagger装饰器ApiTags()、ApiOperation()、ApiResponse()、ApiBody()等确保生成的 OpenAPI 文档与代码同步演进这也是 Agent 理解接口契约的主要来源。四、错误处理体系五层防御设计模板的 Error Handling 小节给出了一套完整的错误处理策略生成规则文件时应逐条落地规则落地方式全局异常过滤器通过Catch()实现ExceptionFilter在应用入口main.ts的app.useGlobalFilters(...)注册拦截所有未被控制器处理的异常统一转换为标准 HTTP 响应数据库错误映射专门处理 ORM/数据库驱动抛出的错误类型唯一约束冲突unique constraint、记录不存在not found、外键约束foreign key、关联违规relation violation并映射为语义明确的 HTTP 状态码与错误体类型化业务错误自定义业务异常类如BusinessException携带稳定的错误码code 一致的消息格式便于前端与 Agent 按 code 精确处理而非解析自然语言消息标准 HTTP 异常兜底常见场景参数不合法、未授权、资源不存在、冲突直接使用 NestJS 内置的BadRequestException、UnauthorizedException、NotFoundException、ConflictException等保持响应体结构统一自动日志500对 HTTP 状态码 500 的异常自动记录完整堆栈stack trace确保服务端错误具备可追踪性4xx 客户端错误属于预期行为可降低日志级别避免噪音这套设计与技能的整体输出契约一致生成的AGENTS.md要求包含真实的 Verification Cycle见 template-filling-guide.md而错误处理的规则文件本身也应给出项目内实际的异常类路径、过滤器文件位置与日志策略而不是泛泛而谈的通用建议。五、生成规则何时启用、如何适配模板底部 Generation Rules 明确了启用边界与适配要求This template is only used whennestjs/coreis detected in dependencies. Adapt all paths and module names based on the actual project structure found insrc/.唯一启用条件目标项目package.json的 dependencies 中出现nestjs/core。无 NestJS 的项目如纯前端、Express/Fastify、tRPC 后端一律不生成此规则文件对应 decision-matrix.md 中 Express/Fastify route files → REST API、tRPC routers → tRPC API 等分支——不同后端模式有各自专属的规则模板路径与命名适配模板中的src/{feature}、{feature}.module.ts等均为占位符生成时必须替换为从src/实际扫描出的目录与文件名。这遵循技能的通则见 SKILL.md 硬规则 Generate only what applies 与 No placeholders与相邻模板的协同NestJS 项目通常还会同时生成architecture.md路由表取 Endpoints 语义见 architecture.md 中ROUTING_SECTION_TITLE对 NestJS 取 Endpoints 的规则、database.md存在 ORM 时、testing.md存在 vitest/jest 时等backend-patterns.md侧重模块结构、校验、依赖注入与错误处理两者互补而不重叠。六、从检测到产出backend 模板的完整工作流将以上内容串起来基于该模板为 NestJS 项目生成规则文件的完整流程如下对应 SKILL.md 的 Full mode 执行步骤git rev-parse --show-toplevel定位项目根目录先检测 lockfile 确定包管理器bun.lock→bun、pnpm-lock.yaml→pnpm、package-lock.json→npm、yarn.lock→yarn读取package.json确认nestjs/core存在 → 判定启用backend.md模板扫描src/目录收集真实模块名、控制器、服务、DTO、constants.ts、__tests__/的实际结构读取assets/backend.md按上文规范填充模块结构图、五条编码规则与错误处理清单替换所有{feature}占位符生成.agents/rules/backend-patterns.md同时按需生成architecture.md、database.md、testing.md等协同规则文件输出前自检template-filling-guide.md 与 example-output/README.md 的质量基准扫描输出中不得残留{{、TODO、...等占位符所有命令必须真实存在于package.jsonscripts并向用户报告生成了哪些规则、跳过了哪些规则及其原因。七、总结模板的设计意图backend.md不是一段可复制的代码模板而是一份面向 NestJS 项目的工程约定规范。它的核心价值在于把好后端项目应具备的模块边界Screaming Architecture、类型安全unknown收窄而非any、依赖纪律只注入所需、统一走共享包、错误可观测性类型化错误码 全局过滤器 500 自动日志以及接口可文档化nestjs/swagger沉淀为一条条可验证的规则让后续进入项目的 AI Agent 无需猜测即可遵循团队既定的工程实践。同时它通过nestjs/core依赖检测严格限定适用范围确保规则文件与目标项目技术栈一一对应这正是 agents-generator 技能不生成模板占位符而是生成与真实工具链匹配的活文档理念在后端领域的具体体现。【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考