datai/docs/archive/api-docs/system/2026-01-21-002-05-api-货币格式化.md

25 KiB
Raw Blame History

API 文档:货币格式化接口

元数据

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

API 概述

货币格式化接口提供了货币符号支持、小数位格式化、千分位分隔符、自动选择格式、自定义格式、多货币显示和实时汇率转换等功能。通过 AOP 在 Service 层统一处理货币格式化,根据用户货币偏好自动格式化货币数据。

接口列表


接口 1获取货币列表

功能描述

获取系统支持的货币列表,包括货币代码、货币符号、货币名称、小数位数、千分位分隔符等信息。

请求方式

GET

请求路径

/system/currency/list

权限要求

  • 无(通常公开或需登录)

请求参数

参数名 类型 必选 说明
currencyCode String 货币代码(如 CNY、USD
status String 状态0正常 1停用

请求示例

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

响应数据结构

参数名 类型 说明
code Integer 状态码200 成功500 失败)
msg String 提示信息
data Array 货币列表
data[].currencyCode String 货币代码(如 CNY、USD
data[].currencySymbol String 货币符号(如 ¥、$
data[].currencyName String 货币名称(如 人民币、美元)
data[].currencyNameEn String 货币英文名称(如 Chinese Yuan、US Dollar
data[].decimalPlaces Integer 小数位数(如 2
data[].thousandsSeparator String 千分位分隔符(如 ,
data[].decimalSeparator String 小数分隔符(如 .
data[].isDefault Boolean 是否默认货币
data[].sortOrder Integer 排序
data[].status String 状态0正常 1停用

响应示例

成功响应:

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "currencyCode": "CNY",
      "currencySymbol": "¥",
      "currencyName": "人民币",
      "currencyNameEn": "Chinese Yuan",
      "decimalPlaces": 2,
      "thousandsSeparator": ",",
      "decimalSeparator": ".",
      "isDefault": true,
      "sortOrder": 1,
      "status": "0"
    },
    {
      "currencyCode": "USD",
      "currencySymbol": "$",
      "currencyName": "美元",
      "currencyNameEn": "US Dollar",
      "decimalPlaces": 2,
      "thousandsSeparator": ",",
      "decimalSeparator": ".",
      "isDefault": false,
      "sortOrder": 2,
      "status": "0"
    },
    {
      "currencyCode": "EUR",
      "currencySymbol": "€",
      "currencyName": "欧元",
      "currencyNameEn": "Euro",
      "decimalPlaces": 2,
      "thousandsSeparator": ".",
      "decimalSeparator": ",",
      "isDefault": false,
      "sortOrder": 3,
      "status": "0"
    },
    {
      "currencyCode": "GBP",
      "currencySymbol": "£",
      "currencyName": "英镑",
      "currencyNameEn": "British Pound",
      "decimalPlaces": 2,
      "thousandsSeparator": ",",
      "decimalSeparator": ".",
      "isDefault": false,
      "sortOrder": 4,
      "status": "0"
    },
    {
      "currencyCode": "JPY",
      "currencySymbol": "¥",
      "currencyName": "日元",
      "currencyNameEn": "Japanese Yen",
      "decimalPlaces": 0,
      "thousandsSeparator": ",",
      "decimalSeparator": ".",
      "isDefault": false,
      "sortOrder": 5,
      "status": "0"
    }
  ]
}

失败响应:

{
  "code": 500,
  "msg": "获取货币列表失败",
  "data": null
}

错误码说明

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

业务规则

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

接口 2获取当前用户货币偏好

功能描述

获取当前登录用户的货币偏好,返回用户的货币代码、货币符号等信息。如果用户未设置货币,返回系统默认货币。

请求方式

GET

请求路径

/system/currency/current

权限要求

  • 无(需要登录)

请求参数

请求示例

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

响应数据结构

参数名 类型 说明
code Integer 状态码200 成功500 失败)
msg String 提示信息
data Object 货币信息
data.currencyCode String 货币代码(如 CNY、USD
data.currencySymbol String 货币符号(如 ¥、$
data.currencyName String 货币名称(如 人民币、美元)
data.currencyNameEn String 货币英文名称(如 Chinese Yuan、US Dollar
data.decimalPlaces Integer 小数位数
data.thousandsSeparator String 千分位分隔符
data.decimalSeparator String 小数分隔符
data.isDefault Boolean 是否系统默认货币

响应示例

成功响应(用户已设置货币):

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "currencyCode": "CNY",
    "currencySymbol": "¥",
    "currencyName": "人民币",
    "currencyNameEn": "Chinese Yuan",
    "decimalPlaces": 2,
    "thousandsSeparator": ",",
    "decimalSeparator": ".",
    "isDefault": false
  }
}

成功响应(用户未设置货币,返回系统默认货币):

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "currencyCode": "CNY",
    "currencySymbol": "¥",
    "currencyName": "人民币",
    "currencyNameEn": "Chinese Yuan",
    "decimalPlaces": 2,
    "thousandsSeparator": ",",
    "decimalSeparator": ".",
    "isDefault": true
  }
}

失败响应:

{
  "code": 500,
  "msg": "获取当前用户货币偏好失败",
  "data": null
}

错误码说明

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

业务规则

  1. 优先级:用户货币偏好 > 系统默认货币
  2. 如果用户未设置货币,返回系统默认货币
  3. 用户货币偏好使用 Redis 缓存,缓存时间 30 分钟
  4. 需要用户登录才能获取货币信息

接口 3切换货币

功能描述

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

请求方式

POST

请求路径

/system/currency/switch

权限要求

  • 无(需要登录)

请求参数

参数名 类型 必选 说明
currencyCode String 货币代码(如 CNY、USD、EUR

请求示例

curl -X POST 'http://localhost:8080/system/currency/switch' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "currencyCode": "USD"
  }'

响应数据结构

参数名 类型 说明
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/currency/default

权限要求

  • 无(通常公开或需登录)

请求参数

请求示例

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

响应数据结构

参数名 类型 说明
code Integer 状态码200 成功500 失败)
msg String 提示信息
data Object 货币信息
data.currencyCode String 货币代码(如 CNY
data.currencySymbol String 货币符号(如 ¥)
data.currencyName String 货币名称(如 人民币)
data.currencyNameEn String 货币英文名称(如 Chinese Yuan
data.decimalPlaces Integer 小数位数
data.thousandsSeparator String 千分位分隔符
data.decimalSeparator String 小数分隔符

响应示例

成功响应:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "currencyCode": "CNY",
    "currencySymbol": "¥",
    "currencyName": "人民币",
    "currencyNameEn": "Chinese Yuan",
    "decimalPlaces": 2,
    "thousandsSeparator": ",",
    "decimalSeparator": "."
  }
}

