服务端开发

Appearance

Spring MVC HTML Fragments：现代化的页面局部更新解决方案 🎯 ​

引言：为什么需要 HTML Fragments？ ​

在传统的 Web 开发中，每次用户交互都需要刷新整个页面，这不仅影响用户体验，还浪费了大量的网络资源。想象一下，仅仅为了更新页面上的一个评论区，却要重新加载整个页面的头部、导航栏、侧边栏等所有内容——这就像为了换一个轮胎而买一辆新车一样不合理！

NOTE

HTML Fragments 是 Spring MVC 为了支持现代化前端框架（如 HTMX 和 Hotwire Turbo）而引入的特性，它允许服务器返回多个 HTML 片段，让客户端可以精确地更新页面的不同部分。

核心概念：什么是 HTML-over-the-wire？ ​

HTML-over-the-wire 是一种现代化的 Web 开发理念，其核心思想是：

  • 服务器直接返回 HTML 片段，而不是 JSON 数据
  • 客户端接收后直接替换页面元素，无需复杂的 JavaScript 处理
  • 获得 SPA 的用户体验，但几乎不需要编写 JavaScript 代码

实现方式一：使用 Collection<ModelAndView> ​

基础用法 ​

kotlin
@GetMapping("/dashboard")
fun dashboard(): ModelAndView {
    return ModelAndView("dashboard") 
    // 问题：整个页面都需要重新渲染
}
kotlin
@GetMapping("/dashboard")
fun dashboard(): List<ModelAndView> { 
    return listOf(
        ModelAndView("posts"),    // 渲染帖子区域
        ModelAndView("comments")  // 渲染评论区域
    )
}

带数据模型的片段渲染 ​

kotlin
@RestController
class DashboardController {

    @GetMapping("/dashboard/update")
    fun updateDashboard(): List<ModelAndView> {
        // 获取最新的帖子数据
        val latestPosts = postService.getLatestPosts() 

        // 获取最新的评论数据
        val latestComments = commentService.getLatestComments() 

        return listOf(
            // 为帖子片段提供数据模型
            ModelAndView("posts").apply {
                addObject("posts", latestPosts) 
                addObject("totalCount", latestPosts.size)
            },
            // 为评论片段提供数据模型
            ModelAndView("comments").apply {
                addObject("comments", latestComments) 
                addObject("hasMore", latestComments.size >= 10)
            }
        )
    }
}

TIP

每个片段都可以有独立的数据模型，这意味着你可以为不同的页面区域提供完全不同的数据，而不需要在一个庞大的模型中包含所有数据。

实现方式二：使用 FragmentsRendering ​

FragmentsRendering 是 Spring 提供的专门用于片段渲染的类型，它提供了更加流畅的 API：

kotlin
@RestController
class NewsController {

    @GetMapping("/news/refresh")
    fun refreshNews(): FragmentsRendering {
        return FragmentsRendering
            .with("breaking-news") // 第一个片段
            .fragment("sports-news") // 添加更多片段
            .fragment("weather-widget") 
            .build()
    }

    @GetMapping("/news/personalized")
    fun personalizedNews(@AuthenticationPrincipal user: User): FragmentsRendering {
        val userPreferences = userService.getPreferences(user.id)

        val builder = FragmentsRendering.with("header")
            .modelAttribute("user", user) 

        // 根据用户偏好动态添加片段
        if (userPreferences.showSports) {
            builder.fragment("sports-section") 
        }

        if (userPreferences.showTech) {
            builder.fragment("tech-section") 
        }

        return builder.build()
    }
}

> `FragmentsRendering` 的优势在于它提供了链式调用的流畅 API，让代码更加清晰和易于维护。

实时更新：结合 Server-Sent Events (SSE) ​

对于需要实时更新的场景，HTML Fragments 可以与 SSE 完美结合：

kotlin
@RestController
class LiveUpdatesController {

    @GetMapping("/live-feed")
    fun liveFeed(): SseEmitter {
        val emitter = SseEmitter(Long.MAX_VALUE) 
        // 启动后台任务推送更新
        startBackgroundTask {
            try {
                // 推送新帖子片段
                emitter.send(
                    SseEmitter.event()
                        .name("post-update") 
                        .data(ModelAndView("post-item").apply {
                            addObject("post", getLatestPost())
                        })
                )
                // 推送通知片段
                emitter.send(
                    SseEmitter.event()
                        .name("notification") 
                        .data(ModelAndView("notification-badge").apply {
                            addObject("count", getUnreadCount())
                        })
                )

                // 模拟定期更新
                Thread.sleep(5000)

            } catch (ex: IOException) {
                // 连接断开，停止发送
                emitter.completeWithError(ex) 
            }
        }

        return emitter
    }

    private fun startBackgroundTask(task: () -> Unit) {
        Thread {
            while (true) {
                task()
            }
        }.start()
    }
}

对应的前端 HTML 模板 ​

