kris/datai

Fork 0

Kris 3d290a8dd1 feat：归档当前所有文件

2026-01-28 18:23:25 +08:00

28 KiB

Raw Permalink Blame History

后端国际化需求

元数据

需求编号：2026-01-21-002-02
创建时间：2026-01-21
创建人：SSOT 架构师
状态：进行中
优先级：高
父需求：2026-01-21-002-项目国际化需求

需求概述

基于项目现有的国际化基础设施（MessageUtils、I18nConfig、messages.properties），扩展后端的国际化功能，支持错误消息、日志消息、验证消息、通知消息的国际化。使用 Spring MessageSource 实现，支持中文和英文两种语言，并考虑后续扩展其他语言的可能性。国际化资源文件位于 d:\idea_demo\datai\datai-admin\src\main\resources\i18n，支持按需加载和动态刷新。语言偏好保存在 sys_user 表，支持根据用户语言偏好返回对应语言的消息。

目标

错误消息国际化：基于现有的 GlobalExceptionHandler 扩展，支持所有系统异常、业务异常的国际化
日志消息国际化：基于现有的 LogAspect 扩展，支持操作日志、系统日志的国际化
验证消息国际化：基于现有的 Spring Validation 和 ValidationUtils 扩展，支持参数校验、业务校验的国际化
通知消息国际化：基于现有的 MessageSystem 扩展，支持邮件、短信、站内信的国际化
框架集成：基于现有的 MessageUtils 和 I18nConfig 扩展，使用 Spring MessageSource 实现
资源管理：国际化资源文件位于 d:\idea_demo\datai\datai-admin\src\main\resources\i18n，支持按需加载和动态刷新
动态加载：支持根据用户语言偏好返回对应语言的消息
语言偏好：系统默认使用中文（Constants.DEFAULT_LOCALE），语言偏好保存在 sys_user 表
语言扩展：先支持中文和英文，考虑后续扩展其他语言（日文、韩文、法文、德文等）

业务上下文

当前问题

项目已有基础的国际化基础设施（MessageUtils、I18nConfig、messages.properties），但未充分利用
GlobalExceptionHandler、LogAspect、ValidationUtils、MessageSystem 中的消息都是硬编码的中文
缺乏根据用户语言偏好返回对应语言消息的机制
缺乏动态刷新国际化资源的能力

现有基础设施

MessageUtils：位于 d:\idea_demo\datai\datai-common\src\main\java\com\datai\common\utils\MessageUtils.java，已封装 Spring MessageSource 的调用
I18nConfig：位于 d:\idea_demo\datai\datai-framework\src\main\java\com\datai\framework\config\I18nConfig.java，已配置 SessionLocaleResolver 和 LocaleChangeInterceptor
messages.properties：位于 d:\idea_demo\datai\datai-admin\src\main\resources\i18n\messages.properties，已包含部分错误消息和验证消息
Constants.DEFAULT_LOCALE：系统默认语言为 Locale.SIMPLIFIED_CHINESE
GlobalExceptionHandler：位于 d:\idea_demo\datai\datai-framework\src\main\java\com\datai\framework\web\exception\GlobalExceptionHandler.java，已处理 AccessDeniedException、ServiceException、RuntimeException 等异常
LogAspect：位于 d:\idea_demo\datai\datai-framework\src\main\java\com\datai\framework\aspectj\LogAspect.java，已使用 @Log 注解记录操作日志
MessageSystem：位于 d:\idea_demo\datai\datai-models\datai-message\src\main\java\com\datai\modelMessage\service\impl\MessageSystemServiceImpl.java，已支持平台消息、邮件通知、短信通知
ValidationUtils：位于 d:\idea_demo\datai\datai-common\src\main\java\com\datai\common\utils\ValidationUtils.java，已提供验证工具方法
ServiceException：位于 d:\idea_demo\datai\datai-common\src\main\java\com\datai\common\exception\ServiceException.java，code 字段类型为 Integer

业务场景

后端国际化
├─ 错误消息
│  ├─ 系统异常：数据库异常、网络异常、文件异常等
│  ├─ 业务异常：用户不存在、密码错误、权限不足等
│  └─ 运行时异常：空指针异常、数组越界等
├─ 日志消息
│  ├─ 操作日志：用户登录、用户登出、数据修改等
│  └─ 系统日志：系统启动、系统关闭、定时任务执行等
├─ 验证消息
│  ├─ 参数校验：必填校验、长度校验、格式校验等
│  └─ 业务校验：用户名重复、邮箱已注册、手机号已注册等
└─ 通知消息
   ├─ 邮件通知：注册成功、密码重置、账号激活等
   ├─ 短信通知：验证码、登录提醒、操作通知等
   └─ 站内信：系统通知、任务提醒、审批通知等