失败响应:

{
  "code": 500,
  "msg": "获取默认货币失败",
  "data": null
}

错误码说明

错误码 说明
200 获取成功
500 获取失败或未找到默认货币

业务规则

  1. 系统必须有默认货币配置
  2. 默认货币从数据库读取
  3. 默认货币使用 Redis 缓存,缓存时间 24 小时
  4. 默认货币用于用户未设置货币时的回退货币

接口 5获取汇率列表

功能描述

获取汇率列表,支持按源货币、目标货币进行筛选。返回实时汇率数据,包括汇率值、更新时间等信息。

请求方式

GET

请求路径

/system/currency/exchangeRate/list

权限要求

  • 无(通常公开或需登录)

请求参数

参数名 类型 必选 说明
sourceCurrency String 源货币代码(如 CNY
targetCurrency String 目标货币代码(如 USD
pageNum Integer 页码,默认 1
pageSize Integer 每页数量,默认 10

请求示例

curl -X GET 'http://localhost:8080/system/currency/exchangeRate/list?sourceCurrency=CNY&pageNum=1&pageSize=10' \
  -H 'Authorization: Bearer {token}'

响应数据结构

参数名 类型 说明
code Integer 状态码200 成功500 失败)
msg String 提示信息
rows Array 汇率列表
total Integer 总记录数
rows[].id Long 汇率ID
rows[].sourceCurrency String 源货币代码(如 CNY
rows[].targetCurrency String 目标货币代码(如 USD
rows[].exchangeRate BigDecimal 汇率值(如 0.145
rows[].updateTime String 更新时间

响应示例

成功响应:

{
  "code": 200,
  "msg": "查询成功",
  "rows": [
    {
      "id": 1,
      "sourceCurrency": "CNY",
      "targetCurrency": "USD",
      "exchangeRate": 0.145,
      "updateTime": "2024-01-26 10:00:00"
    },
    {
      "id": 2,
      "sourceCurrency": "CNY",
      "targetCurrency": "EUR",
      "exchangeRate": 0.132,
      "updateTime": "2024-01-26 10:00:00"
    },
    {
      "id": 3,
      "sourceCurrency": "CNY",
      "targetCurrency": "GBP",
      "exchangeRate": 0.114,
      "updateTime": "2024-01-26 10:00:00"
    },
    {
      "id": 4,
      "sourceCurrency": "CNY",
      "targetCurrency": "JPY",
      "exchangeRate": 21.5,
      "updateTime": "2024-01-26 10:00:00"
    }
  ],
  "total": 4
}

失败响应:

{
  "code": 500,
  "msg": "获取汇率列表失败",
  "data": null
}

错误码说明

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

业务规则

  1. 汇率数据从数据库读取
  2. 汇率数据使用 Redis 缓存,缓存时间 1 小时
  3. 汇率数据每小时自动更新一次
  4. 返回的汇率列表按更新时间降序排序

接口 6格式化货币

功能描述

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

请求方式

POST

请求路径

/system/currency/format

权限要求

  • 无(需要登录)

请求参数

参数名 类型 必选 说明
amount BigDecimal 金额数值
currencyCode String 货币代码(如 CNY、USD不传则使用用户货币偏好
decimalPlaces Integer 小数位数,不传则使用货币默认小数位数
thousandsSeparator String 千分位分隔符(如 ,、.、空格),不传则使用货币默认分隔符
decimalSeparator String 小数分隔符(如 .、,),不传则使用货币默认分隔符
showSymbol Boolean 是否显示货币符号(默认 true

请求示例

curl -X POST 'http://localhost:8080/system/currency/format' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 1234.56,
    "currencyCode": "USD",
    "decimalPlaces": 2,
    "thousandsSeparator": ",",
    "decimalSeparator": ".",
    "showSymbol": true
  }'

响应数据结构

参数名 类型 说明
code Integer 状态码200 成功400/500 失败)
msg String 提示信息
data Object 格式化结果
data.formattedAmount String 格式化后的金额(如 $1,234.56
data.currencyCode String 货币代码(如 USD
data.currencySymbol String 货币符号(如 $
data.decimalPlaces Integer 小数位数
data.thousandsSeparator String 千分位分隔符
data.decimalSeparator String 小数分隔符

响应示例

成功响应:

{
  "code": 200,
  "msg": "格式化成功",
  "data": {
    "formattedAmount": "$1,234.56",
    "currencyCode": "USD",
    "currencySymbol": "$",
    "decimalPlaces": 2,
    "thousandsSeparator": ",",
    "decimalSeparator": "."
  }
}

失败响应(无效的金额):

{
  "code": 400,
  "msg": "无效的金额",
  "data": null
}

失败响应(无效的货币代码):

{
  "code": 400,
  "msg": "无效的货币代码",
  "data": null
}

错误码说明

错误码 说明
200 格式化成功
400 无效的金额或货币代码
500 格式化失败

业务规则

  1. 如果未指定货币代码,使用用户货币偏好
  2. 如果未指定小数位数,使用货币默认小数位数
  3. 如果未指定分隔符,使用货币默认分隔符
  4. 小数位四舍五入
  5. 货币格式化时间 < 10ms

接口 7刷新汇率缓存

功能描述

刷新汇率缓存,清除所有汇率相关的缓存数据,使最新的汇率数据立即生效。

请求方式

DELETE

请求路径

/system/currency/refreshExchangeRateCache

权限要求

  • system:currency:refresh

请求参数

请求示例

curl -X DELETE 'http://localhost:8080/system/currency/refreshExchangeRateCache' \
  -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:currency:exchangeRate:list
  2. 清除所有汇率缓存sys:currency:exchangeRate:*
  3. 刷新后,下次查询时重新加载汇率数据

数据库表结构

sys_currency 表(货币配置表)

CREATE TABLE `sys_currency` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '货币ID',
  `currency_code` varchar(10) NOT NULL COMMENT '货币代码CNY、USD',
  `currency_symbol` varchar(10) NOT NULL COMMENT '货币符号(如:¥、$',
  `currency_name` varchar(50) NOT NULL COMMENT '货币名称(如:人民币)',
  `currency_name_en` varchar(50) NOT NULL COMMENT '货币英文名称Chinese Yuan',
  `decimal_places` int DEFAULT '2' COMMENT '小数位数',
  `thousands_separator` varchar(5) DEFAULT ',' COMMENT '千分位分隔符(如:,',
  `decimal_separator` varchar(5) DEFAULT '.' COMMENT '小数分隔符(如:.',
  `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_currency_code` (`currency_code`),
  KEY `idx_status` (`status`),
  KEY `idx_sort_order` (`sort_order`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT='货币配置表';

sys_exchange_rate 表(汇率数据表)

CREATE TABLE `sys_exchange_rate` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '汇率ID',
  `source_currency` varchar(10) NOT NULL COMMENT '源货币代码CNY',
  `target_currency` varchar(10) NOT NULL COMMENT '目标货币代码USD',
  `exchange_rate` decimal(20,8) NOT NULL COMMENT '汇率值',
  `update_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  `create_by` varchar(64) DEFAULT '' COMMENT '创建者',
  `create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_by` varchar(64) DEFAULT '' COMMENT '更新者',
  `remark` varchar(500) DEFAULT NULL COMMENT '备注',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_source_target` (`source_currency`, `target_currency`),
  KEY `idx_source_currency` (`source_currency`),
  KEY `idx_target_currency` (`target_currency`),
  KEY `idx_update_time` (`update_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT='汇率数据表';

sys_user 表修改(用户表)

ALTER TABLE `sys_user` 
ADD COLUMN `currency_code` varchar(10) DEFAULT 'CNY' COMMENT '货币代码' AFTER `time_zone`;

常用货币列表

货币代码 货币符号 货币名称 货币英文名称 小数位数 千分位分隔符 小数分隔符 是否默认
CNY ¥ 人民币 Chinese Yuan 2 , .
USD $ 美元 US Dollar 2 , .
EUR 欧元 Euro 2 . ,
GBP £ 英镑 British Pound 2 , .
JPY 日元 Japanese Yen 0 , .

货币格式化说明

货币格式化流程

货币格式化
  ├─ 读取用户货币偏好currency_code
  ├─ 读取系统默认货币配置
  ├─ 读取实时汇率数据
  ├─ Service 层 AOP 拦截返回值
  ├─ 识别 BigDecimal 类型字段
  ├─ 根据用户货币偏好和汇率进行格式化
  ├─ 支持单一货币显示¥100.00
  ├─ 支持多货币显示¥100.00 ($14.50, €13.20)
  └─ 返回格式化后的货币数据

货币格式化示例

// 示例:格式化货币金额
BigDecimal amount = new BigDecimal("1234.56");
String currencyCode = "USD";
int decimalPlaces = 2;
String thousandsSeparator = ",";
String decimalSeparator = ".";
boolean showSymbol = true;

DecimalFormat df = new DecimalFormat();
df.setMaximumFractionDigits(decimalPlaces);
df.setMinimumFractionDigits(decimalPlaces);
df.setGroupingUsed(true);
DecimalFormatSymbols symbols = df.getDecimalFormatSymbols();
symbols.setGroupingSeparator(thousandsSeparator.charAt(0));
symbols.setDecimalSeparator(decimalSeparator.charAt(0));
df.setDecimalFormatSymbols(symbols);

String formattedAmount = df.format(amount);
if (showSymbol) {
  formattedAmount = "$" + formattedAmount;
}

// 结果:$1,234.56

汇率转换说明

汇率转换流程

汇率转换
  ├─ 读取用户货币偏好currency_code
  ├─ 读取实时汇率数据
  ├─ 计算转换后的金额
  │  ├─ 源货币金额 × 汇率 = 目标货币金额
  │  └─ 四舍五入到指定小数位
  └─ 返回转换后的金额

汇率转换示例

// 示例:汇率转换
BigDecimal sourceAmount = new BigDecimal("100.00");
String sourceCurrency = "CNY";
String targetCurrency = "USD";
BigDecimal exchangeRate = new BigDecimal("0.145");

BigDecimal targetAmount = sourceAmount.multiply(exchangeRate);
targetAmount = targetAmount.setScale(2, RoundingMode.HALF_UP);

// 结果100.00 CNY = 14.50 USD

缓存策略

缓存键格式

  • 货币列表:sys:currency:list
  • 用户货币:user:currency:{userId}
  • 汇率列表:sys:currency:exchangeRate:list
  • 汇率:sys:currency:exchangeRate:{sourceCurrency}:{targetCurrency}

缓存时间

  • 货币列表缓存24 小时
  • 用户货币缓存30 分钟
  • 汇率列表缓存1 小时
  • 汇率缓存1 小时

缓存刷新规则

  1. 货币列表更新时,清除货币列表缓存
  2. 货币切换时,清除用户货币缓存
  3. 汇率数据更新时,清除汇率缓存
  4. 手动刷新汇率缓存时,清除所有汇率相关缓存

AOP 统一处理说明

AOP 切面设计

@Aspect
@Component
public class CurrencyFormatAspect {
    
    @Autowired
    private CurrencyFormatService currencyFormatService;
    
    @AfterReturning(pointcut = "@annotation(com.datai.common.annotation.CurrencyFormat)", returning = "result")
    public void formatCurrency(JoinPoint joinPoint, Object result) {
        if (result == null) {
            return;
        }
        
        Object formattedResult = currencyFormatService.formatObject(result);
        return formattedResult;
    }
}

AOP 使用示例

@Service
public class OrderServiceImpl implements IOrderService {
    
    @CurrencyFormat
    @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. 审计日志:记录货币设置变更日志

性能要求

  • 货币格式化时间< 10ms
  • 货币切换响应时间< 500ms
  • 汇率转换时间< 10ms
  • 缓存命中率:≥ 95%

相关文档