跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

backend-dev-guidelines

Backend architecture principles, layering, error handling, logging patterns for NestJS. Use when designing NestJS modules, writing service logic, structuring error handling, or setting up structured logging.

sabahattink · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add sabahattink/antigravity-fullstack-hq --skill backend-dev-guidelines

技能说明


name: backend-dev-guidelines description: Backend architecture principles, layering, error handling, logging patterns for NestJS. Use when designing NestJS modules, writing service logic, structuring error handling, or setting up structured logging.

Backend Development Guidelines

NestJS Layered Architecture

src/
├── modules/
│   └── users/
│       ├── users.module.ts         # DI wiring
│       ├── users.controller.ts     # HTTP layer — parse, validate, delegate
│       ├── users.service.ts        # Business logic
│       ├── users.repository.ts     # Data access
│       ├── dto/
│       │   ├── create-user.dto.ts
│       │   └── update-user.dto.ts
│       ├── entities/
│       │   └── user.entity.ts
│       └── users.spec.ts
├── common/
│   ├── filters/                    # Global exception filters
│   ├── guards/                     # Auth/RBAC guards
│   ├── interceptors/               # Logging, transform
│   ├── decorators/                 # Custom decorators
│   └── pipes/                      # Validation pipes
└── config/
    └── configuration.ts

Controller Layer

Controllers should be thin: validate inputs, call services, return responses.

// users/users.controller.ts
import {
  Controller, Get, Post, Put, Delete,
  Body, Param, Query, ParseIntPipe,
  UseGuards, HttpCode, HttpStatus,
} from '@nestjs/common'
import { ApiTags, ApiOperation, ApiBearerAuth } from '@nestjs/swagger'
import { JwtAuthGuard } from '../common/guards/jwt-auth.guard'
import { CurrentUser } from '../common/decorators/current-user.decorator'
import { UsersService } from './users.service'
import { CreateUserDto } from './dto/create-user.dto'
import { UpdateUserDto } from './dto/update-user.dto'
import { PaginationDto } from '../common/dto/pagination.dto'

@ApiTags('users')
@ApiBearerAuth()
@UseGuards(JwtAuthGuard)
@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Get()
  @ApiOperation({ summary: 'List users with pagination' })
  findAll(@Query() pagination: PaginationDto) {
    return this.usersService.findAll(pagination)
  }

  @Get(':id')
  findOne(@Param('id', ParseIntPipe) id: number) {
    return this.usersService.findOneOrFail(id)
  }

  @Post()
  @HttpCode(HttpStatus.CREATED)
  create(@Body() dto: CreateUserDto, @CurrentUser() actor: AuthUser) {
    return this.usersService.create(dto, actor)
  }

  @Put(':id')
  update(
    @Param('id', ParseIntPipe) id: number,
    @Body() dto: UpdateUserDto,
    @CurrentUser() actor: AuthUser,
  ) {
    return this.usersService.update(id, dto, actor)
  }

  @Delete(':id')
  @HttpCode(HttpStatus.NO_CONTENT)
  remove(@Param('id', ParseIntPipe) id: number) {
    return this.usersService.remove(id)
  }
}

Service Layer

// users/users.service.ts
import { Injectable, NotFoundException, ConflictException } from '@nestjs/common'
import { InjectRepository } from '@nestjs/typeorm'
import { UsersRepository } from './users.repository'
import { CreateUserDto } from './dto/create-user.dto'
import { PaginationDto } from '../common/dto/pagination.dto'
import { User } from './entities/user.entity'
import { hash } from 'bcrypt'

@Injectable()
export class UsersService {
  constructor(private readonly repo: UsersRepository) {}

  async findAll(pagination: PaginationDto) {
    return this.repo.findPaginated(pagination)
  }

  async findOneOrFail(id: number): Promise<User> {
    const user = await this.repo.findById(id)
    if (!user) {
      throw new NotFoundException(`User #${id} not found`)
    }
    return user
  }

  async create(dto: CreateUserDto, actor: AuthUser): Promise<User> {
    const existing = await this.repo.findByEmail(dto.email)
    if (existing) {
      throw new ConflictException('Email already registered')
    }

    const passwordHash = await hash(dto.password, 12)

    return this.repo.create({
      ...dto,
      passwordHash,
      createdById: actor.id,
    })
  }

  async update(id: number, dto: UpdateUserDto, actor: AuthUser): Promise<User> {
    const user = await this.findOneOrFail(id)
    return this.repo.save({ ...user, ...dto })
  }

  async remove(id: number): Promise<void> {
    const user = await this.findOneOrFail(id)
    await this.repo.softDelete(user.id)
  }
}

Repository Layer

// users/users.repository.ts
import { Injectable } from '@nestjs/common'
import { DataSource, Repository } from 'typeorm'
import { User } from './entities/user.entity'
import { PaginationDto } from '../common/dto/pagination.dto'

@Injectable()
export class UsersRepository extends Repository<User> {
  constructor(private dataSource: DataSource) {
    super(User, dataSource.createEntityManager())
  }

  async findById(id: number): Promise<User | null> {
    return this.findOne({ where: { id, deletedAt: undefined } })
  }

  async findByEmail(email: string): Promise<User | null> {
    return this.findOne({ where: { email: email.toLowerCase() } })
  }

  async findPaginated(dto: PaginationDto) {
    const [data, total] = await this.findAndCount({
      skip: (dto.page - 1) * dto.limit,
      take: dto.limit,
      order: { createdAt: 'DESC' },
      where: { deletedAt: undefined },
    })
    return {
      data,
      meta: { total, page: dto.page, limit: dto.limit, pages: Math.ceil(total / dto.limit) },
    }
  }
}

DTOs with Validation

// dto/create-user.dto.ts
import {
  IsEmail, IsString, MinLength, MaxLength,
  IsOptional, IsEnum, Matches,
} from 'class-validator'
import { Transform } from 'class-transformer'
import { ApiProperty } from '@nestjs/swagger'

export enum UserRole {
  ADMIN = 'admin',
  USER  = 'user',
}

export class CreateUserDto {
  @ApiProperty({ example: 'jane@example.com' })
  @IsEmail()
  @Transform(({ value }: { value: string }) => value.toLowerCase().trim())
  email: string

  @ApiProperty({ minLength: 8 })
  @IsString()
  @MinLength(8)
  @MaxLength(72) // bcrypt max
  @Matches
阅读完整来源 ↗