kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
datai/docs/archive/api-docs/system/2026-01-21-002-07-api-数字格式化.md

20 KiB
Raw Permalink Blame History

API 文档：数字格式化接口

元数据

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

API 概述

数字格式化接口提供了千分位分隔符、小数位格式化、自动选择格式、自定义格式、后端数字格式化（NumberFormat 和 DecimalFormat）、AOP 自动格式化、Redis 缓存机制、配置管理等功能。通过 AOP 在 Service 层统一处理数字格式化，根据用户数字格式偏好自动格式化数字数据。

接口列表

接口 1：获取数字格式列表

功能描述

获取系统支持的数字格式列表，包括数字格式代码、数字格式名称、千分位分隔符、小数位等信息。

请求方式

GET

请求路径

/system/numberFormat/list

权限要求

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

请求参数

参数名 类型 必选 说明
formatCode String 否 数字格式代码（如 COMMA、DOT、SPACE）
status String 否 状态（0正常 1停用）

请求示例

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

响应数据结构

参数名 类型 说明
code Integer 状态码（200 成功，500 失败）
msg String 提示信息
data Array 数字格式列表
data[].formatCode String 数字格式代码（如 COMMA、DOT、SPACE）
data[].formatName String 数字格式名称（如 逗号分隔）
data[].formatNameEn String 数字格式英文名称（如 Comma Separator）
data[].thousandsSeparator String 千分位分隔符（如 ,、.、 ）
data[].decimalSeparator String 小数分隔符（如 .、,）
data[].decimalPlaces Integer 小数位（如 2、3、4）
data[].isDefault Boolean 是否默认格式
data[].sortOrder Integer 排序
data[].status String 状态（0正常 1停用）

响应示例

成功响应：

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "formatCode": "COMMA",
      "formatName": "逗号分隔",
      "formatNameEn": "Comma Separator",
      "thousandsSeparator": ",",
      "decimalSeparator": ".",
      "decimalPlaces": 2,
      "isDefault": true,
      "sortOrder": 1,
      "status": "0"
    },
    {
      "formatCode": "DOT",
      "formatName": "点分隔",
      "formatNameEn": "Dot Separator",
      "thousandsSeparator": ".",
      "decimalSeparator": ",",
      "decimalPlaces": 2,
      "isDefault": false,
      "sortOrder": 2,
      "status": "0"
    },
    {
      "formatCode": "SPACE",
      "formatName": "空格分隔",
      "formatNameEn": "Space Separator",
      "thousandsSeparator": " ",
      "decimalSeparator": ".",
      "decimalPlaces": 2,
      "isDefault": false,
      "sortOrder": 3,
      "status": "0"
    }
  ]
}

失败响应：

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

错误码说明

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

业务规则

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

接口 2：获取当前用户数字格式偏好

功能描述

获取当前登录用户的数字格式偏好，返回用户的数字格式代码、千分位分隔符、小数位等信息。如果用户未设置数字格式，返回系统默认数字格式。

请求方式

GET

请求路径

/system/user/numberFormat

权限要求

  • 无（需要登录）

请求参数

无

请求示例

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

响应数据结构

参数名 类型 说明
code Integer 状态码（200 成功，500 失败）
msg String 提示信息
data Object 数字格式信息
data.numberFormat String 数字格式代码（如 COMMA、DOT、SPACE）
data.formatName String 数字格式名称（如 逗号分隔）
data.formatNameEn String 数字格式英文名称（如 Comma Separator）
data.thousandsSeparator String 千分位分隔符（如 ,、.、 ）
data.decimalSeparator String 小数分隔符（如 .、,）
data.decimalPlaces Integer 小数位（如 2、3、4）
data.isDefault Boolean 是否系统默认格式

响应示例

成功响应（用户已设置数字格式）：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "numberFormat": "COMMA",
    "formatName": "逗号分隔",
    "formatNameEn": "Comma Separator",
    "thousandsSeparator": ",",
    "decimalSeparator": ".",
    "decimalPlaces": 2,
    "isDefault": false
  }
}

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

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "numberFormat": "COMMA",
    "formatName": "逗号分隔",
    "formatNameEn": "Comma Separator",
    "thousandsSeparator": ",",
    "decimalSeparator": ".",
    "decimalPlaces": 2,
    "isDefault": true
  }
}

失败响应：

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

错误码说明

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

业务规则

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

接口 3：切换数字格式

功能描述

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

请求方式

POST

请求路径

/system/user/switchNumberFormat

权限要求

  • 无（需要登录）

请求参数

参数名 类型 必选 说明
numberFormat String 是 数字格式代码（如 COMMA、DOT、SPACE）
decimalPlaces Integer 否 小数位（如 2、3、4），不传则使用默认值 2

