购物车显示五十二元四角七分,接口却返回五十二元四角八分;某条商品退款后,剩余订单金额又差了一分。遇到这类问题,直接把所有数字调用一次保留两位小数,通常只能让页面看起来正常,无法解释后端、账单和数据库为什么不一致。
本文实现一个可以在本地运行的人民币报价计算器。它接受单价、数量和减免比例,按明确规则生成逐行金额与订单汇总。重点是把输入、计算、传输和持久化之间的精度边界接起来,而不是演示一套真实收款系统。示例不会创建订单、不会调用支付平台,也不包含税务计算。
一、先决定业务规则,再选择数字类型
本实验只处理人民币,最小单位为分,单价最多两位小数,数量只能是正整数。减免比例使用基点字符串表示:一万基点代表全部减免,一千二百五十基点代表减免百分之十二点五。注意这里输入的是“减掉多少”,不是“保留多少”;把八折误传成减免百分之八十,即使每一步运算都精确,结果仍然是错的。
计算顺序固定为:单价换算成分,乘以数量得到行原价;行原价乘减免基点,以一万为分母做非负数四舍五入,得到行优惠;行原价减去行优惠得到行实付;最后分别汇总各行。本文采用逐行舍入,不采用整单只舍入一次。这个决定属于报价契约,应与产品、财务及下游系统确认,不能让不同开发者各自选择。
例如两条独立商品行,每行一分钱,各减免百分之五十。逐行把半分钱优惠舍入为一分钱,总优惠就是两分钱;如果先将两行合并,总价两分钱的一半只有一分钱。两种结果都能来自精确运算,差异在舍入时机。真实系统还需要定义相同商品能否拆行,防止用户通过拆行改变优惠。示例允许独立行,目的是暴露这个规则,不是建议直接采用它做电商促销。
本实验的行身份不包含商品编号,因此相同内容的两行不会自动合并。生产购物车应由后端根据商品、规格、价格版本和优惠资格整理计价行,再执行规则。不能简单按单价合并,因为同价商品可能适用不同优惠;也不能完全相信前端传来的分组,否则计价策略会被页面操作左右。
二、避免在入口处已经丢掉精度
接口里的单价、数量和基点全部采用字符串。收到单价后先检查十进制格式,再分别解析整数部分与小数部分,直接构造整数分。中途不经过浮点数,不使用先转数字再乘一百的路线,也不通过宽松解析函数悄悄接受带单位的尾部字符。
格式规则刻意严格:允许零、普通整数、一位或两位小数;拒绝负数、前导零、指数形式、空白、千位分隔符以及三位小数。对于一元零五厘这样的输入,系统要求调用方先明确处理策略,而不是在进入业务计算之前悄悄舍入。输入格式如果需要支持不同地区的小数点,应在展示层明确转换,并向用户确认含义,不能把逗号既解释为小数点又解释为分组符。
使用整数分并不自动意味着普通数字类型足够。JavaScript 的安全整数上限为9,007,199,254,740,991;超过这个范围后,整数之间可能无法逐一准确区分。本文在代码中始终使用 BigInt,响应则转换成十进制字符串,避免把大金额重新塞回 JSON 数字。MDN 的安全整数说明给出了上限与原因。
需要特别注意的是,BigInt 的除法会截去余数,并且不能直接使用默认 JSON 序列化。示例通过整数公式显式实现舍入,逐个字段转成字符串。不要为了让响应成功就把 BigInt 转回 Number,也不建议全局修改序列化行为来隐藏类型问题,因为其他接口可能并不采用相同的金额契约。MDN 的 BigInt 文档说明了这些语言行为。
三、纯计算模块:金额规则只放一个地方
本次实测环境为 Node.js v24.22.1,不安装第三方依赖。建立空目录,保存下文四个文件:money.mjs、server.mjs、index.html、test.mjs。这里固定的是复现实验版本,不声称它是最新版本。生产部署应采用团队当前支持、已修补的运行时,并把版本写入构建配置。
下面保存为 money.mjs。单价最多十位整数,数量最多一万,最多一百行。上限既限制业务范围,也防止有人提交百万位数字消耗解析与乘法资源。所有对象采用精确字段集合,前端额外传入 total 等字段会被拒绝,避免调用方误以为这些字段参与了服务端计算。
export const POLICY = 'cny-line-discount-v1';
export function amount(s) {
if (typeof s !== 'string' || s.length > 13 || !/^(0|[1-9]\d{0,9})(\.\d{1,2})?$/.test(s)) throw new Error('invalid amount');
const [a, b = ''] = s.split('.');
return BigInt(a) * 100n + BigInt(b.padEnd(2, '0'));
}
export function whole(s, max, field) {
if (typeof s !== 'string' || s.length > 5 || !/^(0|[1-9]\d*)$/.test(s)) throw new Error(`invalid ${field}`);
const n = BigInt(s);
if (n > max) throw new Error(`invalid ${field}`);
return n;
}
export function roundHalfUp(n, d) {
if (n < 0n || d <= 0n) throw new Error('nonnegative numerator required');
return (n + d / 2n) / d;
}
export function display(cents) {
return `${cents / 100n}.${String(cents % 100n).padStart(2, '0')}`;
}
function shape(o, keys) {
if (!o || typeof o !== 'object' || Array.isArray(o) ||
Object.keys(o).sort().join(',') !== [...keys].sort().join(',')) throw new Error('invalid fields');
}
export function quote(data) {
shape(data, ['currency', 'discountBps', 'lines']);
if (data.currency !== 'CNY') throw new Error('unsupported currency');
const bps = whole(data.discountBps, 10000n, 'discount');
if (!Array.isArray(data.lines) || data.lines.length < 1 || data.lines.length > 100) throw new Error('invalid lines');
let subtotal = 0n, discount = 0n;
const lines = data.lines.map(line => {
shape(line, ['unit', 'quantity']);
const unit = amount(line.unit), qty = whole(line.quantity, 10000n, 'quantity');
if (qty === 0n) throw new Error('invalid quantity');
const gross = unit * qty, reduction = roundHalfUp(gross * bps, 10000n);
subtotal += gross; discount += reduction;
return { grossMinor: String(gross), discountMinor: String(reduction), netMinor: String(gross - reduction) };
});
const total = subtotal - discount;
return { currency: 'CNY', policy: POLICY, lines, subtotalMinor: String(subtotal),
discountMinor: String(discount), totalMinor: String(total), total: display(total) };
}
舍入函数只支持非负分子和正分母。本文实际传入的分母固定为一万,所以给分子加五千再做整数除法,恰好实现半数向上的规则。不要把这个函数未经重新定义就拿去处理负金额。负数退款需要明确是复用原交易分摊结果,还是重新计算负向金额;两者在半分边界可能不同。
返回值保留原价、优惠和实付三个组成部分,而不是只返回最终金额。这样可以检查“实付加优惠等于原价”的不变量,也能在后续对账时知道差异产生在哪一步。policy 字段标识计价规则版本,未来改成整单舍入、增加满减或改变合并规则,都应生成新版本,不能用新规则重新解释已经确认的历史订单。
示例的金额上限刻意大于普通数字的安全整数范围,便于测试精度链路;它并不代表真实业务应该允许这么高的订单额度。真正的限额应在身份、币种、商品和业务场景校验后进一步收紧。技术类型容得下某个值,与业务允许接受这个值,是两个独立检查。
四、HTTP 接口:报价可以公开实验,成交必须另行授权
保存下面的 server.mjs。服务只监听回环地址,同时提供页面和报价接口,因此本地无需跨源配置。接口只做纯计算,限制请求体为十六 KiB,要求 JSON,拒绝未知路径。超出限制后不再保存后续正文,避免内存继续增长;生产入口仍要有连接数、速率和请求时间限制,不能只依赖应用层字节计数。
import http from 'node:http';
import { readFile } from 'node:fs/promises';
import { quote } from './money.mjs';
const html = await readFile(new URL('./index.html', import.meta.url));
const send = (res, status, value) => {
res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' });
res.end(JSON.stringify(value));
};
const server = http.createServer((req, res) => {
if (req.method === 'GET' && req.url === '/') {
res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' });
return res.end(html);
}
if (req.method !== 'POST' || req.url !== '/quote') {
req.resume(); return send(res, 404, { error: 'not found' });
}
if (req.headers['content-type']?.split(';')[0].trim() !== 'application/json') {
req.resume(); return send(res, 415, { error: 'JSON required' });
}
let size = 0, chunks = [], done = false;
req.on('data', chunk => {
size += chunk.length;
if (size > 16384) {
if (!done) { done = true; chunks = []; send(res, 413, { error: 'body too large' }); }
} else if (!done) chunks.push(chunk);
});
req.on('end', () => {
if (done) return;
try { send(res, 200, quote(JSON.parse(Buffer.concat(chunks).toString('utf8')))); }
catch (e) { send(res, 400, { error: e.message }); }
});
req.on('error', () => { done = true; chunks = []; });
});
server.requestTimeout = 10000;
server.headersTimeout = 5000;
server.listen(3000, '127.0.0.1', () => console.log('http://127.0.0.1:3000'));
这里把校验异常返回为四百状态码,供读者理解失败分支。正式服务应给不同错误定义稳定代码,例如格式错误、行数超限或币种不支持,展示层再映射成本地化文案;对于数据库、网络或内部异常,只返回不泄露内部细节的错误描述,并在服务端记录关联编号。
这个接口允许用户输入任意单价,所以只能作为计算器。真实下单接口必须根据经过授权的商品标识,在服务端读取价格与优惠资格,再生成权威报价。客户端看到的五十二元四角七分不能成为扣款依据,也不能通过多传一个 total 字段改变成交金额。只共享计算函数、不共享可信数据来源,仍然会造成价格篡改漏洞。
如果要把报价转为订单,应保存报价编号、用户归属、商品与价格版本、规则版本、有效期限和最终分摊结果。确认时重新验证这些条件,明确涨价、优惠失效或库存不足如何反馈。本文没有实现这一步,所以一次成功的计算响应不代表锁价,也不代表预留库存,更不代表任何付款承诺。
五、浏览器保留原始文本,旧响应不能覆盖新输入
保存 index.html。输入框使用文本值,inputmode 仅提示移动端键盘类型,不构成有效性校验;服务端仍需逐项检查。页面不会先把字符串转换成数字,也不会自行重算最终金额。金额展示完全采用服务端返回的十进制文本,减少两套算法逐渐分叉的风险。MDN 的 inputmode 文档明确区分了输入提示和约束。
<!doctype html><meta charset="utf-8"><title>整数报价实验</title>
<form id="form">
<label>单价(元)<input id="unit" inputmode="decimal" value="19.99" required></label>
<label>数量<input id="qty" inputmode="numeric" value="3" required></label>
<label>减免基点<input id="bps" inputmode="numeric" value="1250" required></label>
<button>计算报价</button></form><pre id="out" aria-live="polite"></pre>
<script type="module">
const form = document.querySelector('#form'), out = document.querySelector('#out');
let generation = 0, controller;
form.addEventListener('input', () => {
generation++; controller?.abort(); out.textContent = '输入已变化,请重新计算。';
});
form.onsubmit = async event => {
event.preventDefault();
const mine = ++generation;
controller?.abort(); controller = new AbortController();
const data = { currency: 'CNY', discountBps: document.querySelector('#bps').value,
lines: [{ unit: document.querySelector('#unit').value, quantity: document.querySelector('#qty').value }] };
out.textContent = '计算中……';
try {
const response = await fetch('/quote', { method: 'POST', signal: controller.signal,
headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(data) });
const result = await response.json();
if (mine !== generation) return;
out.textContent = response.ok ? JSON.stringify(result, null, 2) : `校验失败:${result.error}`;
} catch (e) {
if (mine === generation) out.textContent = '请求失败,请重试;没有创建订单或扣款。';
}
};
</script>
页面同时使用请求取消和递增序号。修改任意输入时,旧请求会被取消,展示区提示重新计算;即使旧请求的响应已经进入回调,也必须通过序号检查才允许展示。只在再次提交时更新序号还不够,因为用户可能改完输入后没有再次提交,此时旧报价也不应该继续被当作当前报价。
取消请求只节约客户端等待,不保证服务端停止计算。这里没有状态写入,因此重复请求和取消都不会创建订单。将来如果接入写操作,必须单独设计请求结果未知、幂等与状态查询,不能把 AbortController 当作事务回滚。为了保持本文范围清晰,计算按钮不承担任何成交含义。
六、运行、调用与可核验的测试
进入文件目录启动服务,另开终端执行测试。浏览器访问回环地址即可看到表单,默认单价十九元九角九分、数量三、减免一千二百五十基点。预期原价为五千九百九十七分,优惠为七百五十分,实付为五千二百四十七分,展示五十二元四角七分。
node --version
node server.mjs
# 在另一个终端,进入相同目录
node test.mjs
curl -s http://127.0.0.1:3000/quote \
-H 'Content-Type: application/json' \
--data '{"currency":"CNY","discountBps":"1250","lines":[{"unit":"19.99","quantity":"3"}]}'
下面是完整 test.mjs。测试除了普通报价,还主动检查半分边界、全部减免、零单价、非法格式、超大整数与逐行舍入差异。生成的一万组案例检查基本不变量,但不是穷举证明,也不取代业务规则审查。
import assert from 'node:assert/strict';
import { amount, quote, roundHalfUp, display } from './money.mjs';
let count = 0;
const check = (name, fn) => { fn(); console.log('PASS', ++count, name); };
const input = (unit='19.99', quantity='3', discountBps='1250') => ({currency:'CNY',discountBps,lines:[{unit,quantity}]});
check('exact decimal conversion',()=>assert.equal(amount('0.29'),29n));
check('one decimal padding',()=>assert.equal(amount('1.2'),120n));
check('quote example',()=>{ const r=quote(input()); assert.equal(r.subtotalMinor,'5997'); assert.equal(r.discountMinor,'750'); assert.equal(r.total,'52.47'); });
check('half cent goes up',()=>assert.equal(roundHalfUp(5000n,10000n),1n));
check('below half stays down',()=>assert.equal(roundHalfUp(4999n,10000n),0n));
check('full discount',()=>assert.equal(quote(input('1','1','10000')).total,'0.00'));
check('zero discount',()=>assert.equal(quote(input('1','1','0')).total,'1.00'));
check('zero unit allowed',()=>assert.equal(quote(input('0')).total,'0.00'));
check('line versus order rounding',()=>{const d=input('0.01','1','5000'); d.lines.push({...d.lines[0]}); assert.equal(quote(d).totalMinor,'0'); assert.equal(roundHalfUp(2n*5000n,10000n),1n);});
check('unsafe Number range retained',()=>{const d=input('9999999999.99','10000','0'); d.lines=Array.from({length:100},()=>({...d.lines[0]})); assert.equal(quote(d).totalMinor,'999999999999000000');});
check('invalid amounts rejected',()=>{for(const s of ['1.005','01','1e3','-1',' 1','1,00','Infinity','1',1,null])assert.throws(()=>amount(s));});
check('quantity bounds',()=>{for(const q of ['0','10001','1.5',1])assert.throws(()=>quote(input('1',q)));});
check('discount bounds',()=>assert.throws(()=>quote(input('1','1','10001'))));
check('currency mismatch',()=>assert.throws(()=>quote({...input(),currency:'USD'})));
check('unknown fields',()=>assert.throws(()=>quote({...input(),total:'0.01'})));
check('line limit',()=>assert.throws(()=>quote({...input(),lines:Array(101).fill({unit:'1',quantity:'1'})})));
check('10000 generated invariant cases',()=>{for(let i=0;i<10000;i++){const r=quote(input(display(BigInt(i)),String(i%17+1),String(i%10001))); assert.equal(BigInt(r.totalMinor)+BigInt(r.discountMinor),BigInt(r.subtotalMinor)); assert(BigInt(r.totalMinor)>=0n);}});
for(const [name,body,type,status] of [
['HTTP success',JSON.stringify(input()),'application/json',200],
['HTTP malformed JSON','{','application/json',400],
['HTTP numeric price',JSON.stringify(input(1)),'application/json',400],
['HTTP content type','{}','text/plain',415],
['HTTP size limit',' '.repeat(16385),'application/json',413]
]) { const r=await fetch('http://127.0.0.1:3000/quote',{method:'POST',headers:{'Content-Type':type},body}); assert.equal(r.status,status); await r.text(); console.log('PASS',++count,name); }
console.log(`${count} checks passed`);
这次本地实际执行得到二十二项检查通过,其中十七项针对计算或校验,五项通过真实本地 HTTP 调用检查成功响应、损坏的 JSON、数字类型单价、错误媒体类型和超限正文。大整数测试验证一百行最大示例输入可以完整返回整数分字符串,没有经过普通浮点数。代码块与测试执行所用文件一致。
尚未执行的部分包括真实浏览器交互、移动端键盘、慢网下连续输入、反向代理超时和数据库集成。页面代码经过人工检查,但不能据此宣称跨浏览器验收通过。实际接入前应测试快速重复提交、请求期间修改输入、服务中断、非 JSON 错误页及输入法组合输入,并确认旧结果不会重新出现。
七、落库时保留精度,也保留计算语义
下面给出面向 PostgreSQL 18 的存储边界示例,它不属于上述已经运行的程序。金额以分为单位存入 bigint,外部输入继续使用十进制字符串通过参数绑定传入。示例上限下,最大汇总原价小于有符号八字节整数上限;如果扩大单价、行数或数量,需要重新计算上界,不能因为 Node 使用任意精度整数就假设数据库也不会溢出。
CREATE TABLE quote_totals (
quote_id uuid PRIMARY KEY,
currency text NOT NULL CHECK (currency = 'CNY'),
policy text NOT NULL CHECK (policy = 'cny-line-discount-v1'),
subtotal_minor bigint NOT NULL CHECK (subtotal_minor >= 0),
discount_minor bigint NOT NULL CHECK (discount_minor >= 0),
total_minor bigint NOT NULL CHECK (total_minor >= 0),
CHECK (discount_minor <= subtotal_minor),
CHECK (total_minor = subtotal_minor - discount_minor)
);
-- $1 至 $5 由数据库驱动绑定,禁止拼接用户字符串。
INSERT INTO quote_totals
(quote_id, currency, policy, subtotal_minor, discount_minor, total_minor)
VALUES ($1::uuid, 'CNY', $2, $3::bigint, $4::bigint, $5::bigint);
这张表只演示总额约束,并未实现完整订单模型。正式系统还应有明细记录、归属权限、时间与状态,把明细和汇总放在同一个事务中保存。当前约束能验证总额自洽,却不能证明它与明细相等;不能把数据库中的一个等式误当成完整业务正确性。审计任务应重新汇总保存的行结果,而不是重新读取当前商品价计算旧订单。
PostgreSQL 的 numeric 也能表达精确小数,适合需要不同小数位的领域;但列声明的小数位可能触发输入舍入,因此仍应在应用入口主动校验,而不是让存储层替你决定用户多填的一位如何处理。对于只有整数分的本实验,bigint 的语义更直接。数据库驱动读取大整数时也应保留字符串,避免读出后再转换成普通数字。PostgreSQL 数值类型文档说明了整数范围、精确小数与浮点类型的差异。
八、一分钱差异怎样定位,哪些边界不能照搬
排查金额差异时,先记录规范化后的单位金额、数量、比例、行分组、币种和规则版本,再比较每一步的整数结果。不要只记录页面格式化后的总价。相同最终金额可能来自完全不同的优惠分配,而退款、撤销、发票和对账恰恰需要知道分配过程。日志应避免包含不必要的用户资料,并设置访问权限与保留期限。
如果只有某些半分边界失败,优先检查舍入方向和舍入时机;如果金额越大越容易失败,检查 JSON 数字、驱动类型转换和中间变量;如果只有合并商品或退款时失败,检查计价行身份和原交易分摊结果;如果后端记录正确而页面偶发错误,再检查并发响应和展示缓存。这样能把故障缩小到明确层次,而不是到处添加保留两位小数。
本实验不支持其他币种,也不支持重量计价、汇率、税费、负数、分期或优惠分摊。新增任何一项都应先定义单位、有效位数、舍入节点和剩余尾差分配规则。尤其是整单优惠分摊,不能简单让每行独立舍入后期待总和自然相等;需要确定余数如何分配、同余时如何排序,以及退款时是否复用原分摊。
部署时把计算模块与接口一起版本化,保留旧规则处理历史订单的能力。观察校验失败率、报价延迟、请求体超限与异常比例,给公开入口配置限流;不要为了缓解错误而在前端悄悄取整或放宽格式。金额链路真正可靠的标准,是每个单位、每次转换和每个舍入点都能解释,并能用保存的输入与规则重现结果。
评论
暂无评论。