kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
dd3c36207e
datai/datai-scenes/datai-scene-salesforce/docs/api-docs/2026-01-25-002-06-api.md

9.6 KiB
Raw Blame History

API 文档：日期格式化功能

元数据

  • API 文档编号：2026-01-25-002-06-api
  • 需求编号：2026-01-21-002-06
  • 功能名称：日期格式化功能
  • 版本：3.8.5
  • 发布日期：2026-01-25
  • 状态：已完成
  • 阶段：阶段 9：复盘与接口

API 概述

日期格式化功能提供了用户日期格式偏好管理和系统默认日期格式查询的 API 接口，支持用户设置和切换日期格式偏好，获取系统默认日期格式和常用日期格式列表。

API 列表

1. 获取当前用户日期格式偏好

接口信息

  • 接口路径：/system/user/dateFormat
  • 请求方法：GET
  • 接口描述：获取当前用户日期格式偏好
  • 权限要求：需要登录
  • 接口分类：用户管理

请求参数

无

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "userId": 1,
    "dateFormat": "ISO_8601",
    "dateFormatPattern": null
  }
}

响应字段说明

字段名 类型 说明
code Integer 响应码，200 表示成功
msg String 响应消息
data Object 响应数据
data.userId Long 用户 ID
data.dateFormat String 日期格式模式（ISO_8601、US、EU、CN、JP、KR、SHORT、LONG、CUSTOM）
data.dateFormatPattern String 自定义日期格式（当 dateFormat 为 CUSTOM 时有效）

错误响应

{
  "code": 401,
  "msg": "用户未登录"
}

2. 切换用户日期格式偏好

接口信息

  • 接口路径：/system/user/switchDateFormat
  • 请求方法：POST
  • 接口描述：切换用户日期格式偏好
  • 权限要求：需要登录
  • 接口分类：用户管理

请求参数

{
  "dateFormat": "ISO_8601",
  "dateFormatPattern": null
}

请求字段说明

字段名 类型 必填 说明
dateFormat String 是 日期格式模式（ISO_8601、US、EU、CN、JP、KR、SHORT、LONG、CUSTOM）
dateFormatPattern String 条件必填 自定义日期格式（当 dateFormat 为 CUSTOM 时必填）

响应示例

{
  "code": 200,
  "msg": "操作成功"
}

错误响应

{
  "code": 500,
  "msg": "日期格式模式不能为空"
}

{
  "code": 500,
  "msg": "自定义日期格式不能为空"
}

3. 获取系统默认日期格式

接口信息

  • 接口路径：/system/config/defaultDateFormat
  • 请求方法：GET
  • 接口描述：获取系统默认日期格式
  • 权限要求：需要登录
  • 接口分类：配置管理

请求参数

无

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "dateFormat": "yyyy-MM-dd",
    "dateTimeFormat": "yyyy-MM-dd HH:mm:ss"
  }
}

响应字段说明

字段名 类型 说明
code Integer 响应码，200 表示成功
msg String 响应消息
data Object 响应数据
data.dateFormat String 系统默认日期格式
data.dateTimeFormat String 系统默认日期时间格式

错误响应

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

4. 获取常用日期格式列表

接口信息

  • 接口路径：/system/config/commonDateFormats
  • 请求方法：GET
  • 接口描述：获取常用日期格式列表
  • 权限要求：需要登录
  • 接口分类：配置管理

请求参数

无

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "dateFormats": {
      "ISO_8601": "yyyy-MM-dd",
      "US": "MM/dd/yyyy",
      "EU": "dd/MM/yyyy",
      "CN": "yyyy年MM月dd日",
      "JP": "yyyy/MM/dd",
      "KR": "yyyy. MM. dd.",
      "SHORT": "yy/MM/dd"
    },
    "dateTimeFormats": {
      "ISO_8601": "yyyy-MM-dd HH:mm:ss",
      "US": "MM/dd/yyyy HH:mm:ss",
      "EU": "dd/MM/yyyy HH:mm:ss",
      "CN": "yyyy年MM月dd日 HH:mm:ss",
      "JP": "yyyy/MM/dd HH:mm:ss",
      "KR": "yyyy. MM. dd. HH:mm:ss",
      "SHORT": "yy/MM/dd HH:mm"
    }
  }
}

响应字段说明

字段名 类型 说明
code Integer 响应码，200 表示成功
msg String 响应消息
data Object 响应数据
data.dateFormats Object 常用日期格式列表
data.dateTimeFormats Object 常用日期时间格式列表

日期格式说明

