springboot 之 i18n国际化 三 （隔离资源配置）

在 Spring Boot 中，同时使用全局 i18n（如页面/接口消息）和参数验证（Bean Validation）的国际化是完全可行的，且推荐通过统一的资源文件管理或分离但协调的配置来实现。关键在于理解两者的加载机制并合理组织资源文件。

下面提供 两种主流方案，并附完整示例：

---

✅ 方案一：统一资源文件（推荐）

将 普通业务消息 和 校验错误消息 放在同一套 messages.properties 体系中，通过不同前缀区分。

步骤 1：创建统一的国际化文件

src/main/resources/
└── i18n/
    ├── messages.properties          # 默认
    ├── messages_zh_CN.properties
    └── messages_en_US.properties

文件内容示例：

# === 普通业务消息 ===
welcome.message=Hello, {0}!
user.profile.updated=Profile updated successfully.

# === 校验错误消息（使用标准 Bean Validation 错误码）===
javax.validation.constraints.NotBlank.message=不能为空
javax.validation.constraints.Size.message=长度必须在{min}到{max}之间
org.hibernate.validator.constraints.Email.message=邮箱格式不正确

# === 自定义校验消息 ===
user.name.size=用户名长度必须为2-20个字符
user.phone.invalid=手机号格式错误

💡 优势：只需维护一套文件，语言切换逻辑统一。

---

步骤 2：配置 MessageSource（指向统一文件）

// config/I18nConfig.java
@Configuration
public class I18nConfig {

    @Bean
    public MessageSource messageSource() {
        ResourceBundleMessageSource source = new ResourceBundleMessageSource();
        // 注意：basename 指向你的统一文件（不含 .properties）
        source.setBasename("i18n/messages");
        source.setDefaultEncoding("UTF-8");
        source.setFallbackToSystemLocale(false);
        return source;
    }

    // 配置 LocaleResolver（支持 Accept-Language 或参数切换）
    @Bean
    public LocaleResolver localeResolver() {
        SessionLocaleResolver resolver = new SessionLocaleResolver();
        resolver.setDefaultLocale(Locale.SIMPLIFIED_CHINESE);
        return resolver;
    }

    // 可选：支持 ?lang=zh_CN 切换
    @Bean
    public LocaleChangeInterceptor localeChangeInterceptor() {
        LocaleChangeInterceptor interceptor = new LocaleChangeInterceptor();
        interceptor.setParamName("lang");
        return interceptor;
    }

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(localeChangeInterceptor());
    }
}

🔑 关键点：
Spring 的 LocalValidatorFactoryBean 会自动使用 Spring 容器中的 MessageSource 来解析校验注解的 message 属性！
因此，只要 MessageSource 能加载到包含校验错误码的资源文件，验证国际化就生效。

---

步骤 3：定义 DTO（使用 {key} 引用消息）

public class UserDTO {
    
    @NotBlank(message = "{javax.validation.constraints.NotBlank.message}")
    @Size(min = 2, max = 20, message = "{user.name.size}")
    private String name;

    @Email(message = "{org.hibernate.validator.constraints.Email.message}")
    private String email;

    // getter/setter...
}

✅ 也可以直接使用标准错误码（无需自定义 key）：

@NotBlank // 默认使用 javax.validation.constraints.NotBlank.message
private String name;

---

步骤 4：Controller 同时使用两种国际化

@RestController
public class UserController {

    @Autowired
    private MessageSource messageSource;

    // 1. 参数验证国际化（自动生效）
    @PostMapping("/users")
    public String createUser(@Valid @RequestBody UserDTO user) {
        return "success";
    }

    // 2. 手动获取业务消息国际化
    @GetMapping("/welcome")
    public String welcome(@RequestParam String name, Locale locale) {
        return messageSource.getMessage("welcome.message", new Object[]{name}, locale);
    }

    // 全局异常处理（自动返回国际化校验错误）
    @RestControllerAdvice
    static class GlobalExceptionHandler {
        @ExceptionHandler(MethodArgumentNotValidException.class)
        public ResponseEntity<List<String>> handleValidation(
                MethodArgumentNotValidException ex) {
            List<String> errors = ex.getBindingResult().getFieldErrors().stream()
                .map(FieldError::getDefaultMessage) // ← 自动国际化！
                .collect(Collectors.toList());
            return ResponseEntity.badRequest().body(errors);
        }
    }
}

---

✅ 方案二：分离资源文件（清晰隔离）

如果你希望严格分离业务消息和校验消息：

resources/
├── i18n/
│   ├── messages.properties          # 业务消息
│   └── messages_zh_CN.properties
└── ValidationMessages.properties    # 校验消息（Bean Validation 规范要求）
    └── ValidationMessages_zh_CN.properties

配置说明：

• ValidationMessages.properties：由 Hibernate Validator 自动加载（无需配置）
• messages.properties：由 Spring MessageSource 加载（需配置）

⚠️ 注意：此时 MessageSource 只负责业务消息，校验消息由 Validator 自己处理。

优点 vs 缺点：

方案	优点	缺点
统一文件	维护简单，语言切换一致	文件可能较大
分离文件	职责清晰	需维护两套文件，切换逻辑需同步

📌 建议：除非项目极大，否则优先选择方案一（统一文件）。

---

🔧 关键配置验证（application.yml）

spring:
  messages:
    basename: classpath:i18n/messages   # 仅用于方案一
    encoding: UTF-8
    fallback-to-system-locale: false
  # 校验消息无需额外配置（Hibernate Validator 自动读取 ValidationMessages）

---

🌐 测试效果

请求 1：中文环境

POST /users
Accept-Language: zh-CN
Content-Type: application/json

{"name": "", "email": "bad-email"}

响应（校验错误）：

["不能为空", "邮箱格式不正确"]

请求 2：英文环境

GET /welcome?name=Alice
Accept-Language: en-US

响应（业务消息）：

Hello, Alice!

---

❗ 常见陷阱与解决方案

问题	原因	解决
校验消息未国际化	用了 message = "硬编码" 而非 message = "{key}"	改为引用资源 key
中文乱码	.properties 文件非 UTF-8	IDE 设置文件编码为 UTF-8，并启用 Transparent native-to-ascii conversion
语言未切换	未注册 LocaleChangeInterceptor	添加拦截器并配置 lang 参数
校验消息仍为英文	ValidationMessages_zh_CN.properties 未被加载	检查文件名是否为 ValidationMessages（首字母大写！）

---

✅ 最佳实践总结

1. 统一使用 messages.properties 管理所有文本（包括校验消息）
2. 校验注解始终使用 message = "{your.key}"
3. 通过 Accept-Language 或 ?lang= 实现语言切换
4. 全局异常处理器统一返回校验错误
5. 确保 .properties 文件为 UTF-8 编码

这样，你的 Spring Boot 应用就能同时支持：

• 接口返回的业务消息国际化（如 "操作成功" / "Operation succeeded"）
• 参数校验错误的国际化（如 "邮箱不能为空" / "Email must not be blank"）