常用注解速查表
集中整理 Spring Boot 高频注解，按用途分类。每个注解都带「类比 Laravel」，帮助记忆。
组件与依赖注入
| 注解 | 作用 | 类比 Laravel |
|---|---|---|
@SpringBootApplication | 入口 = 配置 + 扫描 + 自动配置 | public/index.php 启动引导 |
@Component | 注册为容器 Bean | 被容器管理的类 |
@Service | 业务层组件（语义版 @Component） | app/Services 下的类 |
@Repository | 数据访问层组件 | app/Models / Repository |
@Controller | 控制器（返回视图） | 控制器 |
@RestController | 控制器（返回值即 JSON） | 控制器 + return $json |
@Configuration | 配置类 | config/ 文件 / ServiceProvider |
@Bean | 在配置类里手动装配一个对象 | ServiceProvider 里 bind() |
@Autowired | 自动注入依赖 | app(SomeClass::class) |
@Qualifier("name") | 指定注入哪个实现 | 容器里绑定具体实现 |
@Value("${key}") | 读取配置项 | config('xxx') / env('xxx') |
@ConfigurationProperties | 一组配置绑定到类 | 类型安全的 config |
请求映射（路由）
| 注解 | 作用 | 类比 Laravel |
|---|---|---|
@RequestMapping(path) | 类/方法级路由 + 方法约束 | Route::match |
@GetMapping | GET 路由 | Route::get |
@PostMapping | POST 路由 | Route::post |
@PutMapping | PUT 路由 | Route::put |
@DeleteMapping | DELETE 路由 | Route::delete |
@PatchMapping | PATCH 路由 | Route::patch |
参数绑定（请求）
| 注解 | 作用 | 类比 Laravel |
|---|---|---|
@PathVariable | 路径参数 {id} | $request->route('id') |
@RequestParam | 查询参数 | $request->query('page') |
@RequestBody | JSON 请求体 → 对象 | $request->all() + 反序列化 |
@RequestHeader | 请求头 | $request->header() |
@CookieValue | Cookie | $request->cookie() |
@RequestPart | 上传文件 | $request->file() |
@SessionAttribute | 读 Session | session('key') |
@RequestAttribute | 读 request 属性（拦截器写入） | 中间件塞进 request 的数据 |
响应
| 注解 | 作用 | 类比 Laravel |
|---|---|---|
@ResponseStatus(code) | 固定状态码 | response()->status() |
@ResponseBody | 返回值序列化为 JSON | response()->json() |
@JsonIgnore | 序列化时忽略字段 | $hidden |
@JsonProperty("name") | 输出字段改名 | Resource 字段重命名 |
校验（Validation）
| 注解 | 作用 | 类比 Laravel 规则 |
|---|---|---|
@Valid / @Validated | 触发校验 | $request->validate() |
@NotBlank | 非空字符串 | required |
@NotNull | 非 null | required |
@Size(min,max) | 长度 | min:|max: |
@Min / @Max | 数值范围 | min / max |
@Email | 邮箱 | email |
@Pattern(regexp) | 正则 | regex: |
@Positive | 正整数 | integer|min:1 |
@Past / @Future | 时间先后 | before: / after: |
事务 / 缓存 / 异步 / 调度
| 注解 | 作用 | 类比 Laravel |
|---|---|---|
@Transactional | 方法级事务 | DB::transaction() |
@Cacheable | 读缓存，未命中执行并缓存 | Cache::remember |
@CachePut | 总是执行并更新缓存 | Cache::put |
@CacheEvict | 删除缓存 | Cache::forget |
@EnableCaching | 开启缓存 | config/cache.php |
@EnableAsync | 开启异步 | 队列 worker |
@Async | 异步执行 | dispatch() / Queue::push |
@EnableScheduling | 开启定时任务 | Kernel schedule |
@Scheduled(cron) | 定时任务（六段式 cron） | ->dailyAt() |
@PostConstruct | 初始化后执行一次 | ServiceProvider boot() |
@PreDestroy | 销毁前执行 | — |
事件（Events）
| 注解 | 作用 | 类比 Laravel |
|---|---|---|
@EventListener | 监听事件 | Event 的 Listener |
@TransactionalEventListener(AFTER_COMMIT) | 事务提交后监听 | afterCommit 事件 |
安全（Spring Security）
| 注解 | 作用 | 类比 Laravel |
|---|---|---|
@EnableWebSecurity | 开启 Security 配置 | 中间件配置 |
@EnableMethodSecurity | 开启方法级授权 | Gate / Policy |
@PreAuthorize("hasRole('ADMIN')") | 方法前鉴权 | Gate::authorize |
@Secured | 老式角色鉴权 | middleware('role') |
数据访问（JPA）
| 注解 | 作用 | 类比 Eloquent |
|---|---|---|
@Entity | 声明实体 | 继承 Model |
@Table(name) | 映射表 | $table |
@Id | 主键 | — |
@GeneratedValue(IDENTITY) | 自增主键 | $incrementing |
@Column | 字段映射/约束 | migration 列定义 |
@OneToMany(mappedBy) | 一对多 | hasMany |
@ManyToOne | 多对一 | belongsTo |
@ManyToMany | 多对多 | belongsToMany |
@JoinColumn / @JoinTable | 外键 / 中间表 | migration 外键 / 中间表 |
@Query | 自定义 JPQL/原生 SQL | DB::select |
@Modifying | 修改类 @Query | DB::update |
@EntityGraph | 预加载防 N+1 | with() |
配置类里常用的条件注解
| 注解 | 作用 |
|---|---|
@ConditionalOnClass | classpath 有某类才生效 |
@ConditionalOnMissingBean | 没有某 Bean 才生效 |
@ConditionalOnProperty | 配置项满足才生效 |
@ConditionalOnWebApplication | 是 Web 应用才生效 |
记忆技巧
@XxxMapping= 路由注解，@RequestXxx= 参数绑定，@ResponseStatus= 响应控制@EnableXxx= 开一个功能的总开关- 带
@ConfigurationProperties前缀的类 = 「类型安全的配置中心」 - 大部分注解背后都是 AOP 代理 或反射，理解「谁在读注解」比背注解重要