# 从0到1实现：Spring Boot + 自定义注解 + 异步任务 + Redis + SSE 实时进度推送

在日常的 Web 开发中，我们经常会遇到这种需求：

> “前端上传一个文件到后端，后端需要**先处理**，然后**上传到 OSS**，整个过程可能需要几秒甚至几十秒，用户希望能看到实时的任务进度，而不是干等着。”

那该怎么做？
本文我就分享一下我最近在项目里实践的一个**优雅方案**：

> 使用 **Spring Boot + 自定义注解 + 异步任务 + Redis + SSE（Server-Sent Events）** 实现任务进度的实时推送。

---

## 最终效果

上传文件 → 后端异步执行任务 → 前端实时显示进度，比如：

```
处理文件中... 35%
上传到OSS中... 70%
完成 ✅
```

---

## 设计思路

这个功能的核心在于「任务进度的可感知性」。
我们把整个流程拆成几个层次：

1. **任务唯一标识**（taskId）

   * 每个上传/任务都有唯一 taskId，用于追踪进度。

2. **进度状态存储**

   * 用 Redis 保存任务当前的进度状态（方便分布式扩展）。

3. **异步执行任务**

   * 防止阻塞主线程，让任务后台执行。

4. **进度实时通知**

   * 使用 SSE（Server-Sent Events）实现前端实时监听后端推送。

5. **自定义注解 + AOP 封装**

   * 通过一个注解 `@TrackProgress`，自动开启进度追踪逻辑，开发者不需要在业务里手动操作 Redis。

---

## 项目结构

```plaintext
com.example.progress
├── annotation
│   └── TrackProgress.java
├── aspect
│   └── ProgressAspect.java
├── config
│   └── RedisConfig.java
├── controller
│   └── UploadController.java
├── service
│   ├── AsyncTaskService.java
│   ├── ProgressService.java
│   └── SSEManager.java
├── model
│   └── TaskProgress.java
└── ProgressApplication.java
```

---

## 核心注解设计

```java
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface TrackProgress {
    String value() default "";
}
```

> 标注在需要追踪进度的方法上，比如上传任务处理方法。

---

## AOP 切面实现

```java
@Aspect
@Component
@RequiredArgsConstructor
public class ProgressAspect {

    private final ProgressService progressService;

    @Around("@annotation(trackProgress)")
    public Object around(ProceedingJoinPoint joinPoint, TrackProgress trackProgress) throws Throwable {
        String taskId = UUID.randomUUID().toString();
        progressService.start(taskId);
        try {
            Object result = joinPoint.proceed();
            progressService.complete(taskId);
            return result;
        } catch (Exception e) {
            progressService.fail(taskId);
            throw e;
        }
    }
}
```

AOP 自动生成 `taskId`，在任务开始、完成、失败时更新 Redis 状态。

---

## Redis 存储进度状态

```java
@Service
@RequiredArgsConstructor
public class ProgressService {

    private final StringRedisTemplate redisTemplate;
    private static final String PREFIX = "task:progress:";

    public void updateProgress(String taskId, int percent, String message) {
        Map<String, Object> progress = new HashMap<>();
        progress.put("percent", percent);
        progress.put("message", message);
        redisTemplate.opsForValue().set(PREFIX + taskId, new ObjectMapper().writeValueAsString(progress));
    }

    public String getProgress(String taskId) {
        return redisTemplate.opsForValue().get(PREFIX + taskId);
    }

    public void complete(String taskId) {
        updateProgress(taskId, 100, "任务完成 ✅");
    }

    public void fail(String taskId) {
        updateProgress(taskId, -1, "任务失败 ❌");
    }

    public void start(String taskId) {
        updateProgress(taskId, 0, "任务开始");
    }
}
```

---

## 异步任务执行

```java
@Service
@RequiredArgsConstructor
public class AsyncTaskService {

    private final ProgressService progressService;

    @Async
    @TrackProgress
    public void processAndUpload(String taskId, MultipartFile file) throws Exception {
        progressService.updateProgress(taskId, 20, "正在处理文件...");
        Thread.sleep(1000);

        progressService.updateProgress(taskId, 60, "正在上传到OSS...");
        Thread.sleep(2000);

        progressService.updateProgress(taskId, 90, "OSS上传完成，正在收尾...");
        Thread.sleep(500);

        progressService.complete(taskId);
    }
}
```

