1. 项目概述：为什么后端存储富文本是个“技术活”？

刚入行那会儿，接到一个需求：做一个带图文混排的文章发布功能。前端同学很快用富文本编辑器搞定了界面，数据一提交，我这边就傻眼了。前端传过来的不是简单的字符串，而是一大段混杂着<img src="data:image/png;base64,...">这种Base64图片的HTML代码。直接往数据库的TEXT字段里一塞？图片数据动辄几百KB，一条记录就爆了，数据库性能瞬间拉胯，页面加载慢如蜗牛。这才深刻体会到，“存储富文本”远不止是存一段文本那么简单，它本质上是一个涉及内容安全、性能优化、资源管理和前后端协作的系统工程。

所谓富文本，就是带有格式（如加粗、斜体、颜色）和嵌入式资源（主要是图片）的文本内容。在后端视角下，我们面对的核心挑战有两个：一是如何安全、高效地持久化这段结构化的HTML；二是如何妥善处理内嵌的图片资源。前者关乎数据的一致性与检索，后者则直接影响到应用的存储成本、访问速度和可维护性。Spring Boot作为Java领域最流行的全栈框架，其生态提供了从数据接入、业务处理到资源管理的完整解决方案链。这个项目，就是要把这条链跑通，构建一个健壮、可扩展的富文本内容存储后端。

2. 整体架构设计与核心思路拆解

面对富文本存储，尤其是带图片的，我们不能简单地把它看成一个“保存”动作。我们需要一个清晰的分层处理模型。核心思路是：“内容与资源分离，异步处理，统一管理”。

2.1 核心流程与职责划分

整个处理流程始于用户在前端富文本编辑器（如wangEditor、Tinymce）中的编辑操作。当用户点击发布时，一段包含图片<img>标签的HTML字符串将被提交到后端。后端的工作流可以分解为以下几个关键阶段：

1. 请求接收与解析：Spring MVC控制器接收包含富文本HTML的请求参数。
2. 图片提取与上传：这是最核心的一步。后端需要从HTML字符串中解析出所有的图片标签。这些图片可能以两种形式存在：
   • Base64内联图片：形如<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...">。这是编辑器为了即时预览而生成的，数据庞大，必须将其转换为独立的图片文件。
   • 远程图片URL：如果编辑器支持粘贴网络图片，可能会包含外部链接。出于版权和稳定性考虑，通常也需要将其下载并存储到自己的系统中（即“图片爬取”或“资源化”）。
3. 资源存储：将提取出的图片文件上传到专用的文件存储服务。这里有几个主流选择：
   • 本地磁盘：最简单，使用Spring的MultipartFile和java.nio.file包即可。但存在单点故障、扩容困难、备份麻烦等问题，不适合生产环境。
   • 分布式文件系统（如FastDFS、HDFS）：适合大型互联网公司，自建维护成本高。
   • 对象存储服务（如阿里云OSS、腾讯云COS、七牛云Kodo）：当前的主流和推荐方案。它们提供海量、安全、低成本、高可用的存储服务，并自带CDN加速、图片处理（缩略图、水印）等能力。通过其提供的SDK，可以轻松实现文件上传、下载和管理。
4. 内容转义与存储：将原始HTML中的图片src属性，从Base64数据或临时URL，替换为上一步返回的永久访问URL（通常是对象存储提供的CDN链接）。然后，将处理后的“纯净”HTML字符串存储到数据库中。这里需要对HTML进行必要的转义或清洗，防止XSS攻击。
5. 内容读取与渲染：当需要展示内容时，直接从数据库读取HTML字符串，返回给前端。前端无需做任何额外处理，因为里面的图片链接已经是可公开访问的稳定URL了。

2.2 技术栈选型考量

• Spring Boot Web：提供RESTful API端点，处理HTTP请求。
• Spring Data JPA / MyBatis-Plus：用于操作数据库，存储处理后的富文本内容。字段类型通常选用LONGTEXT或CLOB。
• Jsoup：一个优秀的Java HTML解析库。我们将用它来解析提交的HTML，提取、操作<img>标签，替换src属性。它比正则表达式更稳定、安全。
• 阿里云OSS SDK / 腾讯云COS SDK：根据选择的云服务商引入对应的官方SDK，用于文件上传、下载等操作。
• 数据库：MySQL/PostgreSQL。单独创建一张表（如article_content）来存储富文本，与文章元信息（标题、作者、时间）分开，符合设计规范。

