增加文章导入导出功能

Author: yqz

OpenBlog-business/pom.xml

@@ -91,6 +91,11 @@
             <version>8.5.17</version>
         </dependency>
 
+        <dependency>
+            <groupId>org.yaml</groupId>
+            <artifactId>snakeyaml</artifactId>
+        </dependency>
+
         <dependency>
             <groupId>org.projectlombok</groupId>
             <artifactId>lombok</artifactId>

OpenBlog-business/src/main/java/com/yqz/openblog/article/controller/ArticleImportExportController.java

@@ -0,0 +1,58 @@
+package com.yqz.openblog.article.controller;
+
+import com.yqz.openblog.article.dto.ArticleListItemResponse;
+import com.yqz.openblog.article.service.ArticleImportExportService;
+import com.yqz.openblog.article.service.ArticleImportExportService.ArticleMarkdownExportPayload;
+import com.yqz.openblog.common.ApiResponse;
+import com.yqz.openblog.common.web.ClientIpResolver;
+import com.yqz.openblog.security.CurrentUser;
+import jakarta.servlet.http.HttpServletRequest;
+import org.springframework.http.ContentDisposition;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.web.bind.annotation.*;
+import org.springframework.web.multipart.MultipartFile;
+
+import java.nio.charset.StandardCharsets;
+
+@RestController
+@RequestMapping("/api/v1")
+@CrossOrigin(origins = "*")
+public class ArticleImportExportController {
+
+    private final ArticleImportExportService importExportService;
+    private final CurrentUser currentUser;
+
+    public ArticleImportExportController(ArticleImportExportService importExportService, CurrentUser currentUser) {
+        this.importExportService = importExportService;
+        this.currentUser = currentUser;
+    }
+
+    @PostMapping(value = "/articles/import", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
+    @PreAuthorize("hasAnyRole('ADMIN','AUTHOR')")
+    public ApiResponse<ArticleListItemResponse> importMarkdown(
+            @RequestParam("file") MultipartFile file,
+            @RequestParam(value = "mode", defaultValue = "create") String mode,
+            @RequestParam(value = "articleId", required = false) Long articleId) {
+        Long uid = currentUser.userId();
+        return ApiResponse.ok(importExportService.importMarkdown(uid, file, mode, articleId));
+    }
+
+    @GetMapping(value = "/users/me/articles/{articleId}/export", produces = "text/markdown")
+    @PreAuthorize("hasAnyRole('ADMIN','AUTHOR')")
+    public ResponseEntity<byte[]> exportMarkdown(@PathVariable("articleId") Long articleId,
+                                                 HttpServletRequest request) {
+        Long uid = currentUser.userId();
+        String clientIp = ClientIpResolver.resolve(request);
+        ArticleMarkdownExportPayload payload = importExportService.exportMarkdown(uid, articleId, clientIp);
+        ContentDisposition disposition = ContentDisposition.attachment()
+                .filename(payload.filename(), StandardCharsets.UTF_8)
+                .build();
+        return ResponseEntity.ok()
+                .header(HttpHeaders.CONTENT_DISPOSITION, disposition.toString())
+                .contentType(new MediaType("text", "markdown", StandardCharsets.UTF_8))
+                .body(payload.bytes());
+    }
+}

OpenBlog-business/src/main/java/com/yqz/openblog/article/io/ArticleMarkdownDocument.java

@@ -0,0 +1,53 @@
+package com.yqz.openblog.article.io;
+
+/**
+ * 从 .md 解析或导出前的文章 Markdown 文档模型。
+ */
+public class ArticleMarkdownDocument {
+
+    private String title;
+    private String summary;
+    private Long categoryId;
+    private String coverMediaKey;
+    private String contentMarkdown;
+
+    public String getTitle() {
+        return title;
+    }
+
+    public void setTitle(String title) {
+        this.title = title;
+    }
+
+    public String getSummary() {
+        return summary;
+    }
+
+    public void setSummary(String summary) {
+        this.summary = summary;
+    }
+
+    public Long getCategoryId() {
+        return categoryId;
+    }
+
+    public void setCategoryId(Long categoryId) {
+        this.categoryId = categoryId;
+    }
+
+    public String getCoverMediaKey() {
+        return coverMediaKey;
+    }
+
+    public void setCoverMediaKey(String coverMediaKey) {
+        this.coverMediaKey = coverMediaKey;
+    }
+
+    public String getContentMarkdown() {
+        return contentMarkdown;
+    }
+
+    public void setContentMarkdown(String contentMarkdown) {
+        this.contentMarkdown = contentMarkdown;
+    }
+}

OpenBlog-business/src/main/java/com/yqz/openblog/article/io/ArticleMarkdownExporter.java

@@ -0,0 +1,73 @@
+package com.yqz.openblog.article.io;
+
+import com.yqz.openblog.article.dto.ArticleDetailResponse;
+
+/**
+ * 将文章详情序列化为带 YAML Front Matter 的 Markdown 文件内容。
+ */
+public final class ArticleMarkdownExporter {
+
+    private ArticleMarkdownExporter() {
+    }
+
+    public static byte[] toBytes(ArticleDetailResponse detail) {
+        StringBuilder sb = new StringBuilder();
+        sb.append("---\n");
+        sb.append("title: ").append(yamlQuote(detail.getTitle())).append('\n');
+        if (detail.getSummary() != null && !detail.getSummary().isBlank()) {
+            sb.append("summary: ").append(yamlQuote(detail.getSummary())).append('\n');
+        }
+        if (detail.getCategoryId() != null) {
+            sb.append("categoryId: ").append(detail.getCategoryId()).append('\n');
+        }
+        if (detail.getCoverMediaKey() != null && !detail.getCoverMediaKey().isBlank()) {
+            sb.append("coverMediaKey: ").append(yamlQuote(detail.getCoverMediaKey())).append('\n');
+        }
+        if (detail.getId() != null) {
+            sb.append("openblogId: ").append(detail.getId()).append('\n');
+        }
+        if (detail.getPublishedAt() != null) {
+            sb.append("publishedAt: ").append(yamlQuote(detail.getPublishedAt().toString())).append('\n');
+        }
+        sb.append("---\n\n");
+        String body = detail.getContentMarkdown() == null ? "" : detail.getContentMarkdown();
+        sb.append(body);
+        if (!body.endsWith("\n")) {
+            sb.append('\n');
+        }
+        return sb.toString().getBytes(java.nio.charset.StandardCharsets.UTF_8);
+    }
+
+    public static String suggestedFilename(ArticleDetailResponse detail) {
+        Long id = detail.getId();
+        String title = detail.getTitle();
+        String base;
+        if (title == null || title.isBlank()) {
+            base = "article-" + (id == null ? "export" : id);
+        } else {
+            base = title.trim();
+        }
+        base = base.replaceAll("[\\\\/:*?\"<>|]", "-").replaceAll("\\s+", " ").strip();
+        if (base.isEmpty()) {
+            base = "article-" + (id == null ? "export" : id);
+        }
+        if (base.length() > 80) {
+            base = base.substring(0, 80).strip();
+        }
+        return base + ".md";
+    }
+
+    private static String yamlQuote(String value) {
+        if (value == null) {
+            return "\"\"";
+        }
+        boolean needQuote = value.contains(":") || value.contains("#")
+                || value.startsWith(" ") || value.endsWith(" ")
+                || value.contains("\n") || value.contains("\"");
+        if (!needQuote) {
+            return value;
+        }
+        String escaped = value.replace("\\", "\\\\").replace("\"", "\\\"");
+        return "\"" + escaped + "\"";
+    }
+}

OpenBlog-business/src/main/java/com/yqz/openblog/article/io/ArticleMarkdownImporter.java

@@ -0,0 +1,152 @@
+package com.yqz.openblog.article.io;
+
+import com.yqz.openblog.common.BizException;
+import org.yaml.snakeyaml.LoaderOptions;
+import org.yaml.snakeyaml.Yaml;
+import org.yaml.snakeyaml.constructor.SafeConstructor;
+
+import java.nio.charset.StandardCharsets;
+import java.util.Map;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/**
+ * 将 .md 文件文本解析为 {@link ArticleMarkdownDocument}。
+ */
+public final class ArticleMarkdownImporter {
+
+    private static final Pattern FIRST_H1 = Pattern.compile("(?m)^#\\s+(.+?)\\s*$");
+    private static final int MAX_TITLE_LEN = 120;
+    private static final int MAX_SUMMARY_LEN = 255;
+
+    private ArticleMarkdownImporter() {
+    }
+
+    public static ArticleMarkdownDocument parse(byte[] bytes, String originalFilename) {
+        if (bytes == null || bytes.length == 0) {
+            throw new BizException(4002, "Markdown 文件为空");
+        }
+        String raw = stripBom(new String(bytes, StandardCharsets.UTF_8));
+        String normalized = raw.replace("\r\n", "\n").replace('\r', '\n');
+
+        String frontMatter = null;
+        String body;
+        if (normalized.startsWith("---")) {
+            int close = normalized.indexOf("\n---", 3);
+            if (close > 0) {
+                frontMatter = normalized.substring(3, close).trim();
+                body = normalized.substring(close + 4);
+                if (body.startsWith("\n")) {
+                    body = body.substring(1);
+                }
+            } else {
+                body = normalized;
+            }
+        } else {
+            body = normalized;
+        }
+
+        ArticleMarkdownDocument doc = new ArticleMarkdownDocument();
+        if (frontMatter != null && !frontMatter.isBlank()) {
+            applyFrontMatter(doc, frontMatter);
+        }
+
+        String content = body == null ? "" : body.strip();
+        doc.setContentMarkdown(content);
+
+        if (doc.getTitle() == null || doc.getTitle().isBlank()) {
+            doc.setTitle(inferTitle(content, originalFilename));
+        }
+        doc.setTitle(trimTo(doc.getTitle().trim(), MAX_TITLE_LEN));
+
+        if (doc.getSummary() != null) {
+            doc.setSummary(trimTo(doc.getSummary().trim(), MAX_SUMMARY_LEN));
+        }
+
+        if (doc.getTitle().isEmpty()) {
+            throw new BizException(4002, "无法解析文章标题，请在 Front Matter 中设置 title 或使用 # 标题");
+        }
+        if (content.isEmpty()) {
+            throw new BizException(4002, "Markdown 正文不能为空");
+        }
+        return doc;
+    }
+
+    private static void applyFrontMatter(ArticleMarkdownDocument doc, String yamlBlock) {
+        LoaderOptions options = new LoaderOptions();
+        Yaml yaml = new Yaml(new SafeConstructor(options));
+        Object loaded = yaml.load(yamlBlock);
+        if (!(loaded instanceof Map<?, ?> map)) {
+            return;
+        }
+        Object title = map.get("title");
+        if (title != null) {
+            doc.setTitle(String.valueOf(title).trim());
+        }
+        Object summary = map.get("summary");
+        if (summary != null) {
+            doc.setSummary(String.valueOf(summary).trim());
+        }
+        Object categoryId = map.get("categoryId");
+        if (categoryId != null) {
+            doc.setCategoryId(parseLong(categoryId));
+        }
+        Object cover = map.get("coverMediaKey");
+        if (cover != null) {
+            String key = String.valueOf(cover).trim();
+            if (!key.isEmpty()) {
+                doc.setCoverMediaKey(trimTo(key, 64));
+            }
+        }
+    }
+
+    private static Long parseLong(Object value) {
+        if (value instanceof Number n) {
+            return n.longValue();
+        }
+        String s = String.valueOf(value).trim();
+        if (s.isEmpty()) {
+            return null;
+        }
+        try {
+            return Long.parseLong(s);
+        } catch (NumberFormatException ex) {
+            throw new BizException(4002, "Front Matter 中 categoryId 无效");
+        }
+    }
+
+    private static String inferTitle(String body, String originalFilename) {
+        Matcher m = FIRST_H1.matcher(body);
+        if (m.find()) {
+            return m.group(1).trim();
+        }
+        if (originalFilename != null && !originalFilename.isBlank()) {
+            String name = originalFilename.trim();
+            int slash = Math.max(name.lastIndexOf('/'), name.lastIndexOf('\\'));
+            if (slash >= 0) {
+                name = name.substring(slash + 1);
+            }
+            if (name.toLowerCase().endsWith(".md")) {
+                name = name.substring(0, name.length() - 3);
+            }
+            if (!name.isBlank()) {
+                return name.trim();
+            }
+        }
+        return "";
+    }
+
+    private static String stripBom(String s) {
+        if (s != null && !s.isEmpty() && s.charAt(0) == '\uFEFF') {
+            return s.substring(1);
+        }
+        return s;
+    }
+
+    private static String trimTo(String s, int max) {
+        if (s.length() <= max) {
+            return s;
+        }
+        return s.substring(0, max);
+    }
+}