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

API 文档：格式化日期接口

元数据

• 需求编号：2026-01-21-002-06-05
• 创建时间：2026-01-26
• 创建人：SSOT 架构师
• 父需求：2026-01-21-002-06-日期格式化需求

接口概述

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

接口详情

基本信息

• 接口名称：格式化日期
• 接口描述：根据用户日期格式偏好、时区偏好和语言偏好格式化日期
• 请求方式：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
}

业务规则

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

性能要求

• 响应时间：< 10ms
• 格式化精度：支持纳秒级精度

相关文档

• 需求文档
• 设计文档