Spring MessageSource 详解:如何在国际化消息中传递参数

在开发多语言应用程序时，Spring 的 MessageSource 是处理国际化（i18n）文本的核心组件。它允许我们根据用户的 Locale (区域设置) 显示不同的消息。然而，很多时候我们的消息并不是静态的，而是需要包含动态数据，比如用户名、数量、文件名等。这时，我们就需要在获取国际化消息时传递参数。本文将详细介绍如何在 Spring MessageSource 中有效地使用参数。

核心概念：占位符与 java.text.MessageFormat

Spring 的消息参数化功能底层依赖于 Java 标准库中的 java.text.MessageFormat 类。其基本思想是在消息字符串中使用占位符 {index}，其中 index 是一个从 0 开始的整数，代表了传递给消息的参数数组中对应位置的参数。

第一步：在消息属性文件中定义带占位符的消息

首先，你需要在你的消息属性文件（例如 messages.properties, messages_zh_CN.properties, messages_fr.properties 等）中定义包含占位符的消息。

• messages.properties (默认/英文):
• # code=message welcome.user=Welcome, {0}! You have {1} new messages. error.file.notfound=File "{0}" could not be found at path "{1}". greeting=Hello there. action.delete.confirm=Are you sure you want to delete the item named "{0}"?
• messages_zh_CN.properties (简体中文):
• welcome.user=欢迎您, {0}! 您有 {1} 条新消息。 error.file.notfound=在路径 "{1}" 未找到文件 "{0}"。 greeting=您好。 action.delete.confirm=您确定要删除名为 "{0}" 的项目吗？

注意：

1. 占位符索引：{0} 对应传递的第一个参数，{1} 对应第二个，以此类推。
2. 顺序可能不同：不同语言的语序可能导致占位符在消息字符串中的顺序不同（如上面 error.file.notfound 的例子），但 {0} 始终引用第一个参数，{1} 引用第二个。
3. 无需转义：花括号 {} 和数字 0, 1, … 是 MessageFormat 的特殊字符，用于标记占位符。如果想在消息中显示花括号本身，需要使用单引号 ' 进行转义，例如 This is '{not a placeholder}'。

第二步：在 Java 代码中获取消息并传递参数

在你的 Service、Controller 或其他 Spring Bean 中，你需要注入 MessageSource 接口，并调用其 getMessage() 方法来获取格式化后的消息。关键在于使用接受 Object[] args 参数的 getMessage 重载方法。

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.MessageSource;
import org.springframework.context.i18n.LocaleContextHolder; // 常用于 Web 应用获取当前请求 Locale
import org.springframework.stereotype.Service;

import java.util.Locale;

@Service
public class NotificationService {

    @Autowired
    private MessageSource messageSource;

    /**
     * 获取欢迎消息
     * @param username 用户名
     * @param messageCount 新消息数量
     * @return 格式化后的欢迎消息
     */
    public String getWelcomeMessage(String username, int messageCount) {
        // 1. 获取当前的 Locale
        Locale currentLocale = LocaleContextHolder.getLocale();
        // 或者，如果你需要指定 Locale: Locale locale = Locale.SIMPLIFIED_CHINESE;

        // 2.准备参数数组，顺序与消息文件中的 {0}, {1} 对应
        Object[] args = {username, messageCount}; // username -> {0}, messageCount -> {1}

        // 3. 调用 getMessage 获取消息
        // 参数：消息代码，参数数组，当前 Locale
        return messageSource.getMessage("welcome.user", args, currentLocale);
    }

    /**
     * 获取文件未找到的错误消息
     * @param filename 文件名
     * @param path 文件路径
     * @return 格式化后的错误消息
     */
    public String getFileNotFoundError(String filename, String path) {
        Locale currentLocale = LocaleContextHolder.getLocale();
        Object[] args = {filename, path}; // filename -> {0}, path -> {1}

        // 使用带有默认消息的 getMessage 重载，增加健壮性
        // 如果 "error.file.notfound" 找不到，会返回 "Default file not found message"
        return messageSource.getMessage("error.file.notfound", args, "Default file not found message", currentLocale);
    }

    /**
     * 获取简单的问候语（无参数）
     * @return 问候语
     */
     public String getSimpleGreeting() {
        Locale currentLocale = LocaleContextHolder.getLocale();
        // 对于没有参数的消息，args 可以传递 null 或一个空数组
        return messageSource.getMessage("greeting", null, currentLocale);
     }

