接口概述

• 包路径：com.acme.docgen.review
• 接口名称：CodeReviewReportService
• 设计目的：基于静态分析结果生成结构化的代码评审报告，面向技术评审与合规审计。接口提供报告生成、查询、章节标题列出与导出（Markdown/HTML）等能力。包含与报告相关的数据模型定义（项目引用、生成选项、报告、度量、章节、问题、严重级别与导出格式）。

方法列表（按方法名称排序）

1. export(String reportId, ExportFormat format)

• 功能：将指定报告导出为给定格式（Markdown 或 HTML），返回可下载的URL。

2. generate(ProjectRef project, Option option)

• 功能：基于项目引用与规则/展示选项生成评审报告，返回报告ID。

3. get(String reportId)

• 功能：根据报告ID获取完整的报告实体，包含标题、度量、章节与改进建议等信息。

4. listSectionTitles(String reportId)

• 功能：列出指定报告的章节标题列表。

参数说明

• export(String reportId, ExportFormat format)

  • reportId：报告ID。
  • format：导出格式。
    • 枚举 ExportFormat
      • MARKDOWN：导出为Markdown格式。
      • HTML：导出为HTML格式。

• generate(ProjectRef project, Option option)

  • project：项目引用（仓库与提交信息）。
    • 类 ProjectRef
      • gitUrl：Git 仓库地址。
      • commit：提交标识。
      • path：子目录（可选）。
  • option：规则与展示选项。
    • 类 Option
      • ruleSets：规则集列表（例如："naming"、"thread-safety"）。
      • includeSamples：是否在报告中包含示例代码。
      • minimumSeverity：最低严重级别。
        • 枚举 Severity：INFO、MINOR、MAJOR、CRITICAL。

• get(String reportId)

  • reportId：报告ID。

• listSectionTitles(String reportId)

  • reportId：报告ID。

返回值说明

• export(String reportId, ExportFormat format)

  • 返回：String。导出结果的下载URL。

• generate(ProjectRef project, Option option)

  • 返回：String。新生成报告的ID。

• get(String reportId)

  • 返回：ReviewReport。报告实体，包含核心信息。
    • 类 ReviewReport
      • id：报告ID。
      • title：报告标题。
      • metric：度量信息。
        • 类 Metric
          • fileCount：文件数。
          • issueCount：问题数。
          • coverage：覆盖率，取值范围 0.0 ~ 1.0。
      • sections：章节列表。
        • 类 Section
          • heading：章节标题。
          • summary：章节摘要。
          • findings：问题列表。
            • 类 Finding
              • ruleId：规则标识。
              • severity：严重级别（Severity）。
              • location：位置，格式“文件:行号”。
              • advice：修复建议。

• listSectionTitles(String reportId)

  • 返回：List。章节标题列表。

使用示例

• 生成报告并查询详情

import com.acme.docgen.review.CodeReviewReportService;
import com.acme.docgen.review.CodeReviewReportService.Option;
import com.acme.docgen.review.CodeReviewReportService.ProjectRef;
import com.acme.docgen.review.CodeReviewReportService.ReviewReport;
import com.acme.docgen.review.CodeReviewReportService.Severity;
import com.acme.docgen.review.CodeReviewReportService.ExportFormat;

import java.util.Arrays;
import java.util.List;

public class Demo {
    private final CodeReviewReportService service; // 假设已获得实现实例

    public Demo(CodeReviewReportService service) {
        this.service = service;
    }

    public void run() {
        ProjectRef project = new ProjectRef();
        project.gitUrl = "https://example.com/acme/repo.git";
        project.commit = "abc123def456";
        project.path = "module-a"; // 可选

        Option option = new Option();
        option.ruleSets = Arrays.asList("naming", "thread-safety");
        option.includeSamples = true;
        option.minimumSeverity = Severity.MINOR;

        String reportId = service.generate(project, option);

        ReviewReport report = service.get(reportId);
        List<String> titles = service.listSectionTitles(reportId);

        String downloadUrl = service.export(reportId, ExportFormat.MARKDOWN);

        // 使用 report、titles、downloadUrl 进行后续处理
    }
}

注意事项

• ProjectRef.path 为可选字段，用于指定仓库中的子目录。
• Option.minimumSeverity 用于设定最低严重级别阈值。
• Metric.coverage 取值范围为 0.0 至 1.0。
• Finding.location 使用“文件:行号”格式表示问题位置。
• 导出格式受 ExportFormat 枚举限制（MARKDOWN、HTML）。

接口概述

