From 8ab6dbdb8cf9882a8b50ade772a7df77ef82efb6 Mon Sep 17 00:00:00 2001 From: YDY <1960209065@qq.com> Date: Mon, 27 Oct 2025 18:39:26 +0800 Subject: [PATCH] =?UTF-8?q?ydy=E6=B7=BB=E5=8A=A0=E4=BA=86=E6=B3=A8?= =?UTF-8?q?=E9=87=8A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../aurora/controller/ArticleController.java | 92 ++++++-- .../controller/AuroraInfoController.java | 46 ++-- .../controller/BizExceptionController.java | 12 +- .../aurora/controller/CategoryController.java | 20 +- .../aurora/controller/CommentController.java | 13 +- .../controller/ExceptionLogController.java | 3 +- .../controller/FriendLinkController.java | 6 +- .../com/aurora/controller/JobController.java | 18 +- .../aurora/controller/JobLogController.java | 7 +- .../com/aurora/controller/MenuController.java | 16 +- .../controller/OperationLogController.java | 5 +- .../controller/PhotoAlbumController.java | 18 +- .../aurora/controller/PhotoController.java | 17 +- .../aurora/controller/ResourceController.java | 9 +- .../com/aurora/controller/RoleController.java | 3 +- .../com/aurora/controller/TagController.java | 8 +- .../com/aurora/controller/TalkController.java | 14 +- .../aurora/controller/UserAuthController.java | 25 +- .../aurora/controller/UserInfoController.java | 22 +- .../java/com/aurora/mapper/AboutMapper.java | 8 +- .../java/com/aurora/mapper/ArticleMapper.java | 47 ++-- .../com/aurora/mapper/ArticleTagMapper.java | 4 +- .../com/aurora/mapper/CategoryMapper.java | 14 +- .../java/com/aurora/mapper/CommentMapper.java | 32 ++- .../aurora/mapper/ElasticsearchMapper.java | 14 +- .../com/aurora/mapper/ExceptionLogMapper.java | 9 +- .../com/aurora/mapper/FriendLinkMapper.java | 6 +- .../java/com/aurora/mapper/JobLogMapper.java | 11 +- .../java/com/aurora/mapper/JobMapper.java | 24 +- .../java/com/aurora/mapper/MenuMapper.java | 12 +- .../com/aurora/mapper/OperationLogMapper.java | 4 +- .../com/aurora/mapper/PhotoAlbumMapper.java | 12 +- .../java/com/aurora/mapper/RoleMapper.java | 20 +- .../java/com/aurora/mapper/TagMapper.java | 21 +- .../com/aurora/mapper/UniqueViewMapper.java | 12 +- .../com/aurora/mapper/UserAuthMapper.java | 12 +- .../aurora/mapper/WebsiteConfigMapper.java | 6 +- .../com/aurora/service/ArticleService.java | 72 ++++-- .../com/aurora/service/AuroraInfoService.java | 33 +-- .../com/aurora/service/CategoryService.java | 24 +- .../com/aurora/service/CommentService.java | 24 +- .../aurora/service/ExceptionLogService.java | 4 +- .../com/aurora/service/FriendLinkService.java | 4 +- .../com/aurora/service/JobLogService.java | 10 +- .../java/com/aurora/service/JobService.java | 12 +- .../java/com/aurora/service/MenuService.java | 6 +- .../com/aurora/service/PhotoAlbumService.java | 2 +- .../java/com/aurora/service/PhotoService.java | 6 +- .../java/com/aurora/service/RedisService.java | 215 ++++++++++-------- .../com/aurora/service/ResourceService.java | 7 +- .../java/com/aurora/service/RoleService.java | 8 +- .../java/com/aurora/service/TalkService.java | 2 +- .../java/com/aurora/service/TokenService.java | 44 +++- .../com/aurora/service/UserAuthService.java | 16 +- .../com/aurora/service/UserInfoService.java | 20 +- 55 files changed, 730 insertions(+), 401 deletions(-) diff --git a/aurora-springboot/src/main/java/com/aurora/controller/ArticleController.java b/aurora-springboot/src/main/java/com/aurora/controller/ArticleController.java index f79ea68..1c48edf 100644 --- a/aurora-springboot/src/main/java/com/aurora/controller/ArticleController.java +++ b/aurora-springboot/src/main/java/com/aurora/controller/ArticleController.java @@ -19,49 +19,68 @@ import javax.validation.Valid; import java.util.List; import static com.aurora.constant.OptTypeConstant.*; - -@Api(tags = "文章模块") -@RestController -public class ArticleController { - - @Autowired +//API（Application Programming Interface，应用程序编程接口）就像是一个软件服务员 +// 它定义了一套明确的规则，让不同的软件应用能够安全、高效地相互“对话”和协作，而无需了解对方内部的复杂细节 +//使用Swagger注解标记本类为API的"文章模块"分组，方便生成交互式文档 +@Api(tags = "文章模块") //类定义，@Api注解来自Swagger，用于分组API文档,给API接口添加标签 +@RestController //一个REST控制器，返回数据而非视图,返回数据通常为JSON格式,结合了@Controller和@ResponseBody，用于REST API +public class ArticleController { //每个API方法使用@GetMapping、@PostMapping等，对应HTTP方法 + //使用依赖注入自动装配ArticleService，避免手动实例化（推荐构造函数注入，但字段注入常见于简单场景） + @Autowired //字段注入：@Autowired 用于依赖注入 private ArticleService articleService; @Autowired - private UploadStrategyContext uploadStrategyContext; + private UploadStrategyContext uploadStrategyContext; // 注入文件上传策略上下文，用于处理文件存储（如文章图片） @Autowired - private ArticleImportStrategyContext articleImportStrategyContext; + private ArticleImportStrategyContext articleImportStrategyContext; // 注入文章导入策略上下文，支持多种格式的文章导入（如Markdown、Word） + // 获取置顶和推荐文章：HTTP GET请求，路径为/articles/topAndFeatured @ApiOperation("获取置顶和推荐文章") @GetMapping("/articles/topAndFeatured") public ResultVO listTopAndFeaturedArticles() { - return ResultVO.ok(articleService.listTopAndFeaturedArticles()); + return ResultVO.ok(articleService.listTopAndFeaturedArticles());// 调用Service层方法，返回统一封装的结果对象ResultVO } + // 获取所有文章列表（分页卡片形式） @ApiOperation("获取所有文章") @GetMapping("/articles/all") + //返回值是ResultVO>，其中ResultVO是统一的返回结果包装类 + //PageResultDTO是分页结果的封装类，ArticleCardDTO是文章卡片形式的数据传输对象（只包含文章列表展示需要的信息，比如标题、简介） public ResultVO> listArticles() { return ResultVO.ok(articleService.listArticles()); } + // 根据分类ID查询文章：使用@RequestParam接收URL查询参数（如?categoryId=1） @ApiOperation("根据分类id获取文章") @GetMapping("/articles/categoryId") public ResultVO> getArticlesByCategoryId(@RequestParam Integer categoryId) { + //@RequestParam用来接收URL查询参数（就是URL中？后面的参数），如果@RequestParam后没写参数名，默认会匹配和方法名参数一致的查询参数 return ResultVO.ok(articleService.listArticlesByCategoryId(categoryId)); + //PageResultDTO为分页文章卡片数据 } - @ApiOperation("根据id获取文章") + // 根据文章ID获取详情：使用@PathVariable从URL路径中提取参数（如/articles/1） + @ApiOperation("根据id获取文章") //是Swagger相关的注解，用来给接口添加说明，方便生成接口文档让开发、测试人员查看 @GetMapping("/articles/{articleId}") + //@GetMapping表示这是一个处理GET请求的接口，接口路径为/articles/{articleId} + //其中{articleId}是一个路径参数占位符比如请求/articles/1时，1就会作为articleId的值 public ResultVO getArticleById(@PathVariable("articleId") Integer articleId) { + //@PathVariable("articleId"):用于从URL路径中提取和占位符所对应的参数，把它赋值给方法参数Integer articleId return ResultVO.ok(articleService.getArticleById(articleId)); + //调用articleService（业务对象）的getArticleById方法，传入获取到的articleId来查询文章详情 + //最后用ResultVO.ok()把查询到的ArticleDTO（文章数据传输对象）包装成统一的返回结果并返回 } + // 校验文章访问密码：@RequestBody接收JSON格式的密码对象 @ApiOperation("校验文章访问密码") - @PostMapping("/articles/access") + @PostMapping("/articles/access")//处理post请求的接口。请求路径为/articles/access（post请求更适合传递密码这类私密数据） public ResultVO accessArticle(@Valid @RequestBody ArticlePasswordVO articlePasswordVO) { + // @Valid触发参数校验，确保ArticlePasswordVO对象中的参数符合约束（如非空，密码格式，必填） + //@RequestBody表示把请求体（RequestBody）中的JSON数据转换为ArticlePasswordVO类型的对象articlePasswordVO + //调用业务对象articleService的accessArticle方法，传入密码参数对象进行校验，校验完成后通过ResultVO.ok()返回成功的统一结果 articleService.accessArticle(articlePasswordVO); - return ResultVO.ok(); + return ResultVO.ok();// 返回空结果表示成功 } @ApiOperation("根据标签id获取文章") @@ -70,34 +89,42 @@ public class ArticleController { return ResultVO.ok(articleService.listArticlesByTagId(tagId)); } - @ApiOperation("获取所有文章归档") - @GetMapping("/archives/all") + @ApiOperation("获取所有文章归档") //获取文章归档列表（按时间分组） + @GetMapping("/archives/all") //无参数 public ResultVO> listArchives() { + //是文章归档的数据传输对象（包含年月，对应的文章数量等信息） return ResultVO.ok(articleService.listArchives()); } @ApiOperation("获取后台文章") - @GetMapping("/admin/articles") + @GetMapping("/admin/articles") //路径带/admin说明是后台接口，通常需要权限 public ResultVO> listArticlesAdmin(ConditionVO conditionVO) { + //ConditionVO conditionVO是用来传递查询条件，比如文章标题、状态等筛选条件，是一个条件封装的VO（Value Object,值对象）类 + //ArticleAdminDTO是后台文章的数据传输对象（会包含更多的管理相关的信息） return ResultVO.ok(articleService.listArticlesAdmin(conditionVO)); } - @OptLog(optType = SAVE_OR_UPDATE) + // 保存或更新文章：@RequestBody接收文章数据，@Valid触发校验 + @OptLog(optType = SAVE_OR_UPDATE) //项目里自定义注解，记录操作日志（如保存/更新），作用是自动记录该接口的操作日志 @ApiOperation("保存和修改文章") @PostMapping("/admin/articles") public ResultVO saveOrUpdateArticle(@Valid @RequestBody ArticleVO articleVO) { + //@Valid触发对ArticleVO对象的参数校验（比如文章标题不为空，内容长度是否符合要求等），需要在ArticleVO的属性上配置@NotBlank、@Length等校验注解 + //@RequestBody：将前端传递到请求体（JSON形式）的文章数据，转换成ArticleVO类型的对象articleVO articleService.saveOrUpdateArticle(articleVO); return ResultVO.ok(); } @OptLog(optType = UPDATE) @ApiOperation("修改文章是否置顶和推荐") - @PutMapping("/admin/articles/topAndFeatured") + @PutMapping("/admin/articles/topAndFeatured") //处理PUT请求的后台接口（PUT常用于更新数据） public ResultVO updateArticleTopAndFeatured(@Valid @RequestBody ArticleTopFeaturedVO articleTopFeaturedVO) { + //@RequestBody将请求体中JSON格式的“文章ID+置顶状态+推荐状态”数据，转换成ArticleTopFeaturedVO类型的对象articleTopFeaturedVO articleService.updateArticleTopAndFeatured(articleTopFeaturedVO); return ResultVO.ok(); } + // 逻辑删除或恢复文章（通过更新状态字段而非物理删除），不是从数据库删除，而是通过修改文章的“状态字段” @ApiOperation("删除或者恢复文章") @PutMapping("/admin/articles") public ResultVO updateArticleDelete(@Valid @RequestBody DeleteVO deleteVO) { @@ -105,48 +132,69 @@ public class ArticleController { return ResultVO.ok(); } + //直接从数据库删除文章，无法恢复 @OptLog(optType = DELETE) @ApiOperation(value = "物理删除文章") - @DeleteMapping("/admin/articles/delete") + @DeleteMapping("/admin/articles/delete") //处理DELETE请求的后台接口（DELETE请求专门用于删除类操作） public ResultVO deleteArticles(@RequestBody List articleIds) { + //@RequestBody:将请求体中JSON形式的文章ID列表（List articleIds）转换成相应的集合对象，比如前端传递[1,2,3]，就会对应删除ID为1，2,3的文章 articleService.deleteArticles(articleIds); return ResultVO.ok(); } - @OptLog(optType = UPLOAD) + // 上传文章图片：MultipartFile接收文件，返回图片访问路径 + @OptLog(optType = UPLOAD) //表示“上传”类型的操作，用来自动记录“上传文章图片”的操作日志 @ApiOperation("上传文章图片") @ApiImplicitParam(name = "file", value = "文章图片", required = true, dataType = "MultipartFile") + // 给Swagger文档补充参数说明，参数名file，含义是“文章图片”，为必填项，数据类型为MultipartFile（Spring中专门用来接收上传文件的类型） @PostMapping("/admin/articles/images") public ResultVO saveArticleImages(MultipartFile file) { + // 通过策略上下文上传文件，FilePathEnum指定存储路径 + //参数MultipartFile：接受前端上传的图片文件 + //返回值ResultVO：返回图片的访问路径（字符串形式，比如/upload/artic;e/202505/123.jpg) return ResultVO.ok(uploadStrategyContext.executeUploadStrategy(file, FilePathEnum.ARTICLE.getPath())); } + // 后台根据文章ID获取详情（可能包含敏感字段） @ApiOperation("根据id查看后台文章") @ApiImplicitParam(name = "articleId", value = "文章id", required = true, dataType = "Integer") - @GetMapping("/admin/articles/{articleId}") + @GetMapping("/admin/articles/{articleId}")//{articleId}为路径参数，比如查询ID为。。的文章 public ResultVO getArticleBackById(@PathVariable("articleId") Integer articleId) { + //参数@PathVariable：将URL路径中{articleId}对应的数值转换成Integer类型的参数articleId + //ArticleAdminViewDTO是后台文章详情的数据传输对象，包含文章的完整信息（含敏感字段） return ResultVO.ok(articleService.getArticleByIdAdmin(articleId)); } + // 导入文章：文件+类型参数，支持多种格式 @OptLog(optType = UPLOAD) @ApiOperation(value = "导入文章") @PostMapping("/admin/articles/import") public ResultVO importArticles(MultipartFile file, @RequestParam(required = false) String type) { + //参数MultipartFile：接受前端上传的文章导入文件（各种格式） + //@RequestParam(required = false) String type：接受文件类型参数，required=false表示类型参数可选（不传则默认形式） articleImportStrategyContext.importArticles(file, type); return ResultVO.ok(); } - @OptLog(optType = EXPORT) + // 导出文章：返回导出文件的路径或ID列表 + @OptLog(optType = EXPORT) //表示这是“导出”类型的操作，用来记录“到处文章”的操作日志 @ApiOperation(value = "导出文章") @ApiImplicitParam(name = "articleIdList", value = "文章id", required = true, dataType = "List") - @PostMapping("/admin/articles/export") + //value为必填项，数据类型List（文章ID的集合） + @PostMapping("/admin/articles/export")//导出操作需传递文章ID列表，用POST请求更适合传递集合类参数 public ResultVO> exportArticles(@RequestBody List articleIds) { + //@RequestBody：将请求体中JSON形式的文章ID列表转换成List类型的参数articleIds return ResultVO.ok(articleService.exportArticles(articleIds)); + //调用业务层articleService.exportArticles(articleIds)执行文章导出操作，导出完成后返回文件路径/ID列表的统一结果 } + // 搜索文章接口：通过ConditionVO封装搜索条件（如关键词、分类、发布时间范围等） @ApiOperation(value = "搜索文章") @GetMapping("/articles/search") public ResultVO> listArticlesBySearch(ConditionVO condition) { + //ConditionVO condition：接收前端传递的搜索条件 + //如果是GET请求，条件会以查询参数的形式传递，比如/articles/search?keyword=春天&pageNum=1，Spring会自动把查询参数匹配到ConditionVO的属性上） + //ArticleSearchDTO是搜索结果的展示类（只包含标题、简介、发布时间等搜索结果需要的信息） return ResultVO.ok(articleService.listArticlesBySearch(condition)); } diff --git a/aurora-springboot/src/main/java/com/aurora/controller/AuroraInfoController.java b/aurora-springboot/src/main/java/com/aurora/controller/AuroraInfoController.java index 4ed9019..350d288 100644 --- a/aurora-springboot/src/main/java/com/aurora/controller/AuroraInfoController.java +++ b/aurora-springboot/src/main/java/com/aurora/controller/AuroraInfoController.java @@ -23,68 +23,86 @@ import javax.validation.Valid; import static com.aurora.constant.OptTypeConstant.UPDATE; import static com.aurora.constant.OptTypeConstant.UPLOAD; -@Api(tags = "aurora信息") -@RestController +//AuroraInfoController控制器类，用于处理访客上报和首页信息获取的请求 +@Api(tags = "aurora信息")// 使用Swagger注解标记本类为API的"aurora信息"分组，方便生成交互式API文档 +@RestController// 标识本类为RESTful控制器，组合了@Controller和@ResponseBody，所有方法返回值直接写入HTTP响应体 public class AuroraInfoController { - @Autowired + @Autowired // 使用依赖注入自动装配AuroraInfoService，用于处理访客上报和首页信息查询等业务逻辑 private AuroraInfoService auroraInfoService; - @Autowired + @Autowired // 注入文件上传策略上下文，用于处理图片等文件的上传操作 private UploadStrategyContext uploadStrategyContext; @ApiOperation(value = "上报访客信息") - @PostMapping("/report") + @PostMapping("/report") // 处理HTTP POST请求，路径为/report + // 返回ResultVO表示统一响应格式，?通配符表示返回值类型不确定或无返回体 public ResultVO report() { + // 调用Service层方法处理访客上报的业务（如增加访客计数） auroraInfoService.report(); + // 返回操作成功的统一响应 return ResultVO.ok(); } + // 获取系统首页信息（前端展示用） @ApiOperation(value = "获取系统信息") - @GetMapping("/") + @GetMapping("/") // 处理HTTP GET请求，路径为/（通常是根路径或首页） + // 返回结果封装了AuroraHomeInfoDTO对象，包含博客首页所需的各种信息（比如文章标题...) public ResultVO getBlogHomeInfo() { return ResultVO.ok(auroraInfoService.getAuroraHomeInfo()); } + // 获取系统后台管理信息（后台管理界面用） @ApiOperation(value = "获取系统后台信息") - @GetMapping("/admin") + @GetMapping("/admin") // 处理HTTP GET请求，路径为/admin public ResultVO getBlogBackInfo() { + // 调用Service获取后台管理信息，可能包含统计数据、系统状态等 + //AuroraAdminInfoDTO为后台信息的封装类 return ResultVO.ok(auroraInfoService.getAuroraAdminInfo()); } - @OptLog(optType = UPDATE) + //网站配置的后台接口 + @OptLog(optType = UPDATE)// 自定义操作日志注解，记录更新操作（UPDATE为操作类型常量） @ApiOperation(value = "更新网站配置") @PutMapping("/admin/website/config") public ResultVO updateWebsiteConfig(@Valid @RequestBody WebsiteConfigVO websiteConfigVO) { + // @Valid触发参数校验，@RequestBody接收JSON格式的网站配置数据 auroraInfoService.updateWebsiteConfig(websiteConfigVO); return ResultVO.ok(); } - @ApiOperation(value = "获取网站配置") + @ApiOperation(value = "获取网站配置")//获取网站配置的后台接口 @GetMapping("/admin/website/config") public ResultVO getWebsiteConfig() { return ResultVO.ok(auroraInfoService.getWebsiteConfig()); } + // 查看关于我信息（前台展示接口） @ApiOperation(value = "查看关于我信息") - @GetMapping("/about") + @GetMapping("/about")//处理GET请求的普通接口。普通用户也可访问 public ResultVO getAbout() { + //AboutDTO是“关于我”信息的封装类（包含个人介绍，头像，联系方式等） return ResultVO.ok(auroraInfoService.getAbout()); } - @OptLog(optType = UPDATE) - @ApiOperation(value = "修改关于我信息") + //修改“关于我”信息的后台管理接口 + @OptLog(optType = UPDATE) // 记录更新操作日志 + @ApiOperation(value = "修改关于我信息")// 修改关于我信息（后台管理） @PutMapping("/admin/about") public ResultVO updateAbout(@Valid @RequestBody AboutVO aboutVO) { + // @Valid校验AboutVO参数的合法性 auroraInfoService.updateAbout(aboutVO); return ResultVO.ok(); } - @OptLog(optType = UPLOAD) - @ApiOperation(value = "上传博客配置图片") + @OptLog(optType = UPLOAD)// 记录上传操作日志 + @ApiOperation(value = "上传博客配置图片")//后台接口 @ApiImplicitParam(name = "file", value = "图片", required = true, dataType = "MultipartFile") + // Swagger参数说明，name指定参数名，value是描述，required=true表示必填，dataType是数据类型 @PostMapping("/admin/config/images") + // 返回结果是图片访问路径的字符串 public ResultVO savePhotoAlbumCover(MultipartFile file) { + //通过上传策略上下文执行文件上传，FilePathEnum.CONFIG.getPath()指定配置文件存储路径 return ResultVO.ok(uploadStrategyContext.executeUploadStrategy(file, FilePathEnum.CONFIG.getPath())); } diff --git a/aurora-springboot/src/main/java/com/aurora/controller/BizExceptionController.java b/aurora-springboot/src/main/java/com/aurora/controller/BizExceptionController.java index 9d09ef9..c2f8e8d 100644 --- a/aurora-springboot/src/main/java/com/aurora/controller/BizExceptionController.java +++ b/aurora-springboot/src/main/java/com/aurora/controller/BizExceptionController.java @@ -8,20 +8,22 @@ import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; import javax.servlet.http.HttpServletRequest; - +//业务异常处理控制器，用于统一处理BizException类型的异常 @Api(tags = "异常处理模块") -@RestController +@RestController//返回的结果会直接作为响应体返回 public class BizExceptionController { - @SneakyThrows + @SneakyThrows //用于隐藏异常的显示抛出声明（不用写throws Exception等声明） @ApiOperation("/处理BizException") - @RequestMapping("/bizException") + @RequestMapping("/bizException")//映射请求路径为：/bizException，接收该路径的请求来处理异常 public void handleBizException(HttpServletRequest request) { + //HttpServletRequest request：通过请求对象获取存储在其中的异常信息 if (request.getAttribute("bizException") instanceof BizException) { + //如果是BizException类型，先打印该异常信息，再将其强制转换为BizException并抛出 System.out.println(request.getAttribute("bizException")); throw ((BizException) request.getAttribute("bizException")); } else { - throw new Exception(); + throw new Exception();//抛出新的Exception } } diff --git a/aurora-springboot/src/main/java/com/aurora/controller/CategoryController.java b/aurora-springboot/src/main/java/com/aurora/controller/CategoryController.java index 8b58b3b..f6247ec 100644 --- a/aurora-springboot/src/main/java/com/aurora/controller/CategoryController.java +++ b/aurora-springboot/src/main/java/com/aurora/controller/CategoryController.java @@ -20,26 +20,34 @@ import java.util.List; import static com.aurora.constant.OptTypeConstant.*; @Api(tags = "分类模块") -@RestController +@RestController// 标识本类为RESTful控制器，组合了@Controller和@ResponseBody，所有方法返回值直接序列化为JSON响应 public class CategoryController { @Autowired - private CategoryService categoryService; + private CategoryService categoryService; //用于处理分类相关的业务逻辑 - @ApiOperation("获取所有分类") + @ApiOperation("获取所有分类")// Swagger注解描述API功能：获取所有分类（通常用于前台展示） @GetMapping("/categories/all") + // 返回值ResultVO>是统一的响应包装类（用来规范接口返回的格式，比如包含响应状态、提示信息、数据等） + //List是分类数据的列表，CategoryDTO是分类相关的数据传输对象（用来封装分类的信息） public ResultVO> listCategories() { + // 调用Service层方法获取所有分类列表，并用ResultVO包装成成功响应 return ResultVO.ok(categoryService.listCategories()); } - @ApiOperation(value = "查看后台分类列表") + @ApiOperation(value = "查看后台分类列表")// 查看后台分类列表（通常包含分页和查询条件） @GetMapping("/admin/categories") + // 返回分页结果，包含CategoryAdminDTO列表（可能比前台DTO包含更多管理字段） public ResultVO> listCategoriesAdmin(ConditionVO conditionVO) { + //ConditionVO是条件封装类，用来接收前端传递的查询条件（比如分类名称、分页信息等） return ResultVO.ok(categoryService.listCategoriesAdmin(conditionVO)); } - @ApiOperation(value = "搜索文章分类") + @ApiOperation(value = "搜索文章分类")//后台管理的搜索文章分类的接口 @GetMapping("/admin/categories/search") + // 返回CategoryOptionDTO列表，通常用于下拉选择框等场景 + //CategoryOptionDTO是适配“选项选择”场景的分类传输对象（比如下拉选择框里的分类选项，通常只封装分类ID和分类名称等） + //List是符合搜索条件的分类选项列表 public ResultVO> listCategoriesAdminBySearch(ConditionVO conditionVO) { return ResultVO.ok(categoryService.listCategoriesBySearch(conditionVO)); } @@ -47,6 +55,7 @@ public class CategoryController { @OptLog(optType = DELETE) @ApiOperation(value = "删除分类") @DeleteMapping("/admin/categories") + // @RequestBody接收前端以JSON格式传递的请求体数据，转换成要删除的分类ID列表，ResultVO表示无具体返回数据，仅返回操作成功的状态提示 public ResultVO deleteCategories(@RequestBody List categoryIds) { categoryService.deleteCategories(categoryIds); return ResultVO.ok(); @@ -56,6 +65,7 @@ public class CategoryController { @ApiOperation(value = "添加或修改分类") @PostMapping("/admin/categories") public ResultVO saveOrUpdateCategory(@Valid @RequestBody CategoryVO categoryVO) { + // Service层会通过CategorVO中是否包含分类ID等信息，判断是执行添加还是修改操作 categoryService.saveOrUpdateCategory(categoryVO); return ResultVO.ok(); } diff --git a/aurora-springboot/src/main/java/com/aurora/controller/CommentController.java b/aurora-springboot/src/main/java/com/aurora/controller/CommentController.java index fbd0fd6..688e3f1 100644 --- a/aurora-springboot/src/main/java/com/aurora/controller/CommentController.java +++ b/aurora-springboot/src/main/java/com/aurora/controller/CommentController.java @@ -23,24 +23,27 @@ import static com.aurora.constant.OptTypeConstant.*; public class CommentController { @Autowired - private CommentService commentService; + private CommentService commentService;// 使用依赖注入自动装配CommentService，用于处理评论相关的业务逻辑 - @AccessLimit(seconds = 60, maxCount = 3) - @OptLog(optType = SAVE) + @AccessLimit(seconds = 60, maxCount = 3)// 自定义注解：访问限制，60秒内同一用户最多允许3次请求（防刷机制） + @OptLog(optType = SAVE)//SAVE为操作类型常量 @ApiOperation("添加评论") @PostMapping("/comments/save") public ResultVO saveComment(@Valid @RequestBody CommentVO commentVO) { + //CommentVO为评论的参数封装类 commentService.saveComment(commentVO); return ResultVO.ok(); } - @ApiOperation("获取评论") + @ApiOperation("获取评论")// 获取评论列表（通常用于前台展示，支持分页和查询条件） @GetMapping("/comments") + // 返回分页结果，包含CommentDTO列表；PageResultDTO为分页结果封装类，包含总条数、当前页数等分页信息 public ResultVO> getComments(CommentVO commentVO) { + //CommentVO为评论的查询条件封装类，用来接收前端传递的查询条件 return ResultVO.ok(commentService.listComments(commentVO)); } - @ApiOperation(value = "根据commentId获取回复") + @ApiOperation(value = "根据commentId获取回复")// 根据评论ID获取该评论的所有回复列表 @GetMapping("/comments/{commentId}/replies") public ResultVO> listRepliesByCommentId(@PathVariable("commentId") Integer commentId) { return ResultVO.ok(commentService.listRepliesByCommentId(commentId)); diff --git a/aurora-springboot/src/main/java/com/aurora/controller/ExceptionLogController.java b/aurora-springboot/src/main/java/com/aurora/controller/ExceptionLogController.java index f782b3d..a5d7ac0 100644 --- a/aurora-springboot/src/main/java/com/aurora/controller/ExceptionLogController.java +++ b/aurora-springboot/src/main/java/com/aurora/controller/ExceptionLogController.java @@ -23,11 +23,12 @@ import static com.aurora.constant.OptTypeConstant.DELETE; public class ExceptionLogController { @Autowired - private ExceptionLogService exceptionLogService; + private ExceptionLogService exceptionLogService;//Spring依赖注入注解，自动注入ExceptionLogService的实例 @ApiOperation("获取异常日志") @GetMapping("/admin/exception/logs") public ResultVO> listExceptionLogs(ConditionVO conditionVO) { + //ConditionVO conditionVO：封装后台查询异常日志的条件（比如日志的时间范围、异常类型等） return ResultVO.ok(exceptionLogService.listExceptionLogs(conditionVO)); } diff --git a/aurora-springboot/src/main/java/com/aurora/controller/FriendLinkController.java b/aurora-springboot/src/main/java/com/aurora/controller/FriendLinkController.java index e97ba24..b20ff63 100644 --- a/aurora-springboot/src/main/java/com/aurora/controller/FriendLinkController.java +++ b/aurora-springboot/src/main/java/com/aurora/controller/FriendLinkController.java @@ -23,9 +23,9 @@ import static com.aurora.constant.OptTypeConstant.*; public class FriendLinkController { @Autowired - private FriendLinkService friendLinkService; + private FriendLinkService friendLinkService;//调用Service层的友链业务方法 - @ApiOperation(value = "查看友链列表") + @ApiOperation(value = "查看友链列表")//用于前台展示 @GetMapping("/links") public ResultVO> listFriendLinks() { return ResultVO.ok(friendLinkService.listFriendLinks()); @@ -34,6 +34,7 @@ public class FriendLinkController { @ApiOperation(value = "查看后台友链列表") @GetMapping("/admin/links") public ResultVO> listFriendLinkDTO(ConditionVO conditionVO) { + //ConditionVO conditionVO:封装后台查询友链的条件（比如友链名称关键词、分页信息等） return ResultVO.ok(friendLinkService.listFriendLinksAdmin(conditionVO)); } @@ -41,6 +42,7 @@ public class FriendLinkController { @ApiOperation(value = "保存或修改友链") @PostMapping("/admin/links") public ResultVO saveOrUpdateFriendLink(@Valid @RequestBody FriendLinkVO friendLinkVO) { + //FriendLinkVO friendLinkVO:封装友链保存/修改的参数，且会被@Valid校验 friendLinkService.saveOrUpdateFriendLink(friendLinkVO); return ResultVO.ok(); } diff --git a/aurora-springboot/src/main/java/com/aurora/controller/JobController.java b/aurora-springboot/src/main/java/com/aurora/controller/JobController.java index cd95242..a3b76ec 100644 --- a/aurora-springboot/src/main/java/com/aurora/controller/JobController.java +++ b/aurora-springboot/src/main/java/com/aurora/controller/JobController.java @@ -14,7 +14,7 @@ import java.util.List; import static com.aurora.constant.OptTypeConstant.*; -@Api(tags = "定时任务模块") +@Api(tags = "定时任务模块")//定时任务管理的控制器类 @RestController public class JobController { @@ -25,6 +25,7 @@ public class JobController { @ApiOperation("添加定时任务") @PostMapping("/admin/jobs") public ResultVO saveJob(@RequestBody JobVO jobVO) { + //JobVO jobVO：封装添加定时任务的所有参数（包含定时任务的名称、执行时间、执行逻辑相关配置等添加所需信息） jobService.saveJob(jobVO); return ResultVO.ok(); } @@ -46,34 +47,41 @@ public class JobController { } @ApiOperation("根据id获取任务") - @GetMapping("/admin/jobs/{id}") + @GetMapping("/admin/jobs/{id}")//Spring的请求映射注解，{id}是路径参数，前端调用时需填充具体的任务ID + //如：/admin/jobs/5 表示查询ID为5的定时任务 public ResultVO getJobById(@PathVariable("id") Integer jobId) { + //@PathVariable("id"):Spring的参数接收注解，获取URL路径中{id}对应的实际值，赋值给Integer jobId + //JobDTO是定时任务的数据传输对象（封装定时任务的详细信息，比如任务名称、执行规则、状态等），返回该ID对应的定时任务详情 return ResultVO.ok(jobService.getJobById(jobId)); } @ApiOperation("获取任务列表") @GetMapping("/admin/jobs") public ResultVO> listJobs(JobSearchVO jobSearchVO) { + //JobSearchVO jobSearchVO：封装定时任务的查询条件（比如任务名称关键词、任务分组、任务状态等） return ResultVO.ok(jobService.listJobs(jobSearchVO)); } - @ApiOperation("更改任务的状态") + @ApiOperation("更改任务的状态")//比如启用、禁用任务 @PutMapping("/admin/jobs/status") public ResultVO updateJobStatus(@RequestBody JobStatusVO jobStatusVO) { + //JobStatusVO jobStatusVO：封装任务状态修改的参数（包含任务ID、要修改的目标状态等信息） jobService.updateJobStatus(jobStatusVO); return ResultVO.ok(); } - @ApiOperation("执行某个任务") + @ApiOperation("执行某个任务")//说明接口功能是手动触发某个定时任务立即执行（无需等待定时时间） @PutMapping("/admin/jobs/run") public ResultVO runJob(@RequestBody JobRunVO jobRunVO) { + //JobRunVO jobRunVO：封装手动执行任务的参数（包含要执行的任务ID等信息） jobService.runJob(jobRunVO); return ResultVO.ok(); } - @ApiOperation("获取所有job分组") + @ApiOperation("获取所有job分组")//用于后台查询、添加任务时选择分组 @GetMapping("/admin/jobs/jobGroups") public ResultVO> listJobGroup() { + //返回值ResultVO>：返回包含所有任务分组名称的字符串列表 return ResultVO.ok(jobService.listJobGroups()); } } diff --git a/aurora-springboot/src/main/java/com/aurora/controller/JobLogController.java b/aurora-springboot/src/main/java/com/aurora/controller/JobLogController.java index c86e13a..39b4460 100644 --- a/aurora-springboot/src/main/java/com/aurora/controller/JobLogController.java +++ b/aurora-springboot/src/main/java/com/aurora/controller/JobLogController.java @@ -23,11 +23,12 @@ import static com.aurora.constant.OptTypeConstant.DELETE; public class JobLogController { @Autowired - private JobLogService jobLogService; + private JobLogService jobLogService;//调用Service层的日志业务方法 @ApiOperation("获取定时任务的日志列表") @GetMapping("/admin/jobLogs") public ResultVO> listJobLogs(JobLogSearchVO jobLogSearchVO) { + //JobLogSearchVO jobLogSearchVO：封装日志的查询条件（比如任务ID、执行状态、时间范围等） return ResultVO.ok(jobLogService.listJobLogs(jobLogSearchVO)); } @@ -42,13 +43,15 @@ public class JobLogController { @OptLog(optType = DELETE) @ApiOperation("清除定时任务的日志") @DeleteMapping("/admin/jobLogs/clean") + //返回值ResultVO：仅返回操作成功的状态，无具体业务数据 public ResultVO cleanJobLogs() { jobLogService.cleanJobLogs(); return ResultVO.ok(); } - @ApiOperation("获取定时任务日志的所有组名") + @ApiOperation("获取定时任务日志的所有组名")//用于后台查询日志时筛选分组 @GetMapping("/admin/jobLogs/jobGroups") + //返回值ResultVO：返回包含所有日志关联任务分组名称的结果（通常是字符串列表） public ResultVO listJobLogGroups() { return ResultVO.ok(jobLogService.listJobLogGroups()); } diff --git a/aurora-springboot/src/main/java/com/aurora/controller/MenuController.java b/aurora-springboot/src/main/java/com/aurora/controller/MenuController.java index d370f07..deb4137 100644 --- a/aurora-springboot/src/main/java/com/aurora/controller/MenuController.java +++ b/aurora-springboot/src/main/java/com/aurora/controller/MenuController.java @@ -24,11 +24,12 @@ import static com.aurora.constant.OptTypeConstant.*; public class MenuController { @Autowired - private MenuService menuService; + private MenuService menuService;//调用Service层的菜单业务方法 @ApiOperation(value = "查看菜单列表") @GetMapping("/admin/menus") public ResultVO> listMenus(ConditionVO conditionVO) { + //ConditionVO conditionVO：封装菜单的查询条件（比如菜单名称关键词、菜单类型等） return ResultVO.ok(menuService.listMenus(conditionVO)); } @@ -36,6 +37,8 @@ public class MenuController { @ApiOperation(value = "新增或修改菜单") @PostMapping("/admin/menus") public ResultVO saveOrUpdateMenu(@Valid @RequestBody MenuVO menuVO) { + //MenuVO menuVO：封装菜单新增、修改的参数，包含菜单名称、路径、父菜单ID等新增、修改所需信息，且会被@Valid校验 + //menuVO内涵菜单ID判断是新增还是修改 menuService.saveOrUpdateMenu(menuVO); return ResultVO.ok(); } @@ -44,27 +47,32 @@ public class MenuController { @ApiOperation(value = "修改目录是否隐藏") @PutMapping("/admin/menus/isHidden") public ResultVO updateMenuIsHidden(@RequestBody IsHiddenVO isHiddenVO) { + //IsHiddenVO isHiddenVO：封装菜单隐藏状态修改的参数，包含菜单ID\目标隐藏状态等信息 menuService.updateMenuIsHidden(isHiddenVO); return ResultVO.ok(); } @OptLog(optType = DELETE) @ApiOperation(value = "删除菜单") - @DeleteMapping("/admin/menus/{menuId}") + @DeleteMapping("/admin/menus/{menuId}")//{menuId}为路径参数，前端调用时需填充具体的菜单ID + //例如/admin/menus/3：表示删除ID为3的菜单 public ResultVO deleteMenu(@PathVariable("menuId") Integer menuId) { menuService.deleteMenu(menuId); return ResultVO.ok(); } - @ApiOperation(value = "查看角色菜单选项") + @ApiOperation(value = "查看角色菜单选项")//获取用于角色分配菜单时的选项列表，比如给某个角色配置可访问的菜单时，展示可选的菜单 @GetMapping("/admin/role/menus") + //返回值ResultVO>：返回所有可用的菜单选项列表 + //LabelOptionDTO为选项类的数据传输对象（包含菜单ID和菜单名称，用于下拉选择等场景） public ResultVO> listMenuOptions() { return ResultVO.ok(menuService.listMenuOptions()); } - @ApiOperation(value = "查看当前用户菜单") + @ApiOperation(value = "查看当前用户菜单")//用于系统侧边栏展示等场景 @GetMapping("/admin/user/menus") public ResultVO> listUserMenus() { + //无需参数，系统会自动获取当前登录用户的信息 return ResultVO.ok(menuService.listUserMenus()); } } diff --git a/aurora-springboot/src/main/java/com/aurora/controller/OperationLogController.java b/aurora-springboot/src/main/java/com/aurora/controller/OperationLogController.java index cbca7c2..43694c2 100644 --- a/aurora-springboot/src/main/java/com/aurora/controller/OperationLogController.java +++ b/aurora-springboot/src/main/java/com/aurora/controller/OperationLogController.java @@ -23,11 +23,12 @@ import static com.aurora.constant.OptTypeConstant.DELETE; public class OperationLogController { @Autowired - private OperationLogService operationLogService; + private OperationLogService operationLogService;//调用Service层的操作日志业务方法 - @ApiOperation(value = "查看操作日志") + @ApiOperation(value = "查看操作日志")//比如查看用户的新增、修改、删除等操作记录 @GetMapping("/admin/operation/logs") public ResultVO> listOperationLogs(ConditionVO conditionVO) { + //ConditionVO conditionVO：封装操作日志的查询条件（比如操作人、操作类型、时间范围等） return ResultVO.ok(operationLogService.listOperationLogs(conditionVO)); } diff --git a/aurora-springboot/src/main/java/com/aurora/controller/PhotoAlbumController.java b/aurora-springboot/src/main/java/com/aurora/controller/PhotoAlbumController.java index 9f46481..ac2ee65 100644 --- a/aurora-springboot/src/main/java/com/aurora/controller/PhotoAlbumController.java +++ b/aurora-springboot/src/main/java/com/aurora/controller/PhotoAlbumController.java @@ -26,19 +26,21 @@ import static com.aurora.constant.OptTypeConstant.*; @Api(tags = "相册模块") @RestController public class PhotoAlbumController { - @Autowired - private UploadStrategyContext uploadStrategyContext; + private UploadStrategyContext uploadStrategyContext;//用于文件上传 @Autowired - private PhotoAlbumService photoAlbumService; + private PhotoAlbumService photoAlbumService;//相册业务逻辑 @OptLog(optType = UPLOAD) @ApiOperation(value = "上传相册封面") @ApiImplicitParam(name = "file", value = "相册封面", required = true, dataType = "MultipartFile") + //Swagger注解，说明接口的参数信息：参数名file，含义是相册封面，必填，类型为MultipartFile（Spring的文件上传类型） @PostMapping("/admin/photos/albums/upload") + //返回值ResultVO：返回上传后封面图片的存储路径（字符串格式） public ResultVO savePhotoAlbumCover(MultipartFile file) { + //MultipartFile file：接收前端上传的相册封面文件 return ResultVO.ok(uploadStrategyContext.executeUploadStrategy(file, FilePathEnum.PHOTO.getPath())); } @@ -46,17 +48,19 @@ public class PhotoAlbumController { @ApiOperation(value = "保存或更新相册") @PostMapping("/admin/photos/albums") public ResultVO saveOrUpdatePhotoAlbum(@Valid @RequestBody PhotoAlbumVO photoAlbumVO) { + //PhotoAlbumVO photoAlbumVO：封装相册保存、更新的参数，包含相册名称、封面路径、描述等信息，且被@Valid校验 photoAlbumService.saveOrUpdatePhotoAlbum(photoAlbumVO); return ResultVO.ok(); } - @ApiOperation(value = "查看后台相册列表") + @ApiOperation(value = "查看后台相册列表")//分页 @GetMapping("/admin/photos/albums") public ResultVO> listPhotoAlbumBacks(ConditionVO conditionVO) { + //ConditionVO conditionVO：封装相册的查询条件（比如相册名称关键词、创建时间范围等） return ResultVO.ok(photoAlbumService.listPhotoAlbumsAdmin(conditionVO)); } - @ApiOperation(value = "获取后台相册列表信息") + @ApiOperation(value = "获取后台相册列表信息")//获取后台所有相册的基础信息列表（相比于分页列表，更偏向简洁的信息集合） @GetMapping("/admin/photos/albums/info") public ResultVO> listPhotoAlbumBackInfos() { return ResultVO.ok(photoAlbumService.listPhotoAlbumInfosAdmin()); @@ -65,6 +69,8 @@ public class PhotoAlbumController { @ApiOperation(value = "根据id获取后台相册信息") @ApiImplicitParam(name = "albumId", value = "相册id", required = true, dataType = "Integer") @GetMapping("/admin/photos/albums/{albumId}/info") + //返回值ResultVO：返回指定ID的相册详细信息 + //PhotoAlbumAdminDTO是后台相册详细数据传输对象 public ResultVO getPhotoAlbumBackById(@PathVariable("albumId") Integer albumId) { return ResultVO.ok(photoAlbumService.getPhotoAlbumByIdAdmin(albumId)); } @@ -78,7 +84,7 @@ public class PhotoAlbumController { return ResultVO.ok(); } - @ApiOperation(value = "获取相册列表") + @ApiOperation(value = "获取相册列表")//获取前端展示用的相册列表，普通用户也可调用 @GetMapping("/photos/albums") public ResultVO> listPhotoAlbums() { return ResultVO.ok(photoAlbumService.listPhotoAlbums()); diff --git a/aurora-springboot/src/main/java/com/aurora/controller/PhotoController.java b/aurora-springboot/src/main/java/com/aurora/controller/PhotoController.java index 974b0a7..5588a63 100644 --- a/aurora-springboot/src/main/java/com/aurora/controller/PhotoController.java +++ b/aurora-springboot/src/main/java/com/aurora/controller/PhotoController.java @@ -25,10 +25,10 @@ import static com.aurora.constant.OptTypeConstant.*; public class PhotoController { @Autowired - private PhotoService photoService; + private PhotoService photoService;//照片业务逻辑 @Autowired - private UploadStrategyContext uploadStrategyContext; + private UploadStrategyContext uploadStrategyContext;//文件上传服务 @OptLog(optType = UPLOAD) @ApiOperation(value = "上传照片") @@ -44,7 +44,7 @@ public class PhotoController { return ResultVO.ok(photoService.listPhotos(conditionVO)); } - @OptLog(optType = UPDATE) + @OptLog(optType = UPDATE)//修改类型 @ApiOperation(value = "更新照片信息") @PutMapping("/admin/photos") public ResultVO updatePhoto(@Valid @RequestBody PhotoInfoVO photoInfoVO) { @@ -61,32 +61,35 @@ public class PhotoController { } @OptLog(optType = UPDATE) - @ApiOperation(value = "移动照片相册") + @ApiOperation(value = "移动照片相册")//将照片从一个相册移到另一个相册 @PutMapping("/admin/photos/album") public ResultVO updatePhotosAlbum(@Valid @RequestBody PhotoVO photoVO) { + //PhotoVO photoVO：封装照片移动的参数，包含照片ID列表、目标相册ID等信息，且会被@Valid检验：检测目标相册ID是否存在 photoService.updatePhotosAlbum(photoVO); return ResultVO.ok(); } @OptLog(optType = UPDATE) - @ApiOperation(value = "更新照片删除状态") + @ApiOperation(value = "更新照片删除状态")//通常为软删除 @PutMapping("/admin/photos/delete") public ResultVO updatePhotoDelete(@Valid @RequestBody DeleteVO deleteVO) { + //DeleteVO deleteVO：封装照片删除状态更新的参数，包含照片ID列表、目标删除状态等信息，且会被@Valid检验 photoService.updatePhotoDelete(deleteVO); return ResultVO.ok(); } @OptLog(optType = DELETE) - @ApiOperation(value = "删除照片") + @ApiOperation(value = "删除照片")//物理删除或彻底删除 @DeleteMapping("/admin/photos") public ResultVO deletePhotos(@RequestBody List photoIds) { photoService.deletePhotos(photoIds); return ResultVO.ok(); } - @ApiOperation(value = "根据相册id查看照片列表") + @ApiOperation(value = "根据相册id查看照片列表")//前端展示 @GetMapping("/albums/{albumId}/photos") public ResultVO listPhotosByAlbumId(@PathVariable("albumId") Integer albumId) { + //获取对应相册的照片列表，图片展示信息，比如照片URL、名称等 return ResultVO.ok(photoService.listPhotosByAlbumId(albumId)); } diff --git a/aurora-springboot/src/main/java/com/aurora/controller/ResourceController.java b/aurora-springboot/src/main/java/com/aurora/controller/ResourceController.java index 5137797..e577431 100644 --- a/aurora-springboot/src/main/java/com/aurora/controller/ResourceController.java +++ b/aurora-springboot/src/main/java/com/aurora/controller/ResourceController.java @@ -22,9 +22,9 @@ import static com.aurora.constant.OptTypeConstant.*; public class ResourceController { @Autowired - private ResourceService resourceService; + private ResourceService resourceService;//调用Service层的资源业务方法 - @ApiOperation(value = "查看资源列表") + @ApiOperation(value = "查看资源列表")//获取后台管理的资源列表（比如系统的菜单资源、接口资源等） @GetMapping("/admin/resources") public ResultVO> listResources(ConditionVO conditionVO) { return ResultVO.ok(resourceService.listResources(conditionVO)); @@ -32,7 +32,7 @@ public class ResourceController { @OptLog(optType = DELETE) @ApiOperation(value = "删除资源") - @DeleteMapping("/admin/resources/{resourceId}") + @DeleteMapping("/admin/resources/{resourceId}")//{resourceId}为路径参数,前端需传入具体的资源ID public ResultVO deleteResource(@PathVariable("resourceId") Integer resourceId) { resourceService.deleteResource(resourceId); return ResultVO.ok(); @@ -42,12 +42,15 @@ public class ResourceController { @ApiOperation(value = "新增或修改资源") @PostMapping("/admin/resources") public ResultVO saveOrUpdateResource(@RequestBody @Valid ResourceVO resourceVO) { + //ResourceVO resourceVO：封装资源新增、修改的参数，包含资源名称、路径、类型、父资源ID等信息 resourceService.saveOrUpdateResource(resourceVO); return ResultVO.ok(); } + //获取用于角色分配资源时的选项列表（比如给某个角色配置可访问的资源时，展示所有可选的资源） @ApiOperation(value = "查看角色资源选项") @GetMapping("/admin/role/resources") + //返回所有可用的资源选项列表 public ResultVO> listResourceOption() { return ResultVO.ok(resourceService.listResourceOption()); } diff --git a/aurora-springboot/src/main/java/com/aurora/controller/RoleController.java b/aurora-springboot/src/main/java/com/aurora/controller/RoleController.java index 18d9d89..bce249e 100644 --- a/aurora-springboot/src/main/java/com/aurora/controller/RoleController.java +++ b/aurora-springboot/src/main/java/com/aurora/controller/RoleController.java @@ -28,11 +28,12 @@ public class RoleController { @ApiOperation(value = "查询用户角色选项") @GetMapping("/admin/users/role") public ResultVO> listUserRoles() { + //返回所有可用的用户角色选项列表 return ResultVO.ok(roleService.listUserRoles()); } - @ApiOperation(value = "查询角色列表") + @ApiOperation(value = "查询角色列表")//用于后台管理角色，分页的角色列表 @GetMapping("/admin/roles") public ResultVO> listRoles(ConditionVO conditionVO) { return ResultVO.ok(roleService.listRoles(conditionVO)); diff --git a/aurora-springboot/src/main/java/com/aurora/controller/TagController.java b/aurora-springboot/src/main/java/com/aurora/controller/TagController.java index 6218744..c8f12ae 100644 --- a/aurora-springboot/src/main/java/com/aurora/controller/TagController.java +++ b/aurora-springboot/src/main/java/com/aurora/controller/TagController.java @@ -22,24 +22,22 @@ import static com.aurora.constant.OptTypeConstant.*; @Api(tags = "标签模块") @RestController public class TagController { - - @Autowired private TagService tagService; - @ApiOperation("获取所有标签") + @ApiOperation("获取所有标签")//获取系统中所有的标签列表 @GetMapping("/tags/all") public ResultVO> getAllTags() { return ResultVO.ok(tagService.listTags()); } - @ApiOperation("获取前十个标签") + @ApiOperation("获取前十个标签")//获取前10个标签 @GetMapping("/tags/topTen") public ResultVO> getTopTenTags() { return ResultVO.ok(tagService.listTopTenTags()); } - @ApiOperation(value = "查询后台标签列表") + @ApiOperation(value = "查询后台标签列表")//获取后台管理用的标签分页列表 @GetMapping("/admin/tags") public ResultVO> listTagsAdmin(ConditionVO conditionVO) { return ResultVO.ok(tagService.listTagsAdmin(conditionVO)); diff --git a/aurora-springboot/src/main/java/com/aurora/controller/TalkController.java b/aurora-springboot/src/main/java/com/aurora/controller/TalkController.java index 6a21829..10e69e4 100644 --- a/aurora-springboot/src/main/java/com/aurora/controller/TalkController.java +++ b/aurora-springboot/src/main/java/com/aurora/controller/TalkController.java @@ -27,12 +27,12 @@ import static com.aurora.constant.OptTypeConstant.*; public class TalkController { @Autowired - private TalkService talkService; + private TalkService talkService;//说说业务逻辑 @Autowired - private UploadStrategyContext uploadStrategyContext; + private UploadStrategyContext uploadStrategyContext;//文件上传服务 - @ApiOperation(value = "查看说说列表") + @ApiOperation(value = "查看说说列表")//用于前端展示，普通用户可查看 @GetMapping("/talks") public ResultVO> listTalks() { return ResultVO.ok(talkService.listTalks()); @@ -41,6 +41,7 @@ public class TalkController { @ApiOperation(value = "根据id查看说说") @ApiImplicitParam(name = "talkId", value = "说说id", required = true, dataType = "Integer") @GetMapping("/talks/{talkId}") + //返回指定ID的说说详情 public ResultVO getTalkById(@PathVariable("talkId") Integer talkId) { return ResultVO.ok(talkService.getTalkById(talkId)); } @@ -50,6 +51,7 @@ public class TalkController { @ApiImplicitParam(name = "file", value = "说说图片", required = true, dataType = "MultipartFile") @PostMapping("/admin/talks/images") public ResultVO saveTalkImages(MultipartFile file) { + //调用方法，传入图片文件和说说图片的存储路径枚举，完成上传后包装路径返回 return ResultVO.ok(uploadStrategyContext.executeUploadStrategy(file, FilePathEnum.TALK.getPath())); } @@ -61,7 +63,7 @@ public class TalkController { return ResultVO.ok(); } - @OptLog(optType = DELETE) + @OptLog(optType = DELETE)//记录删除说说的相关日志 @ApiOperation(value = "删除说说") @DeleteMapping("/admin/talks") public ResultVO deleteTalks(@RequestBody List talkIds) { @@ -69,13 +71,13 @@ public class TalkController { return ResultVO.ok(); } - @ApiOperation(value = "查看后台说说") + @ApiOperation(value = "查看后台说说")//获取后台管理用的说说分页列表 @GetMapping("/admin/talks") public ResultVO> listBackTalks(ConditionVO conditionVO) { return ResultVO.ok(talkService.listBackTalks(conditionVO)); } - @ApiOperation(value = "根据id查看后台说说") + @ApiOperation(value = "根据id查看后台说说")//查看指定ID的后台说说详情（包含管理相关的信息） @ApiImplicitParam(name = "talkId", value = "说说id", required = true, dataType = "Integer") @GetMapping("/admin/talks/{talkId}") public ResultVO getBackTalkById(@PathVariable("talkId") Integer talkId) { diff --git a/aurora-springboot/src/main/java/com/aurora/controller/UserAuthController.java b/aurora-springboot/src/main/java/com/aurora/controller/UserAuthController.java index 7a6d78c..8afa284 100644 --- a/aurora-springboot/src/main/java/com/aurora/controller/UserAuthController.java +++ b/aurora-springboot/src/main/java/com/aurora/controller/UserAuthController.java @@ -22,24 +22,26 @@ import static com.aurora.constant.OptTypeConstant.UPDATE; public class UserAuthController { @Autowired - private UserAuthService userAuthService; + private UserAuthService userAuthService;//用于调用用户账号相关的业务方法 - @AccessLimit(seconds = 60,maxCount = 1) - @ApiOperation(value = "发送邮箱验证码") + @AccessLimit(seconds = 60,maxCount = 1)//自定义限流注解，限制60s内只能调用1次，防止验证码被频繁发送 + @ApiOperation(value = "发送邮箱验证码")//给指定用户名（邮箱）发送验证码 @ApiImplicitParam(name = "username", value = "用户名", required = true, dataType = "String") @GetMapping("/users/code") public ResultVO sendCode(String username) { + //String username:接收用户的邮箱账号 userAuthService.sendCode(username); return ResultVO.ok(); } - @ApiOperation(value = "获取用户区域分布") + @ApiOperation(value = "获取用户区域分布")//获取用户在不同区域的分布情况（用于后台数据统计分布） @GetMapping("/admin/users/area") + //返回用户区域分布列表 public ResultVO> listUserAreas(ConditionVO conditionVO) { return ResultVO.ok(userAuthService.listUserAreas(conditionVO)); } - @ApiOperation(value = "查询后台用户列表") + @ApiOperation(value = "查询后台用户列表")//分页 @GetMapping("/admin/users") public ResultVO> listUsers(ConditionVO conditionVO) { return ResultVO.ok(userAuthService.listUsers(conditionVO)); @@ -53,30 +55,33 @@ public class UserAuthController { } @OptLog(optType = UPDATE) - @ApiOperation(value = "修改密码") + @ApiOperation(value = "修改密码")//用户自主修改个人密码 @PutMapping("/users/password") public ResultVO updatePassword(@Valid @RequestBody UserVO user) { + //UserVO user：封装密码修改的参数，包含原密码、新密码、验证码等信息，且会被@Valid校验 userAuthService.updatePassword(user); return ResultVO.ok(); } @OptLog(optType = UPDATE) - @ApiOperation(value = "修改管理员密码") + @ApiOperation(value = "修改管理员密码")//后台 @PutMapping("/admin/users/password") public ResultVO updateAdminPassword(@Valid @RequestBody PasswordVO passwordVO) { userAuthService.updateAdminPassword(passwordVO); return ResultVO.ok(); } - @ApiOperation("用户登出") + @ApiOperation("用户登出")//处理用户的登出请求（清除登录状态） @PostMapping("/users/logout") - public ResultVO logout() { + public ResultVO logout() {//返回登出结果 return ResultVO.ok(userAuthService.logout()); } - @ApiOperation(value = "qq登录") + @ApiOperation(value = "qq登录")//通过QQ账号进行第三方登录 @PostMapping("/users/oauth/qq") + //返回登录结果和用户信息 public ResultVO qqLogin(@Valid @RequestBody QQLoginVO qqLoginVO) { + //QQLoginVO qqLoginVO：封装QQ登录的参数，包含QQ授权码、openid等第三方登录所需信息，且会被@Valid校验 return ResultVO.ok(userAuthService.qqLogin(qqLoginVO)); } diff --git a/aurora-springboot/src/main/java/com/aurora/controller/UserInfoController.java b/aurora-springboot/src/main/java/com/aurora/controller/UserInfoController.java index f013264..fc279b1 100644 --- a/aurora-springboot/src/main/java/com/aurora/controller/UserInfoController.java +++ b/aurora-springboot/src/main/java/com/aurora/controller/UserInfoController.java @@ -23,10 +23,10 @@ import static com.aurora.constant.OptTypeConstant.UPDATE; public class UserInfoController { @Autowired - private UserInfoService userInfoService; + private UserInfoService userInfoService;//调用用户信息相关的业务方法 @OptLog(optType = UPDATE) - @ApiOperation("更新用户信息") + @ApiOperation("更新用户信息")//用户自主更新个人基本信息 @PutMapping("/users/info") public ResultVO updateUserInfo(@Valid @RequestBody UserInfoVO userInfoVO) { userInfoService.updateUserInfo(userInfoVO); @@ -38,19 +38,21 @@ public class UserInfoController { @ApiImplicitParam(name = "file", value = "用户头像", required = true, dataType = "MultipartFile") @PostMapping("/users/avatar") public ResultVO updateUserAvatar(MultipartFile file) { + //MultipartFile file:接受用户上传的头像文件，返回更新后头像的存储路径（字符串格式） return ResultVO.ok(userInfoService.updateUserAvatar(file)); } @OptLog(optType = UPDATE) - @ApiOperation("绑定用户邮箱") + @ApiOperation("绑定用户邮箱")//用户绑定个人邮箱（通常需要验证码验证） @PutMapping("/users/email") public ResultVO saveUserEmail(@Valid @RequestBody EmailVO emailVO) { + //EmailVO emailVO:封装邮箱绑定的参数，包含邮箱地址、验证码等绑定信息，且会被@Valid校验 userInfoService.saveUserEmail(emailVO); return ResultVO.ok(); } @OptLog(optType = UPDATE) - @ApiOperation("修改用户的订阅状态") + @ApiOperation("修改用户的订阅状态")//用户自主修改订阅相关状态（比如订阅网站通知、内容推送等） @PutMapping("/users/subscribe") public ResultVO updateUserSubscribe(@RequestBody SubscribeVO subscribeVO) { userInfoService.updateUserSubscribe(subscribeVO); @@ -58,7 +60,7 @@ public class UserInfoController { } @OptLog(optType = UPDATE) - @ApiOperation(value = "修改用户角色") + @ApiOperation(value = "修改用户角色")//后台管理员修改用户的角色（比如普通用户改为编辑） @PutMapping("/admin/users/role") public ResultVO updateUserRole(@Valid @RequestBody UserRoleVO userRoleVO) { userInfoService.updateUserRole(userRoleVO); @@ -66,28 +68,28 @@ public class UserInfoController { } @OptLog(optType = UPDATE) - @ApiOperation(value = "修改用户禁用状态") + @ApiOperation(value = "修改用户禁用状态")//后台管理员禁用/解禁用户账号 @PutMapping("/admin/users/disable") public ResultVO updateUserDisable(@Valid @RequestBody UserDisableVO userDisableVO) { userInfoService.updateUserDisable(userDisableVO); return ResultVO.ok(); } - @ApiOperation(value = "查看在线用户") + @ApiOperation(value = "查看在线用户")//后台管理员查看当前在线的用户列表 @GetMapping("/admin/users/online") public ResultVO> listOnlineUsers(ConditionVO conditionVO) { return ResultVO.ok(userInfoService.listOnlineUsers(conditionVO)); } - @OptLog(optType = DELETE) - @ApiOperation(value = "下线用户") + @OptLog(optType = DELETE)//记录用户下线的日志 + @ApiOperation(value = "下线用户")//后台管理员强制让指定在线用户下线（清除在线状态） @DeleteMapping("/admin/users/{userInfoId}/online") public ResultVO removeOnlineUser(@PathVariable("userInfoId") Integer userInfoId) { userInfoService.removeOnlineUser(userInfoId); return ResultVO.ok(); } - @ApiOperation("根据id获取用户信息") + @ApiOperation("根据id获取用户信息")//获取指定ID用户的个人信息（用于前端查看他人信息或后台查看用户详情） @GetMapping("/users/info/{userInfoId}") public ResultVO getUserInfoById(@PathVariable("userInfoId") Integer userInfoId) { return ResultVO.ok(userInfoService.getUserInfoById(userInfoId)); diff --git a/aurora-springboot/src/main/java/com/aurora/mapper/AboutMapper.java b/aurora-springboot/src/main/java/com/aurora/mapper/AboutMapper.java index 06653c3..f22f912 100644 --- a/aurora-springboot/src/main/java/com/aurora/mapper/AboutMapper.java +++ b/aurora-springboot/src/main/java/com/aurora/mapper/AboutMapper.java @@ -1,10 +1,10 @@ -package com.aurora.mapper; +package com.aurora.mapper;// 在Maven项目中，mapper包通常位于数据访问层，专门负责与数据库的交互操作 -import com.aurora.entity.About; +import com.aurora.entity.About;//导入和数据库对应的实体类About,接口操作的就是这个实体类对应的数据库表 import com.baomidou.mybatisplus.core.mapper.BaseMapper; import org.springframework.stereotype.Repository; -@Repository +@Repository //标注在接口上，用于标记这是一个数据访问层的组件，避免IDE报“找不到Bean"的警告，让Spring扫描并管理该Bean public interface AboutMapper extends BaseMapper { - + //AboutMapper可以直接使用BaseMapper里的基础CRUD方法来操作About对应的数据库表（about），无需手动编写基础的SQL语句 } diff --git a/aurora-springboot/src/main/java/com/aurora/mapper/ArticleMapper.java b/aurora-springboot/src/main/java/com/aurora/mapper/ArticleMapper.java index 978b9fa..b5f98a1 100644 --- a/aurora-springboot/src/main/java/com/aurora/mapper/ArticleMapper.java +++ b/aurora-springboot/src/main/java/com/aurora/mapper/ArticleMapper.java @@ -1,10 +1,12 @@ package com.aurora.mapper; import com.aurora.model.dto.ArticleAdminDTO; +// 导入各种数据传输对象(DTO)，用于前台数据展示 import com.aurora.model.dto.ArticleCardDTO; import com.aurora.model.dto.ArticleDTO; import com.aurora.model.dto.ArticleStatisticsDTO; -import com.aurora.entity.Article; +import com.aurora.entity.Article;//导入和数据库对应的实体类Article,接口操作的就是这个实体类对应的数据库表 +// 导入查询条件值对象 import com.aurora.model.vo.ConditionVO; import com.baomidou.mybatisplus.core.mapper.BaseMapper; import org.apache.ibatis.annotations.Param; @@ -14,33 +16,48 @@ import java.util.List; @Repository +// 定义ArticleMapper接口，继承自MyBatis-Plus的BaseMapper接口，泛型为Article实体类 +// 继承BaseMapper后，自动获得了基本的CRUD（增删改查）方法，如insert、deleteById、updateById、selectById等 public interface ArticleMapper extends BaseMapper
{ - + // 获取置顶和推荐文章列表（通常用于前段首页卡片展示） + // 返回ArticleCardDTO列表，包含文章卡片所需的基本信息 List listTopAndFeaturedArticles(); - + // 分页获取所有文章列表 + // @Param注解给参数起别名，在XML中可以通过#{current}和#{size}引用 + // current: 当前页码，size: 每页大小（每页条数） List listArticles(@Param("current") Long current, @Param("size") Long size); - + // 根据分类ID分页获取文章列表 + // categoryId: 分类ID，用于筛选指定分类的文章 List getArticlesByCategoryId(@Param("current") Long current, @Param("size") Long size, @Param("categoryId") Integer categoryId); - + // 根据文章ID获取单篇文章详情（包含文章完整内容等信息） + // 返回ArticleDTO，通常比ArticleCardDTO包含更多详细信息（如文章正文） ArticleDTO getArticleById(@Param("articleId") Integer articleId); - + // 根据当前文章ID获取上一篇文章的卡片信息（按时间或ID排序） + // 用于文章详情页的"上一篇"导航 ArticleCardDTO getPreArticleById(@Param("articleId") Integer articleId); - + // 根据当前文章ID获取下一篇文章的卡片信息（按时间或ID排序） + // 用于文章详情页的"下一篇"导航 ArticleCardDTO getNextArticleById(@Param("articleId") Integer articleId); - + // 获取第一篇文章的卡片信息（按时间或ID排序，通常是最早的文章） ArticleCardDTO getFirstArticle(); - + // 获取最后一篇文章的卡片信息（按时间或ID排序，通常是最新的文章） ArticleCardDTO getLastArticle(); - + // 根据标签ID分页获取文章归档列表 + // tagId: 标签ID，用于筛选带有指定标签的文章 List listArticlesByTagId(@Param("current") Long current, @Param("size") Long size, @Param("tagId") Integer tagId); - + // 分页获取文章归档列表（通常按时间分组，如按年月） + // 归档页面通常显示文章标题和创建时间，不显示完整内容 List listArchives(@Param("current") Long current, @Param("size") Long size); - + // 统计后台文章数量（根据查询条件） + // conditionVO: 包含各种查询条件，如关键词、状态、时间范围等 + // 返回符合条件的文章总数，用于分页计算 Integer countArticleAdmins(@Param("conditionVO") ConditionVO conditionVO); - + // 按条件分页查询获取后台文章列表（管理员功能） + // 返回ArticleAdminDTO列表，可能包含更多管理字段（如状态、浏览量等） List listArticlesAdmin(@Param("current") Long current, @Param("size") Long size, @Param("conditionVO") ConditionVO conditionVO); - + // 获取文章统计信息（如按分类、标签、状态统计文章数量） + // 用于后台仪表盘的数据展示 List listArticleStatistics(); - + //@Param("参数名")：MyBatis的注解，用于给方法参数命名，方便在对应的XML映射文件中通过#{参数名}获取参数值 } diff --git a/aurora-springboot/src/main/java/com/aurora/mapper/ArticleTagMapper.java b/aurora-springboot/src/main/java/com/aurora/mapper/ArticleTagMapper.java index 5f57d59..45db1de 100644 --- a/aurora-springboot/src/main/java/com/aurora/mapper/ArticleTagMapper.java +++ b/aurora-springboot/src/main/java/com/aurora/mapper/ArticleTagMapper.java @@ -5,6 +5,6 @@ import com.baomidou.mybatisplus.core.mapper.BaseMapper; import org.springframework.stereotype.Repository; @Repository -public interface ArticleTagMapper extends BaseMapper { - +public interface ArticleTagMapper extends BaseMapper {//文章-标签关联模块的数据访问层接口 + //通常用于存储文章ID和标签ID的对应关系，实现文章和标签的多对多关联 } diff --git a/aurora-springboot/src/main/java/com/aurora/mapper/CategoryMapper.java b/aurora-springboot/src/main/java/com/aurora/mapper/CategoryMapper.java index 6dfaf05..6af0776 100644 --- a/aurora-springboot/src/main/java/com/aurora/mapper/CategoryMapper.java +++ b/aurora-springboot/src/main/java/com/aurora/mapper/CategoryMapper.java @@ -1,11 +1,11 @@ package com.aurora.mapper; - +// 导入数据传输对象(DTO)，用于前台数据展示 import com.aurora.model.dto.CategoryAdminDTO; import com.aurora.model.dto.CategoryDTO; -import com.aurora.entity.Category; +import com.aurora.entity.Category;// 导入与数据库表对应的实体类Category，Mapper接口操作的就是这个实体类对应的数据库表 import com.aurora.model.vo.ConditionVO; import com.baomidou.mybatisplus.core.mapper.BaseMapper; -import org.apache.ibatis.annotations.Param; +import org.apache.ibatis.annotations.Param;// 导入MyBatis的参数注解，用于给Mapper方法参数起别名 import org.springframework.stereotype.Repository; import java.util.List; @@ -13,9 +13,13 @@ import java.util.List; @Repository public interface CategoryMapper extends BaseMapper { - + // 获取所有分类列表（通常用于前台展示） + // 返回CategoryDTO列表，包含分类的基本信息（如分类名称、文章数量等） List listCategories(); - + // 分页获取后台分类列表（管理员功能） + // @Param注解给参数起别名，在XML中可以通过#{current}、#{size}、#{conditionVO.xxx}引用 + // current: 当前页码，size: 每页大小，conditionVO: 封装查询条件（如关键词、状态等） + // 返回分页结果，包含CategoryAdminDTO列表（可能比前台DTO包含更多管理字段） List listCategoriesAdmin(@Param("current") Long current, @Param("size") Long size, @Param("conditionVO") ConditionVO conditionVO); } diff --git a/aurora-springboot/src/main/java/com/aurora/mapper/CommentMapper.java b/aurora-springboot/src/main/java/com/aurora/mapper/CommentMapper.java index a97599c..f08b6fa 100644 --- a/aurora-springboot/src/main/java/com/aurora/mapper/CommentMapper.java +++ b/aurora-springboot/src/main/java/com/aurora/mapper/CommentMapper.java @@ -1,10 +1,11 @@ package com.aurora.mapper; - +// 导入评论数据传输对象(DTO)，用于前台数据展示 import com.aurora.model.dto.CommentAdminDTO; import com.aurora.model.dto.CommentCountDTO; import com.aurora.model.dto.CommentDTO; import com.aurora.model.dto.ReplyDTO; -import com.aurora.entity.Comment; +import com.aurora.entity.Comment;// 导入与数据库表对应的实体类Comment +// 导入查询条件值对象 import com.aurora.model.vo.CommentVO; import com.aurora.model.vo.ConditionVO; import com.baomidou.mybatisplus.core.mapper.BaseMapper; @@ -15,19 +16,32 @@ import java.util.List; @Repository public interface CommentMapper extends BaseMapper { - + // 分页获取评论列表（通常用于前台文章详情页的评论展示） + // @Param注解给参数起别名，在XML中可以通过#{current}、#{size}、#{commentVO.xxx}引用 + // current: 当前页码，size: 每页大小，commentVO: 封装评论查询条件（如文章ID、排序方式等） + // 返回CommentDTO列表，包含评论的基本信息和作者信息 List listComments(@Param("current") Long current, @Param("size") Long size, @Param("commentVO") CommentVO commentVO); - + // 根据评论ID列表获取这些评论的所有回复列表 + // commentIdList: 评论ID集合，用于批量查询多个评论的回复 + // 返回ReplyDTO列表，包含回复的详细信息（如回复内容、回复对象等） List listReplies(@Param("commentIds") List commentIdList); - + // 获取前六个热门评论（通常用于前端优先首页展示） + // 可能按点赞数、创建时间等排序规则选取前六个评论 List listTopSixComments(); - + // 统计评论数量（根据查询条件） + // conditionVO: 封装统计条件（如时间范围、文章ID、评论状态等） + // 返回符合条件的评论总数，用于后台分页计算和数据统计 Integer countComments(@Param("conditionVO") ConditionVO conditionVO); - + // 分页获取后台评论列表（管理员功能） + // 返回CommentAdminDTO列表，可能包含更多管理字段（如IP地址、审核状态、操作日志等） List listCommentsAdmin(@Param("current") Long current, @Param("size") Long size, @Param("conditionVO") ConditionVO conditionVO); - + // 根据类型和主题ID列表批量统计评论数量 + // type: 评论类型（如文章评论、友链评论等），topicIds: 主题ID列表（如文章ID列表） + // 返回CommentCountDTO列表，包含每个主题的评论数量统计 List listCommentCountByTypeAndTopicIds(@Param("type") Integer type, @Param("topicIds") List topicIds); - + // 根据类型和单个主题ID统计评论数量 + // topicId: 单个主题ID（如某篇文章的ID） + // 返回CommentCountDTO，包含指定主题的评论数量统计 CommentCountDTO listCommentCountByTypeAndTopicId(@Param("type") Integer type, @Param("topicId") Integer topicId); } diff --git a/aurora-springboot/src/main/java/com/aurora/mapper/ElasticsearchMapper.java b/aurora-springboot/src/main/java/com/aurora/mapper/ElasticsearchMapper.java index 3144254..f408c58 100644 --- a/aurora-springboot/src/main/java/com/aurora/mapper/ElasticsearchMapper.java +++ b/aurora-springboot/src/main/java/com/aurora/mapper/ElasticsearchMapper.java @@ -1,6 +1,7 @@ package com.aurora.mapper; - +// 导入项目内定义的ArticleSearchDTO类，该类作为Elasticsearch文档的实体映射，用于搜索结果的传输 import com.aurora.model.dto.ArticleSearchDTO; +// 导入Spring Data Elasticsearch提供的核心接口ElasticsearchRepository，它封装了基本的Elasticsearch操作 import org.springframework.data.elasticsearch.repository.ElasticsearchRepository; import org.springframework.stereotype.Repository; @@ -9,7 +10,16 @@ import org.springframework.stereotype.Repository; * @author 花未眠 * elasticsearch */ +// @Repository注解将本接口标识为数据访问层（DAO）组件，让Spring能够扫描并管理其实例（如依赖注入） +// 该注解是@Component的特殊化，表明其主要职责是与数据库（此处为Elasticsearch）交互 @Repository -public interface ElasticsearchMapper extends ElasticsearchRepository { +// 定义ElasticsearchMapper接口，继承自ElasticsearchRepository接口 +// ElasticsearchRepository是Spring Data Elasticsearch提供的基础仓库核心接口，提供了丰富的CRUD和搜索方法 +// 内置了和Elasticsearch交互的基础方法（比如全文搜索、数据新增/删除到ES索引等） +// 泛型参数说明： +// - ArticleSearchDTO：指定该Repository管理的实体类型，即Elasticsearch中文档对应的Java对象，用于ES搜索的文章数据传输对象（包含文章标题、内容、标签等用于搜索的字段） +// 该类应使用@Document等注解配置索引映射（如索引名、类型等） +// - Integer：（DTO对应数据）指定实体主键（ID）的数据类型。在Elasticsearch中，每个文档都有一个唯一ID，这里使用Integer类型。 +public interface ElasticsearchMapper extends ElasticsearchRepository {//基于文章搜索模块的数据访问层接口 } diff --git a/aurora-springboot/src/main/java/com/aurora/mapper/ExceptionLogMapper.java b/aurora-springboot/src/main/java/com/aurora/mapper/ExceptionLogMapper.java index 1eead50..1c253a8 100644 --- a/aurora-springboot/src/main/java/com/aurora/mapper/ExceptionLogMapper.java +++ b/aurora-springboot/src/main/java/com/aurora/mapper/ExceptionLogMapper.java @@ -1,10 +1,13 @@ package com.aurora.mapper; -import com.aurora.entity.ExceptionLog; -import com.baomidou.mybatisplus.core.mapper.BaseMapper; +import com.aurora.entity.ExceptionLog;// 导入异常日志实体类ExceptionLog，该实体类与数据库中的异常日志表相对应 +import com.baomidou.mybatisplus.core.mapper.BaseMapper;// 导入MyBatis-Plus的核心接口BaseMapper，它提供了丰富的CRUD（增删改查）操作方法 import org.springframework.stereotype.Repository; @Repository -public interface ExceptionLogMapper extends BaseMapper { +// 定义ExceptionLogMapper接口，继承自MyBatis-Plus的BaseMapper接口 +// 泛型参数ExceptionLog指定了该Mapper操作的实体类型 +// 继承BaseMapper后，无需编写任何方法实现或XML映射文件，即可获得完整的CRUD功能 +public interface ExceptionLogMapper extends BaseMapper {//异常日志模块的数据访问层接口 } diff --git a/aurora-springboot/src/main/java/com/aurora/mapper/FriendLinkMapper.java b/aurora-springboot/src/main/java/com/aurora/mapper/FriendLinkMapper.java index 23f95b8..ae4a505 100644 --- a/aurora-springboot/src/main/java/com/aurora/mapper/FriendLinkMapper.java +++ b/aurora-springboot/src/main/java/com/aurora/mapper/FriendLinkMapper.java @@ -1,10 +1,10 @@ package com.aurora.mapper; - -import com.aurora.entity.FriendLink; +// 实体类中的字段通常与数据库表字段一一映射，包含友链的基本信息如名称、URL等 +import com.aurora.entity.FriendLink;//导入友情链接实体类FriendLink，该实体类与数据库中的友情链接表相对应 import com.baomidou.mybatisplus.core.mapper.BaseMapper; import org.springframework.stereotype.Repository; @Repository -public interface FriendLinkMapper extends BaseMapper { +public interface FriendLinkMapper extends BaseMapper {//友链模块的数据访问层接口 } diff --git a/aurora-springboot/src/main/java/com/aurora/mapper/JobLogMapper.java b/aurora-springboot/src/main/java/com/aurora/mapper/JobLogMapper.java index 23cf9a0..2826afb 100644 --- a/aurora-springboot/src/main/java/com/aurora/mapper/JobLogMapper.java +++ b/aurora-springboot/src/main/java/com/aurora/mapper/JobLogMapper.java @@ -1,14 +1,17 @@ package com.aurora.mapper; -import com.aurora.entity.JobLog; +import com.aurora.entity.JobLog;//导入定时任务日志实体类JobLog，该实体类与数据库中的存储定时任务执行日志表相对应（通常记录任务名称、 +//执行状态、执行时间、异常信息等内容） import com.baomidou.mybatisplus.core.mapper.BaseMapper; import org.springframework.stereotype.Repository; -import java.util.List; +import java.util.List;// 导入Java集合框架中的List接口，用于返回多个日志分组名称的集合 @Repository -public interface JobLogMapper extends BaseMapper { - +public interface JobLogMapper extends BaseMapper {//定时任务日志模块的数据访问层接口 + // 自定义查询方法：获取任务日志的所有分组列表（通常基于特定字段进行分组统计） + // 返回字符串列表，每个字符串代表一个分组标识（如按任务状态分组返回["SUCCESS", "FAILED"]，或按时间维度分组如["2025-10", "2025-09"]） + // 此方法常用于后台管理系统中的日志分类筛选、统计图表展示或日志归档功能 List listJobLogGroups(); } diff --git a/aurora-springboot/src/main/java/com/aurora/mapper/JobMapper.java b/aurora-springboot/src/main/java/com/aurora/mapper/JobMapper.java index 68d422c..28ab2bb 100644 --- a/aurora-springboot/src/main/java/com/aurora/mapper/JobMapper.java +++ b/aurora-springboot/src/main/java/com/aurora/mapper/JobMapper.java @@ -1,21 +1,31 @@ package com.aurora.mapper; - +// 导入定时任务数据传输对象(JobDTO)，用于前台数据展示，通常包含更丰富的业务字段 import com.aurora.model.dto.JobDTO; -import com.aurora.entity.Job; -import com.aurora.model.vo.JobSearchVO; +import com.aurora.entity.Job;// 导入与数据库表对应的实体类Job，Mapper接口操作的就是这个实体类对应的数据库表 +import com.aurora.model.vo.JobSearchVO;// 导入定时任务搜索条件值对象(JobSearchVO)，封装前端传递的搜索参数 import com.baomidou.mybatisplus.core.mapper.BaseMapper; import org.apache.ibatis.annotations.Param; import org.springframework.stereotype.Repository; -import java.util.List; +import java.util.List;// 导入Java集合框架中的List接口，用于返回多个职位的集合 @Repository +// 定义JobMapper接口，继承自MyBatis-Plus的BaseMapper接口 +// 泛型参数Job指定了该Mapper操作的实体类型 +// 继承BaseMapper后，自动获得了数十个基本的CRUD（增删改查）方法 public interface JobMapper extends BaseMapper { - + // 统计满足条件的定时任务数量（用于分页查询中的总数计算） + // @Param注解给参数起别名，在XML中可以通过#{jobSearchVO.xxx}引用参数属性 + // jobSearchVO: 封装搜索条件（如关键词、状态、时间范围等） + // 返回符合条件的定时任务操作总数，Integer类型避免null值问题 Integer countJobs(@Param("jobSearchVO") JobSearchVO jobSearchVO); - + // 分页获取定时任务操作列表（支持条件搜索） + // current: 当前页码（从1开始），size: 每页记录数 + // jobSearchVO: 封装搜索条件对象，包含各种筛选参数 + // 返回JobDTO列表，包含定时任务操作信息和相关业务数据（如定时操作任务名称、类型、统计信息等） List listJobs(@Param("current") Long current, @Param("size") Long size, @Param("jobSearchVO")JobSearchVO jobSearchVO); - + // 获取所有定时任务操作分组列表（用于分类筛选或下拉选择框） + // 返回字符串列表，每个字符串代表一个分组标识 List listJobGroups(); } diff --git a/aurora-springboot/src/main/java/com/aurora/mapper/MenuMapper.java b/aurora-springboot/src/main/java/com/aurora/mapper/MenuMapper.java index 073efef..63ebd7d 100644 --- a/aurora-springboot/src/main/java/com/aurora/mapper/MenuMapper.java +++ b/aurora-springboot/src/main/java/com/aurora/mapper/MenuMapper.java @@ -1,14 +1,20 @@ package com.aurora.mapper; -import com.aurora.entity.Menu; +import com.aurora.entity.Menu;// 导入菜单实体类Menu，该实体类与数据库中的菜单表相对应 import com.baomidou.mybatisplus.core.mapper.BaseMapper; import org.springframework.stereotype.Repository; -import java.util.List; +import java.util.List;// 导入Java集合框架中的List接口，用于返回多个菜单的集合 @Repository +//定义MenuMapper接口，继承自MyBatis-Plus的BaseMapper接口 +// 泛型参数Menu指定了该Mapper操作的实体类型 +// 继承BaseMapper后，自动获得了基本的CRUD方法，如insert、deleteById、updateById、selectById等 public interface MenuMapper extends BaseMapper { - + // 自定义查询方法：根据用户信息ID查询该用户有权访问的菜单列表 + // 用户信息ID通常对应系统用户的主键ID + // 返回菜单实体列表，包含菜单的基本信息（如菜单名称、路径、图标等） + // 此方法通常用于实现基于角色的权限控制（RBAC），不同用户角色看到不同的菜单 List listMenusByUserInfoId(Integer userInfoId); } diff --git a/aurora-springboot/src/main/java/com/aurora/mapper/OperationLogMapper.java b/aurora-springboot/src/main/java/com/aurora/mapper/OperationLogMapper.java index e5c053c..4bd98cd 100644 --- a/aurora-springboot/src/main/java/com/aurora/mapper/OperationLogMapper.java +++ b/aurora-springboot/src/main/java/com/aurora/mapper/OperationLogMapper.java @@ -1,10 +1,12 @@ package com.aurora.mapper; - +// 导入操作日志实体类OperationLog，该实体类与数据库中的操作日志表（如operate_log）相对应 +// 实体类中的字段（如id、operateTime、className等）与数据库表字段一一映射 import com.aurora.entity.OperationLog; import com.baomidou.mybatisplus.core.mapper.BaseMapper; import org.springframework.stereotype.Repository; @Repository public interface OperationLogMapper extends BaseMapper { + //OperationLog实体类通常用于记录系统操作日志（如用户行为、后台管理操作） } diff --git a/aurora-springboot/src/main/java/com/aurora/mapper/PhotoAlbumMapper.java b/aurora-springboot/src/main/java/com/aurora/mapper/PhotoAlbumMapper.java index b0cb1cb..6c25b5a 100644 --- a/aurora-springboot/src/main/java/com/aurora/mapper/PhotoAlbumMapper.java +++ b/aurora-springboot/src/main/java/com/aurora/mapper/PhotoAlbumMapper.java @@ -1,17 +1,23 @@ package com.aurora.mapper; - +// 导入相册管理数据传输对象（PhotoAlbumAdminDTO），用于后台管理界面展示相册信息，通常包含相册基本属性及统计字段（如照片数量） import com.aurora.model.dto.PhotoAlbumAdminDTO; +// 导入相册实体类（PhotoAlbum），该实体类与数据库中的相册表（如 photo_album）相对应，其字段（如相册名、封面图路径）与表结构映射 import com.aurora.entity.PhotoAlbum; +// 导入条件查询值对象（ConditionVO），用于封装前端传递的复杂查询参数（如关键词、状态、时间范围等） import com.aurora.model.vo.ConditionVO; import com.baomidou.mybatisplus.core.mapper.BaseMapper; import org.apache.ibatis.annotations.Param; import org.springframework.stereotype.Repository; -import java.util.List; +import java.util.List;// 导入 Java 集合框架中的 List 接口，用于返回多个相册管理DTO对象的集合 @Repository public interface PhotoAlbumMapper extends BaseMapper { - + // 自定义查询方法：分页获取后台相册管理列表（通常用于管理员控制台） + // @Param 注解为参数指定别名，在 XML 映射文件中可通过 `#{current}`、`#{size}`、`#{condition.xxx}` 引用参数值 + // current: 当前页码（从1开始），size: 每页记录数，用于实现分页查询 + // condition: 封装查询条件的对象，可能包含搜索关键词（如相册名称）、筛选状态（如是否公开）、时间范围等 + // 返回 PhotoAlbumAdminDTO 列表，该 DTO 通常扩展了相册基础信息，包含管理所需的附加字段（如相册下照片数量、创建人信息等） List listPhotoAlbumsAdmin(@Param("current") Long current, @Param("size") Long size, @Param("condition") ConditionVO conditionVO); } diff --git a/aurora-springboot/src/main/java/com/aurora/mapper/RoleMapper.java b/aurora-springboot/src/main/java/com/aurora/mapper/RoleMapper.java index c5b583b..f6558e2 100644 --- a/aurora-springboot/src/main/java/com/aurora/mapper/RoleMapper.java +++ b/aurora-springboot/src/main/java/com/aurora/mapper/RoleMapper.java @@ -1,22 +1,32 @@ package com.aurora.mapper; - +// 导入资源角色数据传输对象（ResourceRoleDTO），用于封装资源与角色的关联信息，通常在权限管理中使用 import com.aurora.model.dto.ResourceRoleDTO; +// 导入角色数据传输对象（RoleDTO），用于前台或服务层角色信息的展示，可能包含角色基本属性及扩展字段 import com.aurora.model.dto.RoleDTO; +// 导入角色实体类（Role），该实体类与数据库中的角色表（如 sys_role）相对应，其字段（如角色名、状态）与表结构映射 [1,2] import com.aurora.entity.Role; +// 导入条件查询值对象（ConditionVO），用于封装前端传递的复杂查询参数（如关键词、状态、时间范围等） import com.aurora.model.vo.ConditionVO; import com.baomidou.mybatisplus.core.mapper.BaseMapper; import org.apache.ibatis.annotations.Param; import org.springframework.stereotype.Repository; -import java.util.List; +import java.util.List;// 导入 Java 集合框架中的 List 接口，用于返回多个角色或字符串的集合 @Repository public interface RoleMapper extends BaseMapper { - + // 自定义查询方法：获取资源与角色的映射列表 + // 返回 ResourceRoleDTO 列表，每个对象可能包含资源路径（如 URL）和可访问该资源的角色列表（如 ROLE_ADMIN） List listResourceRoles(); - + // 自定义查询方法：根据用户信息ID查询该用户所拥有的角色标识列表 + // @Param 注解为参数指定别名 "userInfoId"，在 XML 映射文件中可通过 #{userInfoId}引用参数值 + // userInfoId: 用户信息表的主键 ID，用于关联查询用户-角色关系表 + // 返回字符串列表，每个字符串代表一个角色标识（如 "admin"、"user"），通常用于构建用户的权限集合 List listRolesByUserInfoId(@Param("userInfoId") Integer userInfoId); - + // 自定义查询方法：分页获取角色列表（支持条件查询，通常用于后台角色管理界面） + // current: 当前页码（从1开始），size: 每页记录数 + // conditionVO: 封装查询条件的对象，可能包含角色名称关键词、状态标识、创建时间范围等筛选条件 + // 返回 RoleDTO 列表，该 DTO 通常扩展了角色基础信息，包含管理或展示所需的附加字段（如用户数量、权限列表等） List listRoles(@Param("current") Long current, @Param("size") Long size, @Param("conditionVO") ConditionVO conditionVO); } diff --git a/aurora-springboot/src/main/java/com/aurora/mapper/TagMapper.java b/aurora-springboot/src/main/java/com/aurora/mapper/TagMapper.java index d7a5628..ae0536f 100644 --- a/aurora-springboot/src/main/java/com/aurora/mapper/TagMapper.java +++ b/aurora-springboot/src/main/java/com/aurora/mapper/TagMapper.java @@ -1,9 +1,9 @@ package com.aurora.mapper; -import com.aurora.model.dto.TagAdminDTO; -import com.aurora.model.dto.TagDTO; -import com.aurora.entity.Tag; -import com.aurora.model.vo.ConditionVO; +import com.aurora.model.dto.TagAdminDTO;// 导入标签管理数据传输对象（TagAdminDTO），用于后台管理界面展示标签信息，可能包含更多管理字段 +import com.aurora.model.dto.TagDTO;// 导入标签数据传输对象（TagDTO），用于前台数据展示，通常包含标签基本属性及扩展字段 +import com.aurora.entity.Tag;// 导入标签实体类（Tag），该实体类与数据库中的标签表（如 tag 或 ms_tag）相对应，其字段与表结构映射 +import com.aurora.model.vo.ConditionVO;// 导入条件查询值对象（ConditionVO），用于封装前端传递的复杂查询参数（如关键词、状态、时间范围等） import com.baomidou.mybatisplus.core.mapper.BaseMapper; import org.apache.ibatis.annotations.Param; import org.springframework.stereotype.Repository; @@ -12,13 +12,18 @@ import java.util.List; @Repository public interface TagMapper extends BaseMapper { - + // 自定义查询方法：获取所有标签列表（通常用于前台标签或标签选择框），返回 TagDTO 列表，包含标签的基本信息（如标签名、颜色、图标等），用于前端展示 List listTags(); - + // 自定义查询方法：获取前十热门标签列表（通常用于侧边栏或首页展示），热门标签的判定标准通常是关联的文章数量，关联文章越多的标签越热门 + // 返回 TagDTO 列表，通常按文章数量降序排列，仅返回前10条记录 List listTopTenTags(); - + // 自定义查询方法：根据文章ID查询该文章的所有标签名称列表，返回字符串列表，每个字符串代表一个标签名称，用于文章详情页展示文章的标签集合 + // articleId: 文章的主键ID，用于关联查询文章-标签关系表（如 ms_article_tag） List listTagNamesByArticleId(Integer articleId); - + // 自定义查询方法：分页获取后台标签管理列表（支持条件查询，用于管理员控制台） + // current: 当前页码（从1开始），size: 每页记录数，用于实现分页查询（LIMIT 机制） + // conditionVO: 封装查询条件的对象，可能包含标签名称关键词、状态标识、创建时间范围等筛选条件 + // 返回 TagAdminDTO 列表，该 DTO 通常扩展了标签基础信息，包含管理所需的附加字段（如关联文章数、创建人信息等） List listTagsAdmin(@Param("current") Long current, @Param("size") Long size, @Param("conditionVO") ConditionVO conditionVO); } diff --git a/aurora-springboot/src/main/java/com/aurora/mapper/UniqueViewMapper.java b/aurora-springboot/src/main/java/com/aurora/mapper/UniqueViewMapper.java index 5193f77..3f02ecb 100644 --- a/aurora-springboot/src/main/java/com/aurora/mapper/UniqueViewMapper.java +++ b/aurora-springboot/src/main/java/com/aurora/mapper/UniqueViewMapper.java @@ -1,17 +1,19 @@ package com.aurora.mapper; -import com.aurora.model.dto.UniqueViewDTO; -import com.aurora.entity.UniqueView; +import com.aurora.model.dto.UniqueViewDTO;// 导入独立访客数据传输对象（UniqueViewDTO），用于前台数据展示，通常包含统计结果 +import com.aurora.entity.UniqueView;// 导入独立访客实体类（UniqueView），该实体类与数据库中的独立访客统计表（如 unique_view）相对应 import com.baomidou.mybatisplus.core.mapper.BaseMapper; import org.apache.ibatis.annotations.Param; import org.springframework.stereotype.Repository; -import java.util.Date; -import java.util.List; +import java.util.Date;// 导入 Java 的 Date 类，用于处理时间范围参数 +import java.util.List;// 导入 Java 集合框架中的 List 接口，用于返回多个 UniqueViewDTO 对象的集合 @Repository public interface UniqueViewMapper extends BaseMapper { - + // 自定义查询方法：根据时间范围查询独立访客统计列表（通常用于图表展示或数据分析） + // startTime: 统计开始时间，endTime: 统计结束时间，用于限定查询的时间范围（如查询某一天的UV数据） + // 返回 UniqueViewDTO 列表，每个对象可能包含统计时间点（如日期）和对应的独立访客数量 List listUniqueViews(@Param("startTime") Date startTime, @Param("endTime") Date endTime); } diff --git a/aurora-springboot/src/main/java/com/aurora/mapper/UserAuthMapper.java b/aurora-springboot/src/main/java/com/aurora/mapper/UserAuthMapper.java index 3eeef91..4781787 100644 --- a/aurora-springboot/src/main/java/com/aurora/mapper/UserAuthMapper.java +++ b/aurora-springboot/src/main/java/com/aurora/mapper/UserAuthMapper.java @@ -1,7 +1,9 @@ package com.aurora.mapper; - +// 导入用户管理数据传输对象（UserAdminDTO），用于后台管理界面展示用户信息，通常包含用户基本属性及扩展字段（如角色信息、状态标识等） import com.aurora.model.dto.UserAdminDTO; +// 导入用户认证实体类（UserAuth），该实体类与数据库中的用户认证表（如 user_auth）相对应，其字段（如用户名、密码、状态）与表结构映射 import com.aurora.entity.UserAuth; +// 导入条件查询值对象（ConditionVO），用于封装前端传递的复杂查询参数（如关键词、状态、时间范围等） import com.aurora.model.vo.ConditionVO; import com.baomidou.mybatisplus.core.mapper.BaseMapper; import org.apache.ibatis.annotations.Param; @@ -12,9 +14,13 @@ import java.util.List; @Repository public interface UserAuthMapper extends BaseMapper { - + //自定义查询方法：分页获取后台用户管理列表（通常用于管理员控制台） + // conditionVO: 封装查询条件的对象，可能包含用户名关键词、账号状态、注册时间范围等筛选条件 + // 返回 UserAdminDTO 列表，该 DTO 通常扩展了用户基础信息，包含管理所需的附加字段（如角色列表、最后登录时间等） List listUsers(@Param("current") Long current, @Param("size") Long size, @Param("conditionVO") ConditionVO conditionVO); - + // 自定义统计方法：根据条件统计用户数量（通常用于分页查询中的总数计算） + // conditionVO: 封装统计条件的对象，与 listUsers 方法中的条件一致，确保分页统计的准确性 + // 返回符合条件的用户总数，Integer 类型避免 null 值问题，用于前端分页组件计算总页数 Integer countUser(@Param("conditionVO") ConditionVO conditionVO); } diff --git a/aurora-springboot/src/main/java/com/aurora/mapper/WebsiteConfigMapper.java b/aurora-springboot/src/main/java/com/aurora/mapper/WebsiteConfigMapper.java index 34203d3..87c09c1 100644 --- a/aurora-springboot/src/main/java/com/aurora/mapper/WebsiteConfigMapper.java +++ b/aurora-springboot/src/main/java/com/aurora/mapper/WebsiteConfigMapper.java @@ -1,10 +1,12 @@ package com.aurora.mapper; - +// 导入WebsiteConfig实体类，该类与数据库中的网站配置表相对应 +// 实体类中的字段（如站点名称、Logo路径、备案号等）与数据库表字段一一映射 import com.aurora.entity.WebsiteConfig; import com.baomidou.mybatisplus.core.mapper.BaseMapper; import org.springframework.stereotype.Repository; @Repository public interface WebsiteConfigMapper extends BaseMapper { - + // 接口体为空，不定义任何自定义方法 + // 因为继承BaseMapper已经提供了数十个基础的数据库操作方法 } diff --git a/aurora-springboot/src/main/java/com/aurora/service/ArticleService.java b/aurora-springboot/src/main/java/com/aurora/service/ArticleService.java index 49503d8..d954922 100644 --- a/aurora-springboot/src/main/java/com/aurora/service/ArticleService.java +++ b/aurora-springboot/src/main/java/com/aurora/service/ArticleService.java @@ -1,43 +1,71 @@ +// service 层通常负责业务逻辑处理，是控制器层(Controller)和数据访问层(Mapper)之间的桥梁 package com.aurora.service; - +// 导入文章相关的数据传输对象(DTO)，用于在不同层之间传输数据 import com.aurora.model.dto.*; -import com.aurora.entity.Article; -import com.aurora.model.vo.*; -import com.baomidou.mybatisplus.extension.service.IService; - +import com.aurora.entity.Article;// 导入文章实体类(Article)，与数据库中的文章表相对应 +import com.aurora.model.vo.*;// 导入值对象(VO)，用于接收前端传递的参数 +import com.baomidou.mybatisplus.extension.service.IService;// 导入 MyBatis-Plus 的服务接口，提供了通用的服务层方法 +// 导入 Java 集合框架中的 List 接口，用于返回多个文章的集合或ID列表 import java.util.List; - - +// 定义文章服务接口，继承自 MyBatis-Plus 的 IService 接口，并指定泛型为 Article 实体类 +// 继承 IService 后，自动获得了通用的 CRUD 操作方法，如 save、remove、update、get 等 public interface ArticleService extends IService
{ - + // 获取置顶和推荐文章列表（通常用于首页展示） + // 返回 TopAndFeaturedArticlesDTO 对象，包含置顶文章和推荐文章列表 TopAndFeaturedArticlesDTO listTopAndFeaturedArticles(); - + // 分页获取所有文章列表（用于文章列表页） + // 返回 PageResultDTO 分页结果，包含文章卡片信息列表 PageResultDTO listArticles(); - + // 根据分类ID分页获取文章列表 + // categoryId: 分类ID，用于筛选指定分类下的文章 + // 返回分页的文章卡片列表 PageResultDTO listArticlesByCategoryId(Integer categoryId); - + // 根据文章ID获取单个文章详情（用于文章详情页） + // articleId: 文章主键ID + // 返回 ArticleDTO 对象，包含文章的完整内容及关联信息 ArticleDTO getArticleById(Integer articleId); - + // 校验文章访问密码（用于访问受密码保护的文章） + // articlePasswordVO: 包含文章ID和访问密码的值对象 + // 无返回值，通常通过抛出异常来处理密码错误的情况 void accessArticle(ArticlePasswordVO articlePasswordVO); - + // 根据标签ID分页获取文章列表 + // tagId: 标签ID，用于筛选带有指定标签的文章 + // 返回分页的文章卡片列表 PageResultDTO listArticlesByTagId(Integer tagId); - + // 获取文章归档列表（按时间分组，如按年月归档） + // 返回分页的 ArchiveDTO 列表，包含归档时间和对应的文章列表 PageResultDTO listArchives(); - + // 获取后台文章管理列表（管理员功能，支持条件查询和分页） + // conditionVO: 封装查询条件的值对象，如关键词、状态、时间范围等 + // 返回分页的 ArticleAdminDTO 列表，包含文章的管理信息 PageResultDTO listArticlesAdmin(ConditionVO conditionVO); - + // 保存或更新文章（根据ID判断是新增还是修改） + // articleVO: 包含文章信息的值对象，用于接收前端传递的数据 + // 无返回值，操作结果通过异常或日志处理 void saveOrUpdateArticle(ArticleVO articleVO); - + // 更新文章的置顶和推荐状态 + // articleTopFeaturedVO: 包含文章ID和置顶、推荐状态的值对象 + // 无返回值，直接更新数据库中的文章状态字段 void updateArticleTopAndFeatured(ArticleTopFeaturedVO articleTopFeaturedVO); - + // 更新文章的删除状态（逻辑删除，非物理删除） + // deleteVO: 包含文章ID和删除状态的值对象 + // 无返回值，通过更新文章的删除标记字段实现软删除 void updateArticleDelete(DeleteVO deleteVO); - + // 物理删除文章（从数据库中彻底删除） + // articleIds: 文章ID列表，支持批量删除 + // 无返回值，直接删除数据库中的文章记录 void deleteArticles(List articleIds); - + // 根据文章ID获取后台管理所需的文章详情（可能包含更多管理字段） + // articleId: 文章主键ID + // 返回 ArticleAdminViewDTO 对象，包含文章详情及管理信息 ArticleAdminViewDTO getArticleByIdAdmin(Integer articleId); - + // 导出文章（通常导出为特定格式的文件，如Markdown、PDF等） + // articleIdList: 需要导出的文章ID列表 + // 返回字符串列表，可能包含导出文件的路径或导出内容的标识 List exportArticles(List articleIdList); - + // 根据搜索条件查询文章列表（用于搜索功能） + // condition: 包含搜索关键词等条件的值对象 + // 返回 ArticleSearchDTO 列表，包含文章的搜索相关信息 List listArticlesBySearch(ConditionVO condition); } diff --git a/aurora-springboot/src/main/java/com/aurora/service/AuroraInfoService.java b/aurora-springboot/src/main/java/com/aurora/service/AuroraInfoService.java index 3c31865..3a985dd 100644 --- a/aurora-springboot/src/main/java/com/aurora/service/AuroraInfoService.java +++ b/aurora-springboot/src/main/java/com/aurora/service/AuroraInfoService.java @@ -1,26 +1,31 @@ package com.aurora.service; - +//导入关于我信息的数据传输对象（AboutDTO），用于前台数据展示，通常包含关于我页面的文本内容、作者信息等 import com.aurora.model.dto.AboutDTO; +// 导入博客后台信息数据传输对象（AuroraAdminInfoDTO），用于管理员控制台展示系统统计信息（如访客数、文章数等） import com.aurora.model.dto.AuroraAdminInfoDTO; +// 导入博客首页信息数据传输对象（AuroraHomeInfoDTO），用于前台首页展示核心数据（如置顶文章、分类列表等） import com.aurora.model.dto.AuroraHomeInfoDTO; +// 导入网站配置数据传输对象（WebsiteConfigDTO），用于前台获取站点基本信息（如站点名称、Logo、备案号等） import com.aurora.model.dto.WebsiteConfigDTO; +// 导入关于我信息值对象（AboutVO），用于接收前端传递的关于我信息更新参数 import com.aurora.model.vo.AboutVO; +// 导入网站配置值对象（WebsiteConfigVO），用于接收前端传递的网站配置更新参数 import com.aurora.model.vo.WebsiteConfigVO; public interface AuroraInfoService { - - void report(); - - AuroraHomeInfoDTO getAuroraHomeInfo(); - - AuroraAdminInfoDTO getAuroraAdminInfo(); - + //上报访客信息，通常用于记录用户访问日志或更新访客计数 + void report();//无参数和返回值，执行结果通过异常或日志处理 + //获取博客首页展示信息（用于前台首页渲染） + //返回结果通常包含文章列表、分类数据、标签云、站点统计等聚合信息 + AuroraHomeInfoDTO getAuroraHomeInfo();//@return AuroraHomeInfoDTO 首页信息对象，封装了前台首页所需的所有数据 + // 获取博客后台管理信息（用于管理员控制台仪表盘） + //返回结果通常包含系统核心统计指标，如总访客数、文章数量、评论数量、系统状态等 + AuroraAdminInfoDTO getAuroraAdminInfo();//返回值：后台信息对象，专用于管理员视角的数据展示 + //更新网站配置信息（如站点名称、Logo、页脚信息等）,该方法通常需要权限校验，确保只有管理员可操作 + //@param websiteConfigVO 网站配置值对象，包含待更新的配置字段 void updateWebsiteConfig(WebsiteConfigVO websiteConfigVO); - - WebsiteConfigDTO getWebsiteConfig(); - - void updateAbout(AboutVO aboutVO); - - AboutDTO getAbout(); + WebsiteConfigDTO getWebsiteConfig();//获取当前网站配置信息（用于前台或后台展示）,WebsiteConfigDTO 网站配置数据传输对象，包含所有可配置的站点参数 + void updateAbout(AboutVO aboutVO);//更新关于我信息（用于修改关于页面的内容）,@param aboutVO:关于我信息值对象，包含更新后的关于我内容 + AboutDTO getAbout();//获取关于我信息（用于前台关于页面展示）,@return AboutDTO:关于我信息数据传输对象，用于前端渲染 } diff --git a/aurora-springboot/src/main/java/com/aurora/service/CategoryService.java b/aurora-springboot/src/main/java/com/aurora/service/CategoryService.java index 9ce3e0c..f2fb593 100644 --- a/aurora-springboot/src/main/java/com/aurora/service/CategoryService.java +++ b/aurora-springboot/src/main/java/com/aurora/service/CategoryService.java @@ -1,26 +1,28 @@ package com.aurora.service; -import com.aurora.model.dto.CategoryAdminDTO; +import com.aurora.model.dto.CategoryAdminDTO;// 导入分类管理的数据传输对象（CategoryAdminDTO），用于后台管理界面展示分类信息，通常包含管理所需的扩展字段 import com.aurora.model.dto.CategoryDTO; -import com.aurora.model.dto.CategoryOptionDTO; +import com.aurora.model.dto.CategoryOptionDTO;// 导入分类选项数据传输对象（CategoryOptionDTO），通常用于下拉选择框等场景，仅包含关键标识字段 import com.aurora.entity.Category; -import com.aurora.model.vo.CategoryVO; -import com.aurora.model.vo.ConditionVO; -import com.aurora.model.dto.PageResultDTO; +import com.aurora.model.vo.CategoryVO;// 导入分类值对象（CategoryVO），用于接收前端传递的分类新增或修改参数 +import com.aurora.model.vo.ConditionVO;// 导入条件查询值对象（ConditionVO），用于封装前端传递的复杂查询参数，如关键词、状态、分页信息等 +import com.aurora.model.dto.PageResultDTO;// 导入分页结果数据传输对象（PageResultDTO），用于封装分页查询结果，包含数据列表和总数等信息 import com.baomidou.mybatisplus.extension.service.IService; import java.util.List; - +//主要用于处理分类的增删改查、列表查询和搜索等核心业务逻辑 public interface CategoryService extends IService { - List listCategories(); - + List listCategories();//获取所有分类列表（通常用于前台分类展示或导航菜单）,包含分类的核心展示信息 + //分页获取后台分类管理列表（支持条件查询，用于管理员控制台） + //用于后台管理界面，支持根据条件进行筛选和分页展示 + //@return PageResultDTO 分页结果对象，包含分类管理数据列表和分页信息 PageResultDTO listCategoriesAdmin(ConditionVO conditionVO); - + //根据搜索条件查询分类选项列表（通常用于搜索或筛选场景）,该方法返回精简的分类选项，常用于下拉选择框或搜索联想 List listCategoriesBySearch(ConditionVO conditionVO); - void deleteCategories(List categoryIds); + void deleteCategories(List categoryIds);//批量删除分类（根据分类ID列表物理删除或逻辑删除） - void saveOrUpdateCategory(CategoryVO categoryVO); + void saveOrUpdateCategory(CategoryVO categoryVO);//保存或更新分类信息（根据ID自动判断是新增还是修改操作） } diff --git a/aurora-springboot/src/main/java/com/aurora/service/CommentService.java b/aurora-springboot/src/main/java/com/aurora/service/CommentService.java index 5d45ffc..1417fa5 100644 --- a/aurora-springboot/src/main/java/com/aurora/service/CommentService.java +++ b/aurora-springboot/src/main/java/com/aurora/service/CommentService.java @@ -2,28 +2,32 @@ package com.aurora.service; import com.aurora.model.dto.CommentAdminDTO; import com.aurora.model.dto.CommentDTO; -import com.aurora.model.dto.ReplyDTO; +import com.aurora.model.dto.ReplyDTO;// 导入回复数据传输对象（ReplyDTO），专门用于封装评论的回复信息，通常包含被回复对象标识和回复内容 import com.aurora.entity.Comment; -import com.aurora.model.vo.CommentVO; +import com.aurora.model.vo.CommentVO;// 导入评论值对象（CommentVO），用于接收前端传递的评论新增或修改参数，通常进行参数校验 import com.aurora.model.vo.ConditionVO; import com.aurora.model.dto.PageResultDTO; -import com.aurora.model.vo.ReviewVO; +import com.aurora.model.vo.ReviewVO;// 导入审核值对象（ReviewVO），用于接收评论审核操作的相关参数，如评论ID集合和审核状态 import com.baomidou.mybatisplus.extension.service.IService; import java.util.List; - +//主要用于处理评论的增删改查、回复管理、热门评论筛选和审核等核心业务逻辑 public interface CommentService extends IService { - void saveComment(CommentVO commentVO); - - PageResultDTO listComments(CommentVO commentVO); + void saveComment(CommentVO commentVO);//保存评论信息（包含评论和回复的保存逻辑） - List listRepliesByCommentId(Integer commentId); + PageResultDTO listComments(CommentVO commentVO);//分页获取评论列表（支持条件查询，用于文章详情页的评论展示） - List listTopSixComments(); + List listRepliesByCommentId(Integer commentId);//根据评论ID获取该评论的所有回复列表（实现楼中楼功能） + List listTopSixComments();//获取前六条热门评论（通常用于首页或侧边栏展示） + /** + * 分页获取后台评论管理列表（管理员功能，支持复杂条件查询）,该方法通常用于管理员审核评论，可查看评论状态、操作日志等管理信息 + * @param conditionVO 封装查询条件的值对象，包含关键词、审核状态、时间范围等参数 + * @return PageResultDTO 分页结果对象，包含评论管理数据列表 + */ PageResultDTO listCommentsAdmin(ConditionVO conditionVO); - void updateCommentsReview(ReviewVO reviewVO); + void updateCommentsReview(ReviewVO reviewVO);//更新评论的审核状态（批量审核通过或拒绝）,需要权限校验，确保只有管理员可执行审核操作 } diff --git a/aurora-springboot/src/main/java/com/aurora/service/ExceptionLogService.java b/aurora-springboot/src/main/java/com/aurora/service/ExceptionLogService.java index 0155379..f715b6d 100644 --- a/aurora-springboot/src/main/java/com/aurora/service/ExceptionLogService.java +++ b/aurora-springboot/src/main/java/com/aurora/service/ExceptionLogService.java @@ -5,9 +5,9 @@ import com.aurora.entity.ExceptionLog; import com.aurora.model.vo.ConditionVO; import com.aurora.model.dto.PageResultDTO; import com.baomidou.mybatisplus.extension.service.IService; - +//主要用于处理异常日志的查询、分页展示等核心业务逻辑，通常与全局异常处理器或 AOP 切面配合使用 public interface ExceptionLogService extends IService { - + //分页获取异常日志列表（支持条件查询，通常用于后台管理系统的日志查看界面） PageResultDTO listExceptionLogs(ConditionVO conditionVO); } diff --git a/aurora-springboot/src/main/java/com/aurora/service/FriendLinkService.java b/aurora-springboot/src/main/java/com/aurora/service/FriendLinkService.java index 3bbb0e3..2617b1d 100644 --- a/aurora-springboot/src/main/java/com/aurora/service/FriendLinkService.java +++ b/aurora-springboot/src/main/java/com/aurora/service/FriendLinkService.java @@ -12,9 +12,9 @@ import java.util.List; public interface FriendLinkService extends IService { - List listFriendLinks(); + List listFriendLinks();//获取所有友情链接列表（通常用于前台展示，如友情链接页面或侧边栏） - PageResultDTO listFriendLinksAdmin(ConditionVO conditionVO); + PageResultDTO listFriendLinksAdmin(ConditionVO conditionVO);//分页获取后台友情链接管理列表（支持条件查询，用于管理员控制台） void saveOrUpdateFriendLink(FriendLinkVO friendLinkVO); diff --git a/aurora-springboot/src/main/java/com/aurora/service/JobLogService.java b/aurora-springboot/src/main/java/com/aurora/service/JobLogService.java index 33562fd..a6aeaca 100644 --- a/aurora-springboot/src/main/java/com/aurora/service/JobLogService.java +++ b/aurora-springboot/src/main/java/com/aurora/service/JobLogService.java @@ -3,7 +3,7 @@ package com.aurora.service; import com.aurora.model.dto.JobLogDTO; import com.aurora.entity.JobLog; -import com.aurora.model.vo.JobLogSearchVO; +import com.aurora.model.vo.JobLogSearchVO;// 导入作业日志搜索值对象（JobLogSearchVO），用于封装前端传递的复杂查询参数，如关键词、时间范围、执行状态等筛选条件 import com.aurora.model.dto.PageResultDTO; import com.baomidou.mybatisplus.extension.service.IService; @@ -11,13 +11,13 @@ import java.util.List; public interface JobLogService extends IService { - + //分页获取作业日志列表（支持条件查询，通常用于后台管理系统的日志查看界面） PageResultDTO listJobLogs(JobLogSearchVO jobLogSearchVO); - + //批量删除作业日志记录（根据ID列表物理删除或逻辑删除） void deleteJobLogs(List ids); - + //清空作业日志记录（通常用于清理过期或冗余的日志数据） void cleanJobLogs(); - + //获取作业日志的所有分组列表（通常用于统计或筛选场景） List listJobLogGroups(); } diff --git a/aurora-springboot/src/main/java/com/aurora/service/JobService.java b/aurora-springboot/src/main/java/com/aurora/service/JobService.java index b13b50a..a7eb29f 100644 --- a/aurora-springboot/src/main/java/com/aurora/service/JobService.java +++ b/aurora-springboot/src/main/java/com/aurora/service/JobService.java @@ -12,17 +12,17 @@ public interface JobService extends IService { void saveJob(JobVO jobVO); - void updateJob(JobVO jobVO); + void updateJob(JobVO jobVO);//导入作业值对象（JobVO），用于接收前端传递的作业新增或修改参数，通常需要校验作业是否存在且未被执行中 - void deleteJobs(List tagIds); + void deleteJobs(List tagIds);//批量删除作业（根据ID列表物理删除或逻辑删除） JobDTO getJobById(Integer jobId); - PageResultDTO listJobs(JobSearchVO jobSearchVO); + PageResultDTO listJobs(JobSearchVO jobSearchVO);// 导入作业搜索值对象（JobSearchVO），用于封装前端传递的复杂查询参数，如关键词、状态、时间范围等筛选条件 - void updateJobStatus(JobStatusVO jobStatusVO); - - void runJob(JobRunVO jobRunVO); + void updateJobStatus(JobStatusVO jobStatusVO);// 导入作业状态值对象（JobStatusVO），用于接收作业状态更新参数，如启用、禁用等操作 + //该方法会绕过正常的调度计划，立即触发作业执行一次 + void runJob(JobRunVO jobRunVO);// 导入作业运行值对象（JobRunVO），用于接收立即执行作业的参数，如作业ID、执行参数等 List listJobGroups(); diff --git a/aurora-springboot/src/main/java/com/aurora/service/MenuService.java b/aurora-springboot/src/main/java/com/aurora/service/MenuService.java index 4956642..3ec5b13 100644 --- a/aurora-springboot/src/main/java/com/aurora/service/MenuService.java +++ b/aurora-springboot/src/main/java/com/aurora/service/MenuService.java @@ -10,14 +10,14 @@ import com.aurora.model.vo.MenuVO; import com.baomidou.mybatisplus.extension.service.IService; import java.util.List; - +//主要用于处理菜单的增删改查、层级结构构建、权限过滤和状态管理等核心业务逻辑 public interface MenuService extends IService { - List listMenus(ConditionVO conditionVO); + List listMenus(ConditionVO conditionVO);//根据条件查询菜单列表（支持动态筛选，用于后台管理系统）,常返回菜单的层级结构数据 void saveOrUpdateMenu(MenuVO menuVO); - void updateMenuIsHidden(IsHiddenVO isHiddenVO); + void updateMenuIsHidden(IsHiddenVO isHiddenVO);//该方法通常需要权限校验，确保只有管理员可操作菜单的显示状态 void deleteMenu(Integer menuId); diff --git a/aurora-springboot/src/main/java/com/aurora/service/PhotoAlbumService.java b/aurora-springboot/src/main/java/com/aurora/service/PhotoAlbumService.java index fee236e..2b9ffea 100644 --- a/aurora-springboot/src/main/java/com/aurora/service/PhotoAlbumService.java +++ b/aurora-springboot/src/main/java/com/aurora/service/PhotoAlbumService.java @@ -22,6 +22,6 @@ public interface PhotoAlbumService extends IService { void deletePhotoAlbumById(Integer albumId); - List listPhotoAlbums(); + List listPhotoAlbums();//返回结果通常按相册的创建时间或排序权重进行排序,包含前台展示所需的核心信息 } diff --git a/aurora-springboot/src/main/java/com/aurora/service/PhotoService.java b/aurora-springboot/src/main/java/com/aurora/service/PhotoService.java index c2caed7..6380cb2 100644 --- a/aurora-springboot/src/main/java/com/aurora/service/PhotoService.java +++ b/aurora-springboot/src/main/java/com/aurora/service/PhotoService.java @@ -14,13 +14,13 @@ public interface PhotoService extends IService { PageResultDTO listPhotos(ConditionVO conditionVO); - void updatePhoto(PhotoInfoVO photoInfoVO); + void updatePhoto(PhotoInfoVO photoInfoVO);// 导入照片信息值对象（PhotoInfoVO），用于接收前端传递的照片信息更新参数，通常进行参数校验 - void savePhotos(PhotoVO photoVO); + void savePhotos(PhotoVO photoVO);//导入照片值对象（PhotoVO），用于接收前端传递的照片新增或批量操作参数 void updatePhotosAlbum(PhotoVO photoVO); - void updatePhotoDelete(DeleteVO deleteVO); + void updatePhotoDelete(DeleteVO deleteVO);//导入删除值对象（DeleteVO），用于接收删除操作的参数，如逻辑删除状态标识 void deletePhotos(List photoIds); diff --git a/aurora-springboot/src/main/java/com/aurora/service/RedisService.java b/aurora-springboot/src/main/java/com/aurora/service/RedisService.java index 420e1fe..df50650 100644 --- a/aurora-springboot/src/main/java/com/aurora/service/RedisService.java +++ b/aurora-springboot/src/main/java/com/aurora/service/RedisService.java @@ -1,123 +1,160 @@ package com.aurora.service; -import org.springframework.data.domain.Sort; -import org.springframework.data.geo.Distance; -import org.springframework.data.geo.GeoResults; -import org.springframework.data.geo.Point; -import org.springframework.data.redis.connection.RedisGeoCommands; - -import java.util.List; -import java.util.Map; -import java.util.Set; - +import org.springframework.data.domain.Sort;// 导入 Spring Data 的排序类（Sort），用于指定查询结果的排序方向（如升序、降序） +import org.springframework.data.geo.Distance;// 导入距离类（Distance），用于表示地理空间计算中的距离结果，通常包含数值和单位 +import org.springframework.data.geo.GeoResults;// 导入地理空间查询结果类（GeoResults），用于封装地理空间查询的返回结果，如附近地点列表 +import org.springframework.data.geo.Point;// 导入点类（Point），用于表示地理空间中的坐标点（经度、纬度） +import org.springframework.data.redis.connection.RedisGeoCommands;// 导入 Redis 地理空间命令相关类（RedisGeoCommands），提供地理空间操作的支持（如添加地点、计算距离） + +import java.util.List;// 导入 Java 集合框架中的 List 接口，用于存储有序的元素序列，常用于方法参数或返回列表结果 +import java.util.Map;// 导入 Map 接口，用于存储键值对映射关系，常用于哈希结构操作 +import java.util.Set;// 导入 Set 接口，用于存储不重复的元素集合，常用于集合结构操作 +// 抑制编译器所有类型的警告信息，避免编译时产生警告提示，使代码更简洁 @SuppressWarnings("all") +// 定义 Redis 服务接口（RedisService），声明一系列 Redis 数据操作的方法 +// 该接口封装了 Redis 的常用功能，包括字符串、哈希、列表、集合、有序集合、位操作、地理空间等数据类型的操作 public interface RedisService { - + /** + * 保存键值对并设置过期时间（单位：秒）,该方法将键值对存储到 Redis中，并在指定时间后自动过期，常用于临时数据或缓存场景 + * @param key 键名，用于唯一标识数据 + * @param value 值，可以是任意对象类型，通常通过序列化存储 + * @param time 过期时间（秒），指定数据在 Redis 中的存活时间 + */ void set(String key, Object value, long time); - void set(String key, Object value); - - Object get(String key); - - Boolean del(String key); - - Long del(List keys); + void set(String key, Object value);//保存键值对（除非手动删除,否则永不过期） - Boolean expire(String key, long time); + Object get(String key);//根据键名获取值(Object为值对象），该方法从Redis中查询指定键对应的值，如果键不存在则返回 null - Long getExpire(String key); + Boolean del(String key);//删除指定键的数据,该方法从Redis中移除指定键及其关联值，删除成功返回 true，否则返回 false - Boolean hasKey(String key); + Long del(List keys);//批量删除多个键的数据,该方法一次性删除多个键值对，返回实际删除的键数量 - Long incr(String key, long delta); + Boolean expire(String key, long time);//设置键的过期时间,该方法为已存在的键设置生存时间，超过指定时间后键自动失效 - Long incrExpire(String key, long time); - - Long decr(String key, long delta); + Long getExpire(String key);//获取键的剩余生存时间（单位：秒),该方法查询键的剩余存活时间，返回秒数；如果键不存在或永不过期，返回特定值 + Boolean hasKey(String key);//判断键是否存在,该方法检查Redis是否存在指定的键，常用于验证数据是否已缓存 + //返回自增后的新值 + Long incr(String key, long delta);//对键的值进行自增操作（整数）,该方法将键对应的整数值增加指定步长，常用于计数器、限流等场景 + //返回自增后的新值 + Long incrExpire(String key, long time);//自增并设置过期时间,该方法在自增操作的同时重置键的过期时间，确保计数器在指定时间内有效 + //返回自减后的新值 + Long decr(String key, long delta);//对键的值进行自减操作（整数）,该方法将键对应的整数值减少指定步长，常用于计数器、限流等场景 + /** + * 获取哈希结构中指定字段的值，该方法从Redis哈希类型数据中获取特定字段的值，适用于对象属性存储 + * @param key 哈希键名 @param hashKey 哈希字段名 @return 字段值，如果字段不存在返回 null + */ Object hGet(String key, String hashKey); - + //向哈希结构中设置字段值并设置过期时间,该方法在哈希中设置字段值，并为整个哈希键设置统一的过期时间 Boolean hSet(String key, String hashKey, Object value, long time); - + //向哈希结构中设置字段值（永不过期）,该方法仅设哈希字段值，不修改键的过期时间 void hSet(String key, String hashKey, Object value); - + /** + * 获取整个哈希结构的所有字段和值,该方法返回哈希键对应的全部字段-值映射，适用于获取完整对象数据 + * @param key 哈希键名 @return 字段-值映射表（Map 对象） + */ Map hGetAll(String key); - + //批量设置哈希结构的字段值并设置过期时间,该方法使用 Map 批量设置哈希字段，同时设置整个键的过期时间 Boolean hSetAll(String key, Map map, long time); - + //批量设置哈希结构的字段值（永不过期）,该方法批量设置哈希字段，不修改键的过期时间 void hSetAll(String key, Map map); - + /** + * 删除哈希结构中的指定字段,该方法从哈希中移除一个或多个字段，不影响其他字段 + * @param key 哈希键名 @param hashKey 要删除的字段名（可变参数，可多个） + */ void hDel(String key, Object... hashKey); - + /** + * 判断哈希结构中是否存在指定字段,该方法检查哈希中是否包含特定字段，用于验证字段存在性 + * @param key 哈希键名 @param hashKey 字段名 @return 是否存在（true：存在，false：不存在） + */ Boolean hHasKey(String key, String hashKey); - - Long hIncr(String key, String hashKey, Long delta); - - Long hDecr(String key, String hashKey, Long delta); - - Double zIncr(String key, Object value, Double score); - - Double zDecr(String key, Object value, Double score); - + //返回自增后的新值 + Long hIncr(String key, String hashKey, Long delta);//对哈希结构中指定字段的值进行自增操作（整数）,该方法增加哈希中某个字段的整数值，适用于对象属性的计数场景 + //返回自减后的新值 + Long hDecr(String key, String hashKey, Long delta);//对哈希结构中指定字段的值进行自减操作（整数）,该方法增加哈希中某个字段的整数值，适用于对象属性的计数场景 + //返回增加后的新分数 + Double zIncr(String key, Object value, Double score);//增加有序集合中成员的分数,该方法为有序集合中指定成员增加分数，适用于排行榜、优先级队列等场景 + //返回减少后的新分数 + Double zDecr(String key, Object value, Double score);//减少有序集合中成员的分数,该方法为有序集合中指定成员减少分数，适用于排行榜、优先级队列等场景 + //获取有序集合中指定排名范围的成员及分数（按分数从高到低）,该方法返回有序集合中从高到低排序的成员及其分数，适用于 TopN 查询 Map zReverseRangeWithScore(String key, long start, long end); - - Double zScore(String key, Object value); - - Map zAllScore(String key); - - Set sMembers(String key); - - Long sAdd(String key, Object... values); - - Long sAddExpire(String key, long time, Object... values); - - Boolean sIsMember(String key, Object value); - - Long sSize(String key); - - Long sRemove(String key, Object... values); - - List lRange(String key, long start, long end); - - Long lSize(String key); - - Object lIndex(String key, long index); - - Long lPush(String key, Object value); - - Long lPush(String key, Object value, long time); - - Long lPushAll(String key, Object... values); - - Long lPushAll(String key, Long time, Object... values); - - Long lRemove(String key, long count, Object value); - + //返回分数值，如果成员不存在返回 null + Double zScore(String key, Object value);//获取有序集合中指定成员的分数,该方法查询特定成员在有序集合中的分数值 + + Map zAllScore(String key);//获取有序集合中所有成员的分数,该方法返回有序集合中全部成员的分数映射，适用于数据导出或分析 + + Set sMembers(String key);//获取集合中的所有成员,该方法返回集合键对应的全部成员集合，适用于获取不重复的元素列表 + //返回实际被添加的新成员数量（重复成员不计数） + Long sAdd(String key, Object... values);//向集合中添加一个或多个成员,该方法向集合中插入新成员，重复成员会被自动忽略 + //返回实际被添加的新成员数量 + Long sAddExpire(String key, long time, Object... values);//向集合中添加成员并设置过期时间,该方法添加成员的同时为整个集合键设置过期时间 + + Boolean sIsMember(String key, Object value);//判断指定成员是否在集合中,该方法检查成员是否属于集合，用于验证元素存在性 + //返回成员数量 @param key 集合键名 + Long sSize(String key);//获取集合的成员数量,该方法返回集合中元素的总数，即集合的基数 + //返回实际被移除的成员数量 + Long sRemove(String key, Object... values);//从集合中移除一个或多个成员,该方法从集合中删除指定成员，不存在则忽略 + //返回元素列表 + List lRange(String key, long start, long end);//获取列表中指定范围的元素,该方法返回列表键中从start到end索引的元素子集（包含两端） + + Long lSize(String key);//获取列表的长度,该方法返回列表中元素的总数 @param key 列表键名 + //@return 索引处的元素值 + Object lIndex(String key, long index);//根据索引获取列表中的元素,该方法返回列表中指定索引位置的元素，支持负数索引（-1 表示最后一个） + //@return 插入后列表的长度 + Long lPush(String key, Object value);//向列表尾部插入一个元素,该方法在列表的右端（尾部）添加新元素，适用于队列或日志追加场景 + //@return 插入后列表的长度 + Long lPush(String key, Object value, long time);//向列表尾部插入一个元素并设置过期时间,该方法插入元素的同时重置列表键的过期时间 + //@return 插入后列表的长度 + Long lPushAll(String key, Object... values);//向列表尾部批量插入多个元素,该方法一次性在列表尾部插入多个元素，元素顺序与参数顺序一致 + //@return 插入后列表的长度 + Long lPushAll(String key, Long time, Object... values);//向列表尾部批量插入多个元素并设置过期时间,该方法批量插入元素的同时设置列表键的过期时间 + //返回实际移除数量 @param count 移除数量（正数：从头部开始搜索；负数：从尾部开始搜索；0：全部移除） + Long lRemove(String key, long count, Object value);//从列表中移除指定数量的匹配元素,该方法删除列表中前count个与value相等的元素 + /** + * 设置位图中指定偏移量的比特值,该方法操作位图（Bitmap）数据，将指定偏移量的比特设置为 1 或 0，适用于布隆过滤器、状态记录等场景 + * @param key 位图键名 @param offset 比特偏移量 @param b 比特值（true：1，false：0） + * @return 设置是否成功 + */ Boolean bitAdd(String key, int offset, boolean b); - Boolean bitGet(String key, int offset); - - Long bitCount(String key); + Boolean bitGet(String key, int offset);//获取位图中指定偏移量的比特值,该方法查询位图中特定偏移量的比特状态 - List bitField(String key, int limit, int offset); + Long bitCount(String key);//统计位图中被设置为 1 的比特数量,该方法计算位图中所有值为 1 的比特总数，用于人口统计等 + @param key 位图键名 + //@param limit:要提取的比特数量 @param offset:起始偏移量 @param key:位图键名 @return 比特字段整数值列表 + List bitField(String key, int limit, int offset);//获取位图中指定范围的比特字段值,该方法提取位图中从指定偏移量开始的多个连续比特，返回其整数值列表 + //@return 位图的字节数组表示 + byte[] bitGetAll(String key);//获取整个位图的原始字节数据,该方法返回位图的完整字节数组，适用于底层数据处理或自定义解析 - byte[] bitGetAll(String key); + Long hyperAdd(String key, Object... value);//向HyperLogLog中添加元素,该方法用于基数统计，向HyperLogLog结构中添加元素，用于估算不重复元素数量 - Long hyperAdd(String key, Object... value); - - Long hyperGet(String... key); - - void hyperDel(String key); + Long hyperGet(String... key);//合并多个HyperLogLog并返回估算的基数,该方法将多个HyperLogLog结构合并，并返回估算的唯一元素总数 + void hyperDel(String key);//删除HyperLogLog结构,该方法移除指定的HyperLogLog键 + /** + * 向地理空间索引中添加一个地点,该方法将地点名称及其经纬度坐标添加到地理空间索引中，用于附近地点查询 + * @param key:地理空间键名 @param x:经度坐标 @param y:纬度坐标 @param name:地点名称标识 + * @return 添加成功的元素数量（1：成功，0：失败） + */ Long geoAdd(String key, Double x, Double y, String name); - - List geoGetPointList(String key, Object... place); - + // @return 坐标点列表，每个元素是对应地点的 Point 对象 + List geoGetPointList(String key, Object... place);//获取指定地点的经纬度坐标列表,该方法查询一个或多个地点的坐标信息，返回Point对象列表 + /** + * 计算两个地点之间的地理空间距离,该方法根据经纬度计算两个地点间的实际距离，返回包含数值和单位的 Distance 对象 + * @param key:地理空间键名 @param placeOne:第一个地点名称 @param placeTow:第二个地点名称 + * @return 距离对象（Distance），包含距离值和单位（如米、千米） + */ Distance geoCalculationDistance(String key, String placeOne, String placeTow); - + /** + * 查询指定地点附近的其他地点,该方法以指定地点为中心，查找距离范围内的其他地点，支持排序和数量限制 + * @param key:地理空间键名 @param place:中心地点名称 @param distance:查询距离范围 @param limit:返回结果数量限制 + * @param sort:排序方向（ASC：由近到远，DESC：由远到近） + * @return 地理空间查询结果（GeoResults），包含附近地点列表及其距离信息 + */ GeoResults> geoNearByPlace(String key, String place, Distance distance, long limit, Sort.Direction sort); - List geoGetHash(String key, String... place); + List geoGetHash(String key, String... place);//获取地点的Geohash字符串表示,该方法返回一个或多个地点的 Geohash 值，Geohash是一种用于表示地理位置的编码字符串 } diff --git a/aurora-springboot/src/main/java/com/aurora/service/ResourceService.java b/aurora-springboot/src/main/java/com/aurora/service/ResourceService.java index b4fa407..c5aacbc 100644 --- a/aurora-springboot/src/main/java/com/aurora/service/ResourceService.java +++ b/aurora-springboot/src/main/java/com/aurora/service/ResourceService.java @@ -8,9 +8,12 @@ import com.aurora.model.vo.ResourceVO; import com.baomidou.mybatisplus.extension.service.IService; import java.util.List; - +//主要用于处理资源的增删改查、Swagger 文档导入、条件查询和选项列表生成等核心业务逻辑 public interface ResourceService extends IService { - + /** + * 导入 Swagger 文档中的 API 资源（用于自动化生成或同步接口资源),该方法通常解析 Swagger JSON 或 YAML 文档，提取接口路径、方法等信息并持久化到数据库 + * 无参数和返回值，执行结果通过日志或异常处理 + */ void importSwagger(); void saveOrUpdateResource(ResourceVO resourceVO); diff --git a/aurora-springboot/src/main/java/com/aurora/service/RoleService.java b/aurora-springboot/src/main/java/com/aurora/service/RoleService.java index adb5979..d427f86 100644 --- a/aurora-springboot/src/main/java/com/aurora/service/RoleService.java +++ b/aurora-springboot/src/main/java/com/aurora/service/RoleService.java @@ -1,7 +1,7 @@ package com.aurora.service; -import com.aurora.model.dto.RoleDTO; -import com.aurora.model.dto.UserRoleDTO; +import com.aurora.model.dto.RoleDTO;// 导入角色数据传输对象（RoleDTO），用于前台或管理界面展示角色信息，通常包含角色基本属性及扩展字段（如用户数量、权限列表等） +import com.aurora.model.dto.UserRoleDTO;// 导入用户角色数据传输对象（UserRoleDTO），用于关联用户和角色信息，通常在用户管理或权限分配场景中使用 import com.aurora.entity.Role; import com.aurora.model.vo.ConditionVO; import com.aurora.model.dto.PageResultDTO; @@ -12,12 +12,12 @@ import java.util.List; public interface RoleService extends IService { - List listUserRoles(); + List listUserRoles();//获取用户角色关联列表,返回结果包含用户与角色的关联信息，适用于前端下拉选择或权限分配界面 PageResultDTO listRoles(ConditionVO conditionVO); void saveOrUpdateRole(RoleVO roleVO); - void deleteRoles(List ids); + void deleteRoles(List ids);//一次性删除多个角色记录，通常需要检查角色是否被用户关联，避免误删正在使用的角色 } diff --git a/aurora-springboot/src/main/java/com/aurora/service/TalkService.java b/aurora-springboot/src/main/java/com/aurora/service/TalkService.java index d309035..ceebab1 100644 --- a/aurora-springboot/src/main/java/com/aurora/service/TalkService.java +++ b/aurora-springboot/src/main/java/com/aurora/service/TalkService.java @@ -22,7 +22,7 @@ public interface TalkService extends IService { void deleteTalks(List talkIdList); PageResultDTO listBackTalks(ConditionVO conditionVO); - + //根据说说ID获取后台管理所需的谈话详情，返回的TalkAdminDTO通常比TalkDTO包含更多管理字段，如审核状态、操作日志等 TalkAdminDTO getBackTalkById(Integer talkId); } diff --git a/aurora-springboot/src/main/java/com/aurora/service/TokenService.java b/aurora-springboot/src/main/java/com/aurora/service/TokenService.java index cedea27..b4181f1 100644 --- a/aurora-springboot/src/main/java/com/aurora/service/TokenService.java +++ b/aurora-springboot/src/main/java/com/aurora/service/TokenService.java @@ -1,24 +1,46 @@ package com.aurora.service; -import com.aurora.model.dto.UserDetailsDTO; -import io.jsonwebtoken.Claims; - -import javax.servlet.http.HttpServletRequest; +import com.aurora.model.dto.UserDetailsDTO;// 导入用户详情数据传输对象（UserDetailsDTO），用于封装认证用户的详细信息（如用户名、权限列表、登录时间等） +import io.jsonwebtoken.Claims;// 导入 JWT 声明接口（Claims），代表 JWT Token 的负载部分，包含 token 中存储的键值对信息（如用户标识、签发时间等） +import javax.servlet.http.HttpServletRequest;// 导入 HTTP Servlet 请求对象（HttpServletRequest），用于获取客户端请求中的头信息、参数等，以提取 token +//Token 服务通常用于身份验证和授权 +//主要功能包括：为登录用户创建令牌、验证令牌有效性、解析令牌获取用户信息、管理令牌生命周期等 public interface TokenService { - + /** + * 根据用户详细信息创建 JWT 令牌,该方法将用户的核心信息（如用户名、角色）嵌入令牌负载（Payload）中，并生成数字签名确保令牌完整性 + * @param userDetailsDTO 用户详情数据传输对象，包含生成令牌所需的用户身份信息（如用户名、ID、权限等） + * @return String 生成的 JWT 令牌字符串，通常包含头部（Header）、负载（Payload）和签名（Signature）三部分 + */ String createToken(UserDetailsDTO userDetailsDTO); - + /** + * 根据主题（Subject）创建 JWT 令牌（简化版）,该方法适用于仅需标识主题场景，令牌负载可能仅包含主题信息，适用于简单认证或临时令牌生成 + * @param subject 令牌主题，通常是一个唯一标识符（如用户ID、客户端ID），用于标识令牌的归属主体 + * @return String 生成的 JWT 令牌字符串 + */ String createToken(String subject); - + //刷新用户令牌（通常用于延长令牌有效期）,该方法检查现有令牌的有效期，若即将过期则生成新令牌并更新其过期时间，用户无需重新登录 void refreshToken(UserDetailsDTO userDetailsDTO); - + //续签令牌（可能涉及重新生成令牌或更新令牌关键信息）,与刷新不同，续签可能因安全策略（如密钥轮换）或用户信息变更（如权限更新）而重新生成令牌 void renewToken(UserDetailsDTO userDetailsDTO); - + /** + * 解析 JWT 令牌并获取其声明（Claims）信息,该方法验证令牌的签名有效性，并解析出令牌负载中存储的所有声明（键值对），如用户标识、签发时间、过期时间等 + * @param token 待解析的 JWT 令牌字符串 + * @return Claims 令牌的声明集合对象，可通过其 get() 方法获取具体声明值（如 claims.get("username", String.class)） + */ Claims parseToken(String token); - + /** + * 从 HTTP 请求中提取令牌并解析为完整的用户详情信息 + * 该方法通常从请求头（如 Authorization: Bearer ）或请求参数中提取令牌，然后解析令牌并查询数据库或缓存补全用户详细信息 + * @param request HTTP Servlet 请求对象，用于获取携带令牌的请求头（如 Authorization）或参数（如 access_token） + * @return UserDetailsDTO 用户详情数据传输对象，包含从令牌和系统中获取的完整用户信息（如权限列表、用户状态等） + */ UserDetailsDTO getUserDetailDTO(HttpServletRequest request); - + /** + * 删除（或失效）指定用户的登录状态及相关令牌 + * 该方法通常用于用户主动登出或管理员强制下线，通过移除缓存（如Redis）中的用户令牌映射，使该用户的所有现有令牌立即失效 + * @param userId 用户主键ID，指定要登出的用户标识 + */ void delLoginUser(Integer userId); } diff --git a/aurora-springboot/src/main/java/com/aurora/service/UserAuthService.java b/aurora-springboot/src/main/java/com/aurora/service/UserAuthService.java index 65e89c9..73bb41c 100644 --- a/aurora-springboot/src/main/java/com/aurora/service/UserAuthService.java +++ b/aurora-springboot/src/main/java/com/aurora/service/UserAuthService.java @@ -4,23 +4,23 @@ import com.aurora.model.dto.*; import com.aurora.model.vo.*; import java.util.List; - +//该接口处理用户注册、登录、密码管理、第三方认证和用户信息查询等功能 public interface UserAuthService { - void sendCode(String username); + void sendCode(String username);//向指定用户发送验证码（用于注册、登录或安全操作验证）,该方法发送一次性验证码，并设置有效期和防刷机制 List listUserAreas(ConditionVO conditionVO); - void register(UserVO userVO); + void register(UserVO userVO);// 导入用户值对象（UserVO），用于接收前端传递的用户注册或信息修改参数，通常进行参数校验 - void updatePassword(UserVO userVO); + void updatePassword(UserVO userVO);//返回结果通常按地域分组统计用户数量，支持按时间范围、用户状态等条件筛选 - void updateAdminPassword(PasswordVO passwordVO); + void updateAdminPassword(PasswordVO passwordVO);// 导入密码值对象（PasswordVO），专门用于接收密码修改参数，可能包含旧密码、新密码等敏感信息 PageResultDTO listUsers(ConditionVO condition); - UserLogoutStatusDTO logout(); - - UserInfoDTO qqLogin(QQLoginVO qqLoginVO); + UserLogoutStatusDTO logout();//用户退出登录（清除认证状态和令牌信息),该方法使当前用户的登录状态失效，通常包括清除JWT令牌、会话信息和缓存数据 + //@return UserInfoDTO 用户信息数据传输对象，包含QQ登录成功后获取的用户基本信息 + UserInfoDTO qqLogin(QQLoginVO qqLoginVO);// 导入QQ登录值对象（QQLoginVO），用于接收QQ第三方登录所需的参数，如授权码、OpenID等 } diff --git a/aurora-springboot/src/main/java/com/aurora/service/UserInfoService.java b/aurora-springboot/src/main/java/com/aurora/service/UserInfoService.java index 8556a18..21d98c0 100644 --- a/aurora-springboot/src/main/java/com/aurora/service/UserInfoService.java +++ b/aurora-springboot/src/main/java/com/aurora/service/UserInfoService.java @@ -2,29 +2,33 @@ package com.aurora.service; import com.aurora.model.dto.PageResultDTO; import com.aurora.model.dto.UserInfoDTO; -import com.aurora.model.dto.UserOnlineDTO; +import com.aurora.model.dto.UserOnlineDTO;// 导入在线用户数据传输对象（UserOnlineDTO），用于管理在线用户信息，通常包含会话信息等 import com.aurora.entity.UserInfo; import com.aurora.model.vo.*; import com.baomidou.mybatisplus.extension.service.IService; -import org.springframework.web.multipart.MultipartFile; - +import org.springframework.web.multipart.MultipartFile;// 导入 Spring 的文件上传类，用于处理用户头像等文件上传 +//主要用于处理用户信息的更新、头像管理、邮箱订阅、角色权限和在线用户管理等核心业务 public interface UserInfoService extends IService { void updateUserInfo(UserInfoVO userInfoVO); - + /** + * 更新用户头像（处理图片文件上传并更新头像链接）,该方法接收图片文件，进行格式验证、大小限制检查，然后上传到服务器或云存储 + * @param file 用户上传的头像图片文件（MultipartFile 类型） + * @return String 新头像的访问URL路径,返回新头像的访问路径，便于前端更新显示 + */ String updateUserAvatar(MultipartFile file); void saveUserEmail(EmailVO emailVO); - void updateUserSubscribe(SubscribeVO subscribeVO); + void updateUserSubscribe(SubscribeVO subscribeVO);// 导入订阅值对象（SubscribeVO），用于处理用户订阅相关的参数 - void updateUserRole(UserRoleVO userRoleVO); + void updateUserRole(UserRoleVO userRoleVO);//该方法通常需要权限校验，确保只有管理员可以操作用户角色 - void updateUserDisable(UserDisableVO userDisableVO); + void updateUserDisable(UserDisableVO userDisableVO);//导入用户禁用值对象（UserDisableVO），用于处理用户账户禁用状态参数 PageResultDTO listOnlineUsers(ConditionVO conditionVO); - void removeOnlineUser(Integer userInfoId); + void removeOnlineUser(Integer userInfoId);//强制下线指定用户（根据用户ID移除在线会话）,该方法使指定用户的登录会话立即失效，用户需要重新登录 UserInfoDTO getUserInfoById(Integer id);