第一阶段：

配置数据库、搭建springboot、配置依赖、yml文件、连接前端网站测试等

遇到的最大问题就是版本不兼容，jdk25太新了导致spring和mybatis plus失效，当前修正之后的jdk是21，springboot 3.5.13；

相较于mybatis，plus版省去了很多crud的代码，它提供了较为完整的crud，代码量减少了

1.entity：放和数据库表一模一样的实体类

2.mapper：和数据库打交道，负责增删改查

3.service：写业务逻辑（登录、上传、总结等）

4.controller：对外提供接口，前端/浏览器调用

5.启动类：项目入口，负责扫描所有包

• Python 侧：完成 “标准化项目结构 + PDF/Word/TXT 解析接口”，验证文档解析功能；
• Java 侧：完成 “SpringBoot 基础工程 + Python 服务调用工具 + 文档上传接口”，实现 Java→Python 的文件上传 + 解析调用；
• 链路验证：确保 Java 上传文档→Python 解析→Java 接收结果的全流程通，为第 2 周 “AI 问答、总结” 功能铺路；
• 准备工作：完成讯飞星火密钥获取、数据库表创建，为后续大模型调用、数据存储做准备。

参数格式不匹配，是前后端 / 微服务调用最常见的错误！

• Java 发 JSON
• Python 必须用 Body(...) 接收
• 不能直接写 question: str

注解的核心作用

• 控制反转（IoC）：将对象的创建和管理交给 Spring 容器
• 依赖注入（DI）：自动注入依赖，无需手动创建和传递
• 组件扫描：自动发现和注册组件，减少配置
• 生命周期管理：支持初始化和销毁方法
• AOP 支持：为横切关注点（如事务、日志）提供支持

1.

@RestController用于前后端分离，主要作用是接收前端请求和返回JSON数据；在当前项目中前端直接拿到数据就能渲染展示，不用跳页面

@Controller返回的是页面，老项目用

2.

相比于@Autowired (Spring)、@Resource（java）注入依赖，用@RequiredArgsConstructor (Lombok)更干净更推荐，但是要在要注入依赖的对象前面加上final，这也更安全保证对象不会被篡改；对于通过配置类手动注册的组件（如拦截器、过滤器等），使用显式构造函数时最直接和可靠的方式，确保依赖能够正确传递

3.

在编写代码的时候要做到解耦和划清职责，controller层只负责接收前端请求和返回后端数据，service层编写核心逻辑，mapper层连接数据库并执行SQL语句，各区域要分工明确

4.

实体类要对应数据库表的字段；service层有接口，也有接口的实现类，接口只写方法名不写方法体，实现类里面才是service层的核心逻辑代码，这样符合java设计原则：面向接口编程；好处有：解耦，方便测试维护、方法替换实现，接口不用动、规范统一

5.

@Slf4j 是Lombok提供的注解，可自动生成日志对象，在编译时自动为这个类生成一个名为log的日志对象，可直接使用log.info()、log.error()等方法记录日志

@Service 是spring框架提供的注解，用来标识这是一个服务层组件

• 将此类标记为Spring容器中的一个Bean
• 使Spring能够自动扫描并管理这个类的实例
• 符合Spring的分层架构理念（Controller层、Service层、Repository层）

@Value 是spring框架提供的一个注解，用于从配置文件（如application.properties或application.yml）中获取值并注入到类的字段中

• 集中管理配置：所有配置项集中在配置文件中，便于统一管理
• 环境隔离：不同环境（开发、测试、生产）可以使用不同的配置文件
• 代码简洁：无需编写读取配置文件的代码，Spring 会自动处理

@Data 是Lombok提供的注解，可省略getter和setter

6.

HttpResponse是hutool工具库提供的HTTP客户端工具类，在java后端和python服务之间需要通过HTTP协议进行通信

MultipartFile是spring框架提供的一个接口，用于处理HTTP请求中的文件上传，它封装了上传文件的信息和操作方法，是spring中处理文件上传的标准方式

7.

