Swagger、缓存与对象存储
作者: luote (luote) · 个人主页 luote996.cn
本章介绍脚手架中的接口文档、缓存方案、文件存储与 AI 校验，属于后端进阶但 0 基础读者也应知道「它们是干什么的」。
SpringDoc OpenAPI（Swagger）
作用
自动生成可交互的 HTTP 接口文档，开发阶段在浏览器里直接试调接口，无需先写前端页面。
访问地址
本地启动后端后打开：
http://localhost:8080/swagger-ui.html常用注解
| 注解 | 作用 |
|---|---|
| @Tag | Controller 分组名称 |
| @Operation | 接口摘要 |
| @Parameter | 参数说明 |
| @Schema | DTO/VO 字段说明 |
在 Swagger 中先调 /auth/captcha 获取验证码，再调 /auth/login，拿到 Token 后点击 Authorize 填入 Bearer <token>，即可测试需登录的接口。
JetCache 缓存
为什么需要缓存
读多写少的场景（如用户信息）每次都查 MySQL 压力大。缓存把热点数据放内存或 Redis，降低延迟与数据库负载。
缓存问题（了解概念）
| 问题 | 含义 | 脚手架对策 |
|---|---|---|
| 穿透 | 查不存在的数据，缓存拦不住 | 空值缓存、布隆过滤器思路 |
| 击穿 | 热点 key 过期瞬间大量请求打穿 DB | 互斥锁、逻辑过期 |
| 雪崩 | 大量 key 同时过期 | 随机 TTL |
| 热点 key | 单个 key 访问量极大 | 本地缓存 + 分散 |
| 大 key | value 过大拖慢 Redis | 拆分、压缩 |
详见 缓存方案。
在代码中的样子
UserCacheService 等对查询方法加 @Cached，更新/删除时 @CacheInvalidate。具体 key 规则与 TTL 见 CacheConstant 与配置项 luote.cache.*。
MinIO 与阿里云 OSS
对象存储是什么
图片、视频、文档等文件不适合存 MySQL，应存 对象存储。MinIO 是可自建的 S3 兼容服务；阿里云 OSS 是云厂商托管方案。
StorageService 抽象
StorageService 接口统一 upload、delete、getUrl。StorageServiceImpl 优先写 MinIO，失败时可回落 OSS（保底），对 Controller 透明。
FileController 提供上传接口，返回可访问 URL 给前端展示。
配置
在 .env 中配置 MinIO/OSS 的 endpoint、accessKey、bucket 等，见 环境变量。
Spring AI Alibaba（通义千问）
作用
对用户输入内容做 AI 校验，例如注册昵称是否违规、评论是否含敏感信息。
使用方式
在方法上标注 @AiValidate，AOP 切面 AiValidationAspect 调用 DashScope API，不通过则抛出业务异常。
需在 .env 配置 DASHSCOPE_API_KEY。未配置或关闭开关时不影响主流程（按项目配置而定，以 LuoteProperties 为准）。
与 luote 脚手架的关系
| 模块 | 入口文件 |
|---|---|
| Swagger | config/SwaggerConfig.java |
| 缓存 | common/cache/*、guide/cache.md |
| 存储 | service/impl/StorageServiceImpl.java |
| AI 校验 | common/ai/AiValidationAspect.java |
完成本章后，后端技术栈主线已覆盖。接下来学习前端章节，或直接进入 二次开发入门。
下一章（前端）：TypeScript 基础