datai-vue/docs/api-docs/system/2026-01-21-002-06-api-日期格式化.md

API 文档：日期格式化接口

元数据

• 需求编号：2026-01-21-002-06
• 创建时间：2026-01-26
• 创建人：SSOT 架构师
• 父需求：2026-01-21-002-项目国际化需求

API 概述

日期格式化接口提供了常用日期格式、日期时间格式化、短日期和长日期格式化、自动选择格式、自定义格式、时区转换、多语言日期显示等功能。通过 AOP 在 Service 层统一处理日期格式化，根据用户日期格式偏好、时区偏好和语言偏好自动格式化日期数据。

接口列表

---

接口 1：获取日期格式列表

功能描述

获取系统支持的日期格式列表，包括日期格式代码、日期格式名称、日期格式模式等信息。

请求方式

GET

请求路径

/system/dateFormat/list

权限要求

• 无（通常公开或需登录）

请求参数

参数名	类型	必选	说明
formatCode	String	否	日期格式代码（如 yyyy-MM-dd）
status	String	否	状态（0正常 1停用）

请求示例

curl -X GET 'http://localhost:8080/system/dateFormat/list?status=0' \
  -H 'Authorization: Bearer {token}'

响应数据结构

参数名	类型	说明
code	Integer	状态码（200 成功，500 失败）
msg	String	提示信息
data	Array	日期格式列表
data[].formatCode	String	日期格式代码（如 yyyy-MM-dd）
data[].formatName	String	日期格式名称（如 ISO 8601）
data[].formatNameEn	String	日期格式英文名称（如 ISO 8601）
data[].formatPattern	String	日期格式模式（如 yyyy-MM-dd）
data[].isDefault	Boolean	是否默认格式
data[].sortOrder	Integer	排序
data[].status	String	状态（0正常 1停用）

响应示例

成功响应：

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "formatCode": "yyyy-MM-dd",
      "formatName": "ISO 8601",
      "formatNameEn": "ISO 8601",
      "formatPattern": "yyyy-MM-dd",
      "isDefault": true,
      "sortOrder": 1,
      "status": "0"
    },
    {
      "formatCode": "dd/MM/yyyy",
      "formatName": "欧洲格式",
      "formatNameEn": "European Format",
      "formatPattern": "dd/MM/yyyy",
      "isDefault": false,
      "sortOrder": 2,
      "status": "0"
    },
    {
      "formatCode": "MM/dd/yyyy",
      "formatName": "美国格式",
      "formatNameEn": "US Format",
      "formatPattern": "MM/dd/yyyy",
      "isDefault": false,
      "sortOrder": 3,
      "status": "0"
    },
    {
      "formatCode": "yyyy年MM月dd日",
      "formatName": "中国格式",
      "formatNameEn": "Chinese Format",
      "formatPattern": "yyyy年MM月dd日",
      "isDefault": false,
      "sortOrder": 4,
      "status": "0"
    }
  ]
}

失败响应：

{
  "code": 500,
  "msg": "获取日期格式列表失败",
  "data": null
}

错误码说明

错误码	说明
200	获取成功
500	获取失败

业务规则

1. 日期格式列表从数据库读取
2. 日期格式列表固定，后续不允许用户调整
3. 日期格式列表使用 Redis 缓存，缓存时间 24 小时
4. 返回的日期格式列表按排序字段排序
5. 只返回状态为正常（0）的日期格式

---

接口 2：获取当前用户日期格式偏好

功能描述

获取当前登录用户的日期格式偏好，返回用户的日期格式代码、日期格式名称等信息。如果用户未设置日期格式，返回系统默认日期格式。

请求方式

GET

请求路径

/system/user/dateFormat

权限要求

• 无（需要登录）

请求参数

无

请求示例

curl -X GET 'http://localhost:8080/system/user/dateFormat' \
  -H 'Authorization: Bearer {token}'

响应数据结构

参数名	类型	说明
code	Integer	状态码（200 成功，500 失败）
msg	String	提示信息
data	Object	日期格式信息
data.dateFormat	String	日期格式代码（如 yyyy-MM-dd）
data.dateFormatPattern	String	日期格式模式（如 yyyy-MM-dd）
data.formatName	String	日期格式名称（如 ISO 8601）
data.formatNameEn	String	日期格式英文名称（如 ISO 8601）
data.isDefault	Boolean	是否系统默认格式

