nestjs

NestJS Engineering Practices

Objective

Deliver maintainable, verifiable, and secure NestJS changes without breaking the project's existing boundaries, naming, and technology choices.

This Skill provides decision rules, not scaffolding that must be copied verbatim. User requirements, repository AGENTS.md and project configuration take precedence over the examples in this document.

Workflow

1. Inspect the repository first; do not guess the tech stack based on the Skill:
   • Read package.json, lock files,nest-cli.json, and TypeScript and lint configuration.
   • Inspect main.ts, the root module, relevant feature modules, DTOs, entities or models, tests, and database migrations.
   • Check Git status, preserve the user's existing changes, and do not refactor unrelated code along the way.
2. Clarify the nature of the task: new feature, fix, diagnosis, review, security hardening, or structural adjustment.
3. Determine the external contract and module boundaries first, then implement the smallest complete change.
4. Reuse the project's existing frameworks and conventions; only recommend migration when the current approach causes real problems.
5. Verify according to risk, and truthfully report the commands executed, failure reasons, and uncovered items.

Project Compatibility Principles

• Do not mandate REST, TypeORM, JWT, MySQL, Redis, or Swagger; use them only when the repository already adopts them or the user explicitly requires them.
• Do not perform bulk renames in pursuit of a "standard directory." For existing projects, preserve auth/、system/user/、system/role/、system/menu/、system/dept/、file/、message/、codegen/、common/、config/ and other existing business semantics.
• Do not require changing system/dept to organization, nor require unifying roles, menus, and permissions into authorization。
• Follow the project's package manager, formatting rules, response structure, exception base classes, and database access patterns; when obvious defects are found, explain the risks and make localized fixes.

Core Rules

Modules and Dependencies

• Organize feature modules by business capability; Controllers handle protocol adaptation, Providers handle business use cases, and persistence implementations handle data access.
• Modules should only export Providers that are genuinely needed externally. Prefer unidirectional dependencies; extract shared capabilities or use injection tokens first, then consider forwardRef()。
• common/ may only depend on stable general abstractions, and must not depend in reverse on specific business modules.
• Split services by responsibility and reason for change, not solely by file line count.

DTOs, Models, and Interfaces

• Use classes with class-validator rules for HTTP input; do not use interfaces as runtime-validated DTOs.
• Separate the responsibilities of create, update, query, and response models; do not copy the VO / Form layering of Java projects.
• Entity should only express persistence; do not use it directly as an external response, and do not accept the entire request payload for mass assignment.
• Server-controlled fields must be explicitly mapped via a whitelist. Password hashes, deletion flags, tenants, permissions, and audit fields must not be overwritten by ordinary requests.
• Database bigint identifiers should remain strings in the API and TypeScript to avoid exceeding the safe integer range.

HTTP Contracts and Exceptions

• Configure the global prefix and version only once; Controllers should use relative business paths.
• Lists may use GET /users with pagination parameters; do not mandate an additional /page。
• Resource updates use /:id；PUT to indicate a full replacement,PATCH Indicates a partial update. Do not let Body ID and Path ID become two sources of truth.
• Success responses can be wrapped uniformly, but exceptions must preserve the correct HTTP status, such as 400, 401, 403, 404, 409, 429, and 500.
• For unknown exceptions, log the request ID and server-side context, and return a stable generic message to the client without leaking stack traces, SQL, or secrets.

Data, Security, and Side Effects

• Use transactions for atomic operations such as multi-table writes, state changes, and auditing; execute cache invalidation, messages, and SSE notifications after the transaction commits.
• Do not modify the ORM or framework global prototype to inject business behavior; use explicit helpers, repository wrappers, or query builder functions.
• Treat authentication information, passwords, verification codes, refresh tokens, upload paths, and runtime secrets as sensitive data.
• Permission identifiers should follow the project's existing naming and not mix add/edit and create/update。

Comments

• Comments explain "why," business invariants, security decisions, boundary conditions, and non-obvious side effects, and do not restate the code.
• Use JSDoc/TSDoc for externally exported contracts, complex rules, and compatibility constraints; do not mechanically fill in @param and @returns。
• DTO fields should preferably express constraints jointly through validators and OpenAPI metadata.
• Use private readonly userServicefor injected members; do not add a _ prefix just to indicate private.

Read References on Demand

Only read the reference files relevant to the current task:

• Directories, module boundaries, circular dependencies, and service splitting: read references/architecture.md。
• Controller, routing, DTO, validation, and response contracts: read references/rest-dto-validation.md。
• TypeORM, entities, soft deletion, queries, and transactions: read references/typeorm-transactions.md。
• Login, JWT, RBAC, data permissions, files, and configuration security: read references/auth-security.md。
• Type quality, testing, comments, and delivery checks: read references/testing-comments.md。

Completion Criteria

• Changes conform to the current repository's actual tech stack and naming, without introducing unnecessary new layers.
• Requests are validated at runtime, and output does not expose entity-internal fields or sensitive information.
• Dependency direction is clear; new cross-module dependencies have a clear justification and no avoidable cycles.
• Data writes satisfy transaction and concurrency requirements, and the timing for executing external side effects is clear.
• Use the project's native commands to complete an appropriate amount of typecheck/build, lint, unit tests, and relevant e2e tests.
• Do not mask failures by loosening types, disabling rules, deleting assertions, or weakening tests.
• In the final explanation, state the changes made, verification results, remaining risks, and whether there are baseline failures unrelated to this task.