应用场景

多语言用户：不同国家和地区的用户使用系统，需要看到不同语言的消息
异常处理：系统发生异常时，需要返回用户能理解的语言
日志记录：系统记录日志时，需要根据用户语言偏好记录对应语言的日志消息
通知发送：系统发送通知时，需要根据接收者的语言偏好发送对应语言的通知

功能需求

核心功能

功能 1：错误消息国际化

描述：基于现有的 GlobalExceptionHandler 扩展，实现所有错误消息的国际化
验收标准：
1. 扩展 GlobalExceptionHandler，使用 MessageUtils 获取国际化消息
2. 所有系统异常支持国际化
3. 所有业务异常支持国际化
4. 所有运行时异常支持国际化
5. 支持中文和英文两种语言
6. 支持根据用户语言偏好返回对应语言的消息
7. 明确错误码与国际化资源键的映射规则
优先级：高
依赖关系：无

功能 2：日志消息国际化

描述：基于现有的 LogAspect 扩展，实现所有日志消息的国际化
验收标准：
1. 扩展 LogAspect，使用 MessageUtils 获取国际化日志消息
2. 所有操作日志支持国际化
3. 所有系统日志支持国际化
4. 支持中文和英文两种语言
5. 只在日志记录时根据用户语言偏好记录对应语言的日志消息
6. 明确 @Log 注解的国际化支持方式
7. 明确哪些日志消息需要国际化，以及如何实现
优先级：高
依赖关系：无

功能 3：验证消息国际化

描述：基于现有的 Spring Validation 和 ValidationUtils 扩展，实现所有验证消息的国际化
验收标准：
1. 配置 Spring Validation 的国际化资源文件
2. 所有参数校验支持国际化
3. 所有业务校验支持国际化
4. 支持中文和英文两种语言
5. 支持根据用户语言偏好返回对应语言的验证消息
6. 明确如何与 Spring Validation 的错误消息国际化集成
7. 明确 ValidationUtils 等工具类异常的国际化支持方式
优先级：高
依赖关系：无

功能 4：通知消息国际化

描述：基于现有的 MessageSystem 扩展，实现所有通知消息的国际化
验收标准：
1. 扩展 MessageSystem，使用 MessageUtils 获取国际化通知消息
2. 所有邮件通知支持国际化
3. 所有短信通知支持国际化
4. 所有站内信支持国际化
5. 支持中文和英文两种语言
6. 同一通知消息根据接收者的语言偏好发送不同语言版本
7. 明确模板消息的国际化支持方式
优先级：高
依赖关系：无

功能 5：自定义 MessageSource

描述：实现自定义的 MessageSource，支持动态刷新和按需加载
验收标准：
1. 实现 ReloadableResourceBundleMessageSource，支持动态刷新国际化资源
2. 实现按需加载国际化资源，减少内存占用
3. 明确缓存策略和刷新策略
4. 支持在运行时刷新国际化资源，无需重启应用
优先级：高
依赖关系：无

非功能需求

性能需求

响应时间：国际化消息获取时间 < 10ms
加载时间：国际化资源加载时间 < 1s
内存占用：国际化资源内存占用 < 5MB

可维护性需求

代码可读性：代码符合项目编码规范，注释完整
遵循现有架构：基于现有的 MessageUtils、I18nConfig、GlobalExceptionHandler、LogAspect、MessageSystem 进行扩展

数据需求

数据依赖

依赖 sys_user 表（需要添加 lang_code 字段）
依赖现有的国际化资源文件（messages.properties）

数据流转需求

异常处理
  └─ 读取用户语言偏好（从 sys_user 表）
  └─ 获取对应语言的国际化资源（使用 MessageUtils）
  └─ 返回对应语言的错误消息

日志记录
  └─ 读取用户语言偏好（从 sys_user 表）
  └─ 获取对应语言的国际化资源（使用 MessageUtils）
  └─ 记录对应语言的日志消息

参数校验
  └─ 读取用户语言偏好（从 sys_user 表）
  └─ 获取对应语言的国际化资源（使用 MessageUtils）
  └─ 返回对应语言的验证消息

