datai/docs/archive/api-docs/system/2026-01-21-002-07-05-api-格式化数字.md

API 文档：格式化数字接口

元数据

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

接口概述

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

接口详情

基本信息

• 接口名称：格式化数字
• 接口描述：根据用户数字格式偏好格式化数字
• 请求方式：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
}

业务规则

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

性能要求

• 响应时间：< 1ms
• 格式化精度：支持最多 16 位小数

相关文档

• 需求文档
• 设计文档