---

## 控制器示例

```java
@RestController
@RequestMapping("/api/upload")
@RequiredArgsConstructor
public class UploadController {

    private final AsyncTaskService asyncTaskService;
    private final ProgressService progressService;

    @PostMapping
    public ResponseEntity<?> uploadFile(@RequestParam("file") MultipartFile file) {
        String taskId = UUID.randomUUID().toString();
        asyncTaskService.processAndUpload(taskId, file);
        return ResponseEntity.ok(Map.of("taskId", taskId));
    }

    @GetMapping("/status/{taskId}")
    public ResponseEntity<?> getStatus(@PathVariable String taskId) {
        return ResponseEntity.ok(progressService.getProgress(taskId));
    }
}
```

---

## 前端监听（SSE 简化版）

```javascript
const evtSource = new EventSource(`/api/progress/subscribe/${taskId}`);
evtSource.onmessage = (e) => {
  const data = JSON.parse(e.data);
  document.getElementById('progress').innerText =
    `${data.message} (${data.percent}%)`;
};
```

---

## 进阶：任务进度 + Redis + SSE

* Redis 保存进度，支持集群。
* SSE 订阅同 taskId 渠道，实时推送状态变化。
* 如果服务重启，前端重新订阅即可恢复监听。

---

## 优雅的点

✅ 统一注解管理进度逻辑
✅ 异步 + Redis 支撑分布式
✅ SSE 实时、轻量无轮询
✅ 业务层干净、低侵入

---

## 写在最后

这套设计的核心思路是「解耦」：

* **开发者**只关心业务逻辑；
* **AOP + 注解**自动处理进度逻辑；
* **Redis + SSE**负责状态共享和实时通信。

这不仅能解决「文件上传」的场景，也可以轻松扩展到**大文件导入**、**模型训练**、**数据分析任务**等长耗时操作。

