---
description: Controller、Service、ServiceImpl三层代码模板规范，微服务鉴权、多租户适配
globs: ["**/controller/**/*.java","**/service/**/*.java"]
alwaysApply: false
---
# 冲突优先级声明
Java编码、达梦实体规范优先级高于本文件。

# Controller & Service & ServiceImpl 三层开发规范
## 一、Controller 分层规范
### 1. 基础约束
1. 存放路径：controller/；
2. AdminController：@RestController + @RequestMapping("/api/admin/business/xxx")；
3. AppController：@RestController + @RequestMapping("/api/app/business/xxx")；
4. 统一添加 @Tag 接口文档注解，标注模块名称；
5. 依赖注入仅注入对应Service，禁止直接注入Mapper、Feign（Feign在Service层注入）；
6. 接口权限校验：@PreAuthorize("@ss.hasPermission('business:goods:query')")；
7. APP端接口不添加后台管理类权限标识，仅做登录Token校验。

### 2. 标准CRUD接口模板
1. 新增 POST /create：入参SaveReqVO，返回雪花ID；添加@Idempotent、@ApiAccessLog；
2. 更新 PUT /update：入参SaveReqVO（携带id）；添加@Idempotent、@ApiAccessLog；
3. 删除 DELETE /delete/{id}：路径ID，添加@ApiAccessLog；
4. 分页查询 GET /page：入参PageReqVO，返回PageResult<XxxRespVO>；
5. 单条详情 GET /get/{id}：返回XxxRespVO；
6. 导出 GET /export-excel：分页查询数据，导出Excel，添加导出权限校验。

### 3. Controller禁止项
❌ 禁止Controller编写业务逻辑、数据库查询；
❌ 禁止Controller捕获业务异常，全局统一异常处理器处理；
❌ 禁止Controller直接注入Mapper、Feign接口；
❌ 禁止Admin与APP接口写在同一个Controller；
❌ 禁止接口路径、权限标识混用后台与移动端。

## 二、Service 接口规范
1. 存放路径：service包，命名 XxxService；
2. 仅定义业务抽象方法，不编写实现逻辑；
3. 方法返回值规范：
    - 新增：String（雪花ID）
    - 更新/删除：void
    - 单条查询：XxxDO（不存在抛异常）
    - 分页查询：PageResult<XxxDO>
4. 所有方法添加中文Javadoc注释，写明入参、返回值、异常场景；
5. 跨服务远程调用方法，在Service接口定义对应方法。

## 三、ServiceImpl 实现类规范
1. 存放路径：service/impl，命名 XxxServiceImpl，实现XxxService；
2. 添加 @Service 注解；
3. 依赖注入：@Resource 注入Mapper、Feign接口、其他Service；
4. 业务分层逻辑：
    1. 参数校验（非空、长度、状态合法性）；
    2. 数据库CRUD操作，批量数据处理；
    3. 跨服务Feign远程调用；
    4. 数据转换DO ↔ VO/DTO；
    5. 组装分页、返回结果；
5. 多租户自动过滤：使用MyBatis-Plus租户插件，无需手动拼接租户条件；
6. 不存在数据统一抛出业务异常，禁止返回null。

## 四、通用三层统一约束
1. 入参校验统一使用Hibernate Validator注解，Controller层自动校验；
2. 所有分页返回统一包装 PageResult，包含总条数、当前页、数据列表；
3. 时间、创建人等公共字段由MyBatis-Plus自动填充，无需手动set；
4. 软删除统一框架逻辑删除，ServiceImpl不手动修改deleted字段。
