Merge pull request #210 from vran-dev/docs

feat: update docs

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)

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`

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  功能也是在该模块内实现 |
 
 模块的依赖关系是一个简单的单向依赖