在项目中没有写@ComponentScan是因为在启动类那添加了@SpringBootApplication注解，它包含了@SpringBootConfiguration、@EnableAutoConfiguration、@ComponentScan，其中@ComponentScan能扫描启动类及其子包下的spring组件，包括@Service、@Controller、@Component等等，但是我在项目里连接数据库层的用的是@Mapper，这是mybatis提供的，所有它无法被@SpringBootApplication扫描，所以还得写个@MapperScan

8.

在项目中原本在controller层还有异常处理的代码没有抽离出来，现在通过声明式异常处理控制器类@RestControllerAdvice来进行全局异常处理，新建了BusinessException类（继承RuntimeException）和GlobalExceptionHandler类用来统一处理异常，解耦controller层；@RestControllerAdvice=@ControllerAdvice+@ResponseBody，因此代码能更简洁

9.

要避免硬编码，可以将jwt里面的secret密钥、expiration过期时间配置到yml里，提高了代码的可维护性，在项目上线前还需把secret替换成更安全的随机字符串

10.

在yml的mybatis-plus设置block-attack-enable：ture，能防止全表更新和删除，虽然项目中删除和更新几乎都是通过id等进行操作，可以避免全表操作，但是加了这个不会有坏处，建议以后项目都加上

11.

对ai接口实现了异步处理，@Async搭配CompletableFuture可获取异步处理的结果；在AsyncConfig配置类里使用spring提供的ThreadPoolTaskExecutor来自定义线程池和管理异步任务的执行；项目里在调用ai时采用了异步接口，但异步长时间耗时AI任务+SpringSecurity会丢失登录上下文导致返回用户未登录，主线程提前401，最终通过开启异步、共享安全上下文、主线程等待异步结果（join）等解决了问题

12.

• filter 过滤器：负责 全局、安全、认证、跨域、请求入口拦截   JWT、登录校验、权限、防攻击 → 用 Filter
•  Interceptor 拦截器：负责 业务、日志、接口自定义增强    操作日志、接口统计、业务判断 → 用拦截器

在项目中原来的jwt是自定义的拦截器，由于需要securityconfig实现密码加盐，所以直接把jwt也放进springsecurity，而它是基于Filter设计的，所以此时jwt变成filter配合security合并，并且拦截器是在请求走完Filter、进入spring之后才执行，只拦截Controller层接口，执行时机太晚，而Filter是在最前面执行的

执行顺序：        Filter（包含Security） → Interceptor → Controller

• 写业务小功能：拦截器更好、更简单
• 写安全、认证、全局拦截：过滤器更强、更合理、官方标准
• 现在要配合 SpringSecurity 做 JWT 必须用 Filter，不能用拦截器

关闭CSRF，由于项目是前后端分离、用jwt做登录、接口供第三方调用，所以要在SecurityConfig里关闭

• 看登录方式：

  • JWT/Token → 关 CSRF
  • Session/Cookie → 开 CSRF

• 看项目类型：

  • 前后端分离 → 关
  • 后端渲染页面 → 开

13.

使用hutool工具库替代Spring的RestTemplate实现第三方AI接口调用，原生ResrTemplate需要手动创建配置类、注入bean相对冗余

14.

使用双层token（accessToken + refreshToken），accessToken只有30分钟有效期保证泄露时间短，refreshToken有效期7天，在这7天内用户无需再次登录保证体验，配合前端自动刷新可以做到7天内用户无需再次登录，双层token机制在安全性和用户体验之间找到完美平衡；

accessToken存储位置：前端本地（localStorage），因为验证它时不需要查数据库或redis

refreshToken存储位置：前端 + redis；   原因1：因为要实现主动失效功能，例如用户修改密码、登出、账户被锁定时需要立即失效token，这样即使旧的accessToken还没过期也无法获取新的accessToken，最多就30分钟泄露的时间，大大降低风险；   原因2：防止refreshToken被重复使用，refreshToken是一次性用的，刷新token验证成功后立即删除旧的refreshToken并生成和存储新的refreshToken，即使被泄露也只能用一次

方案	安全性	用户体验
只用一个长有效期 Token	低（泄露后危害大）	好（长时间不用登录）
只用一个短有效期 Token	高	差（频繁登录）
双层 Token	高	好