docs 补充项目注释

2026-06-01 13:58:13 +08:00
parent 107d3326b4
commit e49f3b2260
94 changed files with 2328 additions and 68 deletions
@@ -12,9 +12,22 @@ import lombok.NoArgsConstructor;
@Data
@NoArgsConstructor
 public class PriorityDemo implements Comparable<PriorityDemo> {
+    /**
+     * 队列元素名称。
+     */
    private String name;
+
+    /**
+     * 优先级排序值。
+     */
    private Integer orderNum;

+    /**
+     * 按排序值比较优先级。
+     *
+     * @param other 另一个队列元素
+     * @return 比较结果
+     */
    @Override
    public int compareTo(PriorityDemo other) {
        return Integer.compare(getOrderNum(), other.getOrderNum());
@@ -18,11 +18,20 @@ import java.util.List;
 */
 public class ExportDemoListener extends DefaultExcelListener<ExportDemoVo> {

+    /**
+     * 创建下拉框导入解析监听器。
+     */
    public ExportDemoListener() {
        // 显示使用构造函数，否则将导致空指针
        super(true);
    }

+    /**
+     * 解析并校验一行下拉框演示数据。
+     *
+     * @param data 行数据
+     * @param context 解析上下文
+     */
    @Override
    public void invoke(ExportDemoVo data, AnalysisContext context) {
        // 先校验必填
@@ -23,12 +23,26 @@ import java.util.List;
 */
 public interface TestDemoMapper extends BaseMapperPlus<TestDemo, TestDemoVo> {

+    /**
+     * 自定义分页查询演示数据。
+     *
+     * @param page 分页对象
+     * @param wrapper 查询条件
+     * @return 分页结果
+     */
    @DataPermission({
        @DataColumn(key = "deptName", value = "dept_id"),
        @DataColumn(key = "userName", value = "user_id")
    })
    Page<TestDemoVo> customPageList(@Param("page") Page<TestDemo> page, @Param("ew") Wrapper<TestDemo> wrapper);

+    /**
+     * 分页查询演示 VO 列表并应用数据权限。
+     *
+     * @param page 分页对象
+     * @param wrapper 查询条件
+     * @return 分页结果
+     */
    @Override
    @DataPermission({
        @DataColumn(key = "deptName", value = "dept_id"),
@@ -38,6 +52,12 @@ public interface TestDemoMapper extends BaseMapperPlus<TestDemo, TestDemoVo> {
        return selectVoPage(page, wrapper, this.currentVoClass());
    }

+    /**
+     * 查询演示 VO 列表并应用数据权限。
+     *
+     * @param wrapper 查询条件
+     * @return 演示 VO 列表
+     */
    @Override
    @DataPermission({
        @DataColumn(key = "deptName", value = "dept_id"),
@@ -47,6 +67,12 @@ public interface TestDemoMapper extends BaseMapperPlus<TestDemo, TestDemoVo> {
        return selectVoList(wrapper, this.currentVoClass());
    }

+    /**
+     * 按主键集合查询演示数据并应用数据权限。
+     *
+     * @param idList 主键集合
+     * @return 演示数据列表
+     */
    @Override
    @DataPermission(value = {
        @DataColumn(key = "deptName", value = "dept_id"),
@@ -54,6 +80,12 @@ public interface TestDemoMapper extends BaseMapperPlus<TestDemo, TestDemoVo> {
    }, joinStr = "AND")
    List<TestDemo> selectByIds(@Param(Constants.COLL) Collection<? extends Serializable> idList);

+    /**
+     * 按主键更新演示数据并应用数据权限。
+     *
+     * @param entity 演示数据实体
+     * @return 更新行数
+     */
    @Override
    @DataPermission({
        @DataColumn(key = "deptName", value = "dept_id"),
@@ -1,9 +1,9 @@
 package org.dromara.demo.mcp;

+import lombok.RequiredArgsConstructor;
 import org.dromara.common.mcp.core.McpClientTemplate;
 import org.dromara.common.mcp.core.McpResourceReadResult;
 import org.dromara.common.mcp.core.McpToolCallResult;
-import lombok.RequiredArgsConstructor;
 import org.springframework.beans.factory.ObjectProvider;
 import org.springframework.stereotype.Service;

@@ -42,7 +42,7 @@ public class McpDemoClientService {
    /**
     * 调用外部 MCP 工具接收数据。
     *
-     * @param toolName 工具名称
+     * @param toolName  工具名称
     * @param arguments 工具参数
     * @return 工具返回内容
     */
@@ -65,7 +65,7 @@ public class McpDemoClientService {
     * <p>
     * MCP 返回数据不建议直接入库，应先转换成业务 BO/DTO，再进入业务 Service。
     *
-     * @param toolName 工具名称
+     * @param toolName  工具名称
     * @param arguments 工具参数
     * @return 处理结果
     */
@@ -73,6 +73,13 @@ public class McpDemoClientService {
        return new McpDemoHandleResult("MCP", true, callRemoteTool(toolName, arguments));
    }

+    /**
+     * 执行 MCP Client 操作。
+     *
+     * @param action MCP Client 操作
+     * @param <T>    返回值类型
+     * @return 操作结果
+     */
    private <T> T execute(Function<McpClientTemplate, T> action) {
        McpClientTemplate template = mcpClientTemplateProvider.getIfAvailable();
        if (template == null) {
@@ -85,8 +92,8 @@ public class McpDemoClientService {
     * MCP 数据处理结果。
     *
     * @param sourceType 数据来源类型
-     * @param handled 是否已处理
-     * @param data MCP 原始返回数据
+     * @param handled    是否已处理
+     * @param data       MCP 原始返回数据
     */
    public record McpDemoHandleResult(
        String sourceType,
@@ -28,6 +28,11 @@ import java.util.Map;
@RequiredArgsConstructor
 public class ExportExcelServiceImpl implements IExportExcelService {

+    /**
+     * 导出带下拉框选项的 Excel 示例文件。
+     *
+     * @param response HTTP 响应
+     */
    @Override
    public void exportWithOptions(HttpServletResponse response) {
        // 创建表格数据，业务中一般通过数据库查询
@@ -106,6 +111,13 @@ public class ExportExcelServiceImpl implements IExportExcelService {
            .toResponse(response);
    }

+    /**
+     * 构建下拉框显示值。
+     *
+     * @param cityDataList 城市演示数据列表
+     * @param id 选项 id
+     * @return 下拉框显示值
+     */
    private String buildOptions(List<DemoCityData> cityDataList, Integer id) {
        Map<Integer, List<DemoCityData>> groupByIdMap =
            StreamUtils.groupByKey(cityDataList, DemoCityData::getId);
@@ -246,6 +258,11 @@ public class ExportExcelServiceImpl implements IExportExcelService {
    }


+    /**
+     * 自定义写入多个工作表。
+     *
+     * @param response HTTP 响应
+     */
    @Override
    public void customExport(HttpServletResponse response) {
        ExcelBuilder.writer(ExportDemoVo.class).sheetName("自定义导出").toResponse(response, wrapper -> {