Appearance

API 控制器规范 ​

资源控制器 ​

应该 优先采用 REST 风格：资源化路径 + 标准 HTTP 动词（GET/POST/PUT/DELETE）。管理端与前台 必须 分控制器类，不得混用鉴权与路径前缀。

放置与命名 ​

ecshopx-<domain>/.../api/
├── admin/v1/   # 管理后台，如 @RequestMapping("/api/v1/goods")
└── front/v1/   # H5 / 小程序，如 @RequestMapping("/api/v1/h5app/wxapp/goods")
项规范示例
类名资源名 + ControllerItemsController
开放 API集中在 ecshopx-openapiopenapi.thirdapi.v1 / v2

路径前缀遵循 路由与 API 分组 约定。

单数还是复数？ ​

URL 路径与资源集合 推荐 使用复数形式（与历史 API 对齐时以仓库既有路由为准）。类名以业务资源语义命名，如 ItemsController（商品条目集合）。

职责边界 ​

控制器 只 做：

  1. 解析请求（@RequestParam、@PathVariable、@RequestBody）；
  2. 触发鉴权（@AdminAuth、@FrontAuth 等）；
  3. 调用 service，返回 ApiResult 或 @DingoResponse 包装结果。

禁止：

禁止项说明
复杂 SQL / 直接注入 Mapper经 Service → Repository/Mapper
跨模块注入对方 Mapper使用 Port 或 dispatch
长事务与多步补偿下沉 Service / Orchestrator
私有「工具方法」堆积提取到 Service 或独立组件

代码体量与注释 ​

  • 单方法 应该 ≤ 约 80 行；复杂逻辑下沉 Service；
  • 方法名 应该 自解释，不必 为每个路由方法写 JavaDoc；
  • 复杂业务规则（为何如此处理）可以 在方法内或 Service 写简短注释；
  • 禁止 遗留未使用的 public 方法；禁止 大段注释掉的死代码。

响应与异常 ​

  • 必须 使用项目统一响应与全局异常处理（@DingoResponse、模块 ExceptionAdvice）；
  • 不要 在 Controller 内 try/catch 吞掉异常后返回随意 JSON，除非有明确降级产品需求。

相关章节 ​