125 lines
3.3 KiB
Markdown
125 lines
3.3 KiB
Markdown
# API 文档：查询语言列表接口
|
||
|
||
## 元数据
|
||
- **需求编号**：2026-01-26-002-08-01
|
||
- **创建时间**：2026-01-26
|
||
- **创建人**：SSOT 架构师
|
||
- **父需求**：2026-01-26-002-08-语言管理功能
|
||
- **状态**：已完成
|
||
|
||
## 功能概述
|
||
分页查询语言列表，支持按语言代码、语言名称、状态进行筛选。
|
||
|
||
## 接口信息
|
||
|
||
### 基本信息
|
||
- **接口名称**：查询语言列表
|
||
- **接口功能**：分页查询系统支持的语言列表
|
||
- **请求方式**：GET
|
||
- **请求路径**：`/system/language/list`
|
||
- **权限要求**：`system:language:list`
|
||
|
||
### 请求参数
|
||
|
||
| 参数名 | 类型 | 必选 | 说明 | 示例值 |
|
||
|--------|------|------|------|--------|
|
||
| pageNum | Integer | 否 | 页码，默认 1 | 1 |
|
||
| pageSize | Integer | 否 | 每页数量，默认 10 | 10 |
|
||
| langCode | String | 否 | 语言代码（模糊匹配） | zh-CN |
|
||
| langName | String | 否 | 语言名称（模糊匹配） | 中文 |
|
||
| status | String | 否 | 状态（0正常 1停用） | 0 |
|
||
|
||
### 响应参数
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | Integer | 状态码（200 成功） |
|
||
| msg | String | 提示信息 |
|
||
| rows | Array | 数据列表 |
|
||
| total | Integer | 总记录数 |
|
||
|
||
### 请求示例
|
||
|
||
```http
|
||
GET /system/language/list?pageNum=1&pageSize=10&status=0
|
||
```
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "查询成功",
|
||
"rows": [
|
||
{
|
||
"id": 1,
|
||
"langCode": "zh-CN",
|
||
"langName": "简体中文",
|
||
"langNameEn": "Simplified Chinese",
|
||
"sortOrder": 1,
|
||
"status": "0",
|
||
"isDefault": "1",
|
||
"createTime": "2026-01-26 10:00:00",
|
||
"updateTime": "2026-01-26 10:00:00"
|
||
},
|
||
{
|
||
"id": 2,
|
||
"langCode": "en-US",
|
||
"langName": "英语（美国）",
|
||
"langNameEn": "English (United States)",
|
||
"sortOrder": 2,
|
||
"status": "0",
|
||
"isDefault": "0",
|
||
"createTime": "2026-01-26 10:00:00",
|
||
"updateTime": "2026-01-26 10:00:00"
|
||
}
|
||
],
|
||
"total": 2
|
||
}
|
||
```
|
||
|
||
## 错误码
|
||
|
||
| 错误码 | 说明 | 处理建议 |
|
||
|--------|------|----------|
|
||
| 401 | 未登录或登录已过期 | 重新登录 |
|
||
| 403 | 无权限访问 | 联系管理员分配权限 |
|
||
| 500 | 服务器内部错误 | 联系技术支持 |
|
||
|
||
## 业务规则
|
||
|
||
1. **分页规则**：
|
||
- 默认返回第 1 页，每页 10 条记录
|
||
- 支持自定义分页参数
|
||
|
||
2. **筛选规则**：
|
||
- 支持按语言代码模糊匹配
|
||
- 支持按语言名称模糊匹配
|
||
- 支持按状态精确匹配
|
||
|
||
3. **排序规则**：
|
||
- 默认按排序字段（sortOrder）升序排列
|
||
- 相同排序字段按创建时间降序排列
|
||
|
||
4. **数据权限**：
|
||
- 需要登录用户
|
||
- 需要具备 `system:language:list` 权限
|
||
|
||
## 缓存策略
|
||
|
||
- **缓存类型**：Redis
|
||
- **缓存键**：`system:language:list:{pageNum}:{pageSize}:{langCode}:{langName}:{status}`
|
||
- **缓存时间**：300 秒（5 分钟）
|
||
- **缓存更新**：
|
||
- 新增语言后清除相关缓存
|
||
- 修改语言后清除相关缓存
|
||
- 删除语言后清除相关缓存
|
||
- 修改语言状态后清除相关缓存
|
||
|
||
## 注意事项
|
||
|
||
1. 查询结果包含语言的基本信息，包括是否为默认语言
|
||
2. 状态为停用的语言不会在前端语言选择列表中显示
|
||
3. 默认语言只能有一个，设置新的默认语言会自动取消旧的默认语言
|
||
4. 建议前端对查询结果进行缓存，减少重复请求
|