后端开发约定

1. 标准模块结构

主系统模块一般按下面组织：
packages/api/src/modules/{module-name}/
├── {module-name}.module.ts
├── controllers/
│ ├── console/
│ └── web/
├── services/
└── dto/

2. 控制器装饰器

@ConsoleController(path, groupName)

主程序后台接口，默认路由前缀：
/consoleapi/{path}
例子：
@ConsoleController("user", "用户管理")
export class UserController {}

@WebController(path | options)

主程序前台接口，默认路由前缀：
/api/{path}
例子：
@WebController("article")
export class ArticleController {}

3. 常用装饰器

@Playground

取当前登录用户：
@Post
create(@Body dto: CreateDto, @Playground user: UserPlayground) { return this.service.create(dto, user.id);
}

@Public

公开接口，不走登录校验：
@Public
@Get("config")
config { return {};
}

@Permissions(...)

声明接口权限点：
@Permissions({ code: "role:create", name: "创建角色", action: "创建",
})
@Post
create {}

@MemberOnly(...)

声明会员功能访问点：
@MemberOnly({ code: "advanced:export", name: "高级导出",
})
@Post("export")
export {}

@BuildFileUrl([...fields])

自动把相对路径补成完整文件 URL：
@BuildFileUrl(["avatar", "items.*.cover"])
@Get(":id")
detail {}

@SkipTransform

跳过统一响应包装，适合 webhook、回调、原始流返回。

4. 参数校验

常用UUIDValidationPipe：
@Get(":id")
detail(@Param("id", UUIDValidationPipe) id: string) {}
上一篇请求处理链路下一篇BaseController 与 BaseService

共 319 篇文档 · 内容同步自官方帮助中心