响应示例

成功响应（用户已设置日期格式）：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "dateFormat": "yyyy-MM-dd",
    "dateFormatPattern": "yyyy-MM-dd",
    "formatName": "ISO 8601",
    "formatNameEn": "ISO 8601",
    "isDefault": false
  }
}

成功响应（用户未设置日期格式，返回系统默认格式）：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "dateFormat": "yyyy-MM-dd",
    "dateFormatPattern": "yyyy-MM-dd",
    "formatName": "ISO 8601",
    "formatNameEn": "ISO 8601",
    "isDefault": true
  }
}

失败响应：

{
  "code": 500,
  "msg": "获取当前用户日期格式偏好失败",
  "data": null
}

错误码说明

错误码	说明
200	获取成功
500	获取失败或未找到用户信息

业务规则

1. 优先级：用户日期格式偏好 > 系统默认格式
2. 如果用户未设置日期格式，返回系统默认日期格式
3. 用户日期格式偏好使用 Redis 缓存，缓存时间 24 小时
4. 需要用户登录才能获取日期格式信息

---

接口 3：切换日期格式

功能描述

切换当前登录用户的日期格式偏好，更新用户日期格式设置，清除相关缓存，返回切换结果。日期格式切换后，前端需要刷新页面重新加载日期数据。

请求方式

POST

请求路径

/system/user/switchDateFormat

权限要求

• 无（需要登录）

请求参数

参数名	类型	必选	说明
dateFormat	String	是	日期格式代码（如 yyyy-MM-dd、dd/MM/yyyy）
dateFormatPattern	String	否	自定义日期格式模式（如 yyyy年MM月dd日）

请求示例

curl -X POST 'http://localhost:8080/system/user/switchDateFormat' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "dateFormat": "dd/MM/yyyy"
  }'

响应数据结构

参数名	类型	说明
code	Integer	状态码（200 成功，400/500 失败）
msg	String	提示信息
data	Object	数据对象（通常为 null）

响应示例

成功响应：

{
  "code": 200,
  "msg": "日期格式切换成功",
  "data": null
}

失败响应（无效的日期格式代码）：

{
  "code": 400,
  "msg": "无效的日期格式代码",
  "data": null
}

失败响应（未找到用户信息）：

{
  "code": 500,
  "msg": "未找到用户信息",
  "data": null
}

错误码说明

错误码	说明
200	切换成功
400	无效的日期格式代码
500	切换失败或未找到用户信息

业务规则

1. 验证日期格式代码的有效性
2. 更新用户日期格式偏好到数据库
3. 清除用户日期格式缓存
4. 清除相关数据缓存（如日期数据缓存等）
5. 日期格式切换后，前端需要刷新页面重新加载日期数据
6. 日期格式切换记录审计日志
7. 日期格式切换响应时间 < 500ms

---

接口 4：获取系统默认日期格式

功能描述

获取系统默认日期格式配置，返回系统默认日期格式的详细信息。系统默认日期格式用于用户未设置日期格式时的回退格式。

请求方式

GET

请求路径

/system/dateFormat/default

权限要求

• 无（通常公开或需登录）

请求参数

无

请求示例

curl -X GET 'http://localhost:8080/system/dateFormat/default' \
  -H 'Authorization: Bearer {token}'

响应数据结构

参数名	类型	说明
code	Integer	状态码（200 成功，500 失败）
msg	String	提示信息
data	Object	日期格式信息
data.dateFormat	String	日期格式代码（如 yyyy-MM-dd）
data.dateFormatPattern	String	日期格式模式（如 yyyy-MM-dd）
data.formatName	String	日期格式名称（如 ISO 8601）
data.formatNameEn	String	日期格式英文名称（如 ISO 8601）

响应示例

成功响应：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "dateFormat": "yyyy-MM-dd",
    "dateFormatPattern": "yyyy-MM-dd",
    "formatName": "ISO 8601",
    "formatNameEn": "ISO 8601"
  }
}

失败响应：

{
  "code": 500,
  "msg": "获取默认日期格式失败",
  "data": null
}

错误码说明

错误码	说明
200	获取成功
500	获取失败或未找到默认日期格式

业务规则

