接口设计约定

本文说明 art-design-pro-server 的接口设计约定。它适合在新增接口、排查响应结构、补权限码或维护 Swagger 文档时阅读。

接口基础约定

后端接口默认使用统一前缀和 URI 版本：

/api/v1/**

常见接口形态：

GET    /api/v1/<resource>
POST   /api/v1/<resource>
PATCH  /api/v1/<resource>/:id
DELETE /api/v1/<resource>/:id

项目中也存在少量特殊用途接口，例如健康检查、通知流、文件访问等，应按具体控制器实现为准。

Controller、DTO、Service 分工

层级	职责
Controller	定义路由、HTTP 方法、Swagger 标注、权限声明、参数入口
DTO	定义请求参数、校验规则和 Swagger schema
Service	编排业务逻辑、调用 Prisma、处理业务状态
Repository	在复杂模块中封装可复用的数据访问逻辑

建议 Controller 保持薄层，只做请求入口和响应出口，不承载复杂业务流程。

统一响应结构

普通接口返回值会被 TransformInterceptor 包装为：

{
  "code": 200,
  "msg": "请求成功",
  "data": {}
}

可用 @SuccessMessage() 自定义成功消息：

@SuccessMessage('创建成功')

特殊接口如果需要保留原始响应结构，可以使用 @SkipTransform()。

参数校验

全局 ValidationPipe 已启用：

{
  whitelist: true,
  forbidNonWhitelisted: true,
  transform: true
}

这意味着：

• DTO 中没有声明的字段会被拒绝。
• 请求参数会按 DTO 类型尝试转换。
• 新增接口时应优先补 DTO，而不是在 Service 中手动解析任意对象。

权限声明

接口权限使用 @ApiPermission() 声明：

@ApiPermission(API_PERMISSION_CODES.USER.CREATE)

权限码统一维护在：

src/modules/api-permissions/api-permissions.constants.ts

新增需要授权的接口时，建议同步确认：

• 控制器方法是否声明了权限码。
• 权限码是否加入常量定义。
• 初始化或同步脚本是否能写入对应权限数据。
• 前端按钮权限、接口调用和后端权限码是否能对应。

错误处理

异常由 AllExceptionFilter 统一转换。常见映射包括：

异常来源	返回行为
HttpException	按异常状态码和消息返回
Prisma 唯一约束冲突	返回冲突提示
Prisma 外键或记录不存在	返回可读业务提示
JWT 过期或无效	返回未授权状态
未知异常	非生产环境返回异常消息，生产环境返回通用错误

接口中不建议直接拼接临时响应结构。优先抛出 Nest 标准异常或返回业务数据，让全局过滤器和拦截器处理统一格式。

Swagger 约定

后端在 Swagger 启用时挂载到：

/docs

新增接口时建议补齐：

• @ApiTags()
• @ApiOperation()
• @ApiResponse() 或相关响应说明
• DTO 上的字段说明
• 需要鉴权的接口补 @ApiBearerAuth()

新增接口检查清单

新增接口完成后，建议确认：

• 路由路径、HTTP 方法和版本前缀符合当前约定。
• DTO 校验覆盖必填字段、枚举、分页、时间范围等参数。
• Service 中业务逻辑清晰，复杂查询已拆到 repository 或专门 service。
• 权限码、Swagger、默认数据或同步脚本已按需要补齐。
• 前端 src/api 中有对应封装，页面没有绕过统一请求层。