如果想体验完整工程代码，我在文末贴了一个可运行版本：
[Spring Boot 进度追踪示例（Redis + SSE + 注解）](#)


Web文件传输时进度感知问题

> 本文整理了 Spring Boot 开发中最常用的注解，涵盖核心配置、MVC 层、事务、AOP、数据访问、缓存、异步任务、安全、测试等方面，快速构建高质量的企业级应用。

---

## 一、核心注解

| 注解                         | 说明                                                                    |
| -------------------------- | --------------------------------------------------------------------- |
| `@SpringBootApplication`   | 标记主类，组合了 `@Configuration`、`@EnableAutoConfiguration`、`@ComponentScan` |
| `@Configuration`           | 标记配置类，替代 XML 配置文件                                                     |
| `@EnableAutoConfiguration` | 启用自动配置机制                                                              |
| `@ComponentScan`           | 指定扫描组件的包路径                                                            |
| `@Component`               | 通用组件注解，标记类为 Spring 管理的 Bean                                           |
| `@Bean`                    | 在配置类中定义 Bean                                                          |
| `@Lazy`                    | 延迟初始化 Bean（默认单例在启动时初始化）                                               |

---

## 二、分层注解（用于分层结构）

| 注解                | 说明                                             |
| ----------------- | ---------------------------------------------- |
| `@Controller`     | 标记 MVC 控制器类                                    |
| `@RestController` | 组合 `@Controller` + `@ResponseBody`，返回 JSON/XML |
| `@Service`        | 标记业务逻辑层类                                       |
| `@Repository`     | 标记数据访问层（DAO）类，并自动处理数据库异常                       |

---

## 三、依赖注入

| 注解           | 说明                                  |
| ------------ | ----------------------------------- |
| `@Autowired` | 自动注入依赖（按类型匹配）                       |
| `@Qualifier` | 与 `@Autowired` 配合使用，按名称注入           |
| `@Resource`  | JDK 注解，按名称或类型注入                     |
| `@Value`     | 注入配置文件属性（如 `@Value("${app.name}")`） |
| `@Primary`   | 当存在多个同类型 Bean 时，指定优先注入的 Bean        |

---

## 四、MVC 与 Web 层

| 注解                                                                                  | 说明                          |
| ----------------------------------------------------------------------------------- | --------------------------- |
| `@RequestMapping`                                                                   | 映射 HTTP 请求（URL、方法、参数等）      |
| `@GetMapping` / `@PostMapping` / `@PutMapping` / `@DeleteMapping` / `@PatchMapping` | 对应不同的 HTTP 方法               |
| `@ResponseBody`                                                                     | 将方法返回值作为响应体（非视图）            |
| `@RequestBody`                                                                      | 接收请求体数据（如 JSON）             |
| `@PathVariable`                                                                     | 获取 URL 路径参数（如 `/user/{id}`） |
| `@RequestParam`                                                                     | 获取请求参数（如 `?name=xxx`）       |
| `@RequestHeader`                                                                    | 获取请求头信息                     |
| `@CookieValue`                                                                      | 获取 Cookie 值                 |
| `@CrossOrigin`                                                                      | 允许跨域请求                      |
| `@ModelAttribute`                                                                   | 绑定请求参数到模型对象                 |
| `@SessionAttributes`                                                                | 将模型数据存储到 Session            |
| `@ResponseStatus`                                                                   | 指定响应的 HTTP 状态码              |
| `@ExceptionHandler`                                                                 | 处理控制器中的异常                   |
| `@ControllerAdvice`                                                                 | 全局异常处理与全局数据绑定               |

---

## 五、配置与属性绑定

| 注解                                                   | 说明                                    |
| ---------------------------------------------------- | ------------------------------------- |
| `@ConfigurationProperties`                           | 将配置文件属性绑定到类                           |
| `@EnableConfigurationProperties`                     | 启用指定类的配置属性绑定                          |
| `@PropertySource`                                    | 加载自定义配置文件                             |
| `@Profile`                                           | 指定 Bean 在特定环境下生效（如 `@Profile("dev")`） |
| `@Conditional`                                       | 条件化 Bean 创建的通用注解                      |
| `@ConditionalOnBean` / `@ConditionalOnMissingBean`   | 当存在/不存在指定 Bean 时生效                    |
| `@ConditionalOnClass` / `@ConditionalOnMissingClass` | 当类路径存在/不存在时生效                         |
| `@ConditionalOnProperty`                             | 当配置属性满足条件时生效                          |

---

## 六、AOP（面向切面编程）

| 注解                | 说明                                                  |
| ----------------- | --------------------------------------------------- |
| `@Aspect`         | 标记类为切面类                                             |
| `@Pointcut`       | 定义切入点（如 `execution(* com.example.service.*.*(..))`） |
| `@Before`         | 前置通知（方法执行前）                                         |
| `@After`          | 后置通知（方法执行后）                                         |
| `@AfterReturning` | 返回后通知（正常返回）                                         |
| `@AfterThrowing`  | 异常通知（发生异常后）                                         |
| `@Around`         | 环绕通知（可控制目标方法执行）                                     |

---

## 七、事务管理

| 注解                             | 说明                     |
| ------------------------------ | ---------------------- |
| `@Transactional`               | 开启事务管理，可配置传播行为与隔离级别    |
| `@EnableTransactionManagement` | 启用事务（Spring Boot 默认开启） |

---

## 八、数据访问（JPA / MyBatis）

| 注解                                            | 说明              |
| --------------------------------------------- | --------------- |
| `@Entity`                                     | 标记 JPA 实体类      |
| `@Table`                                      | 指定实体类对应的表名      |
| `@Id`                                         | 标记主键            |
| `@GeneratedValue`                             | 主键生成策略          |
| `@Column`                                     | 指定列名            |
| `@Transient`                                  | 忽略字段            |
| `@Repository`                                 | DAO 层注解         |
| `@Query` / `@Param`                           | JPA 自定义查询与参数绑定  |
| `@Mapper`                                     | MyBatis 映射器接口   |
| `@Insert` / `@Update` / `@Delete` / `@Select` | MyBatis 注解式 SQL |

---

## 九、缓存注解

| 注解               | 说明        |
| ---------------- | --------- |
| `@EnableCaching` | 启用缓存功能    |
| `@Cacheable`     | 标记方法结果可缓存 |
| `@CachePut`      | 执行方法并更新缓存 |
| `@CacheEvict`    | 删除缓存      |
| `@Caching`       | 组合多个缓存操作  |

---

## 十、异步与定时任务

| 注解                  | 说明                  |
| ------------------- | ------------------- |
| `@EnableAsync`      | 启用异步方法支持            |
| `@Async`            | 声明方法异步执行            |
| `@EnableScheduling` | 启用定时任务支持            |
| `@Scheduled`        | 定义定时任务（支持 cron 表达式） |

---

## 十一、安全控制（Spring Security）

| 注解                   | 说明                                 |
| -------------------- | ---------------------------------- |
| `@EnableWebSecurity` | 启用 Web 安全配置                        |
| `@PreAuthorize`      | 方法执行前进行权限验证                        |
| `@PostAuthorize`     | 方法执行后验证权限                          |
| `@Secured`           | 限定访问角色（如 `@Secured("ROLE_ADMIN")`） |

---

## 十二、测试相关注解

| 注解                      | 说明                    |
| ----------------------- | --------------------- |
| `@SpringBootTest`       | 启动完整 Spring Boot 测试环境 |
| `@Test`                 | JUnit 测试方法注解          |
| `@MockBean`             | 替换 Bean 为 Mock 对象     |
| `@AutoConfigureMockMvc` | 自动配置 MockMvc          |
| `@DataJpaTest`          | 测试 JPA 层组件            |
| `@WebMvcTest`           | 测试 MVC 控制器（仅加载 Web 层） |

---

## 十三、其他常用注解

| 注解                                           | 说明                                               |
| -------------------------------------------- | ------------------------------------------------ |
| `@Order`                                     | 指定加载顺序（值越小优先）                                    |
| `@Scope`                                     | 指定 Bean 作用域（singleton、prototype、request、session） |
| `@Deprecated`                                | 标记过时                                             |
| `@NonNull` / `@NotNull`                      | 参数或返回值非空校验                                       |
| `@Size` / `@Email`                           | 长度与邮箱格式校验                                        |
| `@Valid` / `@Validated`                      | 启用参数校验                                           |
| `@EventListener`                             | 声明事件监听方法                                         |
| `@EnableFeignClients` / `@FeignClient`       | 启用并定义 Feign 客户端                                  |
| `@LoadBalanced`                              | 启用 RestTemplate 负载均衡                             |
| `@RegisterReflectionForBinding`              | 注册类支持 JSON 反射绑定                                  |
| `@Slf4j`                                     | Lombok 日志注解                                      |
| `@RequiredArgsConstructor`                   | 生成包含 `final` 字段的构造函数                             |
| `@NoArgsConstructor` / `@AllArgsConstructor` | 生成无参 / 全参构造函数                                    |

---

## ✨总结

Spring Boot 通过注解驱动的方式，大幅简化了配置与开发流程。掌握这些常用注解，不仅能写出结构清晰、可维护性高的应用，还能充分发挥 Spring Boot 的自动化与约定优于配置的优势。



Spring Boot 常用注解

在Web应用开发中，文件上传是一个极其常见的需求。随着云服务的普及，将文件直接存储到云存储服务（如阿里云OSS、腾讯云COS、AWS S3等）已成为标准做法。然而，一个关键的架构问题随之而来：文件上传的路径，究竟应该让前端直接与OSS交互，还是统一经由后端服务器转发？

这个问题没有唯一的正确答案，但有一个在当前环境下被广泛认为是最佳的实践。让我们深入分析一下两种模式的优劣。

## 方案一：前端直传OSS

在这种模式下，前端应用直接从OSS服务提供商获取一个临时上传凭证，然后使用这个凭证将文件直接上传到OSS，上传成功后，将文件的最终地址告诉后端服务器。

**流程大致如下：**
1.  前端请求后端API，获取上传凭证（例如，阿里云的STS Token）。
2.  后端校验用户权限，向OSS服务商申请临时Token，并返回给前端。
3.  前端使用这个临时Token，调用OSS的SDK，将文件直接上传至OSS。
4.  上传成功后，OSS返回文件地址。
5.  前端将文件地址提交给后端，保存到业务数据库中。

### 优势

1.  **极高的性能**：文件流不经过后端服务器，节省了服务器的上行和下行带宽，大大减轻了后端服务器的负载和压力。
2.  **高扩展性与稳定性**：OSS等云服务专为海量文件存储和分发设计，自带容灾和扩展能力，上传体验更稳定、更快速。
3.  **更好的用户体验**：上传进度、断点续传等功能可以由OSS SDK直接提供，体验更佳。

### 劣势

1.  **安全风险管控复杂**：虽然使用了临时凭证，但权限控制的粒度需要精心设计。比如，临时Token的权限范围、有效期、允许上传的路径和文件类型等，都需要在后端严格管控，否则可能产生安全漏洞。
2.  **后端业务逻辑受限**：如果文件上传后需要立即进行处理（如图像压缩、内容审核、病毒扫描等），直传模式就不太方便，通常需要配合OSS的“回调”或“事件通知”功能来实现，增加了架构的复杂性。
3.  **客户端依赖**：需要在前端引入OSS的SDK，略微增加前端应用的体积。

---

## 方案二：后端代理上传

这是传统的方式，前端将文件通过`multipart/form-data`形式提交给自己的后端服务器，再由后端服务器使用永久秘钥将文件转发到OSS。

**流程大致如下：**
1.  前端通过表单或API将文件数据发送到后端接口。
2.  后端接收文件流，进行权限验证、病毒扫描、内容校验等。
3.  后端使用自己的AccessKey，调用OSS SDK将文件上传至OSS。
4.  后端将上传成功后的文件地址保存到数据库，并返回给前端。

### 优势

1.  **安全性高，控制力强**：所有请求都经过后端服务器，可以方便地进行严格的权限校验、内容安全审查、文件类型和大小限制等。
2.  **业务处理无缝衔接**：文件上传后可以立即在服务器端进行后续处理，流程简单直接。
3.  **对前端透明**：前端无需关心使用的是哪家云存储，后端可以随时更换存储服务商而前端无感。

### 劣势

1.  **服务器性能瓶颈**：文件流需要经过后端服务器，消耗大量的服务器带宽和CPU资源。当上传大文件或并发量高时，服务器可能成为性能和单点故障的瓶颈。
2.  **用户体验可能不佳**：上传速度受限于后端服务器的带宽，且实现断点续传、分片上传等功能更为复杂。
3.  **扩展性差**：需要自行优化服务器和带宽来应对上传流量高峰，成本较高且不灵活。

---

## 核心安全机制：STS（安全令牌服务）

在分析前端直传的劣势时，我们提到了安全风险。而**STS（Security Token Service）** 正是解决这个问题的钥匙。

STS是云厂商提供的一种颁发临时访问凭证的服务。这些临时凭证具备以下特点：
*   **时效性极短**：通常有效期为15分钟至几小时。
*   **权限受限**：遵循“最小权限原则”，只能执行特定的操作（如：只能向指定目录上传文件）。
*   **无需暴露主账号秘钥**：前端使用的是有时效、有限权的Token，即使泄露，危害也远小于泄露后端的永久AccessKey。

通过STS，我们既享受了前端直传的性能优势，又极大地规避了安全风险。这使得“前端直传+STS”的组合成为了事实上的最佳实践。

---

## 最佳实践推荐：前端直传 + STS + 后端管控

综合以上分析，我们推荐采用一种**混合架构**，它集两种模式之长，避两者之短。

**架构流程图：**

```mermaid
sequenceDiagram
    participant U as 前端用户
    participant S as 后端服务器
    participant STS as 云STS服务
    participant O as 对象存储(OSS)

    U->>S: 1. 请求上传凭证
    Note right of S: 校验用户权限、<br>定义上传策略
    S->>STS: 2. 申请临时Token
    STS-->>S: 3. 返回临时Token
    S-->>U: 4. 返回临时Token和上传配置
    U->>O: 5. 使用临时Token直传文件
    O-->>U: 6. 返回文件URL
    U->>S: 7. 通知上传成功(提交文件URL)
    Note right of S: 保存文件信息到DB
```

**这个方案的核心要点：**

1.  **上传凭证由后端签发**：后端完全掌控了上传的“准入”规则。它可以：
    *   验证用户是否已登录。
    *   动态定义上传路径（如：`user_{uid}/avatar/{random_name}.jpg`），避免覆盖和冲突。
    *   严格限制上传的文件类型、大小。
    *   通过STS服务，生成一个受限的临时Token返回给前端。

2.  **文件流前端直传**：前端拿到凭证后，直接与OSS通信，享受高性能和稳定性。可以利用OSS SDK的强大功能，实现分片上传、断点续传和进度条。

3.  **后端负责最终登记**：前端上传成功后，将最终的文件地址发送回后端，由后端将其与业务实体（如用户、文章）关联，并存入数据库。

4.  **（可选）结合云函数处理后续任务**：如果文件上传后需要即时处理（如生成缩略图），可以配置OSS的事件触发器，当文件上传完成后，自动通知一个云函数（如Serverless Function）或消息队列，由它们来异步处理，从而不阻塞主上传流程。

## 结论

对于绝大多数场景，**“前端直传 + STS临时凭证 + 后端权限与控制”** 是现代Web应用上传文件到OSS的最佳实践。

*   **追求性能和扩展性？** 它做到了。
*   **担心安全问题？** STS和严格的后端策略提供了坚实保障。
*   **需要复杂的后处理？** 通过事件驱动和异步处理可以优雅地解决。

因此，在架构选型时，请优先考虑这种混合模式。它有效地在前端的灵活性与后端控制力之间取得了平衡，既能应对高并发海量文件上传的挑战，又能确保业务和数据的安全可靠。

OSS到底应该前端直传还是交给后端处理？

在Spring项目中，`Filter`和`Interceptor`是处理HTTP请求的两种常见机制，它们功能相似，但职责和能力不同。理解它们的区别，是写出优雅架构代码的关键。

#### **核心概念与作用**

*   **过滤器（Filter）**：属于 **Servlet 规范**，是任何Java Web项目都能用的标准组件。它在请求进入 **Servlet容器（如Tomcat）** 后，但还未到达Spring MVC的`DispatcherServlet`之前就起作用。
    *   **作用**：处理**底层**的、与Web框架无关的事情。比如：字符编码设置、CORS跨域支持、全局请求/响应日志、IP黑名单过滤等。

*   **拦截器（Interceptor）**：属于 **Spring MVC 框架**的组件。它在请求经过`DispatcherServlet`之后，进入具体的Controller方法之前（以及之后）发挥作用。
    *   **作用**：处理**业务层**的、与Spring MVC紧密相关的逻辑。比如：用户登录状态验证、权限校验、日志审计、Controller执行时间计算等。

#### **核心区别：一张图看懂执行顺序**

这是理解它们的关键。一个HTTP请求的处理流程如下：

**HTTP Request → Tomcat → `Filter` → `DispatcherServlet` → `Interceptor` → `Controller`**

**响应则反过来：**
`Controller` → `Interceptor`(postHandle) → `DispatcherServlet` → `Filter` → **HTTP Response**

**简单对比表：**

| 特性 | 过滤器 (Filter) | 拦截器 (Interceptor) |
| :--- | :--- | :--- |
| **所属规范** | Servlet API | Spring MVC |
| **依赖关系** | 不依赖Spring，是Web服务器的一部分 | 依赖Spring容器 |
| **作用范围** | 对所有请求生效（包括静态资源） | 只对Spring MVC管理的请求生效 |
| **获取Bean** | 不能直接注入Spring Bean | 可以直接使用`@Autowired`注入 |
| **控制粒度** | 粗粒度，基于请求/响应 | 细粒度，可获取处理请求的Handler、ModelAndView等 |

#### **代码示例：一看就会**

**1. 自定义过滤器**

```java
// 使用 @WebFilter 注解，或在 Configuration 中使用 FilterRegistrationBean
@Component
public class LogFilter implements Filter {
    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
            throws IOException, ServletException {
        // 1. 在Controller之前执行
        System.out.println("Filter: 请求进入 - " + ((HttpServletRequest) request).getRequestURI());
        long startTime = System.currentTimeMillis();
        
        // 放行请求到下一个过滤器或DispatcherServlet
        chain.doFilter(request, response);
        
        // 2. 在返回响应给客户端之前执行
        long duration = System.currentTimeMillis() - startTime;
        System.out.println("Filter: 响应返回，耗时 " + duration + "ms");
    }
}
```

**2. 自定义拦截器**

```java
@Component
public class AuthInterceptor implements HandlerInterceptor {
    
    // 可以正常注入Spring Bean
    @Autowired
    private UserService userService;

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        // Controller方法执行前调用
        String token = request.getHeader("Authorization");
        if (!userService.isValidToken(token)) {
            response.sendError(401, "未授权");
            return false; // 中断流程，不执行Controller
        }
        System.out.println("Interceptor: 权限校验通过");
        return true; // 放行，继续执行Controller
    }

    @Override
    public void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView) throws Exception {
        // Controller方法执行后，但视图渲染前调用
        System.out.println("Interceptor: Controller执行完毕");
    }
}
```

**注册拦截器：**

```java
@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Autowired
    private AuthInterceptor authInterceptor;

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(authInterceptor)
                .addPathPatterns("/api/**") // 只拦截/api开头的请求
                .excludePathPatterns("/api/login"); // 排除登录接口
    }
}
```

#### **如何选择？**

*   **用 Filter 的场景**：当你需要处理的内容与Spring无关，是Web应用的通用能力时。例如：全局CORS、请求体加密/解密、XSS防范、全局日志。
*   **用 Interceptor 的场景**：当你需要Spring上下文支持，且业务与Controller紧密相关时。例如：登录拦截、接口权限验证、审计日志、Controller性能监控。

**一句话总结：Filter是Web容器的保安，Interceptor是Spring MVC的秘书。**

一言蔽之：过滤器与拦截器的区别和作用

作为开发者，我们都知道 Elasticsearch (ES) 很强大，但对服务器内存和CPU也是占用不小。在项目初期或者数据量没那么恐怖的时候，完全可以选择一个更轻量、同样基于 Lucene 的强者：**Apache Solr**。

今天就从零开始，快速搞定 Solr。

#### **1. 安装Solr（极速上手）**

这里以 Linux 为例，Mac 类似，Windows 请下载 zip 包。

```bash
# 下载 Solr (这里以 8.11.1 为例，请替换为最新版本)
wget https://archive.apache.org/dist/lucene/solr/8.11.1/solr-8.11.1.tgz

# 解压
tar -xzf solr-8.11.1.tgz

# 启动 ( -p 指定端口，-d 以守护进程运行)
cd solr-8.11.1
./bin/solr start -p 8983 -d
```

访问 `http://你的服务器IP:8983/solr`，能看到 Admin UI 就成功了！

#### **2. 创建核心（Core）与配置字段**

Solr 中的 Core 类似于 ES 的 Index，是数据的容器。

**创建 Core：**
```bash
./bin/solr create_core -c my_core -p 8983
```

**配置字段（`managed-schema`）：**
在 Admin UI 找到 `my_core` -> `Schema`。这里我们通过 UI 添加字段，底层实际是修改 `managed-schema` 文件。

*   **`id`** (系统默认已有): `type="string"`，唯一标识。
*   **`title`**: 文章标题，需要分词。
*   **`content`**: 文章内容，需要分词。
*   **`create_time`**: 创建时间，`type="pdate"`。

**关键字段类型（FieldType）：**

*   **`text_general`**: 最常用的文本类型，会分词、转小写，适用于标题、内容等。
*   **`string`**: 字符串类型，**不分词**，适用于 ID、标签、状态等需要精确匹配的字段。
*   **`pint` / `plong`**: 整数/长整数。
*   **`pfloat` / `pdouble`**: 浮点数。
*   **`pdate`**: 日期时间类型。

#### **3. 加入中文分词器（IK Analyzer）**

默认分词对中文不友好（单字切分）。我们需要 IK Analyzer。

1.  **下载 IK Jar 包**
    去 Maven 仓库搜索 `ik-analyzer-solr`，下载对应版本的 Jar 文件（如 `ik-analyzer-8.5.0.jar`）。

2.  **部署 Jar 包**
    将 jar 包放入 `server/solr-webapp/webapp/WEB-INF/lib/` 目录下。

3.  **配置字段类型**
    在 `managed-schema` 中，新增一个 IK 分词字段类型：

    ```xml
    <fieldType name="text_ik" class="solr.TextField">
        <analyzer type="index">
            <tokenizer class="org.wltea.analyzer.lucene.IKTokenizerFactory" useSmart="false"/>
        </analyzer>
        <analyzer type="query">
            <tokenizer class="org.wltea.analyzer.lucene.IKTokenizerFactory" useSmart="true"/>
        </analyzer>
    </fieldType>
    ```
    *   `index` 用细粒度分词，保证召回。
    *   `query` 用智能分词，提升准确率。

4.  **修改字段类型**
    将 `title` 和 `content` 字段的 `type` 改为我们刚定义的 `text_ik`。
5.  **重启 Solr**
    `./bin/solr restart -p 8983`

#### **4. 集成 SpringBoot**

在 `pom.xml` 中添加依赖：

```xml
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-solr</artifactId>
</dependency>
```

在 `application.yml` 中配置：

```yaml
spring:
  data:
    solr:
      host: http://localhost:8983/solr # 你的 Solr 地址
```

创建一个文档实体类：

```java
import org.springframework.data.annotation.Id;
import org.springframework.data.solr.core.mapping.Indexed;
import org.springframework.data.solr.core.mapping.SolrDocument;

@SolrDocument(collection = "my_core") // 指定 Core 名
public class Article {
    @Id
    @Indexed
    private String id;
    
    @Indexed(type = "text_ik") // 使用 IK 分词的字段
    private String title;
    
    @Indexed(type = "text_ik")
    private String content;
    
    @Indexed(type = "pdate")
    private Date createTime;
    
    // getter/setter 省略
}
```

创建 Repository：

```java
public interface SolrArticleRepository extends SolrCrudRepository<Article, String> {
    // Spring Data 会自动实现
    List<Article> findByTitleOrContent(String title, String content);
    
    // 更复杂的查询可以使用 @Query 注解
    @Query("title:*?0* OR content:*?0*")
    List<Article> findByKeyword(String keyword);
}
```

#### **5. 调用：增删改查**

在 Service 中注入 Repository 即可操作。

```java
@Service
public class SearchService {

    @Autowired
    private SolrArticleRepository solrRepo;

    // 新增或更新
    public void save(Article article) {
        if(article.getId() == null) {
            article.setId(UUID.randomUUID().toString());
        }
        article.setCreateTime(new Date());
        solrRepo.save(article);
    }

    // 按 ID 查询
    public Optional<Article> findById(String id) {
        return solrRepo.findById(id);
    }

    // 关键词搜索
    public List<Article> search(String keyword) {
        return solrRepo.findByKeyword(keyword);
    }

    // 按 ID 删除
    public void delete(String id) {
        solrRepo.deleteById(id);
    }
}
```

**总结**

一套流程下来，你会发现 Solr 的 Admin UI 对开发者非常友好，配置和调试都很直观。对于大多数中小规模的搜索场景，Solr 在性能上和 ES 相差无几，但资源消耗却友好得多。

如果你的项目正面临资源瓶颈，又想快速引入一个强大的搜索功能，Solr 绝对是一个值得你花半天时间尝试的优秀选择。

**行动路线：**
1.  官网下载 -> 启动。
2.  创建 Core -> 配置 IK 分词。
3.  SpringBoot 集成 -> 写个增删改查接口。
4.  搞定！