1. 系统必须有默认日期格式配置
2. 默认日期格式从配置文件读取
3. 默认日期格式使用 Redis 缓存，缓存时间 24 小时
4. 默认日期格式用于用户未设置日期格式时的回退格式

---

接口 5：格式化日期

功能描述

根据用户日期格式偏好、时区偏好和语言偏好格式化日期，返回格式化后的日期字符串。支持自定义日期格式，包括日期格式、时区转换、多语言本地化等。

请求方式

POST

请求路径

/system/dateFormat/format

权限要求

• 无（需要登录）

请求参数

参数名	类型	必选	说明
dateTime	String	是	日期时间（ISO 8601 格式，如 2026-01-26T10:30:00Z）
dateFormat	String	否	日期格式代码（如 yyyy-MM-dd），不传则使用用户日期格式偏好
dateFormatPattern	String	否	自定义日期格式模式（如 yyyy年MM月dd日），不传则使用日期格式默认模式
timeZone	String	否	时区（如 Asia/Shanghai），不传则使用用户时区偏好
locale	String	否	语言环境（如 zh_CN、en_US），不传则使用用户语言偏好
includeTime	Boolean	否	是否包含时间（默认 false）

请求示例

curl -X POST 'http://localhost:8080/system/dateFormat/format' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "dateTime": "2026-01-26T10:30:00Z",
    "dateFormat": "yyyy-MM-dd",
    "dateFormatPattern": "yyyy年MM月dd日",
    "timeZone": "Asia/Shanghai",
    "locale": "zh_CN",
    "includeTime": true
  }'

响应数据结构

参数名	类型	说明
code	Integer	状态码（200 成功，400/500 失败）
msg	String	提示信息
data	Object	格式化结果
data.formattedDateTime	String	格式化后的日期时间（如 2026年01月26日 18:30:00）
data.dateFormat	String	日期格式代码（如 yyyy-MM-dd）
data.dateFormatPattern	String	日期格式模式（如 yyyy年MM月dd日）
data.timeZone	String	时区（如 Asia/Shanghai）
data.locale	String	语言环境（如 zh_CN）
data.includeTime	Boolean	是否包含时间

响应示例

成功响应：

{
  "code": 200,
  "msg": "格式化成功",
  "data": {
    "formattedDateTime": "2026年01月26日 18:30:00",
    "dateFormat": "yyyy-MM-dd",
    "dateFormatPattern": "yyyy年MM月dd日",
    "timeZone": "Asia/Shanghai",
    "locale": "zh_CN",
    "includeTime": true
  }
}

失败响应（无效的日期时间）：

{
  "code": 400,
  "msg": "无效的日期时间",
  "data": null
}

失败响应（无效的日期格式代码）：

{
  "code": 400,
  "msg": "无效的日期格式代码",
  "data": null
}

错误码说明

错误码	说明
200	格式化成功
400	无效的日期时间或日期格式代码
500	格式化失败

业务规则

1. 如果未指定日期格式，使用用户日期格式偏好
2. 如果未指定日期格式模式，使用日期格式默认模式
3. 如果未指定时区，使用用户时区偏好
4. 如果未指定语言环境，使用用户语言偏好
5. 自动将 UTC 时间转换为用户时区
6. 根据用户语言偏好本地化日期（如星期几、月份名称）
7. 日期格式化时间 < 10ms

---

接口 6：刷新日期格式缓存

功能描述

刷新日期格式缓存，清除所有日期格式相关的缓存数据，使最新的日期格式数据立即生效。

请求方式

DELETE

请求路径

/system/dateFormat/refreshCache

权限要求

• system:dateFormat:refresh

请求参数

无

请求示例

curl -X DELETE 'http://localhost:8080/system/dateFormat/refreshCache' \
  -H 'Authorization: Bearer {token}'

响应数据结构

参数名	类型	说明
code	Integer	状态码（200 成功，500 失败）
msg	String	提示信息
data	Object	数据对象（通常为 null）

响应示例

成功响应：

{
  "code": 200,
  "msg": "日期格式缓存刷新成功",
  "data": null
}

失败响应：

{
  "code": 500,
  "msg": "日期格式缓存刷新失败",
  "data": null
}

错误码说明

错误码	说明
200	刷新成功
500	刷新失败

业务规则