通知发送
  └─ 读取接收者语言偏好（从 sys_user 表）
  └─ 获取对应语言的国际化资源（使用 MessageUtils）
  └─ 发送对应语言的通知消息

业务规则

资源缺失处理：国际化资源缺失时，返回默认语言（中文）的资源
语言偏好优先级：用户登录信息（sys_user.lang_code） > 请求参数（lang） > 请求头（Accept-Language） > 系统默认语言（Constants.DEFAULT_LOCALE）
异常处理：国际化资源加载失败时，返回系统默认消息
默认语言：系统默认使用中文（Constants.DEFAULT_LOCALE = Locale.SIMPLIFIED_CHINESE）
语言偏好存储：语言偏好保存在 sys_user 表（需要添加 lang_code 字段）
资源管理方式：国际化资源文件位于 d:\idea_demo\datai\datai-admin\src\main\resources\i18n
资源加载策略：支持按需加载国际化资源，使用自定义 MessageSource
资源命名规范：国际化资源键采用点号分隔（如 error.user.not.found、validation.username.required）
语言代码规范：使用标准的语言代码（如 zh_CN、en_US）
语言扩展性：先支持中文和英文，考虑后续扩展其他语言（日文、韩文、法文、德文等）
遵循现有架构：基于现有的 MessageUtils、I18nConfig、GlobalExceptionHandler、LogAspect、MessageSystem 进行扩展

国际化资源管理

资源文件结构

资源文件位置：d:\idea_demo\datai\datai-admin\src\main\resources\i18n

src/main/resources/i18n/
├── messages.properties           # 默认资源（中文）
├── messages_en_US.properties     # 英文资源
├── messages_ja_JP.properties     # 日文资源（预留）
├── messages_ko_KR.properties     # 韩文资源（预留）
├── messages_fr_FR.properties     # 法文资源（预留）
└── messages_de_DE.properties     # 德文资源（预留）

资源文件命名：messages_{lang}_{country}.properties
- 中文：messages.properties（默认）
- 英文：messages_en_US.properties

资源加载策略

加载方式：使用自定义的 ReloadableResourceBundleMessageSource 按需加载

配置方式：在 application.yml 中配置

spring:
  messages:
    basename: i18n/messages
    encoding: UTF-8
    fallback-to-system-locale: false
    cache-duration: 3600s

缓存策略：启用 MessageSource 默认缓存，缓存时间为 3600 秒
动态刷新：支持动态刷新国际化资源（无需重启应用），通过管理接口触发

资源命名规范

命名规则：使用点号分隔，按模块分类
- 错误消息：error.{module}.{specific}
- 验证消息：validation.{field}.{rule}
- 日志消息：log.{module}.{action}
- 通知消息：notification.{type}.{template}

示例：

# 错误消息
error.user.not.found=用户不存在
error.user.password.incorrect=密码错误
error.user.permission.denied=权限不足

# 验证消息
validation.username.required=用户名不能为空
validation.username.length=用户名长度必须在{min}到{max}之间
validation.email.format=邮箱格式不正确

# 日志消息
log.user.login.success=用户登录成功
log.user.logout.success=用户登出成功
log.user.update.success=用户信息更新成功

# 通知消息
notification.email.register.subject=注册成功
notification.email.register.content=欢迎注册{appName}，您的账号已创建成功
notification.sms.verify.code=您的验证码是{code}，有效期{minutes}分钟

语言偏好管理

获取方式：基于现有的 I18nConfig 配置，支持从以下方式获取
- 用户登录信息：从 sys_user 表的 lang_code 字段查询
- 请求参数：?lang=zh_CN（通过 LocaleChangeInterceptor）
- 请求头：Accept-Language: zh-CN
优先级：用户登录信息（sys_user.lang_code） > 请求参数（lang） > 请求头（Accept-Language） > 系统默认语言（Constants.DEFAULT_LOCALE）
默认语言：系统默认使用中文（Constants.DEFAULT_LOCALE = Locale.SIMPLIFIED_CHINESE）
存储位置：保存在 sys_user 表（需要添加 lang_code 字段）

消息国际化实现

错误消息国际化