posts.html 模板示例
html
<!-- posts.html -->
<div id="posts-container">
  <h3>最新帖子</h3>
  <div th:each="post : ${posts}" class="post-item">
    <h4 th:text="${post.title}">帖子标题</h4>
    <p th:text="${post.content}">帖子内容</p>
    <small th:text="${post.createdAt}">发布时间</small>
  </div>
  <div th:if="${totalCount == 0}" class="no-posts">暂无帖子</div>
</div>
comments.html 模板示例
html
<!-- comments.html -->
<div id="comments-container">
  <h3>最新评论</h3>
  <div th:each="comment : ${comments}" class="comment-item">
    <strong th:text="${comment.author}">作者</strong>
    <p th:text="${comment.content}">评论内容</p>
    <small th:text="${comment.createdAt}">评论时间</small>
  </div>
  <div th:if="${hasMore}" class="load-more">
    <button>加载更多评论</button>
  </div>
</div>

实际应用场景 ​

1. 社交媒体动态更新 ​

kotlin
@RestController
class SocialFeedController {

    @GetMapping("/feed/refresh")
    fun refreshFeed(@RequestParam lastUpdateTime: LocalDateTime): FragmentsRendering {
        val newPosts = feedService.getPostsSince(lastUpdateTime)
        val notifications = notificationService.getUnreadNotifications()
        return FragmentsRendering
            .with("feed-posts")
            .modelAttribute("posts", newPosts) 
            .fragment("notification-bell")
            .modelAttribute("notifications", notifications) 
            .fragment("online-friends")
            .modelAttribute("friends", friendService.getOnlineFriends()) 
            .build()
    }
}

2. 电商购物车更新 ​

kotlin
@RestController
class ShoppingCartController {

    @PostMapping("/cart/add/{productId}")
    fun addToCart(@PathVariable productId: Long): List<ModelAndView> {
        val cartItem = cartService.addProduct(productId) 
        val updatedCart = cartService.getCurrentCart()
        return listOf(
            // 更新购物车图标和数量
            ModelAndView("cart-badge").apply {
                addObject("itemCount", updatedCart.totalItems) 
            },
            // 更新购物车详情
            ModelAndView("cart-details").apply {
                addObject("cart", updatedCart) 
                addObject("totalPrice", updatedCart.totalPrice)
            },
            // 显示成功提示
            ModelAndView("success-toast").apply {
                addObject("message", "商品已添加到购物车") 
            }
        )
    }
}

与响应式编程的结合 ​

Spring MVC 还支持返回 Flux<ModelAndView> 来实现响应式的片段更新：

kotlin
@RestController
class ReactiveUpdatesController {

    @GetMapping("/reactive-updates")
    fun reactiveUpdates(): Flux<ModelAndView> {
        return Flux.interval(Duration.ofSeconds(2)) 
            .take(10) // 只发送10次更新
            .map { index ->
                ModelAndView("live-counter").apply {
                    addObject("count", index) 
                    addObject("timestamp", LocalDateTime.now())
                }
            }
            .doOnComplete {
                println("实时更新完成") 
            }
    }
}

WARNING

使用响应式流时，确保客户端能够正确处理流式数据，并且要注意资源管理，避免内存泄漏。

最佳实践与注意事项 ​

✅ 推荐做法 ​

片段设计原则

  1. 保持片段独立性：每个片段应该是自包含的，不依赖其他片段的状态
  2. 合理划分粒度：片段不宜过小（增加网络开销）也不宜过大（失去局部更新的优势）
  3. 统一命名规范：使用清晰的片段名称，如 user-profile、product-list 等

⚠️ 注意事项 ​

性能考虑

  • 避免频繁更新：过于频繁的片段更新可能影响用户体验
  • 控制片段数量：单次请求返回的片段数量不宜过多
  • 缓存策略：对于相对静态的片段，考虑使用适当的缓存策略

🔧 错误处理 ​

kotlin
@RestController
class RobustFragmentsController {

    @GetMapping("/dashboard/safe-update")
    fun safeUpdateDashboard(): ResponseEntity<*> {
        return try {
            val fragments = listOf(
                ModelAndView("posts"),
                ModelAndView("comments")
            )
            ResponseEntity.ok(fragments) 
        } catch (ex: Exception) {
            // 返回错误片段
            ResponseEntity.ok(
                listOf(
                    ModelAndView("error-message").apply {
                        addObject("error", "更新失败，请稍后重试") 
                    }
                )
            )
        }
    }
}

总结 ​

HTML Fragments 为 Spring MVC 带来了现代化的页面更新能力，它完美地平衡了开发复杂度和用户体验：

  • 🎯 精确更新：只更新需要变化的页面部分
  • 🚀 简化开发：无需复杂的前端状态管理
  • 🔄 实时性：支持 SSE 实现实时更新
  • 🛠️ 灵活性：支持多种返回类型和响应式编程

通过合理使用 HTML Fragments，你可以构建出既具有现代化用户体验，又保持代码简洁的 Web 应用程序！ 🎉