格式代码 日期格式 日期时间格式 说明
ISO_8601 yyyy-MM-dd yyyy-MM-dd HH:mm:ss ISO 8601 标准格式
US MM/dd/yyyy MM/dd/yyyy HH:mm:ss 美国格式
EU dd/MM/yyyy dd/MM/yyyy HH:mm:ss 欧洲格式
CN yyyy年MM月dd日 yyyy年MM月dd日 HH:mm:ss 中国格式
JP yyyy/MM/dd yyyy/MM/dd HH:mm:ss 日本格式
KR yyyy. MM. dd. yyyy. MM. dd. HH:mm:ss 韩国格式
SHORT yy/MM/dd yy/MM/dd HH:mm 短格式
LONG yyyy年MM月dd日 EEEE yyyy年MM月dd日 EEEE HH:mm:ss 长格式
CUSTOM 自定义 自定义 自定义格式

错误响应

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

使用示例

示例 1：获取当前用户日期格式偏好

请求

GET /system/user/dateFormat
Authorization: Bearer {token}

响应

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "userId": 1,
    "dateFormat": "ISO_8601",
    "dateFormatPattern": null
  }
}

示例 2：切换用户日期格式偏好为美国格式

请求

POST /system/user/switchDateFormat
Authorization: Bearer {token}
Content-Type: application/json

{
  "dateFormat": "US",
  "dateFormatPattern": null
}

响应

{
  "code": 200,
  "msg": "操作成功"
}

示例 3：切换用户日期格式偏好为自定义格式

请求

POST /system/user/switchDateFormat
Authorization: Bearer {token}
Content-Type: application/json

{
  "dateFormat": "CUSTOM",
  "dateFormatPattern": "yyyy/MM/dd"
}

响应

{
  "code": 200,
  "msg": "操作成功"
}

示例 4：获取系统默认日期格式

请求

GET /system/config/defaultDateFormat
Authorization: Bearer {token}

响应

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "dateFormat": "yyyy-MM-dd",
    "dateTimeFormat": "yyyy-MM-dd HH:mm:ss"
  }
}

示例 5：获取常用日期格式列表

请求

GET /system/config/commonDateFormats
Authorization: Bearer {token}

响应

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "dateFormats": {
      "ISO_8601": "yyyy-MM-dd",
      "US": "MM/dd/yyyy",
      "EU": "dd/MM/yyyy",
      "CN": "yyyy年MM月dd日",
      "JP": "yyyy/MM/dd",
      "KR": "yyyy. MM. dd.",
      "SHORT": "yy/MM/dd"
    },
    "dateTimeFormats": {
      "ISO_8601": "yyyy-MM-dd HH:mm:ss",
      "US": "MM/dd/yyyy HH:mm:ss",
      "EU": "dd/MM/yyyy HH:mm:ss",
      "CN": "yyyy年MM月dd日 HH:mm:ss",
      "JP": "yyyy/MM/dd HH:mm:ss",
      "KR": "yyyy. MM. dd. HH:mm:ss",
      "SHORT": "yy/MM/dd HH:mm"
    }
  }
}

注意事项

1. 日期格式模式

  • 日期格式模式必须是预定义的格式之一（ISO_8601、US、EU、CN、JP、KR、SHORT、LONG、CUSTOM）
  • 当日期格式模式为 CUSTOM 时，必须提供自定义日期格式
  • 自定义日期格式必须符合 Java DateTimeFormatter 的格式规范

2. 缓存机制

  • 用户日期格式偏好使用 Redis 缓存，TTL 为 24 小时
  • 用户切换日期格式偏好时，缓存会立即清除
  • 获取用户日期格式偏好时，会优先从缓存中读取

3. 权限控制

  • 所有接口都需要登录
  • 用户只能设置和获取自己的日期格式偏好
  • 系统默认日期格式和常用日期格式列表对所有登录用户可见

4. 错误处理

  • 日期格式模式不能为空时，返回错误提示
  • 自定义日期格式不能为空时（当 dateFormat 为 CUSTOM 时），返回错误提示
  • 用户未登录时，返回 401 错误码

5. 时区转换

  • 日期格式化会结合时区转换功能，先进行时区转换，再进行日期格式化
  • 时区转换切面（TimeZoneConvertAspect）的执行顺序优先于日期格式化切面（DateFormatAspect）

6. 多语言支持

  • 日期格式化支持多语言日期显示（星期几、月份名称的本地化）
  • 根据用户语言偏好自动选择语言

相关文档

更新记录

版本 日期 更新内容 更新人
3.8.5 2026-01-25 初始版本 SSOT 架构师