实现方式：基于现有的 GlobalExceptionHandler 扩展，使用 MessageUtils 获取国际化消息
ServiceException 的 code 字段类型：当前为 Integer，需要明确错误码与国际化资源键的映射规则
错误码与国际化资源键的映射规则：
- 方案 1：保持 ServiceException 的 code 字段为 Integer，创建错误码枚举或常量类，定义错误码与国际化资源键的映射
- 方案 2：修改 ServiceException 的 code 字段类型为 String，直接使用国际化资源键

推荐方案：方案 1（保持 Integer 类型，使用错误码枚举）

public enum ErrorCode {
    USER_NOT_FOUND(1001, "error.user.not.found"),
    USER_PASSWORD_INCORRECT(1002, "error.user.password.incorrect"),
    USER_PERMISSION_DENIED(1003, "error.user.permission.denied");

    private final Integer code;
    private final String messageKey;

    ErrorCode(Integer code, String messageKey) {
        this.code = code;
        this.messageKey = messageKey;
    }

    public Integer getCode() {
        return code;
    }

    public String getMessageKey() {
        return messageKey;
    }
}

GlobalExceptionHandler 实现示例：

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ServiceException.class)
    public AjaxResult handleServiceException(ServiceException e, HttpServletRequest request) {
        log.error(e.getMessage(), e);
        Integer code = e.getCode();
        String messageKey = ErrorCode.getMessageKeyByCode(code);
        String message = MessageUtils.message(messageKey, e.getArgs());
        return StringUtils.isNotNull(code) ? AjaxResult.error(code, message) : AjaxResult.error(message);
    }
}

支持范围：
- 系统异常：数据库异常、网络异常、文件异常等
- 业务异常：用户不存在、密码错误、权限不足等
- 运行时异常：空指针异常、数组越界等

验证消息国际化

实现方式：配置 Spring Validation 的国际化资源文件，使用 MessageUtils 获取国际化消息

Spring Validation 配置：

@Configuration
public class ValidationConfig {

    @Autowired
    private MessageSource messageSource;

    @Bean
    public Validator validator() {
        LocalValidatorFactoryBean validator = new LocalValidatorFactoryBean();
        validator.setValidationMessageSource(messageSource);
        return validator;
    }
}

ValidationUtils 异常的国际化支持方式：

添加新的国际化验证方法，保持原有方法向后兼容

public class ValidationUtils {

    /**
     * 验证字符串不为空（国际化版本）
     */
    public static void validateNotBlankI18n(String str, String messageKey, Object... args) {
        if (str == null || str.trim().isEmpty()) {
            throw new IllegalArgumentException(MessageUtils.message(messageKey, args));
        }
    }

    /**
     * 验证对象不为null（国际化版本）
     */
    public static void validateNotNullI18n(Object obj, String messageKey, Object... args) {
        if (obj == null) {
            throw new IllegalArgumentException(MessageUtils.message(messageKey, args));
        }
    }

    // 保持原有方法向后兼容
    public static void validateNotBlank(String str, String message) {
        if (str == null || str.trim().isEmpty()) {
            throw new IllegalArgumentException(message);
        }
    }
}

支持范围：
- 参数校验：必填校验、长度校验、格式校验等
- 业务校验：用户名重复、邮箱已注册、手机号已注册等

日志消息国际化

实现方式：基于现有的 LogAspect 扩展，使用 MessageUtils 获取国际化日志消息

@Log 注解的扩展方式：

使用现有的 title 属性作为国际化资源键
保持向后兼容，title 可以是中文描述或国际化资源键

