5.6 KiB
5.6 KiB
API 文档：数据库国际化功能
元数据
- 需求编号：2026-01-21-002-03
- 创建时间：2026-01-25
- 创建人：SSOT 架构师
- 父需求：2026-01-21-002-项目国际化需求
API 概述
数据库国际化功能 API 提供了语言切换、语言偏好管理、国际化资源刷新等功能，支持用户在运行时动态切换语言，并自动刷新相关缓存。API 遵循 RESTful 规范，使用标准的 HTTP 方法（GET、POST、PUT）进行数据交互。
接口列表
接口 1：刷新国际化资源
功能描述
刷新国际化资源，清除 MessageSource 的缓存，强制重新加载国际化资源文件。
请求方式
POST
请求路径
/system/i18n/refresh
权限要求
system:i18n:refresh- 国际化资源刷新权限
请求参数
无
响应参数
| 参数名 | 类型 | 说明 |
|---|---|---|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
成功示例
{
"code": 200,
"msg": "国际化资源刷新成功"
}
失败示例
{
"code": 500,
"msg": "当前 MessageSource 不支持动态刷新"
}
{
"code": 500,
"msg": "国际化资源刷新失败"
}
接口 2：获取当前语言偏好
功能描述
获取当前用户的语言偏好，包括语言代码、语言名称、国家名称等信息。
请求方式
GET
请求路径
/system/i18n/currentLocale
权限要求
system:i18n:query- 国际化查询权限
请求参数
无
响应参数
| 参数名 | 类型 | 说明 |
|---|---|---|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 返回数据 |
| data.langCode | String | 语言代码（zh_CN 或 en_US） |
| data.language | String | 语言名称（中文 或 English） |
| data.country | String | 国家名称（中国 或 United States） |
成功示例
{
"code": 200,
"msg": "操作成功",
"data": {
"langCode": "zh_CN",
"language": "中文",
"country": "中国"
}
}
{
"code": 200,
"msg": "操作成功",
"data": {
"langCode": "en_US",
"language": "English",
"country": "United States"
}
}
失败示例
{
"code": 500,
"msg": "未找到用户信息"
}
接口 3：切换语言
功能描述
切换当前用户的语言偏好，更新用户的 lang_code 字段，刷新 Token，清除用户缓存，强制重新加载数据。
请求方式
POST
请求路径
/system/i18n/switch
权限要求
system:i18n:switch- 语言切换权限
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| langCode | String | 是 | 语言代码，支持 zh_CN 或 en_US |
请求示例
{
"langCode": "en_US"
}
响应参数
| 参数名 | 类型 | 说明 |
|---|---|---|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
成功示例
{
"code": 200,
"msg": "语言切换成功"
}
失败示例
{
"code": 500,
"msg": "不支持的语言代码"
}
{
"code": 500,
"msg": "未找到用户信息"
}
{
"code": 500,
"msg": "语言切换失败"
}
接口 4：更新用户语言偏好
功能描述
更新当前用户的语言偏好，更新用户的 lang_code 字段，但不刷新 Token 和清除缓存。
请求方式
PUT
请求路径
/system/i18n/updateLocale
权限要求
system:i18n:update- 语言偏好更新权限
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| langCode | String | 是 | 语言代码，支持 zh_CN 或 en_US |
请求示例
{
"langCode": "en_US"
}
响应参数
| 参数名 | 类型 | 说明 |
|---|---|---|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
成功示例
{
"code": 200,
"msg": "语言偏好更新成功"
}
失败示例
{
"code": 500,
"msg": "不支持的语言代码"
}
{
"code": 500,
"msg": "未找到用户信息"
}
{
"code": 500,
"msg": "更新语言偏好失败"
}
错误码
| 错误码 | 说明 | 处理建议 |
|---|---|---|
| 200 | 操作成功 | 无 |
| 400 | 请求参数错误 | 检查请求参数是否符合要求 |
| 401 | 未授权 | 检查用户是否已登录 |
| 403 | 无权限 | 检查用户是否有相应的权限 |
| 500 | 不支持的语言代码 | 检查 langCode 是否为 zh_CN 或 en_US |
| 501 | 未找到用户信息 | 检查用户是否已登录 |
| 502 | 当前 MessageSource 不支持动态刷新 | 检查 MessageSource 配置 |
| 503 | 国际化资源刷新失败 | 检查国际化资源文件是否存在 |
| 504 | 语言切换失败 | 检查用户信息和数据库连接 |
| 505 | 更新语言偏好失败 | 检查用户信息和数据库连接 |