    /**
     * 获取删除确认信息
     * @param itemName 要删除的项的名称
     * @return 格式化后的确认消息
     */
    public String getDeleteConfirmation(String itemName) {
        Locale currentLocale = LocaleContextHolder.getLocale();
        Object[] args = {itemName}; // itemName -> {0}
        return messageSource.getMessage("action.delete.confirm", args, currentLocale);
    }
}

关键点：

• MessageSource 注入: 使用 @Autowired 将 MessageSource Bean 注入到你的类中。
• Locale 获取: 在 Web 应用中，LocaleContextHolder.getLocale() 是获取当前请求 Locale 的便捷方式（需要正确配置 LocaleResolver）。在非 Web 环境或需要特定 Locale 时，可以直接创建 Locale 对象（如 Locale.US, Locale.SIMPLIFIED_CHINESE）。
• Object[] args: 这是传递参数的核心。数组中元素的顺序必须与消息定义中的 {0}, {1}, … 占位符一一对应。数组元素可以是任何对象，MessageFormat 会调用它们的 toString() 方法（或进行特定的数字/日期格式化）。
• getMessage() 重载:getMessage(String code, Object[] args, Locale locale): 最常用的方法。getMessage(String code, Object[] args, String defaultMessage, Locale locale): 提供了一个默认消息，以防 code 在属性文件中找不到，避免抛出 NoSuchMessageException。

第三步：在视图层中使用（以 Thymeleaf 和 JSP 为例）

在视图层展示这些动态消息通常更方便，Spring MVC 集成了对常用视图技术的支持。

1. Thymeleaf

Thymeleaf 提供了非常简洁的语法 #{...} 来直接获取国际化消息和传递参数。

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <title>国际化消息示例</title>
</head>
<body>

    <!-- 假设 Controller 向 Model 添加了 'currentUser' 和 'newMessageCount' 变量 -->
    <p th:text="#{welcome.user(${currentUser}, ${newMessageCount})}">Default welcome message</p>

    <!-- 参数可以是字面量或变量 -->
    <p th:text="#{error.file.notfound('config.xml', '/etc/app/')}">Default file error</p>

    <!-- 无参数消息 -->
    <p th:text="#{greeting}">Default greeting</p>

    <!-- 单个参数 -->
    <p th:text="#{action.delete.confirm('Important Document')}">Default delete confirmation</p>

</body>
</html>

• 语法：#{message.code(param1, param2, ...)}
• Thymeleaf 会自动获取当前的 Locale 并调用 MessageSource。

2. JSP (使用 Spring 标签库)

如果你使用 JSP，可以利用 Spring 的 spring 标签库。

<%@ taglib prefix="spring" uri="http://www.springframework.org/tags" %>
<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<html>
<head>
    <title>国际化消息示例 (JSP)</title>
</head>
<body>

    <%-- 假设 'currentUser' 和 'newMessageCount' 是 request attributes --%>
    <p>
        <%-- 使用嵌套的 <spring:argument> --%>
        <spring:message code="welcome.user">
            <spring:argument value="${currentUser}"/> <%-- 对应 {0} --%>
            <spring:argument value="${newMessageCount}"/> <%-- 对应 {1} --%>
        </spring:message>
    </p>

    <p>
        <%-- 使用 arguments 属性，用逗号分隔 --%>
        <spring:message code="error.file.notfound" arguments="config.xml,/etc/app/" />
        <%-- 或者也可用 <spring:argument> --%>
        <%--
        <spring:message code="error.file.notfound">
            <spring:argument value="config.xml"/>
            <spring:argument value="/etc/app/"/>
        </spring:message>
        --%>
    </p>

    <p>
        <spring:message code="greeting"/>
    </p>

    <p>
        <spring:message code="action.delete.confirm" arguments="${itemToDeleteName}"/> <%-- 单个参数 --%>
    </p>

</body>
</html>

• 需要先在 JSP 文件顶部声明 spring 标签库。
• 可以使用 <spring:argument> 子标签按顺序提供参数，也可以直接在 <spring:message> 标签的 arguments 属性中提供一个逗号分隔的参数列表。

总结

通过在消息属性文件中使用 {index} 占位符，并结合 MessageSource.getMessage() 方法传递 Object[] 参数数组，或者利用 Thymeleaf 的 #{...} 语法或 JSP 的 <spring:message> 标签，我们可以轻松地在 Spring 应用中创建和管理包含动态数据的国际化消息。这种方式极大地提高了应用程序的灵活性和用户体验，使得向不同语言环境的用户展示定制化信息变得简单而高效。