kris/datai

Fork 0

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

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

23 KiB

Raw Blame History

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	获取失败

业务规则

日期格式列表从数据库读取
日期格式列表固定，后续不允许用户调整
日期格式列表使用 Redis 缓存，缓存时间 24 小时
返回的日期格式列表按排序字段排序
只返回状态为正常（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	获取失败或未找到用户信息

业务规则

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

接口 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	切换失败或未找到用户信息

业务规则

验证日期格式代码的有效性
更新用户日期格式偏好到数据库
清除用户日期格式缓存
清除相关数据缓存（如日期数据缓存等）
日期格式切换后，前端需要刷新页面重新加载日期数据
日期格式切换记录审计日志
日期格式切换响应时间 < 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	获取失败或未找到默认日期格式

业务规则

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

接口 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	格式化失败

业务规则

如果未指定日期格式，使用用户日期格式偏好
如果未指定日期格式模式，使用日期格式默认模式
如果未指定时区，使用用户时区偏好
如果未指定语言环境，使用用户语言偏好
自动将 UTC 时间转换为用户时区
根据用户语言偏好本地化日期（如星期几、月份名称）
日期格式化时间 < 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	刷新失败

业务规则

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

数据库表结构

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 小时

缓存刷新规则

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

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;
    }
}

注意事项

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

性能要求

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

23 KiB Raw Blame History Unescape Escape

API 文档：日期格式化接口

元数据

API 概述

接口列表

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

功能描述

请求方式

请求路径

权限要求

请求参数

请求示例

响应数据结构

响应示例

错误码说明

业务规则

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

功能描述

请求方式

请求路径

权限要求

请求参数

请求示例

响应数据结构

响应示例

错误码说明

业务规则

接口 3：切换日期格式

功能描述

请求方式

请求路径

权限要求

请求参数

请求示例

响应数据结构

响应示例

错误码说明

业务规则

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

功能描述

请求方式

请求路径

权限要求

请求参数

请求示例

响应数据结构

响应示例

错误码说明

业务规则

接口 5：格式化日期

功能描述

请求方式

请求路径

权限要求

请求参数

请求示例

响应数据结构

响应示例

错误码说明

业务规则

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

功能描述

请求方式

请求路径

权限要求

请求参数

请求示例

响应数据结构

响应示例

错误码说明

业务规则

数据库表结构

sys_date_format 表（日期格式配置表）

sys_user 表修改（用户表）

常用日期格式列表

日期时间格式列表

日期格式化说明

日期格式化流程

日期格式化示例

时区转换说明

23 KiB

Raw Blame History