Controller
职责
Controller（api 包）是 HTTP 请求的入口适配层，负责：
- 接收并解析请求参数（Query、Path、Body）
- 调用鉴权注解（
@AdminAuth、@FrontAuth等） - 委托
service完成业务，封装统一响应（ApiResult、@DingoResponse） - 记录操作日志（
@ShopLog等，管理端常见）
Controller 不应包含复杂 SQL、跨表事务编排、或可复用的领域规则；这些属于 service 及以下层级。
放置位置
ecshopx-<domain>/src/main/java/cn/shopex/ecshopx/<domain>/api/
├── admin/v1/ # 管理后台 API
└── front/v1/ # 商城 / 小程序 / H5 前台 API开放 API 的 HTTP 控制器集中在 ecshopx-openapi 模块（openapi.thirdapi.v1 / v2），业务 Bundle 通过 openapi 包提供 Port 实现，详见 路由与 API 分组。
真实类路径示例
管理端 — 商品
cn.shopex.ecshopx.goods.api.admin.v1.ItemsController- 源文件：
ecshopx-goods/src/main/java/cn/shopex/ecshopx/goods/api/admin/v1/ItemsController.java - 路由前缀：
@RequestMapping("/api/v1/goods")
前台 — 商品
cn.shopex.ecshopx.goods.api.front.v1.ItemsController- 源文件：
ecshopx-goods/src/main/java/cn/shopex/ecshopx/goods/api/front/v1/ItemsController.java - 路由前缀：
@RequestMapping("/api/v1/h5app/wxapp/goods")
订单 — 前台支付
cn.shopex.ecshopx.orders.api.front.v1.PaymentController- 源文件：
ecshopx-orders/src/main/java/cn/shopex/ecshopx/orders/api/front/v1/PaymentController.java - 路由前缀：
@RequestMapping("/api/v1/h5app/wxapp/trade")
禁止事项
| 禁止 | 说明 |
|---|---|
| 在 Controller 写复杂 SQL 或直接注入 Mapper | 数据访问应经 service → repository / mapper |
| 跨模块直接注入对方 Bundle 的 Mapper / Repository | 应通过 Port 或 dispatch 事件 |
| 在 Controller 内编排长事务、多步补偿逻辑 | 下沉至 service 或专用 Orchestrator |
| 绕过统一响应与异常约定 | 使用项目既有 @DingoResponse、全局异常处理 |
| 前台与后台共用同一 Controller 类 | 按 admin / front 分包，鉴权与路径分离 |