精度丢失的根源：number_format设置
freemarker在将数字类型转换为字符串类型进行输出时，会默认应用当前的number_format设置。这个设置通常在配置文件（如freemarker.properties）或模板环境中进行全局配置，例如number_format=0.###、number_format=#,##0.00等。这些格式化规则主要用于面向用户展示的数字，以提高可读性。当数字被格式化为字符串时，如果其小数位数超过了number_format所允许的精度，就会发生四舍五入或截断。
考虑以下示例代码，它展示了原始问题中可能导致精度丢失的场景：
<#-- 假设a.value为 "-1.234567" -->
<#if a.value?is_string>
<#-- 将字符串转换为数字 -->
<#assign numericValue = a.value?number>
<#if numericValue < 0>
<#-- 这里，numericValue?abs会得到内部数字1.234567，
但当它通过 ${...} 转换为字符串输出时，会受number_format影响 -->
"aValue": "${numericValue?abs}"
<#else>
<#-- 同理，如果a.value是"1.234567"，这里也会受number_format影响 -->
"aValue": "${numericValue}"
在上述代码中，当a.value为-1.234567时，numericValue?abs会得到内部数字1.234567。但当这个数字被${...}语法转换为字符串输出时，Freemarker会应用当前的number_format设置。如果number_format被设置为"0.###"（表示最多三位小数），那么1.234567就会被格式化为1.235，从而导致精度丢失。
解决方案：使用?c内置函数保留精度
为了避免这种由格式化引起的精度丢失，并确保数字以一致的、机器可读的格式输出，Freemarker提供了?c（computer-friendly）内置函数。
当数字使用?c进行格式化时，它将遵循以下规则：
- 始终使用点（.）作为小数分隔符，不受Locale影响。
- 绝不使用分组分隔符（如千位分隔符，例如3,000,000会输出为3000000）。
- 会显示最多16位小数，足以满足大多数高精度需求，避免不必要的四舍五入。
因此，正确的做法是在输出数字时明确指定?c，尤其是在生成JSON、CSV、XML或其他需要精确数字表示的数据时。
以下是使用?c修正后的代码示例：
<#-- 假设a.value为 "-1.234567" 或 "1.234567" -->
<#if a.value?is_string>
<#-- 确保将字符串转换为数字后，在输出时使用?c保留精度 -->
<#assign numericValue = a.value?number>
<#-- 无论数字是正数还是负数，都通过?c来确保输出精度 -->
<#if numericValue < 0>
"aValue": "${numericValue?abs?c}" <-- 使用?abs?c确保绝对值和精度
<#else>
"aValue": "${numericValue?c}" <-- 即使是正数，也建议使用?c保持一致性
<#else>
<#-- 处理a.value不是字符串的情况，或根据业务逻辑进行其他处理 -->
"aValue": "Invalid Input"
在这个修正后的示例中，无论numericValue是正数还是负数，其绝对值或本身在转换为字符串输出时，都会通过?c来保证完整精度。例如，当a.value是-1.234567时，numericValue?abs?c将正确输出1.234567，而不是1.235。
深入理解 number_format 与 ?c
Freemarker的number_format设置通常用于控制数字在面向用户界面中的显示方式，使其符合特定地域文化的习惯，提高可读性。例如，在某些地区，千位分隔符是逗号，小数分隔符是点；而在另一些地区，则可能相反。
而?c则提供了一种绕过这些用户友好格式的机制。它强制使用一种对计算机程序更友好的、无歧义的格式。这对于API响应、数据导出（如生成JSON、CSV文件）、数据库导入/导出等场景至关重要，因为这些场景下数据的精确性和一致性远比美观性更重要。当其他程序需要解析这些数字字符串时，?c格式能够确保解析的准确性，避免因格式差异导致的错误。
注意事项
- 何时使用 ?c： 当你需要输出的数字将被其他程序解析、用于数据交换（如JSON、XML），或要求高精度、无歧义的表示时，务必使用?c。
- 何时使用默认格式： 当数字是为最终用户展示，且需要根据地域文化（Locale）进行格式化时，可以使用默认的格式化（即不加?c，让number_format生效）。
- ?number的纯粹性： 再次强调，?number本身是一个解析操作，它将字符串转换为Freemarker内部的数字类型（通常是Java的BigDecimal或Double），这个过程不会引入舍入。所有舍入都是在数字类型转换为字符串类型时，由number_format或缺乏?c导致。
- 字符串到数字的健壮性： 在实际应用中，如果a.value可能不是一个合法的数字字符串，a.value?number可能会抛出TemplateModelException。为了增强模板的健壮性，应考虑在转换前使用a.value?is_number进行判断，或者结合default内置函数来提供默认值，例如${a.value?number!0}。
总结
Freemarker在处理数字精度问题上提供了清晰的机制。理解?number、?abs等操作符与number_format、?c等格式化选项之间的关系是关键。当需要确保数字在转换为字符串时保持完整精度并适用于机器解析时，?c是你的首选工具。通过正确使用?c，可以避免不必要的精度丢失，保证数据传输的准确性，从而构建出更健壮、更可靠的Freemarker模板。
