堆栈

设计与多媒体 社区

技能解读

当前原文的自动摘译,尚未人工审校。

主题

主题 · 何时使用 · 参考错误处理 · 异常过滤器、域错误 -> HTTP 映射 · reference/error-handling.md 配置 · 环境变量、配置模块、验证 · reference/config.md 身份验证 · 守卫、JWT 策略、RBAC · reference/auth.md API 设计 · 端点、DTO、Swagger、分页 · reference/api-design.md

陷阱

NestJS 代码库中 Claude 特定的故障模式:从域/应用程序层抛出 HttpException - Claude 默认在任何地方都出现 HTTP 异常。领域层必须抛出特定于领域的异常;异常过滤器将它们映射到 HTTP 响应。使用 process.env.X 代替 ConfigService — Claude 出于习惯而使用了 process.env。始终注射ConfigService并使用.get()。

关键规则(始终适用)

域层不得导入 HTTP 异常 - 使用域异常,在过滤器中映射 从不直接访问process.env - 在防护中使用 ConfigService Auth,而不是在服务中 - 域接收所有输入/输出的经过验证的用户上下文 DTO - 切勿直接公开实体 模块内的相对导入 - 跨模块的路径别名

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
设计与多媒体
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@tomevault-io · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
即装即用
是否需要外部接口密钥
不需要
兼容的系统
未声明(默认跨平台)
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
  • 读取环境变量
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

NestJS-specific implementation of DDD + Hexagonal + CQRS patterns. For the underlying theory (aggregates, domain events, architecture layers), see `engineering-toolkit:engineering-foundations`. This skill covers the NestJS-specific HOW. Before applying any topic, read its reference file in `reference/`.

## Topics

| Topic | When to Use | Reference |
|---|---|---|
| **Error Handling** | Exception filters, domain error -> HTTP mapping | `reference/error-handling.md` |
| **Config** | Environment variables, config modules, validation | `reference/config.md` |
| **Auth** | Guards, JWT strategies, RBAC | `reference/auth.md` |
| **API Design** | Endpoints, DTOs, Swagger, pagination | `reference/api-design.md` |
| **Code Structure** | Where to place code, resolving circular imports | `reference/code-structure.md` |
| **Logging** | Structured logging with Pino, correlation IDs | `reference/logging.md` |
| **Domain Model (NestJS)** | @nestjs/cqrs AggregateRoot, EventPublisher | `reference/nestjs-domain-model.md` |
| **TypeORM Migrations** | Creating database migrations | `reference/typeorm-migrations.md` |
| **TypeORM Queries** | Writing queries and transactions | `reference/typeorm-queries.md` |

## Architecture Overview

```
+------------------------------------------------------------------+
|                     PRESENTATION LAYER                            |
|  apps/ (HTTP Controllers, DTOs, Request/Response handling)        |
+------------------------------------------------------------------+
|                     APPLICATION LAYER                             |
|  modules/ (Commands, Queries, Handlers, Events)                   |
+------------------------------------------------------------------+
|                       DOMAIN LAYER                                |
|  libs/common/domain/ (Entities, Value Objects, Enums)             |
+------------------------------------------------------------------+
|                    INFRASTRUCTURE LAYER                            |
|  libs/ (Repositories, External APIs, Database, Messaging)         |
+------------------------------------------------------------------+
```

## Quick Decision Guide

```
Writing an endpoint?
  -> reference/api-design.md + reference/code-structure.md

Handling errors?
  -> reference/error-handling.md

Setting up config/env?
  -> reference/config.md

Adding authentication?
  -> reference/auth.md

Writing a database query?
  -> reference/typeorm-queries.md

Creating a migration?
  -> reference/typeorm-migrations.md

Implementing a domain model with events?
  -> reference/nestjs-domain-model.md

Adding logging?
  -> reference/logging.md
```

## Gotchas

Claude-specific failure modes in NestJS codebases:

- **Throwing `HttpException` from domain/application layer** — Claude defaults to HTTP exceptions everywhere. Domain layer must throw domain-specific exceptions; the exception filter maps them to HTTP responses.
- **Using `process.env.X` instead of ConfigService** — Claude reaches for `process.env` out of habit. Always inject `ConfigService` and use `.get()`.
- **Putting auth logic in services** — Claude tends to add `if (!user.isAdmin)` checks inside service methods. Auth belongs in guards; services receive already-validated context.
- **Returning entities directly from controllers** — Claude skips DTO mapping when "it's the same shape anyway." Always use response DTOs, even if they mirror the entity — the contract must be explicit.
- **Circular imports between modules** — Claude creates circular dependencies when wiring cross-module services. Use `forwardRef()` as last resort; prefer restructuring.
- **Logging message-first instead of context-first** — Claude writes `logger.log('User created', { userId })` instead of `logger.log({ userId }, 'User created')`. Pino expects context object first.
- **Raw SQL when QueryBuilder suffices** — Claude jumps to raw SQL for anything beyond `.find()`. Follow the hierarchy: built-in methods > QueryBuilder > raw SQL.
- **Forgetting to release QueryRunner** — Must always release in a `finally` block. Claude sometimes puts `release()` only in the happy path.
- **Importing from other module's internal paths** — Use the module's public API (barrel exports), not deep `../other-module/internal/file` imports.

## Key Rules (Always Apply)

- **Domain layer MUST NOT import HTTP exceptions** — use domain exceptions, map in filters
- **Never access `process.env` directly** — use ConfigService
- **Auth in guards, not in services** — domain receives validated user context
- **DTOs for all input/output** — never expose entities directly
- **Relative imports within modules** — path aliases across modules
- **Context-first logging** — structured fields before message string
- **Query hierarchy** — built-in methods first, query builder second, raw SQL last resort
- **Release query runners** — always in a `finally` block

---
> Source: [anpham1925/claude-marketplace](https://github.com/anpham1925/claude-marketplace) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。