diff --git a/docs/develop/_sidebar.md b/docs/develop/_sidebar.md index f856971..dd2fe16 100644 --- a/docs/develop/_sidebar.md +++ b/docs/develop/_sidebar.md @@ -1,5 +1,8 @@ * 构建指南 - * [后端构建](/develop/build/index.md) + * [项目构建](/develop/build/index.md) + +* 系统扩展 + * [如何扩展文件导出类型?](/develop/how-to-add-export-type/index.md) * 系统架构 * [模块和包](/develop/module-and-package/index.md) diff --git a/docs/develop/how-to-add-export-type/index.md b/docs/develop/how-to-add-export-type/index.md new file mode 100644 index 0000000..3c5ab06 --- /dev/null +++ b/docs/develop/how-to-add-export-type/index.md @@ -0,0 +1,132 @@ +# 如何扩展导出文件类型? + +> Note: 本节内容默认读者有 Java 开发能力 + +## 实现步骤 + +### 一、扩展文件类型 + +在 `com.databasir.core.domain.document.generator.DocumentFileType` 中新增文件类型 + +```java +@AllArgsConstructor +@Getter +public enum DocumentFileType { + + MARKDOWN("md", "Markdown"), + + PLANT_UML_ER_SVG("svg", "UML SVG"), + + PLANT_UML_ER_PNG("png", "UML PNG"), + ; + + private String fileExtension; + + private String name; + +} +``` + +`DocumentFilType` 是一个枚举类型,构造器需要传入两个参数 + +| 名称 | 说明 | | +| ------------- | ------------------------------------------------------------ | ---- | +| fileExtension | 代表导出文件的后缀,用户导出项目文件时系统会使用 `项目名 + "." + {{fileExtension}}` 去命名文件 | | +| name | 展示给用户的标签 | | + +比如我现在要新增一个 excel 格式的导出类型,那么新增一个枚举值 `EXCEL` + +```java +@AllArgsConstructor +@Getter +public enum DocumentFileType { + + MARKDOWN("md", "Markdown"), + + PLANT_UML_ER_SVG("svg", "UML SVG"), + + PLANT_UML_ER_PNG("png", "UML PNG"), + + EXCEL("xlsx", "Excel") + ; + + private String fileExtension; + + private String name; + +} +``` + + + +### 二、实现文件生成逻辑 + +接下来就是定义一个类,该类需要实现接口 `com.databasir.core.domain.document.generator.DocumentFileGenerator` + +```java +public interface DocumentFileGenerator { + + boolean support(DocumentFileType type); + + void generate(DocumentFileGenerateContext context, OutputStream outputStream); + + @Getter + @Builder + class DocumentFileGenerateContext { + + @NonNull + private DocumentFileType documentFileType; + + @NonNull + private DatabaseDocumentResponse databaseDocument; + + } +} +``` + +其中 + +- support 方法标识该类支持生成的文件类型 +- generate 是具体的生成逻辑 + +继续完善的 excel 导出的扩展,记住实现类一定要加上spring 的 `@Component` 注解,不然 [Databasir](https://github.com/vran-dev/databasir) 无法找到该实现类 + +```java +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.springframework.stereotype.Component; + +@Component +@Slf4j +@RequiredArgsConstructor +public class MarkdownDocumentFileGenerator implements DocumentFileGenerator { + + @Override + public boolean support(DocumentFileType type) { + // 这里表示该实现类是支持 EXCEL 格式导出的 + return type == DocumentFileType.EXCEL; + } + + @Override + public void generate(DocumentFileGenerateContext context, OutputStream outputStream) { + Path path = .... // excel path + byte[] bytes = Files.readAllBytes(path); + // 将文件的字节流通过 stream 写出即可 + outputStream.write(bytes) + } +} +``` + + + + + +## 示例 + +[Databasir](https://github.com/vran-dev/databasir) 目前已经提供了 markdown、png、svg 三种格式的文件导出,其中 png 和 svg 文件是基于 plantuml 导出的实体关系图。 + +对应的源码如下,读者可以参考 + +- SVG:`com.databasir.core.domain.document.generator.plantuml.PlantUmlErSvgFileGenerator` +- PNG:`com.databasir.core.domain.document.generator.plantuml.PlantUmlPngFileGenerator` +- Markdown:`com.databasir.core.domain.document.generator.MarkdownDocumentFileGenerator` \ No newline at end of file diff --git a/docs/develop/module-and-package/index.md b/docs/develop/module-and-package/index.md index 52d7eaa..94102a8 100644 --- a/docs/develop/module-and-package/index.md +++ b/docs/develop/module-and-package/index.md @@ -2,13 +2,13 @@ Databasir 基于 Gradle 进行模块管理,当前共有 5 个模块 -| 模块名称 | 职责 | -| -------- | ------------------------------------------------------------ | -| api | 所有的接口和定时任务均在该模块定义 | -| common | 定义了项目通用的类,比如加解密工具、业务异常、标准 HTTP 返回类型等 | -| core | 核心业务模块,包含了所有的业务逻辑 | -| dao | 数据访问层,包含了数据库的实体、数据访问对象以及项目模型的 SQL 文件 | -| plugin | jdbc 封装模块,将从 jdbc 获取的数据库元信息转换成 Databasir 的 Java 对象,文档信息的 DIFF 功能也是在该模块内实现 | +| 模块名称 | 职责 | +|---------------| ------------------------------------------------------------ | +| api | 所有的接口和定时任务均在该模块定义 | +| common | 定义了项目通用的类,比如加解密工具、业务异常、标准 HTTP 返回类型等 | +| core | 核心业务模块,包含了所有的业务逻辑 | +| dao | 数据访问层,包含了数据库的实体、数据访问对象以及项目模型的 SQL 文件 | +| meta(原plugin) | jdbc 封装模块,将从 jdbc 获取的数据库元信息转换成 Databasir 的 Java 对象,文档信息的 DIFF 功能也是在该模块内实现 | 模块的依赖关系是一个简单的单向依赖