整体架构

模块组成

forge-core 作为框架的核心实现层，对外只暴露三类 Bean：异常处理器、响应拦截器、版本路由扩展。

装配链路

本模块没有声明 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports。三大子系统全部依赖 Spring Boot 默认的组件扫描：

1. 业务工程的 @SpringBootApplication 启动类被加载，触发包扫描
2. Spring 在 classpath 上扫到 cn.cvking.forge.config.ApiVersionConfig、cn.cvking.forge.advice.GlobalResponseAdvice、cn.cvking.forge.exception.GlobalExceptionHandler
3. 三者分别以 @Configuration 与 @RestControllerAdvice 身份注册为 Bean
4. ApiVersionConfig 实现的 WebMvcRegistrations.getRequestMappingHandlerMapping() 在 Spring MVC 初始化阶段被回调，用 APIVersionHandlerMapping 替换默认的 RequestMappingHandlerMapping

装配前提

组件扫描只能扫到「启动类所在包及其子包」。如果业务工程启动类的包路径与 cn.cvking.forge 不在同一根包下，必须显式声明 scanBasePackages 把 cn.cvking.forge 也纳入扫描，否则三大 Bean 都不会被注册，框架特性全部失效。

三大子系统入口

子系统	入口类	注解	触发时机
异常处理	GlobalExceptionHandler	@RestControllerAdvice + @ExceptionHandler	Controller 抛异常
响应包装	GlobalResponseAdvice	@RestControllerAdvice + ResponseBodyAdvice	Controller 正常返回，HttpMessageConverter 写出前
版本路由	ApiVersionConfig + APIVersionHandlerMapping	@Configuration + WebMvcRegistrations	Spring MVC 注册路由阶段

详细原理分别见 异常处理器、响应拦截器、版本路由。

关键依赖

forge-core 的 pom.xml 只声明 4 个依赖：

GroupId	ArtifactId	用途
cn.cvking	forge-api	Result / BusinessException / 常量 / 错误枚举
cn.cvking	forge-processor	三个面向用户的注解
org.springframework.boot	spring-boot-starter-web	Spring MVC、@RestControllerAdvice、ResponseBodyAdvice
org.springframework.boot	spring-boot-starter-validation	Bean Validation 异常类型

设计取舍

选项	选择	理由
装配方式	@Configuration 自动扫描，不使用 AutoConfiguration.imports	模块体量小，三大 Bean 都靠基础注解就能注册；保持轻量、零样板
注解归属	注解定义在 processor，使用入口在 core	processor 集中放编译期产物 + 注解契约，core 只消费；职责切分清晰
包扫描根	沿用业务工程的 @SpringBootApplication	业务方零配置；代价是必须把启动类放在 core 的祖先包下
异常处理粒度	7 个 @ExceptionHandler 全部内置	覆盖 80% 场景；不够时业务方再加自己的 @RestControllerAdvice 即可