请求示例

curl -X POST 'http://localhost:8080/system/user/switchNumberFormat' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "numberFormat": "DOT",
    "decimalPlaces": 3
  }'

响应数据结构

参数名 类型 说明
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. 数字格式切换响应时间 < 100ms

接口 4：获取系统默认数字格式

功能描述

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

请求方式

GET

请求路径

/system/numberFormat/default

权限要求

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

请求参数

无

请求示例

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

响应数据结构

参数名 类型 说明
code Integer 状态码（200 成功，500 失败）
msg String 提示信息
data Object 数字格式信息
data.numberFormat String 数字格式代码（如 COMMA、DOT、SPACE）
data.formatName String 数字格式名称（如 逗号分隔）
data.formatNameEn String 数字格式英文名称（如 Comma Separator）
data.thousandsSeparator String 千分位分隔符（如 ,、.、 ）
data.decimalSeparator String 小数分隔符（如 .、,）
data.decimalPlaces Integer 小数位（如 2、3、4）

响应示例

成功响应：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "numberFormat": "COMMA",
    "formatName": "逗号分隔",
    "formatNameEn": "Comma Separator",
    "thousandsSeparator": ",",
    "decimalSeparator": ".",
    "decimalPlaces": 2
  }
}

失败响应：

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

错误码说明

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

业务规则

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

接口 5：格式化数字

功能描述

根据用户数字格式偏好格式化数字，返回格式化后的数字字符串。支持自定义数字格式，包括千分位分隔符、小数位格式化等。

请求方式

POST

请求路径

/system/numberFormat/format

权限要求

  • 无（需要登录）

请求参数

参数名 类型 必选 说明
number Number 是 数字（如 1234.5678）
numberFormat String 否 数字格式代码（如 COMMA、DOT、SPACE），不传则使用用户数字格式偏好
decimalPlaces Integer 否 小数位（如 2、3、4），不传则使用用户小数位偏好
usePercentage Boolean 否 是否使用百分比格式（默认 false）

请求示例

curl -X POST 'http://localhost:8080/system/numberFormat/format' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "number": 1234.5678,
    "numberFormat": "COMMA",
    "decimalPlaces": 2,
    "usePercentage": false
  }'

响应数据结构

参数名 类型 说明
code Integer 状态码（200 成功，400/500 失败）
msg String 提示信息
data Object 格式化结果
data.formattedNumber String 格式化后的数字（如 1,234.57）
data.numberFormat String 数字格式代码（如 COMMA、DOT、SPACE）
data.thousandsSeparator String 千分位分隔符（如 ,、.、 ）
data.decimalSeparator String 小数分隔符（如 .、,）
data.decimalPlaces Integer 小数位（如 2、3、4）
data.usePercentage Boolean 是否使用百分比格式

响应示例

成功响应：

{
  "code": 200,
  "msg": "格式化成功",
  "data": {
    "formattedNumber": "1,234.57",
    "numberFormat": "COMMA",
    "thousandsSeparator": ",",
    "decimalSeparator": ".",
    "decimalPlaces": 2,
    "usePercentage": false
  }
}

失败响应（无效的数字）：

{
  "code": 400,
  "msg": "无效的数字",
  "data": null
}

失败响应（无效的数字格式代码）：

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

错误码说明

错误码 说明
200 格式化成功
400 无效的数字或数字格式代码
500 格式化失败

业务规则

  1. 如果未指定数字格式，使用用户数字格式偏好
  2. 如果未指定小数位，使用用户小数位偏好
  3. 小数位四舍五入
  4. 支持整数、浮点数、大数字格式化
  5. 支持负数格式化
  6. 支持百分比格式化
  7. 数字格式化时间 < 1ms

接口 6：刷新数字格式缓存

功能描述

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

请求方式

DELETE

请求路径

/system/numberFormat/refreshCache

权限要求

  • system:numberFormat:refresh

请求参数

无

请求示例

curl -X DELETE 'http://localhost:8080/system/numberFormat/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:numberFormat:list）
  2. 清除用户数字格式缓存（sys:numberFormat:{userId}）
  3. 刷新后，下次查询时重新加载数字格式数据

数据库表结构

sys_user 表修改（用户表）

ALTER TABLE `sys_user` 
ADD COLUMN `number_format` varchar(50) DEFAULT NULL COMMENT '数字格式（COMMA、DOT、SPACE）' AFTER `date_format_pattern`,
ADD COLUMN `decimal_places` int DEFAULT NULL COMMENT '小数位（2、3、4）' AFTER `number_format`;

常用数字格式列表

