384 lines
10 KiB
Markdown
384 lines
10 KiB
Markdown
# API 文档：后端国际化接口
|
||
|
||
## 元数据
|
||
- **需求编号**：2026-01-21-002-02
|
||
- **创建时间**：2026-01-26
|
||
- **创建人**：SSOT 架构师
|
||
- **父需求**：2026-01-21-002-项目国际化需求
|
||
|
||
## API 概述
|
||
后端国际化接口提供了国际化资源管理、语言偏好管理等功能，支持错误消息、日志消息、验证消息、通知消息的国际化。系统支持中文和英文两种语言，可根据用户语言偏好返回对应语言的消息。
|
||
|
||
## 接口列表
|
||
|
||
---
|
||
|
||
### 接口 1：刷新国际化资源
|
||
|
||
#### 功能描述
|
||
刷新系统内的国际化资源缓存（MessageSource），使最新的资源变更立即生效，无需重启应用。该接口主要用于在修改国际化资源文件后，使变更立即生效。
|
||
|
||
#### 请求方式
|
||
POST
|
||
|
||
#### 请求路径
|
||
`/system/i18n/refresh`
|
||
|
||
#### 权限要求
|
||
- `system:i18n:refresh`
|
||
|
||
#### 请求参数
|
||
无
|
||
|
||
#### 请求示例
|
||
```bash
|
||
curl -X POST 'http://localhost:8080/system/i18n/refresh' \
|
||
-H 'Authorization: Bearer {token}'
|
||
```
|
||
|
||
#### 响应数据结构
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | Integer | 状态码（200 成功，500 失败） |
|
||
| msg | String | 提示信息 |
|
||
| data | Object | 数据对象（通常为 null） |
|
||
|
||
#### 响应示例
|
||
|
||
**成功响应：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "国际化资源刷新成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**失败响应：**
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"msg": "国际化资源刷新失败",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**不支持动态刷新：**
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"msg": "当前 MessageSource 不支持动态刷新",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 错误码说明
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 200 | 刷新成功 |
|
||
| 500 | 刷新失败或 MessageSource 不支持动态刷新 |
|
||
|
||
---
|
||
|
||
### 接口 2：获取当前语言偏好
|
||
|
||
#### 功能描述
|
||
获取当前登录用户的语言偏好信息，包括语言代码、语言名称和国家名称。该接口用于前端初始化时获取用户的语言设置。
|
||
|
||
#### 请求方式
|
||
GET
|
||
|
||
#### 请求路径
|
||
`/system/i18n/currentLocale`
|
||
|
||
#### 权限要求
|
||
- `system:i18n:query`
|
||
|
||
#### 请求参数
|
||
无
|
||
|
||
#### 请求示例
|
||
```bash
|
||
curl -X GET 'http://localhost:8080/system/i18n/currentLocale' \
|
||
-H 'Authorization: Bearer {token}'
|
||
```
|
||
|
||
#### 响应数据结构
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | Integer | 状态码（200 成功，500 失败） |
|
||
| msg | String | 提示信息 |
|
||
| data | Object | 语言偏好信息 |
|
||
| data.langCode | String | 语言代码（如 zh_CN、en_US） |
|
||
| data.language | String | 语言名称（如 中文、English） |
|
||
| data.country | String | 国家名称（如 中国、United States） |
|
||
|
||
#### 响应示例
|
||
|
||
**成功响应（中文）：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"langCode": "zh_CN",
|
||
"language": "中文",
|
||
"country": "中国"
|
||
}
|
||
}
|
||
```
|
||
|
||
**成功响应（英文）：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"langCode": "en_US",
|
||
"language": "English",
|
||
"country": "United States"
|
||
}
|
||
}
|
||
```
|
||
|
||
**失败响应：**
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"msg": "未找到用户信息",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 错误码说明
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 200 | 获取成功 |
|
||
| 500 | 获取失败或未找到用户信息 |
|
||
|
||
---
|
||
|
||
### 接口 3：更新用户语言偏好
|
||
|
||
#### 功能描述
|
||
更新当前登录用户的语言偏好设置，将语言偏好持久化到数据库（sys_user 表的 lang_code 字段）。更新后，系统将根据新的语言偏好返回对应语言的消息。
|
||
|
||
#### 请求方式
|
||
PUT
|
||
|
||
#### 请求路径
|
||
`/system/i18n/updateLocale`
|
||
|
||
#### 权限要求
|
||
- `system:i18n:update`
|
||
|
||
#### 请求参数
|
||
| 参数名 | 类型 | 必选 | 说明 |
|
||
|--------|------|------|------|
|
||
| langCode | String | 是 | 目标语言代码（支持 zh_CN、en_US） |
|
||
|
||
#### 请求示例
|
||
```bash
|
||
curl -X PUT 'http://localhost:8080/system/i18n/updateLocale' \
|
||
-H 'Authorization: Bearer {token}' \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{
|
||
"langCode": "en_US"
|
||
}'
|
||
```
|
||
|
||
#### 响应数据结构
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | Integer | 状态码（200 成功，400/500 失败） |
|
||
| msg | String | 提示信息 |
|
||
| data | Object | 数据对象（通常为 null） |
|
||
|
||
#### 响应示例
|
||
|
||
**成功响应：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "语言偏好更新成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**失败响应（不支持的语言代码）：**
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"msg": "不支持的语言代码",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**失败响应（未找到用户信息）：**
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"msg": "未找到用户信息",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 错误码说明
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 200 | 更新成功 |
|
||
| 400 | 不支持的语言代码 |
|
||
| 500 | 更新失败或未找到用户信息 |
|
||
|
||
#### 业务规则
|
||
1. 支持的语言代码：zh_CN（简体中文）、en_US（美式英语）
|
||
2. 语言代码不能为空
|
||
3. 更新后，用户需要重新登录或刷新页面才能看到语言切换效果
|
||
4. 语言偏好保存在 sys_user 表的 lang_code 字段
|
||
|
||
---
|
||
|
||
## 国际化资源说明
|
||
|
||
### 资源文件位置
|
||
国际化资源文件位于：`datai-admin/src/main/resources/i18n/`
|
||
|
||
### 资源文件列表
|
||
- `messages.properties` - 默认资源（中文）
|
||
- `messages_en_US.properties` - 英文资源
|
||
|
||
### 资源命名规范
|
||
- 错误消息：error.{module}.{specific}
|
||
- 验证消息：validation.{field}.{rule}
|
||
- 日志消息：log.{module}.{action}
|
||
- 通知消息：notification.{type}.{template}
|
||
|
||
### 资源示例
|
||
|
||
**错误消息（messages.properties）：**
|
||
```properties
|
||
error.user.not.found=用户不存在
|
||
error.user.password.incorrect=密码错误
|
||
error.user.permission.denied=权限不足
|
||
```
|
||
|
||
**错误消息（messages_en_US.properties）：**
|
||
```properties
|
||
error.user.not.found=User not found
|
||
error.user.password.incorrect=Incorrect password
|
||
error.user.permission.denied=Permission denied
|
||
```
|
||
|
||
**验证消息（messages.properties）：**
|
||
```properties
|
||
validation.username.required=用户名不能为空
|
||
validation.username.length=用户名长度必须在{min}到{max}之间
|
||
validation.email.format=邮箱格式不正确
|
||
```
|
||
|
||
**验证消息（messages_en_US.properties）：**
|
||
```properties
|
||
validation.username.required=Username is required
|
||
validation.username.length=Username length must be between {min} and {max}
|
||
validation.email.format=Invalid email format
|
||
```
|
||
|
||
**日志消息（messages.properties）：**
|
||
```properties
|
||
log.user.login.success=用户登录成功
|
||
log.user.logout.success=用户登出成功
|
||
log.user.update.success=用户信息更新成功
|
||
```
|
||
|
||
**日志消息（messages_en_US.properties）：**
|
||
```properties
|
||
log.user.login.success=User logged in successfully
|
||
log.user.logout.success=User logged out successfully
|
||
log.user.update.success=User information updated successfully
|
||
```
|
||
|
||
**通知消息（messages.properties）：**
|
||
```properties
|
||
notification.email.register.subject=注册成功
|
||
notification.email.register.content=欢迎注册{appName}，您的账号已创建成功
|
||
notification.sms.verify.code=您的验证码是{code}，有效期{minutes}分钟
|
||
notification.platform.system=系统通知
|
||
```
|
||
|
||
**通知消息（messages_en_US.properties）：**
|
||
```properties
|
||
notification.email.register.subject=Registration Successful
|
||
notification.email.register.content=Welcome to {appName}, your account has been created successfully
|
||
notification.sms.verify.code=Your verification code is {code}, valid for {minutes} minutes
|
||
notification.platform.system=System Notification
|
||
```
|
||
|
||
---
|
||
|
||
## 语言偏好优先级
|
||
|
||
系统按以下优先级获取语言偏好：
|
||
1. **用户登录信息**（sys_user.lang_code）- 最高优先级
|
||
2. **请求参数**（?lang=zh_CN）
|
||
3. **请求头**（Accept-Language: zh-CN）
|
||
4. **系统默认语言**（Constants.DEFAULT_LOCALE = Locale.SIMPLIFIED_CHINESE）- 最低优先级
|
||
|
||
---
|
||
|
||
## 国际化消息获取流程
|
||
|
||
### 错误消息国际化
|
||
```
|
||
1. 捕获异常（ServiceException、RuntimeException 等）
|
||
2. 获取错误码（ServiceException.code）
|
||
3. 根据错误码查找对应的国际化资源键（ErrorCode 枚举）
|
||
4. 使用 MessageUtils 获取对应语言的错误消息
|
||
5. 返回国际化的错误消息
|
||
```
|
||
|
||
### 日志消息国际化
|
||
```
|
||
1. 拦截方法调用（LogAspect）
|
||
2. 获取 @Log 注解的 title 属性
|
||
3. 判断 title 是否为国际化资源键（以 log. 开头）
|
||
4. 使用 MessageUtils 获取对应语言的日志消息
|
||
5. 记录国际化的日志消息
|
||
```
|
||
|
||
### 验证消息国际化
|
||
```
|
||
1. 执行参数校验（Spring Validation）
|
||
2. 捕获校验异常（MethodArgumentNotValidException 等）
|
||
3. 使用 MessageUtils 获取对应语言的验证消息
|
||
4. 返回国际化的验证消息
|
||
```
|
||
|
||
### 通知消息国际化
|
||
```
|
||
1. 准备发送通知
|
||
2. 获取接收者的语言偏好（从 sys_user 表）
|
||
3. 使用 MessageUtils 获取对应语言的通知消息
|
||
4. 发送国际化的通知消息
|
||
```
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **资源刷新**：修改国际化资源文件后，需要调用刷新接口使变更生效
|
||
2. **语言代码**：使用标准的语言代码格式（如 zh_CN、en_US）
|
||
3. **参数占位符**：资源消息支持参数占位符（如 {appName}、{code}），使用 MessageUtils 传入参数值
|
||
4. **资源缺失**：如果某个语言的资源缺失，系统会返回默认语言（中文）的资源
|
||
5. **缓存策略**：国际化资源默认缓存 3600 秒，可通过配置调整
|
||
6. **权限控制**：所有接口都需要相应的权限才能访问
|
||
7. **用户登录**：获取和更新语言偏好需要用户已登录
|
||
|
||
---
|
||
|
||
## 相关文档
|
||
|
||
- [需求文档](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/requirements/2026-01-21-002-02-后端国际化需求.md)
|
||
- [设计文档](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/design/2026-01-21-002-02-后端国际化设计.md)
|
||
- [实现文档](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/implementation/2026-01-25-002-02-implementation-后端国际化功能.md)
|
||
- [通用国际化接口](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/api-docs/common/2026-01-26-002-01-api-通用国际化.md)
|