堆栈
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 设计与多媒体
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 即装即用
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 读取环境变量
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
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 -->
章节与文件索引
按说明文件中的顺序排列。
主题
陷阱
关键规则(始终适用)
文件/命令 -> engineering-toolkit:engineering-foundations · reference/ · reference/error-handling.md · reference/config.md · reference/auth.md · reference/api-design.md · reference/code-structure.md · reference/logging.md
内容校验值 -> 58701f688d03
当前原文的自动摘译,尚未人工审校。
主题
主题 · 何时使用 · 参考错误处理 · 异常过滤器、域错误 -> HTTP 映射 ·
reference/error-handling.md配置 · 环境变量、配置模块、验证 ·reference/config.md身份验证 · 守卫、JWT 策略、RBAC ·reference/auth.mdAPI 设计 · 端点、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 - 切勿直接公开实体 模块内的相对导入 - 跨模块的路径别名