From 32863c5ce3c07f736cdab438a364427482c1b83c Mon Sep 17 00:00:00 2001 From: zhangjf Date: Tue, 17 Feb 2026 10:22:58 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85=20Controller=20?= =?UTF-8?q?=E8=81=8C=E8=B4=A3=E4=B8=8E=E5=8F=82=E6=95=B0=E6=A0=A1=E9=AA=8C?= =?UTF-8?q?=E8=A7=84=E8=8C=83\n\n-=20=E5=9C=A8=E5=BC=80=E5=8F=91=E8=A7=84?= =?UTF-8?q?=E8=8C=83=E4=B8=AD=E6=96=B0=E5=A2=9E=208.4=20Controller=20?= =?UTF-8?q?=E4=B8=8E=E8=AF=B7=E6=B1=82=E5=8F=82=E6=95=B0=E6=A0=A1=E9=AA=8C?= =?UTF-8?q?=E8=A7=84=E8=8C=83\n-=20=E6=98=8E=E7=A1=AE=20Controller=20?= =?UTF-8?q?=E5=8F=AA=E8=B4=9F=E8=B4=A3=E6=95=B0=E6=8D=AE=E6=8E=A5=E6=94=B6?= =?UTF-8?q?/=E6=A0=A1=E9=AA=8C=E3=80=81=E8=B0=83=E7=94=A8=E4=B8=9A?= =?UTF-8?q?=E5=8A=A1Service=E5=92=8C=E5=B0=81=E8=A3=85=E8=BF=94=E5=9B=9E?= =?UTF-8?q?=E7=BB=93=E6=9E=9C\n-=20=E5=BB=BA=E8=AE=AE=E4=BD=BF=E7=94=A8=20?= =?UTF-8?q?@Valid/@Validated=20+=20@NotBlank/@NotNull=20=E7=AD=89=E6=B3=A8?= =?UTF-8?q?=E8=A7=A3=E5=81=9A=E5=BF=85=E5=A1=AB=E6=A0=A1=E9=AA=8C\n-=20?= =?UTF-8?q?=E6=8F=90=E4=BE=9B=E7=99=BB=E5=BD=95=E6=8E=A5=E5=8F=A3=E5=8F=82?= =?UTF-8?q?=E6=95=B0=E6=A0=A1=E9=AA=8C=E7=A4=BA=E4=BE=8B=E5=92=8C=E5=85=A8?= =?UTF-8?q?=E5=B1=80=E5=BC=82=E5=B8=B8=E5=A4=84=E7=90=86=E7=A4=BA=E4=BE=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/资金服务平台 FundPlatform 架构设计文档.md | 64 +++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/doc/资金服务平台 FundPlatform 架构设计文档.md b/doc/资金服务平台 FundPlatform 架构设计文档.md index 3211a44..f1799dd 100644 --- a/doc/资金服务平台 FundPlatform 架构设计文档.md +++ b/doc/资金服务平台 FundPlatform 架构设计文档.md @@ -3419,6 +3419,70 @@ fund-sys/ - 业务服务层使用 `com.fundplatform.sys.service` / `com.fundplatform.sys.domain` 等包名，与数据访问层在物理结构上清晰分离； - Controller 只依赖业务服务层，不直接依赖 `ServiceImpl` 或 Mapper。 +### 8.4 Controller 与请求参数校验规范 + +1. **Controller 职责** + - 仅负责： + - 接收请求数据（包含 Header、Path、Query、Body）； + - 调用**业务服务层**（`XxxService` / `XxxDomainService`）； + - 对业务层返回结果进行封装和格式转换（如封装为统一 `Result`）； + - 明确禁止在 Controller 中编写业务规则、事务控制、跨聚合业务编排等复杂逻辑； + - Controller 不直接依赖 MyBatis 的 `ServiceImpl` / Mapper，只依赖业务服务接口。 + +2. **请求参数校验（Bean Validation）** + - 强制启用 Spring Validation，对外暴露的接口必须进行参数校验： + - 使用 `@Valid` 或 `@Validated` 标注方法参数或类； + - 对必填字段使用 `@NotBlank`（字符串）、`@NotNull`（对象）、`@NotEmpty`（集合/数组）等注解； + - 对数值范围使用 `@Min`、`@Max`、`@Positive`、`@PositiveOrZero` 等注解； + - 对字符串长度使用 `@Size`； + - 推荐在 DTO 层（如 `LoginRequestDTO`、`CustomerCreateDTO`）上声明校验规则，而不是在 Entity 上； + - 统一使用全局异常处理（如 `@RestControllerAdvice`）拦截 `MethodArgumentNotValidException` / `ConstraintViolationException`，返回统一错误结构。 + +3. **示例：登录接口参数校验** + +```java +@Data +public class LoginRequestDTO { + + @NotBlank(message = "用户名不能为空") + private String username; + + @NotBlank(message = "密码不能为空") + private String password; +} + +@RestController +@RequestMapping("/api/v1/auth") +@RequiredArgsConstructor +public class AuthController { + + private final AuthService authService; + + @PostMapping("/login") + public Result login(@Valid @RequestBody LoginRequestDTO request) { + LoginVO vo = authService.login(request); + return Result.success(vo); + } +} +``` + +4. **示例：全局参数校验异常处理** + +```java +@RestControllerAdvice +public class GlobalExceptionHandler { + + @ExceptionHandler(MethodArgumentNotValidException.class) + public Result handleValidationException(MethodArgumentNotValidException ex) { + String message = ex.getBindingResult().getFieldErrors().stream() + .findFirst() + .map(FieldError::getDefaultMessage) + .orElse("请求参数不合法"); + return Result.error(400, message); + } +} +``` + --- ## 九、附录