校园小红薯项目 — 注解总结

项目campus-xiaohongshuSpring Boot 后端整理日期2026-08-19说明本文按用途分类汇总项目中出现的全部注解及其作用并标注实际出现位置。一、启动类 / 全局功能开关这类注解放在启动类CampusApplication.java或配置类上用来开启整个应用的某项能力。注解作用项目中的位置SpringBootApplicationSpring Boot 启动类标识组合了ConfigurationEnableAutoConfigurationComponentScan是应用入口CampusApplicationMapperScanMyBatis 注解指定要扫描并注册为 Mapper 代理对象的包路径MapperScan(com.chenpperr.xhs.mapper)EnableAsync开启异步方法执行能力配合Async使用启动类EnableScheduling开启定时任务调度让Scheduled生效启动类、LikeSyncTaskEnableWebSecurity开启 Spring Security 的 Web 安全功能SecurityConfigEnableMethodSecurity开启方法级权限控制如PreAuthorizeSecurityConfig二、Spring MVC 控制器层2.1 类与方法的路由映射注解作用RestController标识控制器类等于ControllerResponseBody所有方法返回值自动转成 JSONRequestMapping定义请求的根路径如RequestMapping(/api/v1/posts)也可限定 methodGetMapping映射 GET 请求查询如listPosts、getPostByIdPostMapping映射 POST 请求新增如publishPost、aiPolishPutMapping映射 PUT 请求修改DeleteMapping映射 DELETE 请求删除如deletePost2.2 参数绑定注解作用项目示例PathVariable从URL 路径占位符中取值如/posts/{id}取出idPathVariable(id) Long idRequestParam从查询字符串 / 表单中取值如?current1size10可设defaultValue、requiredRequestParam(valuecategory, requiredfalse)RequestBody把请求体 JSON反序列化成 Java 对象POST/PUT 常用RequestBody Valid PostPublishDTO dto三、参数校验Jakarta Validation这些注解标在 DTO 字段上声明规则Valid负责触发校验。注解作用项目示例Valid放在 Controller 方法参数前触发对该对象的级联校验校验失败抛MethodArgumentNotValidExceptionpublishPost(RequestBody Valid ...)NotBlank字符串非 null 且去空格后非空仅用于字符串NotBlank(message标题不能为空)Size限制长度/大小范围Size(max50, message标题长度不能超过50字)Pattern正则校验手机号Pattern(regexp^1[3-9]\\d{9}$)Email校验邮箱格式UpdateUserDTO.email注意Pattern/Email对null放行所以项目里用它们实现选填语义。校验失败由GlobalExceptionHandler统一捕获并返回友好提示。四、Spring IoC 容器 / Bean 管理4.1 声明 Bean注解作用Component通用组件交给 Spring 容器管理如LikeSyncTaskService业务逻辑层组件语义化的Component如各ServiceImplConfiguration配置类内部可用Bean定义组件如AiConfig、SecurityConfigBean在配置类方法上把方法返回值注册为 Spring BeanMapperMyBatis 注解标识数据访问层接口DAO4.2 依赖注入注解作用AutowiredSpring 按类型自动注入依赖RequiredArgsConstructorLombok 注解为所有final字段生成构造器——项目中配合构造器注入使用如PostController是比Autowired字段注入更推荐的写法Lazy延迟初始化注入的 Bean项目中FeedServiceImpl用它打破循环依赖4.3 读取配置 / 条件装配注解作用项目示例Value注入配置文件中的单个属性值支持默认值Value(${jwt.secret})、Value(${upload.local.path:./uploads})ConfigurationProperties把配置文件中某前缀的一组属性批量绑定到对象AiConfig绑定ai.*ConditionalOnProperty条件装配仅当配置项满足条件时才创建该 Bean用upload.type切换OssServiceImpl/LocalUploadServiceImpl五、MyBatis-Plus 持久层注解作用项目示例TableName指定实体类对应的数据库表名TableName(post)TableId标识主键字段type指定生成策略TableId(typeIdType.AUTO)自增主键六、Lombok编译期生成样板代码注解作用Data一键生成 getter/setter/toString/equals/hashCodeGetter只生成 getterBuilder生成建造者模式支持链式构造对象如PostLike.builder()...NoArgsConstructor生成无参构造器AllArgsConstructor生成全参构造器RequiredArgsConstructor生成 final 字段构造器见第四节Slf4j生成log日志对象直接调用log.info/error七、全局异常处理注解作用项目示例RestControllerAdvice全局异常处理器类对所有 Controller 生效等于ControllerAdviceResponseBodyGlobalExceptionHandlerExceptionHandler指定该方法处理哪种异常ExceptionHandler(BusinessException.class)ResponseStatus设置异常响应的 HTTP 状态码ResponseStatus(HttpStatus.BAD_REQUEST)八、事务与定时任务注解作用项目示例Transactional声明式事务方法内出错自动回滚rollbackForException.class表示所有异常都回滚FollowServiceImpl的关注/取关操作Scheduled按 cron 表达式周期性执行方法Scheduled(cron30 */15 * * * ?)每 15 分钟同步 Redis 点赞到 MySQL项目中LikeSyncTask特意不用Transactional注释说明了原因同类内部调用不走 AOP 代理事务不会生效。九、Jackson 序列化 自定义脱敏注解注解作用JsonSerialize指定字段用自定义序列化器输出using指向序列化器类JacksonAnnotationsInside元注解把多个 Jackson 注解打包进一个自定义注解Sensitive项目自定义注解标在 VO 字段上序列化时自动打码脱敏。内部组合了上面两个 Jackson 注解Sensitive用在UserProfileVO上手机号用SensitiveType.MOBILE、邮箱用SensitiveType.EMAIL脱敏。十、元注解用于定义自定义注解这几个出现在Sensitive.java的定义里是注解的注解注解作用Target限定注解能标注的位置如ElementType.FIELD只能标字段Retention注解保留到什么时期RetentionPolicy.RUNTIME表示运行时可反射读取脱敏靠的就是运行时反射Documented让注解出现在 Javadoc 文档中十一、测试与 Java 核心注解作用TestJUnit 标记测试方法SpringBootTest启动完整 Spring 上下文做集成测试OverrideJava 核心注解标识方法重写父类/接口方法编译器检查项目中出现最多38 次总结一张请求生命周期串联图用一个发布笔记请求串起这些注解的协作过程前端 POST /api/v1/posts (JSON) │ ├─ RestController PostMapping → 路由到 PostController.publishPost ├─ RequestBody → JSON 转成 PostPublishDTO ├─ Valid → 触发校验 │ └─ NotBlank / Size → 字段规则不合法抛异常 │ └─ RestControllerAdvice ExceptionHandler → 统一返回错误 ├─ Service (PostServiceImpl) → 业务处理 │ ├─ Transactional → 事务保护 │ └─ Mapper TableName/TableId → MyBatis-Plus 操作数据库 ├─ Slf4j → 记录日志 └─ 返回 Result → Jackson 序列化Sensitive 字段自动脱敏