注意：绝对不要将Base64图片直接存入数据库的文本字段。这会导致数据行巨大，严重影响数据库的查询性能、备份效率和网络传输。数据库应专注于存储结构化数据和“引用”，而非二进制大对象。

3. 核心细节解析与实操要点

3.1 富文本内容的安全处理与数据库设计

接收到的富文本HTML直接存储是危险的，因为它可能包含恶意脚本（XSS攻击）。虽然前端编辑器可能有一定过滤，但后端必须进行二次清洗。

1. 使用Jsoup进行HTML清洗与转义：

import org.jsoup.Jsoup; import org.jsoup.safety.Safelist; public class HtmlUtils { /** * 使用Jsoup的白名单机制清洗HTML，只允许安全的标签和属性。 * 这是防止XSS攻击的关键一步。 */ public static String clean(String html) { if (html == null) return ""; // 定义白名单。这里以文章内容为例，允许常见的文本格式和图片标签。 Safelist safelist = Safelist.relaxed() .addTags("div", "span", "section") // 添加额外允许的标签 .addAttributes("img", "style") // 允许img标签有style属性 .addProtocols("img", "src", "http", "https", "data"); // 允许src为http/https和data协议（用于后续提取） // 清理HTML String cleanHtml = Jsoup.clean(html, safelist); // 进一步，我们可以选择转义所有标签属性值中的引号，增加安全性 // 但Jsoup.clean已经做了很好的处理。 return cleanHtml; } }

在控制器接收参数后，首先调用HtmlUtils.clean()方法对原始HTML进行清洗。

2. 数据库表设计：

CREATE TABLE `article_content` ( `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键ID', `article_id` bigint(20) NOT NULL COMMENT '关联的文章ID', `content` longtext NOT NULL COMMENT '清洗并处理后的富文本HTML内容', `create_time` datetime DEFAULT CURRENT_TIMESTAMP, `update_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, PRIMARY KEY (`id`), KEY `idx_article_id` (`article_id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='文章富文本内容表';

使用utf8mb4字符集以支持完整的Unicode（如表情符号）。LONGTEXT类型在MySQL中最多可存储约4GB文本，完全足够。

3.2 图片提取、上传与URL替换策略

这是整个流程的引擎。我们的目标是：遍历HTML中的所有<img>标签，将src属性中的Base64数据或临时网络图片，替换为云存储的永久URL。

1. 图片提取与上传服务实现：首先，我们需要一个服务，它接收清洗后的HTML，负责图片处理并返回处理后的HTML。

@Service @Slf4j public class RichTextService { @Autowired private CloudStorageService cloudStorageService; // 云存储服务封装 /** * 处理富文本内容，上传其中的图片并替换URL * @param htmlContent 清洗后的原始HTML * @return 处理后的HTML（图片src已替换为云存储URL） */ public String processRichText(String htmlContent) { if (StringUtils.isBlank(htmlContent)) { return htmlContent; } // 使用Jsoup将HTML解析为Document对象，便于DOM操作 Document doc = Jsoup.parse(htmlContent); // 选择所有的img标签 Elements imgElements = doc.select("img"); for (Element img : imgElements) { String src = img.attr("src"); if (StringUtils.isBlank(src)) { continue; } String newUrl; // 判断是否为Base64图片 if (src.startsWith("data:image")) { newUrl = uploadBase64Image(src); } // 可选：判断是否为需要抓取的网络图片（可根据域名白名单过滤） // else if (src.startsWith("http://") || src.startsWith("https://")) { // newUrl = uploadNetworkImage(src); // } else { // 如果不是Base64也不是需要处理的网络图片，则跳过（可能是已经处理过的云存储URL） continue; } // 如果上传成功，替换src属性 if (newUrl != null) { img.attr("src", newUrl); log.info("图片替换成功，新URL: {}", newUrl); } else { // 上传失败，可以选择移除该图片标签或保留原src（不推荐） img.remove(); log.warn("图片上传失败，已移除标签，原src: {}", src); } } // 返回处理后的HTML字符串。body().html()获取body内的html，如果原始内容就是完整HTML，可以用doc.html() return doc.body().html(); } /** * 上传Base64格式的图片到云存储 * @param base64Data data:image/png;base64,iVBORw0KGgoAAA... * @return 云存储的访问URL，失败返回null */ private String uploadBase64Image(String base64Data) { try { // 1. 解析Base64数据头，获取MIME类型和纯数据部分 String[] parts = base64Data.split(","); String header = parts[0]; // data:image/png;base64 String data = parts[1]; // 实际的Base64编码字符串 String mimeType = header.split(";")[0].split(":")[1]; // image/png // 2. 将Base64字符串解码为字节数组 byte[] imageBytes = Base64.getDecoder().decode(data); // 3. 根据MIME类型确定文件扩展名 String fileExtension = getFileExtensionFromMimeType(mimeType); // 生成一个唯一的文件名，防止冲突。例如：UUID + 扩展名 String fileName = UUID.randomUUID().toString().replace("-", "") + fileExtension; // 4. 调用云存储服务上传字节数组 // CloudStorageService.upload(byte[] bytes, String fileName) 返回访问URL return cloudStorageService.upload(imageBytes, fileName); } catch (Exception e) { log.error("Base64图片上传失败", e); return null; } } private String getFileExtensionFromMimeType(String mimeType) { switch (mimeType) { case "image/jpeg": return ".jpg"; case "image/png": return ".png"; case "image/gif": return ".gif"; case "image/webp": return ".webp"; case "image/bmp": return ".bmp"; default: return ".dat"; // 未知类型 } } }

2. 云存储服务封装（以阿里云OSS为例）：

@Component @Slf4j public class AliyunOssService implements CloudStorageService { @Value("${oss.endpoint}") private String endpoint; @Value("${oss.accessKeyId}") private String accessKeyId; @Value("${oss.accessKeySecret}") private String accessKeySecret; @Value("${oss.bucketName}") private String bucketName; @Value("${oss.baseUrl}") private String baseUrl; // 绑定的自定义域名或OSS默认域名 private OSS ossClient; @PostConstruct public void init() { ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret); } @PreDestroy public void shutdown() { if (ossClient != null) { ossClient.shutdown(); } } @Override public String upload(byte[] bytes, String fileName) { try { // 可以在这里添加目录结构，如按日期归档：`images/2024/05/17/filename.jpg` String objectName = "rich-text/" + LocalDate.now().format(DateTimeFormatter.ofPattern("yyyy/MM/dd")) + "/" + fileName; // 创建上传请求 PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, objectName, new ByteArrayInputStream(bytes)); // 可选：设置对象元信息或ACL // ObjectMetadata metadata = new ObjectMetadata(); // metadata.setContentType("image/jpeg"); // putObjectRequest.setMetadata(metadata); // 上传文件 ossClient.putObject(putObjectRequest); // 返回文件的完整访问URL。如果配置了CDN或自定义域名，用baseUrl拼接 return baseUrl + "/" + objectName; } catch (Exception e) { log.error("OSS上传文件失败: {}", fileName, e); throw new RuntimeException("文件上传失败", e); } } }

在application.yml中配置：

oss: endpoint: oss-cn-hangzhou.aliyuncs.com accessKeyId: your-access-key-id accessKeySecret: your-access-key-secret bucketName: your-bucket-name baseUrl: https://cdn.yourdomain.com # 建议使用自定义域名绑定CDN

3.3 控制器与完整业务逻辑串联

最后，在控制器中串联所有步骤：

@RestController @RequestMapping("/api/article") public class ArticleController { @Autowired private RichTextService richTextService; @Autowired private ArticleService articleService; @PostMapping("/save") public ApiResult saveArticle(@RequestBody ArticleSaveDTO dto) { // 1. 安全清洗HTML String cleanHtml = HtmlUtils.clean(dto.getContent()); // 2. 处理图片，上传并替换URL String processedHtml = richTextService.processRichText(cleanHtml); // 3. 保存到数据库 (ArticleService负责将processedHtml存入article_content表) Long articleId = articleService.saveContent(processedHtml, dto.getTitle(), dto.getAuthor()); return ApiResult.success(articleId); } @GetMapping("/{id}/content") public ApiResult getContent(@PathVariable Long id) { // 直接从数据库读取处理后的HTML，无需任何处理，直接返回给前端 String htmlContent = articleService.getContentById(id); return ApiResult.success(htmlContent); } }

4. 实操过程与核心环节实现详解

4.1 环境搭建与依赖引入

首先创建一个Spring Boot项目（使用Spring Initializr或IDE直接创建），选择必要的依赖：

• Spring Web：用于构建Web API。
• Spring Data JPA：简化数据库操作（也可选MyBatis-Plus）。
• MySQL Driver：数据库驱动。
• Lombok：简化实体类代码（可选但推荐）。

然后，在pom.xml中手动添加核心工具库：

<!-- Jsoup HTML解析 --> <dependency> <groupId>org.jsoup</groupId> <artifactId>jsoup</artifactId> <version>1.17.2</version> </dependency> <!-- 阿里云OSS SDK --> <dependency> <groupId>com.aliyun.oss</groupId> <artifactId>aliyun-sdk-oss</artifactId> <version>3.17.4</version> </dependency> <!-- Apache Commons Lang3 用于字符串等工具 --> <dependency> <groupId>org.apache.commons</groupId> <artifactId>commons-lang3</artifactId> <version>3.14.0</version> </dependency>

4.2 核心服务类逐行解读与配置

1. 图片上传的异步优化：上面的RichTextService是同步处理的，如果一篇文章有10张图，每张图上传耗时1秒，用户就要等待10秒。这是不可接受的。我们必须引入异步处理。

@Service @Slf4j public class AsyncRichTextService { @Autowired private CloudStorageService cloudStorageService; @Autowired private ThreadPoolTaskExecutor taskExecutor; // 注入Spring管理的线程池 public CompletableFuture<String> processRichTextAsync(String htmlContent) { if (StringUtils.isBlank(htmlContent)) { return CompletableFuture.completedFuture(htmlContent); } Document doc = Jsoup.parse(htmlContent); Elements imgElements = doc.select("img"); List<CompletableFuture<Void>> futures = new ArrayList<>(); for (Element img : imgElements) { String src = img.attr("src"); if (!src.startsWith("data:image")) { continue; } // 为每张图片上传任务创建一个异步Future CompletableFuture<Void> future = CompletableFuture.runAsync(() -> { String newUrl = uploadBase64Image(src); if (newUrl != null) { // 注意：这里需要线程安全的更新DOM。一个简单的方法是先收集替换映射，最后统一替换。 // 更优方案是使用线程安全的引用或锁，但为了简化，我们可以改变策略： // 不在循环内直接替换，而是将任务提交到线程池，返回（图片索引，新URL）的Future。 // 这里展示另一种思路：使用同步锁或并发安全的集合。 synchronized (doc) { img.attr("src", newUrl); } } }, taskExecutor).exceptionally(ex -> { log.error("图片异步上传失败", ex); return null; }); futures.add(future); } // 等待所有图片上传任务完成 return CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])) .thenApply(v -> { // 所有任务完成后，返回处理后的HTML return doc.body().html(); }); } // ... uploadBase64Image 方法同上 ... }

在控制器中，可以这样调用：

@PostMapping("/save-async") public CompletableFuture<ApiResult> saveArticleAsync(@RequestBody ArticleSaveDTO dto) { String cleanHtml = HtmlUtils.clean(dto.getContent()); return asyncRichTextService.processRichTextAsync(cleanHtml) .thenApply(processedHtml -> { Long articleId = articleService.saveContent(processedHtml, dto.getTitle(), dto.getAuthor()); return ApiResult.success(articleId); }) .exceptionally(ex -> ApiResult.error("处理失败")); }

这样，图片上传并行执行，总耗时接近于最慢的那张图片的上传时间，极大提升了响应速度。

2. 云存储配置与最佳实践：

• 使用自定义域名并开启CDN：不要直接使用OSS的默认Endpoint域名返回给前端。应该绑定一个自定义域名（如cdn.yourdomain.com）并开启CDN加速，提升图片加载速度，并隐藏后端存储服务商信息。
• 设置合理的存储目录结构：如rich-text/{year}/{month}/{day}/{filename}。这有利于按时间归档、清理和进行生命周期管理（如自动将30天前的文件转移到低频访问存储以节省成本）。
• 上传回调与持久化：对于异步上传，一个更稳健的模式是“先持久化文章，再异步处理图片”。即先保存一个带有临时图片标记（如<img src="temp-id">）的HTML到数据库，并立即返回文章ID给前端。后台异步任务处理图片上传和URL替换，完成后更新数据库中的HTML内容。这保证了主流程的快速响应，但增加了状态管理的复杂性。

4.3 数据库操作与事务边界

保存文章内容和元信息可能涉及多张表（如文章表、内容表）。我们需要确保在保存过程中发生异常时，数据的一致性。

@Service @Transactional public class ArticleServiceImpl implements ArticleService { @Autowired private ArticleRepository articleRepo; @Autowired private ArticleContentRepository contentRepo; @Override public Long saveContent(String processedHtml, String title, String author) { // 1. 保存文章基本信息 Article article = new Article(); article.setTitle(title); article.setAuthor(author); article.setStatus(ArticleStatus.DRAFT); Article savedArticle = articleRepo.save(article); // 2. 保存富文本内容 ArticleContent content = new ArticleContent(); content.setArticleId(savedArticle.getId()); content.setContent(processedHtml); contentRepo.save(content); return savedArticle.getId(); } }

@Transactional注解确保了这两个保存操作在一个数据库事务中，要么全部成功，要么全部回滚。注意，如果图片上传是异步的且不在这个事务里，那么事务只保证文本内容与文章记录的原子性，图片上传的成功与否需要额外的补偿机制（如失败重试、状态标记）来处理。

5. 常见问题、排查技巧与性能优化实录

在实际开发中，你会遇到各种各样的问题。下面是我踩过的一些坑和总结的经验。

5.1 典型问题与解决方案速查表

5.2 性能优化与进阶技巧

1. 图片压缩与格式转换：在上传到OSS前，可以使用Thumbnailator或ImageMagick的Java封装库对图片进行压缩和格式转换（如将PNG转为WebP）。这能显著减少存储空间和流量消耗，提升加载速度。可以在uploadBase64Image方法中解码字节数组后加入压缩逻辑。

   private byte[] compressImage(byte[] originalBytes, String mimeType) throws IOException { if (!mimeType.equals("image/png") && !mimeType.equals("image/jpeg")) { return originalBytes; // 暂只处理PNG和JPEG } ByteArrayInputStream inputStream = new ByteArrayInputStream(originalBytes); ByteArrayOutputStream outputStream = new ByteArrayOutputStream(); Thumbnails.of(inputStream) .scale(1.0) // 保持原尺寸 .outputQuality(0.8) // 设置JPEG质量（0.0-1.0） .outputFormat(mimeType.equals("image/png") ? "PNG" : "JPEG") .toOutputStream(outputStream); return outputStream.toByteArray(); }

2. 引入消息队列进行最终一致性保证：对于“先存文章，后异步处理图片”的模式，可以将图片处理任务放入消息队列（如RabbitMQ、RocketMQ）。文章保存后，发送一个包含文章ID和原始HTML的消息。一个独立的消费者服务从队列取出消息，执行图片处理，并更新数据库。这样实现了应用解耦，提高了系统的可靠性和扩展性。

3. 内容缓存：文章内容一旦发布，很少变更。可以将处理后的完整HTML（或JSON）缓存到Redis中。当读取文章内容时，先查缓存，命中则直接返回，极大减轻数据库压力。缓存键可以设计为article:content:{id}，并设置合理的过期时间（如24小时）。当文章被编辑更新时，需要清除对应的缓存。

4. 数据库选型补充：对于内容非常长（如小说、手册）的场景，可以考虑使用专门用于存储大文本的数据库，如MongoDB（其BSON文档天然适合存储JSON/HTML），或者仍然使用MySQL但将LONGTEXT字段单独存放在不同的表空间，以避免影响核心业务表的查询性能。