• 接口名称：com.acme.docgen.spec.ApiSpecExtractor
• 类型：Java 接口
• 继承关系：无
• 设计目的：从 Java 源代码解析生成 API 规格，支持规格差异对比、导出为多种格式，以及规格一致性与完整性校验
• 相关模型：
  • ParseRequest：解析请求参数
  • ApiSpec：规格对象
  • Endpoint：规格中的端点定义
  • DiffRequest：对比请求参数
  • Change：变更项
  • ExportFormat：导出格式（MARKDOWN、HTML、OPENAPI_JSON）

方法列表（按名称排序）

• diff(DiffRequest request)
  • 功能：对比两份 API 规格，输出变更列表；列表按“Breaking”优先排序
• export(ApiSpec spec, ExportFormat format)
  • 功能：将 API 规格导出为指定格式，并返回生成文件的下载 URL
• parse(ParseRequest request)
  • 功能：从源码目录解析生成 API 规格对象
• validate(ApiSpec spec)
  • 功能：校验 API 规格的一致性与完整性，返回警告信息列表

参数说明

• diff(DiffRequest request)
  • request.base：基线规格
  • request.head：对比分支规格
  • request.breakingOnly：是否仅返回破坏性变更
• export(ApiSpec spec, ExportFormat format)
  • spec.name：规格名称
  • spec.version：规格版本
  • spec.endpoints：端点列表
  • format：导出格式
    • 可选值：MARKDOWN、HTML、OPENAPI_JSON
• parse(ParseRequest request)
  • request.sourceDir：源码根目录路径
  • request.languageLevel：语言级别（例如 "8"、"11"、"17"）
  • request.includeDeprecated：是否包含标记为 @Deprecated 的元素
  • request.includePackages：需要包含的包名列表（完全限定包名）
• validate(ApiSpec spec)
  • spec.name：规格名称
  • spec.version：规格版本
  • spec.endpoints：端点列表
    • endpoint.method：HTTP 方法（GET/POST/PUT/DELETE）
    • endpoint.path：请求路径
    • endpoint.summary：摘要说明
    • endpoint.requestType：请求类型（FQN）
    • endpoint.responseType：响应类型（FQN）

返回值说明

• parse(ParseRequest request) → ApiSpec
  • name：规格名称
  • version：规格版本
  • endpoints：端点集合
• diff(DiffRequest request) → List
  • 列表按破坏性变更优先排序
  • Change.type：变更类型（Added/Removed/Modified/Deprecated）
  • Change.location：变更位置（端点或字段路径）
  • Change.detail：变更详情描述
  • Change.breaking：是否为破坏性变更
• export(ApiSpec spec, ExportFormat format) → String
  • 返回导出结果的下载 URL
• validate(ApiSpec spec) → List
  • 返回警告信息列表；当未发现问题时可能为空列表

使用示例

import com.acme.docgen.spec.ApiSpecExtractor;
import com.acme.docgen.spec.ApiSpecExtractor.*;

public class Demo {
    public void run(ApiSpecExtractor extractor) {
        // 1) 解析规格
        ParseRequest parseReq = new ParseRequest();
        parseReq.sourceDir = "/path/to/src";
        parseReq.languageLevel = "17";
        parseReq.includeDeprecated = false;
        // 可选：限定包
        // parseReq.includePackages = List.of("com.acme.app.api");
        ApiSpec specV1 = extractor.parse(parseReq);

        // 2) 再次解析（或从其他来源获得）进行对比
        ApiSpec specV2 = extractor.parse(parseReq);

        DiffRequest diffReq = new DiffRequest();
        diffReq.base = specV1;
        diffReq.head = specV2;
        diffReq.breakingOnly = true;
        java.util.List<Change> changes = extractor.diff(diffReq);

        // 3) 导出规格
        String url = extractor.export(specV2, ExportFormat.OPENAPI_JSON);

        // 4) 校验规格
        java.util.List<String> warnings = extractor.validate(specV2);
    }
}

注意事项

• ParseRequest.languageLevel 为字符串形式的语言级别（如 "8"、"11"、"17"）。
• Endpoint.requestType 与 Endpoint.responseType 为类型的完全限定名（FQN）。
• DiffRequest.breakingOnly 为 true 时，仅返回 Change.breaking 为 true 的变更；返回列表按破坏性变更优先排序。
• ExportFormat 取值限于枚举定义的三种格式；export 返回的下载 URL 具体格式未在接口中规定。
• 源码解析基于 ParseRequest.sourceDir 指向的目录；包过滤（includePackages）仅包含指定包及其元素的解析。
• 规格校验（validate）返回警告信息列表，用于提示一致性与完整性问题；错误与异常处理行为未在接口中定义。