Chance.js 生成巴西 CPF 纳税人识别号:chance.cpf() 用法与校验位算法全解析
Chance.js 生成巴西 CPF 纳税人识别号:chance.cpf() 用法与校验位算法全解析
CPF(Cadastro de Pessoas Físicas)是巴西自然人的纳税人识别号,常用于巴西地区的表单测试、用户资料模拟与本地化数据生成。本文围绕 chancejs 中 person 模块的 cpf 文档,完整讲解 chance.cpf() 的调用方式、formatted 参数行为,并结合 源码实现 与 测试用例 剖析 CPF 的生成流程与两位校验位的计算原理,帮助你直接落地到需要巴西场景数据的项目中。
一、快速上手:一行代码生成合法 CPF
chance.cpf() 是 Chance 中用于生成巴西纳税人识别号(CPF)的快捷方法,无需任何参数即可调用:
// 基础用法
chance.cpf()
调用一次会返回一个格式完整、校验位合法的 14 位字符串,形如:
chance.cpf();
// => '607.116.899-62'
每次调用都会产生不同的随机结果,返回值的固定形态为 XXX.XXX.XXX-XX:前 9 位是随机主体数字,后 2 位是由算法计算出的校验位。
二、formatted 参数:按需保留或移除标点
CPF 的标准展示格式带有分隔符,但许多存储层或接口(如数据库字段、API 请求体)要求纯数字串。cpf 方法通过 formatted 选项控制输出格式:
// 省略标点,仅返回 11 位纯数字
chance.cpf({ formatted: false });
// => '18641718397'
参数行为小结:
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
formatted |
boolean | true |
为 true 时返回 XXX.XXX.XXX-XX 格式;为 false 时移除所有非数字字符,返回 11 位纯数字 |
从源码看,该默认值由统一的 initOptions 机制注入(见下文第三节),即不传任何参数时等价于 chance.cpf({ formatted: true })。
三、源码级剖析:CPF 是如何生成的
chance.cpf 的实现位于 chance.js,完整逻辑如下(为便于阅读做了注释标注):
// CPF; ID to identify taxpayers in Brazil
Chance.prototype.cpf = function (options) {
options = initOptions(options, {
formatted: true // 默认输出带格式的字符串
});
var n = this.n(this.natural, 9, { max: 9 }); // 生成 9 位随机数字
var d1 = n[8]*2 + n[7]*3 + n[6]*4 + n[5]*5 + n[4]*6 + n[3]*7 + n[2]*8 + n[1]*9 + n[0]*10;
d1 = 11 - (d1 % 11);
if (d1 >= 10) {
d1 = 0; // 余数小于 2 时校验位取 0
}
var d2 = d1*2 + n[8]*3 + n[7]*4 + n[6]*5 + n[5]*6 + n[4]*7 + n[3]*8 + n[2]*9 + n[1]*10 + n[0]*11;
d2 = 11 - (d2 % 11);
if (d2 >= 10) {
d2 = 0;
}
var cpf = '' + n[0] + n[1] + n[2] + '.' + n[3] + n[4] + n[5] + '.' + n[6] + n[7] + n[8] + '-' + d1 + d2;
return options.formatted ? cpf : cpf.replace(/\D/g, '');
};
整个流程可以拆解为三个关键环节:
1. 默认值注入:initOptions
方法开头调用的 initOptions 是 Chance 内部统一的选项合并工具,定义于 chance.js:
function initOptions(options, defaults) {
options = options || {};
if (defaults) {
for (var i in defaults) {
if (typeof options[i] === 'undefined') {
options[i] = defaults[i]; // 未显式传入的属性用默认值填充
}
}
}
return options;
}
它遵循"缺省补默认"策略:只有用户未显式传入 formatted 时才将其置为 true,从而保证 chance.cpf() 与 chance.cpf({ formatted: true }) 行为完全一致。
2. 随机主体:this.n + this.natural
9 位主体数字通过 this.n(this.natural, 9, { max: 9 }) 生成。其中 n 是 Chance 的批量生成方法(chance.js),它接收一个生成函数、生成个数以及透传给该函数的附加参数,返回一个长度为 9 的数组:
Chance.prototype.n = function(fn, n) {
testRange(typeof fn !== "function", "Chance: The first argument must be a function.");
if (typeof n === 'undefined') { n = 1; }
var i = n, arr = [], params = slice.call(arguments, 2);
i = Math.max(0, i);
for (null; i--; null) {
arr.push(fn.apply(this, params));
}
return arr;
};
即重复调用 9 次 natural({ max: 9 }),得到 0~9 之间的 9 位随机数字,作为 CPF 的主体部分。
3. 校验位:巴西官方加权求余算法
CPF 的后两位并非随机数,而是由前 9 位数字按巴西官方算法计算而来,这也是生成结果能通过校验的关键:
第一位校验位 d1:前 9 位数字按权重 10、9、8、7、6、5、4、3、2 加权求和,对 11 取余后用 11 减去余数;若结果大于等于 10(即余数小于 2),校验位取 0:
d1 = 11 - ((n0×10 + n1×9 + ... + n8×2) % 11)
d1 >= 10 时 d1 = 0
源码中 n[8]*2+n[7]*3+...+n[0]*10 的书写顺序正是从末位(权重 2)到首位(权重 10)的加权求和。
第二位校验位 d2:将 d1 纳入计算,前 10 位(9 位主体 + d1)按权重 11、10、9、8、7、6、5、4、3、2 加权求和,同样取模 11 求补:
d2 = 11 - ((d1×2 + n0×11 + n1×10 + ... + n8×3) % 11)
d2 >= 10 时 d2 = 0
最终将 9 位主体与两个校验位按 XXX.XXX.XXX-XX 模板拼接;当 formatted 为 false 时,通过 cpf.replace(/\D/g, '') 正则移除全部非数字字符,得到 11 位纯数字串。
四、测试用例验证:输出必为合法形态
仓库的 person 模块测试 对 cpf() 做了严格的批量断言,可作为使用与接入时的参考:
// chance.cpf()
test('cpf() returns a random valid taxpayer number for Brazil citizens (CPF)', t => {
_.times(1000, () => {
let cpf = chance.cpf()
t.true(_.isString(cpf))
t.true(/^\d{3}.\d{3}.\d{3}-\d{2}$/m.test(cpf))
t.is(cpf.length, 14)
})
})
测试在 1000 次迭代中验证了三个约束:
- 返回值必然是字符串类型;
- 形态必须匹配
^\d{3}.\d{3}.\d{3}-\d{2}$(三个 3 位数字块、一个 2 位数字块,以.和-分隔); - 格式化输出的长度固定为 14(含 3 个分隔符)。
五、同族方法与延伸:从 CPF 到 CNPJ
CPF 对应巴西自然人识别号,而在同一源码区域中还提供了面向企业的 CNPJ 生成器(chance.js),两者都遵循"随机主体 + 加权求余校验位"的同一设计模式,只是主体位数(12 位)、权重分配与 d1 阈值判断(d1 < 2 时取 0)不同。当你的项目需要完整的巴西身份场景数据时,可将二者结合使用。
在 person 模块文档 中,cpf 与 aadhar(印度)、ssn(美国)等同属区域化身份标识生成能力,适合在需要多国本地化测试数据的场景中按国家维度选用。
六、典型应用场景与注意事项
适用场景:
- 巴西站点的注册、表单、下单流程的前端演示数据或自动化测试数据;
- 需要"格式合法、可通过基础校验"的 CPF 占位数据(数据库种子、接口 Mock);
- 与
formatted: false结合,产出符合后端存储规范的 11 位纯数字。
注意事项:
- 该方法的输出虽满足 CPF 官方校验算法,但它是随机生成的虚拟号码,不代表任何真实存在的巴西公民身份,切勿用于身份认证、风控或任何真实业务决策;
- 若需求是"校验用户输入的真实 CPF 是否合法",应使用专门的校验库而非本生成器;
- 当前仓库的 Chance 版本为 1.1.13(见 chance.js),
cpf方法的formatted行为以该版本实现为准。
小结:chance.cpf() 是 Chance 提供的一个实现完整、输出可校验的巴西 CPF 生成器——默认输出带分隔符的 14 位字符串,传入 { formatted: false } 即可获得 11 位纯数字。理解其 initOptions 默认值注入、n + natural 批量随机与加权求余校验位算法后,你不仅能正确使用它,还能在需要时按同样思路扩展其他地区识别号的生成逻辑。