@Target({ ElementType.PARAMETER, ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Log {
    /**
     * 模块（可以是中文描述或国际化资源键）
     */
    public String title() default "";

    // ... 其他属性
}

LogAspect 实现示例：

@Aspect
@Component
public class LogAspect {

    @AfterReturning(pointcut = "@annotation(controllerLog)", returning = "jsonResult")
    public void doAfterReturning(JoinPoint joinPoint, Log controllerLog, Object jsonResult) {
        try {
            String title = controllerLog.title();
            String logMessage;

            if (title.startsWith("log.") || title.startsWith("error.") || title.startsWith("validation.") || title.startsWith("notification.")) {
                logMessage = MessageUtils.message(title);
            } else {
                logMessage = title;
            }

            log.info(logMessage);
        } catch (Exception e) {
            log.error("国际化日志消息获取失败: {}", e.getMessage(), e);
        }
    }
}

需要国际化的日志消息：
- 操作日志：用户登录、用户登出、数据修改等
- 系统日志：系统启动、系统关闭、定时任务执行等
实现方式：只在日志记录时根据用户语言偏好记录对应语言的日志消息

通知消息国际化

实现方式：基于现有的 MessageSystem 扩展，使用 MessageUtils 获取国际化通知消息

MessageSystem 扩展方式：

添加根据用户 ID 获取 Locale 的方法
添加发送国际化通知的方法

@Service
public class MessageSystemServiceImpl implements IMessageSystemService {

    @Autowired
    private ISysUserService userService;

    /**
     * 根据用户ID获取Locale
     */
    private Locale getLocaleFromUser(Long userId) {
        try {
            SysUser user = userService.selectUserById(userId);
            if (user != null && StringUtils.isNotEmpty(user.getLangCode())) {
                return Locale.forLanguageTag(user.getLangCode());
            }
            return Constants.DEFAULT_LOCALE;
        } catch (Exception e) {
            log.error("获取用户语言偏好失败: {}", e.getMessage(), e);
            return Constants.DEFAULT_LOCALE;
        }
    }

    /**
     * 发送国际化邮件通知
     */
    public void sendI18nEmailNotification(Long userId, String templateCode, Object[] args) {
        Locale locale = getLocaleFromUser(userId);
        String subject = MessageUtils.message("notification.email." + templateCode + ".subject", args, locale);
        String content = MessageUtils.message("notification.email." + templateCode + ".content", args, locale);
        emailService.send(userId, subject, content);
    }
}

模板消息的国际化支持方式：
- 为每个模板消息定义不同语言的版本
- 根据接收者的语言偏好选择对应语言的模板
- 同一通知消息根据接收者的语言偏好发送不同语言版本
支持范围：
- 邮件通知：注册成功、密码重置、账号激活等
- 短信通知：验证码、登录提醒、操作通知等
- 站内信：系统通知、任务提醒、审批通知等

语言代码规范

语言代码格式：{language}_{country}
- 中文：zh_CN
- 英文：en_US
扩展语言：
- 日文：ja_JP
- 韩文：ko_KR
- 法文：fr_FR
- 德文：de_DE

性能优化

资源缓存：启用 MessageSource 默认缓存，减少文件读取，缓存时间为 3600 秒
懒加载：按需加载国际化资源，减少内存占用
缓存刷新：支持动态刷新缓存，通过管理接口触发

动态刷新国际化资源

触发方式：通过管理接口触发刷新

实现方式：

@RestController
@RequestMapping("/system/i18n")
public class I18nController {

    @Autowired
    private MessageSource messageSource;

    /**
     * 刷新国际化资源
     */
    @PreAuthorize("@ss.hasPermi('system:i18n:refresh')")
    @PostMapping("/refresh")
    public AjaxResult refresh() {
        try {
            if (messageSource instanceof ReloadableResourceBundleMessageSource) {
                ((ReloadableResourceBundleMessageSource) messageSource).clearCache();
                log.info("国际化资源刷新成功");
                return AjaxResult.success("国际化资源刷新成功");
            } else {
                return AjaxResult.error("当前 MessageSource 不支持动态刷新");
            }
        } catch (Exception e) {
            log.error("国际化资源刷新失败: {}", e.getMessage(), e);
            return AjaxResult.error("国际化资源刷新失败");
        }
    }
}

分布式环境：如果系统是分布式部署，需要通过消息队列通知所有节点刷新缓存

数据库变更

sys_user 表变更

变更类型：ALTER TABLE（添加字段）
变更内容：添加 lang_code 字段

SQL 语句：

ALTER TABLE `sys_user` ADD COLUMN `lang_code` VARCHAR(10) DEFAULT 'zh_CN' COMMENT '语言代码（如：zh_CN、en_US）';

字段定义：
- 字段名：lang_code
- 字段类型：VARCHAR(10)
- 默认值：zh_CN
- 是否允许为空：是
- 字段注释：语言代码（如：zh_CN、en_US）
索引：不需要添加索引（语言偏好查询不频繁）

SysUser 实体类变更

变更内容：添加 langCode 属性

代码示例：

public class SysUser extends BaseEntity {
    // ... 其他字段

    /**
     * 语言代码
     */
    @Schema(title = "语言代码")
    private String langCode;

    public String getLangCode() {
        return langCode;
    }

    public void setLangCode(String langCode) {
        this.langCode = langCode;
    }
}

SysUserMapper XML 变更

变更内容：在查询语句中添加 lang_code 字段