1. 清除日期格式列表缓存（sys:dateFormat:list）
2. 清除用户日期格式缓存（user:dateFormat:*）
3. 刷新后，下次查询时重新加载日期格式数据

---

数据库表结构

sys_date_format 表（日期格式配置表）

CREATE TABLE `sys_date_format` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '日期格式ID',
  `format_code` varchar(50) NOT NULL COMMENT '日期格式代码（如：yyyy-MM-dd）',
  `format_name` varchar(50) NOT NULL COMMENT '日期格式名称（如：ISO 8601）',
  `format_name_en` varchar(50) NOT NULL COMMENT '日期格式英文名称（如：ISO 8601）',
  `format_pattern` varchar(100) NOT NULL COMMENT '日期格式模式（如：yyyy-MM-dd）',
  `is_default` tinyint(1) DEFAULT '0' COMMENT '是否默认格式（0否 1是）',
  `sort_order` int DEFAULT '0' COMMENT '排序',
  `status` char(1) DEFAULT '0' COMMENT '状态（0正常 1停用）',
  `create_by` varchar(64) DEFAULT '' COMMENT '创建者',
  `create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_by` varchar(64) DEFAULT '' COMMENT '更新者',
  `update_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  `remark` varchar(500) DEFAULT NULL COMMENT '备注',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_format_code` (`format_code`),
  KEY `idx_status` (`status`),
  KEY `idx_sort_order` (`sort_order`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT='日期格式配置表';

sys_user 表修改（用户表）

ALTER TABLE `sys_user` 
ADD COLUMN `date_format` varchar(50) DEFAULT NULL COMMENT '日期格式' AFTER `currency_code`,
ADD COLUMN `date_format_pattern` varchar(100) DEFAULT NULL COMMENT '日期格式模式' AFTER `date_format`;

---

常用日期格式列表

日期格式代码	日期格式名称	日期格式英文名称	日期格式模式	是否默认
yyyy-MM-dd	ISO 8601	ISO 8601	yyyy-MM-dd	是
dd/MM/yyyy	欧洲格式	European Format	dd/MM/yyyy	否
MM/dd/yyyy	美国格式	US Format	MM/dd/yyyy	否
yyyy年MM月dd日	中国格式	Chinese Format	yyyy年MM月dd日	否

---

日期时间格式列表

日期时间格式代码	日期时间格式名称	日期时间格式英文名称	日期时间格式模式
yyyy-MM-dd HH:mm:ss	短格式	Short Format	yyyy-MM-dd HH:mm:ss
yyyy年MM月dd日 HH时mm分ss秒	长格式	Long Format	yyyy年MM月dd日 HH时mm分ss秒

---

日期格式化说明

日期格式化流程

日期格式化
  ├─ 读取用户日期格式偏好（date_format）
  ├─ 读取用户时区偏好（time_zone）
  ├─ 读取用户语言偏好（lang_code）
  ├─ 读取系统默认日期格式配置
  ├─ 将 UTC 时间转换为用户时区
  ├─ 根据用户日期格式偏好格式化日期
  ├─ 根据用户语言偏好本地化日期
  │  ├─ 星期几本地化（中文：星期一；英文：Monday）
  │  └─ 月份名称本地化（中文：一月；英文：January）
  └─ 返回格式化后的日期

日期格式化示例

// 示例：格式化日期
String dateTimeStr = "2026-01-26T10:30:00Z";
String dateFormat = "yyyy年MM月dd日";
String timeZone = "Asia/Shanghai";
String locale = "zh_CN";
boolean includeTime = true;

// 解析日期时间
ZonedDateTime utcDateTime = ZonedDateTime.parse(dateTimeStr);
ZoneId userTimeZone = ZoneId.of(timeZone);
ZonedDateTime userDateTime = utcDateTime.withZoneSameInstant(userTimeZone);

// 格式化日期
DateTimeFormatter formatter = DateTimeFormatter.ofPattern(dateFormatPattern, Locale.forLanguageTag(locale));
String formattedDateTime = formatter.format(userDateTime);

// 结果：2026年01月26日

---

时区转换说明

时区转换流程

时区转换
  ├─ 读取用户时区偏好（time_zone）
  ├─ 读取系统默认时区配置
  ├─ 将 UTC 时间转换为用户时区
  │  ├─ ZonedDateTime.parse(utcDateTime)
  │  ├─ withZoneSameInstant(userTimeZone)
  │  └─ 返回用户时区时间
  └─ 返回转换后的时间

时区转换示例

// 示例：时区转换
String utcDateTimeStr = "2026-01-26T10:30:00Z";
String userTimeZone = "Asia/Shanghai";

// 解析 UTC 时间
ZonedDateTime utcDateTime = ZonedDateTime.parse(utcDateTimeStr);

// 转换为用户时区
ZoneId timeZone = ZoneId.of(userTimeZone);
ZonedDateTime userDateTime = utcDateTime.withZoneSameInstant(timeZone);

// 结果：2026-01-26T18:30:00+08:00[Asia/Shanghai]

---

多语言本地化说明

多语言本地化流程

多语言本地化
  ├─ 读取用户语言偏好（lang_code）
  ├─ 读取系统默认语言配置
  ├─ 根据用户语言偏好本地化日期
  │  ├─ 星期几本地化
  │  │  ├─ 中文：星期一、星期二、...、星期日
  │  │  └─ 英文：Monday、Tuesday、...、Sunday
  │  └─ 月份名称本地化
  │     ├─ 中文：一月、二月、...、十二月
  │     └─ 英文：January、February、...、December
  └─ 返回本地化后的日期

多语言本地化示例

// 示例：多语言本地化
String locale = "zh_CN";
ZonedDateTime dateTime = ZonedDateTime.now();

// 本地化星期几
String dayOfWeek = dateTime.format(DateTimeFormatter.ofPattern("EEEE", Locale.forLanguageTag(locale)));
// 中文：星期一
// 英文：Monday

// 本地化月份名称
String monthName = dateTime.format(DateTimeFormatter.ofPattern("MMMM", Locale.forLanguageTag(locale)));
// 中文：一月
// 英文：January

---

缓存策略

缓存键格式

• 日期格式列表：sys:dateFormat:list
• 用户日期格式：user:dateFormat:{userId}

缓存时间

• 日期格式列表缓存：24 小时
• 用户日期格式缓存：24 小时

缓存刷新规则

1. 日期格式列表更新时，清除日期格式列表缓存
2. 日期格式切换时，清除用户日期格式缓存
3. 手动刷新日期格式缓存时，清除所有日期格式相关缓存

---

AOP 统一处理说明

AOP 切面设计

@Aspect
@Component
public class DateFormatAspect {
    
    @Autowired
    private DateFormatService dateFormatService;
    
    @AfterReturning(pointcut = "@annotation(com.datai.common.annotation.DateFormat)", returning = "result")
    public void formatDate(JoinPoint joinPoint, Object result) {
        if (result == null) {
            return;
        }
        
        Object formattedResult = dateFormatService.formatObject(result);
        return formattedResult;
    }
}

AOP 使用示例

@Service
public class OrderServiceImpl implements IOrderService {
    
    @DateFormat
    @Override
    public Order getOrderById(Long orderId) {
        Order order = orderMapper.selectOrderById(orderId);
        return order;
    }
}

---

注意事项

1. 日期格式验证：切换日期格式时，必须验证日期格式代码的有效性
2. 日期格式化：日期格式化在 Service 层通过 AOP 统一处理
3. 日期存储：所有日期字段使用 LocalDateTime 或 ZonedDateTime 类型存储
4. 时区转换：自动将 UTC 时间转换为用户时区
5. 缓存管理：日期格式和用户日期格式需要缓存，提高性能
6. 页面刷新：日期格式切换后立即刷新页面，重新加载日期数据
7. 日期格式列表：日期格式列表固定存储在数据库中，后续不允许用户调整
8. 多语言本地化：根据用户语言偏好本地化日期（如星期几、月份名称）
9. 权限控制：所有用户都可以设置和切换日期格式
10. 审计日志：记录日期格式设置变更日志

---

性能要求

• 日期格式化时间：< 10ms
• 日期格式切换响应时间：< 500ms
• 时区转换时间：< 10ms
• 缓存命中率：≥ 90%

---

相关文档

• 需求文档
• 设计文档
• 架构决策记录
• SQL 脚本
• 提示词文档
• 参考代码
• 实施方案
• 会话记录
• 变更日志
• 复盘文档