数字格式代码 数字格式名称 数字格式英文名称 千分位分隔符 小数分隔符 小数位 是否默认
COMMA 逗号分隔 Comma Separator , . 2 是
DOT 点分隔 Dot Separator . , 2 否
SPACE 空格分隔 Space Separator . 2 否

数字格式化说明

数字格式化流程

数字格式化
  ├─ 读取用户数字格式偏好（number_format）
  ├─ 读取用户小数位偏好（decimal_places）
  ├─ 读取系统默认数字格式配置
  ├─ 根据用户数字格式偏好格式化数字
  │  ├─ 使用 NumberFormat 进行标准格式化
  │  ├─ 使用 DecimalFormat 进行自定义格式化
  │  ├─ 添加千分位分隔符
  │  ├─ 格式化小数位（四舍五入）
  │  └─ 支持负数格式化
  └─ 返回格式化后的数字

数字格式化示例

// 示例：格式化数字
double number = 1234.5678;
String numberFormat = "COMMA";
int decimalPlaces = 2;

// 创建 DecimalFormat
DecimalFormatSymbols symbols = DecimalFormatSymbols.getInstance();
symbols.setGroupingSeparator(',');
symbols.setDecimalSeparator('.');

String pattern = "#,##0." + String.format("%0" + decimalPlaces + "d", 0).replace("0", "0");
DecimalFormat decimalFormat = new DecimalFormat(pattern, symbols);

// 格式化数字
String formattedNumber = decimalFormat.format(number);

// 结果：1,234.57

多语言数字显示说明

多语言数字显示流程

多语言数字显示
  ├─ 读取用户语言偏好（lang_code）
  ├─ 读取系统默认语言配置
  ├─ 根据用户语言偏好显示数字
  │  ├─ 中文：逗号分隔（1,234.56）
  │  ├─ 英文：逗号分隔（1,234.56）
  │  ├─ 德文：点分隔（1.234,56）
  │  └─ 法文：空格分隔（1 234,56）
  └─ 返回格式化后的数字

多语言数字显示示例

// 示例：多语言数字显示
double number = 1234.5678;
String locale = "zh_CN";
int decimalPlaces = 2;

// 创建 NumberFormat
NumberFormat numberFormat = NumberFormat.getNumberInstance(Locale.forLanguageTag(locale));
numberFormat.setMinimumFractionDigits(decimalPlaces);
numberFormat.setMaximumFractionDigits(decimalPlaces);

// 格式化数字
String formattedNumber = numberFormat.format(number);

// 中文：1,234.57
// 英文：1,234.57
// 德文：1.234,57
// 法文：1 234,57

缓存策略

缓存键格式

  • 数字格式列表：sys:numberFormat:list
  • 用户数字格式：sys:numberFormat:{userId}

缓存时间

  • 数字格式列表缓存：24 小时
  • 用户数字格式缓存：24 小时

缓存刷新规则

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

AOP 统一处理说明

AOP 切面设计

@Aspect
@Component
public class NumberFormatAspect {
    
    @Autowired
    private NumberFormatService numberFormatService;
    
    @AfterReturning(pointcut = "@annotation(com.datai.common.annotation.NumberFormat)", returning = "result")
    public void formatNumber(JoinPoint joinPoint, Object result) {
        if (result == null) {
            return;
        }
        
        Object formattedResult = numberFormatService.formatObject(result);
        return formattedResult;
    }
}

AOP 使用示例

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

注意事项

  1. 数字格式验证：切换数字格式时，必须验证数字格式代码的有效性
  2. 数字格式化：数字格式化在 Service 层通过 AOP 统一处理
  3. 数字存储：所有数字字段使用 BigDecimal 类型存储，避免精度丢失
  4. 小数位四舍五入：数字小数位四舍五入
  5. 缓存管理：数字格式和用户数字格式需要缓存，提高性能
  6. 页面刷新：数字格式切换后立即刷新页面，重新加载数字数据
  7. 数字格式列表：数字格式列表固定存储在配置文件中，后续不允许用户调整
  8. 多语言数字显示：根据用户语言偏好显示数字（如中文逗号分隔、德文点分隔、法文空格分隔）
  9. 权限控制：所有用户都可以设置和切换数字格式
  10. 审计日志：记录数字格式设置变更日志
  11. 线程安全：NumberFormat 和 DecimalFormat 是线程安全的，可以在多线程环境下安全使用
  12. 格式验证：用户输入的数字格式必须经过验证，防止注入攻击

性能要求

  • 数字格式化时间：< 1ms
  • 数字格式切换响应时间：< 100ms
  • 缓存命中率：≥ 90%

相关文档